@travetto/cli 2.2.0 → 2.2.3

package/README.md

@@ -38,19 +38,19 @@ This will show all the available options/choices that are exposed given the curr
 
 ## Extending
 
-Extending the `cli` is fairly straightforward.  It is built upon [commander](https://www.npmjs.com/package/commander), with a plugin model that is extensible:
+Extending the `cli` is fairly straightforward.  It is built upon [commander](https://www.npmjs.com/package/commander), with a model that is extensible:
 
-**Code: Echo Plugin**
+**Code: Echo Command**
 ```typescript
 import '@travetto/base';
-import { BasePlugin } from '@travetto/cli/src/plugin-base';
+import { CliCommand } from '@travetto/cli/src/command';
 
 /**
  * `npx trv echo`
  *
  * Allows for cleaning of the cache dire
  */
-export class CliEchoPlugin extends BasePlugin {
+export class CliEchoCommand extends CliCommand {
   name = 'echo';
 
   getOptions() {
@@ -72,7 +72,7 @@ export class CliEchoPlugin extends BasePlugin {
 
 With the corresponding output:
 
-**Terminal: Echo Plugin Help**
+**Terminal: Echo Command Help**
 ```bash
 $ trv echo --help
 
@@ -85,7 +85,7 @@ Options:
 
 And actually using it:
 
-**Terminal: Echo Plugin Run**
+**Terminal: Echo Command Run**
 ```bash
 $ trv echo -u bOb rOb DRoP
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@travetto/cli",
   "displayName": "Command Line Interface",
-  "version": "2.2.0",
+  "version": "2.2.3",
   "description": "CLI infrastructure for travetto framework",
   "keywords": [
     "cli",
@@ -27,7 +27,7 @@
     "directory": "module/cli"
   },
   "dependencies": {
-    "@travetto/base": "^2.2.0",
+    "@travetto/base": "^2.2.3",
     "commander": "^9.4.0"
   },
   "docDependencies": {

package/src/{plugin.ts → command-manager.ts}

@@ -1,9 +1,9 @@
 import { SourceIndex } from '@travetto/boot/src/internal/source';
 
 import { color } from './color';
-import { BasePlugin } from './plugin-base';
+import { CliCommand } from './command';
 
-const PLUGIN_PACKAGE = [
+const COMMAND_PACKAGE = [
   [/^run$/, 'app', true],
   [/^compile$/, 'compiler', true],
   [/^test$/, 'test', false],
@@ -15,14 +15,14 @@ const PLUGIN_PACKAGE = [
 ] as const;
 
 /**
- * Manages loading and finding all plugins
+ * Manages loading and finding all commands
  */
-export class PluginManager {
+export class CliCommandManager {
 
   /**
-   * Get list of all plugins available
+   * Get list of all commands available
    */
-  static getPluginMapping(): Map<string, string> {
+  static getCommandMapping(): Map<string, string> {
     const all = new Map<string, string>();
     for (const { file } of SourceIndex.find({ folder: 'bin', filter: /bin\/cli-/ })) {
       all.set(file.replace(/^.*\/bin\/.+?-(.*?)[.][^.]*$/, (_, f) => f), file);
@@ -31,13 +31,13 @@ export class PluginManager {
   }
 
   /**
-   * Load plugin module
+   * Load command
    */
-  static async loadPlugin(cmd: string, op?: (p: BasePlugin) => unknown): Promise<BasePlugin> {
+  static async loadCommand(cmd: string, op?: (p: CliCommand) => unknown): Promise<CliCommand> {
     const command = cmd.replace(/:/g, '_');
-    const f = this.getPluginMapping().get(command)!;
+    const f = this.getCommandMapping().get(command)!;
     if (!f) {
-      const cfg = PLUGIN_PACKAGE.find(([re]) => re.test(cmd));
+      const cfg = COMMAND_PACKAGE.find(([re]) => re.test(cmd));
       if (cfg) {
         const [, pkg, prod] = cfg;
         console.error(color`
@@ -51,7 +51,7 @@ ${{ identifier: `npm i ${prod ? '' : '--save-dev '}@travetto/${pkg}` }}`);
     for (const v of values) {
       try {
         const inst = new v();
-        if (inst instanceof BasePlugin) {
+        if (inst instanceof CliCommand) {
           if (op) {
             await op(inst);
           }
@@ -59,17 +59,17 @@ ${{ identifier: `npm i ${prod ? '' : '--save-dev '}@travetto/${pkg}` }}`);
         }
       } catch { }
     }
