@travetto/cli 3.0.0-rc.1 → 3.0.0-rc.10

package/README.md

@@ -1,5 +1,5 @@
 <!-- This file was generated by @travetto/doc and should not be modified directly -->
-<!-- Please modify https://github.com/travetto/travetto/tree/main/module/cli/doc.ts and execute "npx trv doc" to rebuild -->
+<!-- Please modify https://github.com/travetto/travetto/tree/main/module/cli/DOC.ts and execute "npx trv doc" to rebuild -->
 # Command Line Interface
 ## CLI infrastructure for travetto framework
 
@@ -10,7 +10,7 @@ npm install @travetto/cli
 
 The cli is the primary structure for interacting with the external requirements of the framework.  This can range from running tests, to running applications, to generating email templates. The main executable can be installed globally or locally.  If installed globally and locally, it will defer to the local installation for execution.
 
-As is the custom, modules are able to register their own cli extensions as scripts, whose name starts with `cli-`.  These scripts are then picked up at runtime and all available options are provided when viewing the help documentation.  The following are all the supported cli operations and the various settings they allow.
+As is the custom, modules are able to register their own cli extensions as scripts, whose name starts with `cli.`.  These scripts are then picked up at runtime and all available options are provided when viewing the help documentation.  The following are all the supported cli operations and the various settings they allow.
 
 ## General
 
@@ -21,17 +21,12 @@ $ trv --help
 Usage:  [options] [command]
 
 Options:
-  -V, --version                          output the version number
-  -h, --help                             display help for command
+  -V, --version             output the version number
+  -h, --help                display help for command
 
 Commands:
-  build [options]
-  clean [options]
-  doc [options]
   echo [options] [args...]
-  run [options] [application] [args...]
-  test [options] [regexes...]
-  help [command]                         display help for command
+  help [command]            display help for command
 ```
 
 This will show all the available options/choices that are exposed given the currently installed modules.
@@ -42,8 +37,7 @@ Extending the `cli` is fairly straightforward.  It is built upon [commander](htt
 
 **Code: Echo Command**
 ```typescript
-import '@travetto/base';
-import { CliCommand } from '@travetto/cli/src/command';
+import { CliCommand } from '@travetto/cli';
 
 /**
  * `npx trv echo`
@@ -54,7 +48,7 @@ export class CliEchoCommand extends CliCommand {
   name = 'echo';
 
   getOptions() {
-    return { uppercase: this.boolOption({ desc: 'Upper case', def: false }) };
+    return { uppercase: this.boolOption({ desc: 'Upper case' }) };
   }
 
   getArgs() {
@@ -65,7 +59,7 @@ export class CliEchoCommand extends CliCommand {
     if (this.cmd.uppercase) {
       args = args.map(x => x.toUpperCase());
     }
-    console.log(args);
+    console.log!(args);
   }
 }
 ```
@@ -79,7 +73,7 @@ $ trv echo --help
 Usage:  echo [options] [args...]
 
 Options:
-  -u, --uppercase  Upper case (default: false)
+  -u, --uppercase  Upper case
   -h, --help       display help for command
 ```
 
@@ -89,5 +83,5 @@ And actually using it:
 ```bash
 $ trv echo -u bOb rOb DRoP
 
-[ 'bOb', 'rOb', 'DRoP' ]
+[ 'BOB', 'ROB', 'DROP' ]
 ```

package/__index__.ts

@@ -0,0 +1,7 @@
+export * from './src/command';
+export * from './src/command-manager';
+export * from './src/execute';
+export * from './src/help';
+export * from './src/color';
+export * from './src/module';
+export * from './src/scm';

package/package.json

@@ -1,7 +1,6 @@
 {
   "name": "@travetto/cli",
-  "displayName": "Command Line Interface",
-  "version": "3.0.0-rc.1",
+  "version": "3.0.0-rc.10",
   "description": "CLI infrastructure for travetto framework",
   "keywords": [
     "cli",
@@ -15,23 +14,25 @@
     "name": "Travetto Framework"
   },
   "files": [
+    "__index__.ts",
     "src",
+    "support",
     "bin"
   ],
-  "main": "bin/trv.js",
-  "bin": {
-    "trv": "bin/trv.js"
-  },
+  "bin": "trv.js",
+  "main": "__index__.ts",
   "repository": {
     "url": "https://github.com/travetto/travetto.git",
     "directory": "module/cli"
   },
   "dependencies": {
-    "@travetto/base": "^3.0.0-rc.1",
-    "commander": "^9.4.0"
+    "@travetto/base": "^3.0.0-rc.9",
+    "@travetto/terminal": "^3.0.0-rc.6",
+    "@travetto/worker": "^3.0.0-rc.9",
+    "commander": "^10.0.0"
   },
-  "docDependencies": {
-    "@travetto/app": true
+  "travetto": {
+    "displayName": "Command Line Interface"
   },
   "publishConfig": {
     "access": "public"

package/src/color.ts

@@ -1,29 +1,19 @@
-import { ColorUtil } from '@travetto/boot/src/color';
+import { Util } from '@travetto/base';
+import { GlobalTerminal } from '@travetto/terminal';
 
-const colorSet = {
-  input: ColorUtil.makeColorer('yellow'),
-  output: ColorUtil.makeColorer('magenta'),
-  path: ColorUtil.makeColorer('cyan'),
-  success: ColorUtil.makeColorer('green', 'bold'),
-  failure: ColorUtil.makeColorer('red', 'bold'),
-  param: ColorUtil.makeColorer('green'),
-  type: ColorUtil.makeColorer('cyan'),
-  description: ColorUtil.makeColorer('white', 'faint', 'bold'),
-  title: ColorUtil.makeColorer('white', 'bold'),
-  identifier: ColorUtil.makeColorer('blue', 'bold'),
-  subtitle: ColorUtil.makeColorer('white'),
-  subsubtitle: ColorUtil.makeColorer('white', 'faint')
-} as const;
+const tplFn = GlobalTerminal.templateFunction({
+  input: 'oliveDrab',
+  output: 'pink',
+  path: 'teal',
+  success: 'green',
+  failure: 'red',
+  param: 'yellow',
+  type: 'cyan',
+  description: 'white',
+  title: 'brightWhite',
+  identifier: 'dodgerBlue',
+  subtitle: 'lightGray',
+  subsubtitle: 'darkGray'
+});
 
-/**
- * Colorize a string, as a string interpolation
- *
- * @example
- * ```
- * color`${{title: 'Main Title'}} is ${{subtitle: 'Sub Title}}`
- * ```
- */
-export const color = ColorUtil.makeTemplate(colorSet);
-
-
-export type ColoredElement = keyof typeof colorSet;
+export const cliTpl = Util.makeTemplate(tplFn);

