[RFC] @marblejs/cli

[JozefFlakus]

This RFC aims to propose a new @marblejs/cli module for Marble.js command-line interface tool.

Technical idea

A command-line tool that allows to register custom commands, that can work within application Context .

The initial idea is to have a similar and consistent interface as we currently have for all other sort of effects and treat the spawned CLI commands similar to MsgEffect - by acting on triggered Events. The only difference is that the CliEffect should return as an output the status code with optional message which defines whether the command was successfully spawned or an error occured.

import { event } from '@marblejs/core';

export const FooCommand =
  event('FOO_COMMAND')(t.type({
    bar: t.string,
  }));

import { act, useContext, matchEvent } from '@marblejs/core';
import { eventValidator$ } from '@marblejs/middleware-io';
import { CliEffect } from '@marblejs/cli';

export const foo$: CliEffect = (cmd$, ctx) => {
  const dependency1 = useContext(Dependency1Token)(ctx.ask);
  const dependency2 = useContext(Dependency2Token)(ctx.ask);
  // ...
 
  return cmd$.pipe(
    matchEvent(FooCommand),
    act(eventValidator$(FooCommand)),
    act(event => pipe(
       // ....
    ),
  );
};

Each defined CliEffect command handlers can be registered in the listener, similar to other modules:

import { commandLineListener } from '@marblejs/cli';

export const listener = commandLineListener({
  effects: [
    foo$,
    // ....
  ],
});

Registered command can be triggered like follows:

$ marble send <command_name> [arguments]
$ marble s <command_name> [arguments]

Ideally the command could be triggered like this:

$ marble send "FOO_COMMAND" --bar "something"

Feature set

1st stage scope:

• ability to trigger custom (user registered) commands via command-line interface

2nd stage scope:

• ability to create custom command aliases aka command namespaces (in form of routing, similar to the way how @marblejs/http routing does)

n-th stage scope:

• generate different Effect boilerplate code (eg. WsEffect, MsgEffect, HttpEffect, etc.)
• ability to scaffold basic project structure (eg. normal/workspace). It should allow to generate a boilerplate application structure by creating a new folder and populating an initial set of files
• trigger custom commands directly to defined message bus / channels

Packages to consider

• Commander.js - https://github.com/tj/commander.js/

Related issues

• CLI to efficiently scaffold Marble applications #109

[DawidYerginyan]

For the 2nd stage I'd imagine this to work in such a way that we could group commands intro a tree indefinitely, so, for example the root marble command could print help:

$ marble
Marble CLI controls resource creation and <does stuff> like getting routing info or something else.

 Find more information at:
 https://docs.marblejs.com/cli

Basic Commands (Beginner):
  create     Create a Marble  resource like {effect, server, middleware, cliCommand}
  get        Get specific information about your project like {routes, commands, queries, messages, middlewares}

Going deeper into the tree, we could call, another group command and get help printed once again:

$ marble create
You must specify a resource to create.

Resources to create:
  effect           Creates a basic Marble Effect.
  microservice     Creates boilerplate for setting up a http/messaging microservice.

And finally going into the help section of a particular command

$ marble create microservice --help
The main argument is the microservice name
  marble create microservice [name]
  marble create microservice products

This will scaffold a microservice for you, given a multi-package environment is already in place in the root directory of the project, like so:
${repositoryRootDir}/services/<name>
${repositoryRootDir}/services/products

Depending on the provided options, you\'ll get features like an http server or the messaging protocol.

Options:
  -http --http                  Creates a http server. (Default: true)          
  -mp --msg-protocol string     Creates a messaging server. (One of {amqp, redis, etc.}) (Default: amqp)

This could be achieved in a similar way to how effects are composed together into a Tree structure, something in the means of:

const createMicroserviceCliCommand$ = (...);

const createCliGroup$ = createCommandGroup({
  name: 'create',
  description: '<help content>',
  commands: [createMicroserviceCliCommand, ...other commands],
});

const rootCliGroup$ = createCommandGroup({
  name: undefined,
  description: 'root help content',
  commands: [createCliGroup$, getCliGroup$, ...other groups],
});

That would give us the structure of

marble
  create
    microservice
    ...
  routes
  get
    ...

And then at some point/stage in time, open the possibility of extending the default set of commands with your own command groups/namespaces like.

const myCompanyCliGroup$ = createCommandGroup({
  name: 'my-company',
  description: 'MyCompany set of cli commands to perform company operations',
  commands: [migrateCommand$, generateReport$, spawnJiraBugTicket$],
});

marble
  my-company
    migrate
    generate-report
    spawn-jira-bug-ticket

Also, another thing worth including somewhere in the future stages would be to accept standard input and prompt. So if someone would want to create cli commands for doing something that requires credentials would be cool to support two options:

Standard input

$ db_credentials.txt | marble my-company migrate-database products

Prompt

import { prompt } from '@marblejs/cli';

export const foo$: CliEffect = (cmd$, ctx) => {
  const dependency1 = useContext(Dependency1Token)(ctx.ask);
  const dependency2 = useContext(Dependency2Token)(ctx.ask);
  // ...
 
  return cmd$.pipe(
    matchEvent(FooCommand),
    act(eventValidator$(FooCommand)),
    act(event => {
      ...
      const userData = prompt(t.type({
        username: t.string,
        password: t.string
      }));
      ...
    },
  );
};

$ marble foo
Executing...
username: Dawid
password:
Executing...