-    throw new Error(`Not a valid plugin: ${cmd}`);
+    throw new Error(`Not a valid command: ${cmd}`);
   }
 
   /**
-   * Load all available plugins
+   * Load all available commands
    */
-  static async loadAllPlugins(op?: (p: BasePlugin) => unknown | Promise<unknown>): Promise<BasePlugin[]> {
+  static async loadAllCommands(op?: (p: CliCommand) => unknown | Promise<unknown>): Promise<CliCommand[]> {
     return Promise.all(
-      [...this.getPluginMapping().keys()]
+      [...this.getCommandMapping().keys()]
         .sort((a, b) => a.localeCompare(b))
-        .map(k => this.loadPlugin(k, op))
+        .map(k => this.loadCommand(k, op))
     );
   }
 }

package/src/{plugin-base.ts → command.ts}

@@ -1,3 +1,4 @@
+import { appendFile } from 'fs/promises';
 import * as commander from 'commander';
 
 import { CompletionConfig } from './types';
@@ -6,9 +7,9 @@ import { CliUtil } from './util';
 
 type Completion = Record<string, string[]>;
 
-type ParamPrimitive = string | number | boolean | string[] | number[];
+type OptionPrimitive = string | number | boolean;
 
-type ParamConfig<K extends ParamPrimitive = ParamPrimitive> = {
+type CoreOptionConfig<K> = {
   type?: Function;
   key?: string;
   short?: string | false;
@@ -16,19 +17,26 @@ type ParamConfig<K extends ParamPrimitive = ParamPrimitive> = {
   desc: string;
   completion?: boolean;
   def?: K;
-  choices?: K[] | readonly K[];
   combine?: (v: string, curr: K) => K;
 };
 
+export type OptionConfig<K extends OptionPrimitive = OptionPrimitive> = CoreOptionConfig<K> & {
+  choices?: K[] | readonly K[];
+};
+
+export type ListOptionConfig<K extends OptionPrimitive = OptionPrimitive> = CoreOptionConfig<K[]>;
+
+type AllOptionConfig<K extends OptionPrimitive = OptionPrimitive> = OptionConfig<K> | ListOptionConfig<K>;
+
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-type ParamMap<T = any> = { [key in keyof T]: T[key] extends ParamPrimitive ? ParamConfig<T[key]> : never };
+type OptionMap<T = any> = { [key in keyof T]: T[key] extends OptionPrimitive ? AllOptionConfig<T[key]> : never };
 
-type Shape<M extends ParamMap> = { [k in keyof M]: Exclude<M[k]['def'], undefined> };
+type Shape<M extends OptionMap> = { [k in keyof M]: Exclude<M[k]['def'], undefined> };
 
 /**
- * Base plugin
+ * Base command
  */
-export abstract class BasePlugin<V extends ParamMap = ParamMap> {
+export abstract class CliCommand<V extends OptionMap = OptionMap> {
   /**
    * Command object
    */
@@ -51,7 +59,7 @@ export abstract class BasePlugin<V extends ParamMap = ParamMap> {
   abstract action(...args: unknown[]): void | Promise<void>;
 
   /**
-   * Setup environment before plugin runs
+   * Setup environment before command runs
    */
   envInit?(): Promise<void> | void;
   /**
@@ -70,13 +78,17 @@ export abstract class BasePlugin<V extends ParamMap = ParamMap> {
    * Extra help
    */
   help?(): Promise<string> | string;
+  /**
+   * Supports JSON IPC?
+   */
+  jsonIpc?(...args: unknown[]): Promise<unknown>;
 
   /**
    * Define option
    */
-  option(cfg: ParamConfig<string>): ParamConfig<string> {
-    if (cfg.combine && cfg.def) {
-      cfg.def = cfg.combine(cfg.def, cfg.def);
+  option<K extends OptionPrimitive, T extends OptionConfig<K>>(cfg: T): T {
+    if ('combine' in cfg && cfg.combine && cfg.def && !Array.isArray(cfg.def)) {
+      cfg.def = cfg.combine(`${cfg.def}`, cfg.def);
     }
     return { type: String, ...cfg };
   }
@@ -84,11 +96,11 @@ export abstract class BasePlugin<V extends ParamMap = ParamMap> {
   /**
    * Define option
    */
-  choiceOption<K extends string | number>({ choices, ...cfg }: ParamConfig<K> & { choices: K[] | readonly K[] }): ParamConfig<K> {
-    const config: ParamConfig<K> = {
+  choiceOption<K extends string, T extends (OptionConfig<K> & { choices: K[] | readonly K[] })>({ choices, ...cfg }: T): T {
+    // @ts-expect-error
+    const config: T = {
       type: String,
-      // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
-      combine: (v: string, acc: K): K => choices.includes(v as K) ? v as K : acc,
+      combine: (v: K, acc) => choices.includes(v) ? v : acc,
       choices,
       completion: true,
       ...cfg
@@ -99,7 +111,7 @@ export abstract class BasePlugin<V extends ParamMap = ParamMap> {
   /**
    * Define list option
    */
-  listOption(cfg: ParamConfig<string[]>): ParamConfig<string[]> {
+  listOption<T extends ListOptionConfig<string>>(cfg: T): T {
     return {
       type: String,
       def: [],
@@ -112,7 +124,7 @@ export abstract class BasePlugin<V extends ParamMap = ParamMap> {
   /**
    * Define bool option
    */
-  boolOption(cfg: ParamConfig<boolean>): ParamConfig<boolean> {
+  boolOption(cfg: OptionConfig<boolean>): OptionConfig<boolean> {
     return {
       type: Boolean,
       combine: CliUtil.toBool.bind(CliUtil),
@@ -124,7 +136,7 @@ export abstract class BasePlugin<V extends ParamMap = ParamMap> {
   /**
    * Define int option
    */
-  intOption({ lower, upper, ...cfg }: ParamConfig<number> & { lower?: number, upper?: number }): ParamConfig<number> {
+  intOption({ lower, upper, ...cfg }: OptionConfig<number> & { lower?: number, upper?: number }): OptionConfig<number> {
     return {
       type: Number,
       combine: CliUtil.toInt.bind(CliUtil, lower, upper),
@@ -143,9 +155,8 @@ export abstract class BasePlugin<V extends ParamMap = ParamMap> {
   /**
    * Expose configuration as constrained typed object
    */
-  get cmd(): Shape<ReturnType<Exclude<this['getOptions'], undefined>>> {
-    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
-    return this.#cmd.opts() as Shape<ReturnType<Exclude<this['getOptions'], undefined>>>;
+  get cmd(): Shape<V> {
+    return this.#cmd.opts();
   }
 
   /**
@@ -169,11 +180,11 @@ export abstract class BasePlugin<V extends ParamMap = ParamMap> {
    * Process all options into final set before registering with commander
    * @returns
    */
-  async finalizeOptions(): Promise<ParamConfig[]> {
+  async finalizeOptions(): Promise<AllOptionConfig[]> {
     const opts = this.getOptions?.();
     const used = new Set();
 
-    return (opts ? Object.entries(opts) : []).map(([k, cfg]) => {
+    return (opts ? Object.entries<AllOptionConfig>(opts) : []).map(([k, cfg]) => {
       cfg.key = k;
       cfg.name ??= k.replace(/([a-z])([A-Z])/g, (_, l, r: string) => `${l}-${r.toLowerCase()}`);
       if (cfg.short === undefined) {
@@ -206,6 +217,7 @@ export abstract class BasePlugin<V extends ParamMap = ParamMap> {
       if (cfg.type !== Boolean || cfg.def) {
         key = `${key} <${cfg.name}>`;
       }
+      // @ts-expect-error
       cmd = cfg.combine ? cmd.option(key, cfg.desc, cfg.combine, cfg.def) : cmd.option(key, cfg.desc, (cur, acc) => cur, cfg.def);
     }
 
@@ -219,6 +231,14 @@ export abstract class BasePlugin<V extends ParamMap = ParamMap> {
   async runAction(...args: unknown[]): Promise<void> {
     await this.envInit?.();
     await this.build();
+    if (process.env.TRV_CLI_JSON_IPC && this.jsonIpc) {
+      const data = await this.jsonIpc(...args);
+      if (data !== undefined) {
+        const payload = JSON.stringify({ type: this.name, data });
+        await appendFile(process.env.TRV_CLI_JSON_IPC, `${payload}\n`);
+        return;
+      }
+    }
     return await this.action(...args);
   }
 
@@ -241,7 +261,7 @@ export abstract class BasePlugin<V extends ParamMap = ParamMap> {
     for (const el of await this.finalizeOptions()) {
       if (el.completion) {
         out[''] = [...out['']!, `--${el.name} `];
-        if (el.choices) {
+        if ('choices' in el && el.choices) {
           out[`--${el.name} `] = el.choices.map(x => `${x}`);
           if (el.short) {
             out[`- ${el.short} `] = el.choices.map(x => `${x}`);

package/src/execute.ts

@@ -2,7 +2,7 @@ import { program as commander } from 'commander';
 
 import { CliUtil } from './util';
 import { CompletionConfig } from './types';
-import { PluginManager } from './plugin';
+import { CliCommandManager } from './command-manager';
 import { HelpUtil } from './help';
 import { version } from '../package.json';
 
@@ -16,31 +16,31 @@ export class ExecutionManager {
    */
   static async runCompletion(args: string[]): Promise<void> {
     const cfg: CompletionConfig = { all: [], task: {} };
-    await PluginManager.loadAllPlugins(x => x.setupCompletion(cfg));
+    await CliCommandManager.loadAllCommands(x => x.setupCompletion(cfg));
     const res = await CliUtil.getCompletion(cfg, args.slice(3));
     console.log(res.join(' '));
     return;
   }
 
   /**
-   * Run plugin
+   * Run command
    */
-  static async runPlugin(args: string[]): Promise<void> {
+  static async runCommand(args: string[]): Promise<void> {
     const cmd = args[2];
 
-    let plugin;
+    let command;
 
     try {
-      // Load a single plugin
-      plugin = await PluginManager.loadPlugin(cmd);
-      await plugin.setup(commander);
+      // Load a single command
+      command = await CliCommandManager.loadCommand(cmd);
+      await command.setup(commander);
     } catch (err) {
       return HelpUtil.showHelp(commander, `Unknown command ${cmd}`);
     }
 
     try {
       if (args.includes('-h') || args.includes('--help')) {
-        return plugin.showHelp();
+        return command.showHelp();
       } else {
         commander.parse(args);
       }
@@ -48,13 +48,13 @@ export class ExecutionManager {
       if (!(err instanceof Error)) {
         throw err;
       }
-      return plugin.showHelp(err);
+      return command.showHelp(err);
     }
   }
 
   /**
    * Execute the command line
-   * @param args argv
+   * @param args
    */
   static async run(args: string[]): Promise<void> {
     const width = +(process.env.TRV_CONSOLE_WIDTH ?? process.stdout.columns ?? 120);
@@ -68,10 +68,10 @@ export class ExecutionManager {
       await this.runCompletion(args);
     } else {
       if (cmd && !cmd.startsWith('-')) {
-        await this.runPlugin(args);
+        await this.runCommand(args);
       } else {
-        // Load all plugins
-        await PluginManager.loadAllPlugins(x => x.setup(commander));
+        // Load all commands
+        await CliCommandManager.loadAllCommands(x => x.setup(commander));
         HelpUtil.showHelp(commander);
       }
     }

package/src/util.ts

@@ -1,3 +1,4 @@
+import * as timers from 'timers/promises';
 import * as readline from 'readline';
 import { Writable } from 'stream';
 
@@ -94,10 +95,6 @@ export class CliUtil {
     }));
   }
 
-  static sleep(ms: number): Promise<void> {
-    return new Promise(r => setTimeout(r, ms));
-  }
-
   /**
    * Waiting message with a callback to end
    *
@@ -129,12 +126,12 @@ export class CliUtil {
       .finally(() => done = true);
 
     if (delay) {
-      await Promise.race([this.sleep(delay), final]);
+      await Promise.race([timers.setTimeout(delay), final]);
     }
 
     while (!done) {
       await writeLine(`${this.#waitState[i = (i + 1) % this.#waitState.length]} ${message}`);
-      await this.sleep(50);
+      await timers.setTimeout(50);
     }
 
     if (i >= 0) {