package/src/command-manager.ts

@@ -1,13 +1,13 @@
-import { SourceIndex } from '@travetto/boot/src/internal/source';
+import { ShutdownManager } from '@travetto/base';
+import { RootIndex } from '@travetto/manifest';
 
-import { color } from './color';
+import { cliTpl } from './color';
 import { CliCommand } from './command';
 
 const COMMAND_PACKAGE = [
   [/^run$/, 'app', true],
-  [/^compile$/, 'compiler', true],
   [/^test$/, 'test', false],
-  [/^command:service$/, 'command', true],
+  [/^service$/, 'command', true],
   [/^model:(install|export)$/, 'model', true],
   [/^openapi:(spec|client)$/, 'openapi', true],
   [/^email:(compile|dev)$/, 'email-template', false],
@@ -24,8 +24,8 @@ export class CliCommandManager {
    */
   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);
+    for (const { outputFile: output, import: imp } of RootIndex.findSupport({ filter: /\/cli[.]/, checkProfile: false })) {
+      all.set(output.replace(/^.*\/cli[.](.*?)[.][^.]+$/, (_, f) => f), imp);
     }
     return all;
   }
@@ -33,43 +33,64 @@ export class CliCommandManager {
   /**
    * Load command
    */
-  static async loadCommand(cmd: string, op?: (p: CliCommand) => unknown): Promise<CliCommand> {
+  static async loadCommand(
+    cmd: string,
+    cfg: {
+      filter?: (p: CliCommand) => boolean;
+      failOnMissing?: boolean;
+    } = {}
+  ): Promise<CliCommand | undefined> {
     const command = cmd.replace(/:/g, '_');
-    const f = this.getCommandMapping().get(command)!;
-    if (!f) {
-      const cfg = COMMAND_PACKAGE.find(([re]) => re.test(cmd));
-      if (cfg) {
-        const [, pkg, prod] = cfg;
-        console.error(color`
+    const found = this.getCommandMapping().get(command)!;
+    if (!found) {
+      const matchedCfg = COMMAND_PACKAGE.find(([re]) => re.test(cmd));
+      if (matchedCfg) {
+        const [, pkg, prod] = matchedCfg;
+        console.error!(cliTpl`
 ${{ title: 'Missing Package' }}\n${'-'.repeat(20)}\nTo use ${{ input: cmd }} please run:\n
-${{ identifier: `npm i ${prod ? '' : '--save-dev '}@travetto/${pkg}` }}`);
-        process.exit(1);
+${{ identifier: `npm i ${prod ? '' : '--save-dev '}@travetto/${pkg}` }}
+`);
+        await ShutdownManager.exit(1);
       }
       throw new Error(`Unknown command: ${cmd}`);
     }
-    const values = Object.values<{ new(...args: unknown[]): unknown }>(await import(f));
-    for (const v of values) {
-      try {
-        const inst = new v();
-        if (inst instanceof CliCommand) {
-          if (op) {
-            await op(inst);
+    try {
+      const values = Object.values<{ new(...args: unknown[]): unknown }>(await import(found));
+      for (const v of values) {
+        try {
+          const inst = new v();
+          if (inst instanceof CliCommand && (!cfg.filter || cfg.filter(inst))) {
+            return inst;
           }
-          return inst;
-        }
-      } catch { }
+        } catch { }
+      }
+    } catch (importErr) {
+      console.error(`Import error: ${cmd}`, importErr);
+    }
+    if (cfg.failOnMissing ?? false) {
+      throw new Error(`Not a valid command: ${cmd}`);
     }
-    throw new Error(`Not a valid command: ${cmd}`);
   }
 
   /**
    * Load all available commands
    */
   static async loadAllCommands(op?: (p: CliCommand) => unknown | Promise<unknown>): Promise<CliCommand[]> {
-    return Promise.all(
+    const commands = await Promise.all(
       [...this.getCommandMapping().keys()]
-        .sort((a, b) => a.localeCompare(b))
-        .map(k => this.loadCommand(k, op))
+        .map(k => this.loadCommand(k, {
+          filter(cmd: CliCommand) {
+            return RootIndex.getFunctionMetadata(cmd.constructor)?.abstract !== true && cmd.isActive?.() !== false;
+          }
+        }))
     );
+
+    return await Promise.all(commands
+      .filter((x): x is Exclude<typeof x, undefined> => !!x)
+      .sort((a, b) => a.name.localeCompare(b.name))
+      .map(async x => {
+        await op?.(x);
+        return x;
+      }));
   }
 }

package/src/command.ts

@@ -1,11 +1,10 @@
-import { appendFile } from 'fs/promises';
-import * as commander from 'commander';
+import { appendFile, mkdir } from 'fs/promises';
+import type commander from 'commander';
 
-import { CompletionConfig } from './types';
-import { HelpUtil } from './help';
-import { CliUtil } from './util';
+import { path } from '@travetto/manifest';
+import { ConsoleManager, DataUtil, defineGlobalEnv, GlobalEnvConfig, ShutdownManager } from '@travetto/base';
 
-type Completion = Record<string, string[]>;
+import { HelpUtil } from './help';
 
 type OptionPrimitive = string | number | boolean;
 
@@ -29,10 +28,16 @@ export type ListOptionConfig<K extends OptionPrimitive = OptionPrimitive> = Core
 type AllOptionConfig<K extends OptionPrimitive = OptionPrimitive> = OptionConfig<K> | ListOptionConfig<K>;
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-type OptionMap<T = any> = { [key in keyof T]: T[key] extends OptionPrimitive ? AllOptionConfig<T[key]> : never };
+export type OptionMap<T = any> = { [key in keyof T]: T[key] extends OptionPrimitive ? AllOptionConfig<T[key]> : never };
 
 type Shape<M extends OptionMap> = { [k in keyof M]: Exclude<M[k]['def'], undefined> };
 
+function clamp(v: number, l?: number, u?: number): number | undefined {
+  if (l !== undefined && v < l) { return; }
+  if (u !== undefined && v > u) { return; }
+  return v;
+}
+
 /**
  * Base command
  */
@@ -61,7 +66,7 @@ export abstract class CliCommand<V extends OptionMap = OptionMap> {
   /**
    * Setup environment before command runs
    */
-  envInit?(): Promise<void> | void;
+  envInit?(): Promise<GlobalEnvConfig> | GlobalEnvConfig;
   /**
    * Get Options for commander
    */
@@ -69,7 +74,7 @@ export abstract class CliCommand<V extends OptionMap = OptionMap> {
   /**
     * Get args
     */
-  getArgs?(): string;
+  getArgs?(): string | undefined;
   /**
    * Initialization code for adding options
    */
@@ -82,7 +87,10 @@ export abstract class CliCommand<V extends OptionMap = OptionMap> {
    * Supports JSON IPC?
    */
   jsonIpc?(...args: unknown[]): Promise<unknown>;
-
+  /**
+   * Is the command active/eligible for usage
+   */
+  isActive?(): boolean;
   /**
    * Define option
    */
@@ -127,7 +135,8 @@ export abstract class CliCommand<V extends OptionMap = OptionMap> {
   boolOption(cfg: OptionConfig<boolean>): OptionConfig<boolean> {
     return {
       type: Boolean,
-      combine: CliUtil.toBool.bind(CliUtil),
+      combine: (val, curr): boolean =>
+        (val !== undefined ? DataUtil.coerceType(val, Boolean, false) : undefined) ?? curr,
       completion: true,
       ...cfg
     };
@@ -139,19 +148,11 @@ export abstract class CliCommand<V extends OptionMap = OptionMap> {
   intOption({ lower, upper, ...cfg }: OptionConfig<number> & { lower?: number, upper?: number }): OptionConfig<number> {
     return {
       type: Number,
-      combine: CliUtil.toInt.bind(CliUtil, lower, upper),
+      combine: (val, curr): number => clamp(DataUtil.coerceType(val, Number, false), lower, upper) ?? curr,
       ...cfg
     };
   }
 
-  /**
-   * Pre-compile on every cli execution
-   */
-  async build(): Promise<void> {
-    await (await import('@travetto/base/bin/lib/'))
-      .BuildUtil.build();
-  }
-
   /**
    * Expose configuration as constrained typed object
    */
@@ -166,14 +167,21 @@ export abstract class CliCommand<V extends OptionMap = OptionMap> {
     return this.#cmd.args;
   }
 
+  exit(code = 0): Promise<void> {
+    return ShutdownManager.exit(code);
+  }
+
   /**
    * Render help with additional message or extra text
    */
-  async showHelp(err?: string | Error, extra?: string): Promise<never> {
+  async showHelp(err?: string | Error, extra?: string, exitOnError = true): Promise<void> {
     if (err && typeof err !== 'string') {
       err = err.message;
     }
     HelpUtil.showHelp(this.#cmd, err, extra || (await this.help?.()) || '');
+    if (exitOnError) {
+      return this.exit(err ? 1 : 0);
+    }
   }
 
   /**
@@ -209,19 +217,27 @@ export abstract class CliCommand<V extends OptionMap = OptionMap> {
     if (this.init) {
       cmd = await this.init?.(cmd);
     }
-    if (this.getArgs) {
-      cmd = cmd.arguments(this.getArgs?.());
+    const args = this.getArgs?.();
+    if (args) {
+      cmd = cmd.arguments(args);
     }
     for (const cfg of await this.finalizeOptions()) {
-      let key = `${cfg.short ? `-${cfg.short}, ` : ''}--${cfg.name}`;
-      if (cfg.type !== Boolean || cfg.def) {
-        key = `${key} <${cfg.name}>`;
+      const pre = cfg.short ? `-${cfg.short}, ` : '';
+      if (cfg.type === Boolean) {
+        if (cfg.def) {
+          cmd.option(`${pre}--no-${cfg.name}`, `Disables: ${cfg.desc}`);
+        } else {
+          cmd.option(`${pre}--${cfg.name}`, cfg.desc);
+        }
+      } else {
+        const key = `${pre}--${cfg.name} <${cfg.name}>`;
+        // @ts-expect-error
+        cmd = cmd.option(key, cfg.desc, cfg.combine ?? ((cur, acc): unknown => cur), cfg.def);
       }
-      // @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);
     }
 
     cmd = cmd.action(this.runAction.bind(this));
+
     return this.#cmd = cmd;
   }
 
@@ -229,46 +245,20 @@ export abstract class CliCommand<V extends OptionMap = OptionMap> {
    * Runs the action at execution time
    */
   async runAction(...args: unknown[]): Promise<void> {
-    await this.envInit?.();
-    await this.build();
-    if (process.env.TRV_CLI_JSON_IPC && this.jsonIpc) {
+    if (this.envInit) {
+      defineGlobalEnv(await this.envInit());
+      ConsoleManager.setDebugFromEnv();
+    }
+
+    if (process.env.TRV_CLI_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`);
+        await mkdir(path.dirname(process.env.TRV_CLI_IPC), { recursive: true });
+        await appendFile(process.env.TRV_CLI_IPC, `${payload}\n`);
         return;
       }
     }
     return await this.action(...args);
   }
-
-  /**
-   * Collection tab completion information
-   */
-  async setupCompletion(config: CompletionConfig): Promise<void> {
-    const task = await this.complete();
-    config.all = [...config.all, this.name];
-    if (task) {
-      config.task[this.name] = task;
-    }
-  }
-
-  /**
-   * Return tab completion information
-   */
-  async complete(): Promise<Completion | void> {
-    const out: Completion = { '': [] };
-    for (const el of await this.finalizeOptions()) {
-      if (el.completion) {
-        out[''] = [...out['']!, `--${el.name} `];
-        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}`);
-          }
-        }
-      }
-    }
-    return out;
-  }
 }

package/src/execute.ts

@@ -1,38 +1,27 @@
+import fs from 'fs/promises';
 import { program as commander } from 'commander';
 
-import { CliUtil } from './util';
-import { CompletionConfig } from './types';
+import { PackageUtil, path, RootIndex } from '@travetto/manifest';
+import { GlobalTerminal } from '@travetto/terminal';
+import { ShutdownManager } from '@travetto/base';
+
 import { CliCommandManager } from './command-manager';
 import { HelpUtil } from './help';
-import { version } from '../package.json';
 
 /**
  * Execution manager
  */
 export class ExecutionManager {
 
-  /**
-   * Run tab completion given the full args list
-   */
-  static async runCompletion(args: string[]): Promise<void> {
-    const cfg: CompletionConfig = { all: [], task: {} };
-    await CliCommandManager.loadAllCommands(x => x.setupCompletion(cfg));
-    const res = await CliUtil.getCompletion(cfg, args.slice(3));
-    console.log(res.join(' '));
-    return;
-  }
-
   /**
    * Run command
    */
-  static async runCommand(args: string[]): Promise<void> {
-    const cmd = args[2];
-
+  static async runCommand(cmd: string, args: string[]): Promise<void> {
     let command;
 
     try {
       // Load a single command
-      command = await CliCommandManager.loadCommand(cmd);
+      command = (await CliCommandManager.loadCommand(cmd, { failOnMissing: true }))!;
       await command.setup(commander);
     } catch (err) {
       return HelpUtil.showHelp(commander, `Unknown command ${cmd}`);
@@ -42,38 +31,63 @@ export class ExecutionManager {
       if (args.includes('-h') || args.includes('--help')) {
         return command.showHelp();
       } else {
-        commander.parse(args);
+        await commander.parseAsync([process.argv[0], process.argv[1], cmd, ...args]);
       }
     } catch (err) {
       if (!(err instanceof Error)) {
         throw err;
+      } else {
+        console.error(err);
       }
       return command.showHelp(err);
     }
   }
 
+  /**
+   * Run file expecting a main method
+   */
+  static async runMain(file: string, args: string[]): Promise<void> {
+    try {
+      // If referenced file exists
+      if (await (fs.stat(path.resolve(file)).then(() => true, () => false))) {
+        file = path.join(RootIndex.manifest.mainModule, file);
+      }
+
+      const imp = RootIndex.getFromImport(file)?.import;
+      if (!imp) {
+        throw new Error(`Unknown file: ${file}`);
+      }
+
+      const mod = await import(imp);
+      await ShutdownManager.exitWithResponse(await mod.main(...args));
+    } catch (err) {
+      await ShutdownManager.exitWithResponse(err, true);
+    }
+  }
+
   /**
    * Execute the command line
    * @param args
    */
-  static async run(args: string[]): Promise<void> {
-    const width = +(process.env.TRV_CONSOLE_WIDTH ?? process.stdout.columns ?? 120);
+  static async run(argv: string[]): Promise<void> {
+    const { init } = await import('@travetto/base/support/init.js');
+    await init();
+
+    const width = GlobalTerminal.width;
     commander
-      .version(version)
+      .version(PackageUtil.getFrameworkVersion())
       .configureOutput({ getOutHelpWidth: () => width, getErrHelpWidth: () => width });
 
-    const cmd = args[2];
-
-    if (cmd === 'complete') {
-      await this.runCompletion(args);
+    const [, , cmd, ...args] = argv;
+    if (cmd === 'main') {
+      const [file, ...rest] = args;
+      await this.runMain(file, rest);
+    } else if (cmd && !cmd.startsWith('-')) {
+      await this.runCommand(cmd, args);
     } else {
-      if (cmd && !cmd.startsWith('-')) {
-        await this.runCommand(args);
-      } else {
-        // Load all commands
-        await CliCommandManager.loadAllCommands(x => x.setup(commander));
-        HelpUtil.showHelp(commander);
-      }
+      // Load all commands
+      await CliCommandManager.loadAllCommands(x => x.setup(commander));
+      HelpUtil.showHelp(commander);
     }
   }
 }