@travetto/cli 3.4.0-rc.8 → 3.4.0

package/README.md

@@ -59,7 +59,7 @@ This module also has a tight integration with the [VSCode plugin](https://market
 At it's heart, a cli command is the contract defined by what flags, and what arguments the command supports. Within the framework this requires three criteria to be met:
    *  The file must be located in the `support/` folder, and have a name that matches `cli.*.ts`
    *  The file must be a class that has a main method
-   *  The class must use the [@CliCommand](https://github.com/travetto/travetto/tree/main/module/cli/src/decorators.ts#L20) decorator
+   *  The class must use the [@CliCommand](https://github.com/travetto/travetto/tree/main/module/cli/src/decorators.ts#L15) decorator
 
 **Code: Basic Command**
 ```typescript
@@ -93,7 +93,7 @@ Examples of mappings:
 The pattern is that underscores(_) translate to colons (:), and the `cli.` prefix, and `.ts` suffix are dropped.
 
 ## Binding Flags
-[@CliCommand](https://github.com/travetto/travetto/tree/main/module/cli/src/decorators.ts#L20) is a wrapper for [@Schema](https://github.com/travetto/travetto/tree/main/module/schema/src/decorator/schema.ts#L14), and so every class that uses the [@CliCommand](https://github.com/travetto/travetto/tree/main/module/cli/src/decorators.ts#L20) decorator is now a full [@Schema](https://github.com/travetto/travetto/tree/main/module/schema/src/decorator/schema.ts#L14) class. The fields of the class represent the flags that are available to the command.
+[@CliCommand](https://github.com/travetto/travetto/tree/main/module/cli/src/decorators.ts#L15) is a wrapper for [@Schema](https://github.com/travetto/travetto/tree/main/module/schema/src/decorator/schema.ts#L14), and so every class that uses the [@CliCommand](https://github.com/travetto/travetto/tree/main/module/cli/src/decorators.ts#L15) decorator is now a full [@Schema](https://github.com/travetto/travetto/tree/main/module/schema/src/decorator/schema.ts#L14) class. The fields of the class represent the flags that are available to the command.
 
 **Code: Basic Command with Flag**
 ```typescript
@@ -130,7 +130,7 @@ $ trv basic:flag --loud
 HELLO
 ```
 
-The [@CliCommand](https://github.com/travetto/travetto/tree/main/module/cli/src/decorators.ts#L20) supports the following data types for flags:
+The [@CliCommand](https://github.com/travetto/travetto/tree/main/module/cli/src/decorators.ts#L15) supports the following data types for flags:
    *  Boolean values
    *  Number values. The [@Integer](https://github.com/travetto/travetto/tree/main/module/schema/src/decorator/field.ts#L172), [@Float](https://github.com/travetto/travetto/tree/main/module/schema/src/decorator/field.ts#L178), [@Precision](https://github.com/travetto/travetto/tree/main/module/schema/src/decorator/field.ts#L166), [@Min](https://github.com/travetto/travetto/tree/main/module/schema/src/decorator/field.ts#L107) and [@Max](https://github.com/travetto/travetto/tree/main/module/schema/src/decorator/field.ts#L117) decorators help provide additional validation.
    *  String values. [@MinLength](https://github.com/travetto/travetto/tree/main/module/schema/src/decorator/field.ts#L107), [@MaxLength](https://github.com/travetto/travetto/tree/main/module/schema/src/decorator/field.ts#L117), [@Match](https://github.com/travetto/travetto/tree/main/module/schema/src/decorator/field.ts#L99) and [@Enum](https://github.com/travetto/travetto/tree/main/module/schema/src/decorator/field.ts#L78) provide additional constraints
@@ -170,7 +170,7 @@ Options:
 $ trv basic:arg 20
 
 Execution failed:
- * Argument  is bigger than (10)
+ * Argument volume is bigger than (10)
 
 Usage: basic:arg [options] [volume:number]
 
@@ -233,7 +233,7 @@ $ trv basic:arglist 10 5 3 9 8 1
 $ trv basic:arglist 10 5 3 9 20 1
 
 Execution failed:
- * Argument [4] is bigger than (10)
+ * Argument volumes[4] is bigger than (10)
 
 Usage: basic:arglist [options] <volumes...:number>
 
@@ -360,7 +360,7 @@ CuStOm
 ```
 
 ## VSCode Integration
-By default, cli commands do not expose themselves to the VSCode extension, as the majority of them are not intended for that sort of operation.  [RESTful API](https://github.com/travetto/travetto/tree/main/module/rest#readme "Declarative api for RESTful APIs with support for the dependency injection module.") does expose a cli target `run:rest` that will show up, to help run/debug a rest application.  Any command can mark itself as being a run target, and will be eligible for running from within the [VSCode plugin](https://marketplace.visualstudio.com/items?itemName=arcsine.travetto-plugin). This is achieved by setting the `runTarget` field on the [@CliCommand](https://github.com/travetto/travetto/tree/main/module/cli/src/decorators.ts#L20) decorator.  This means the target will be visible within the editor tooling.
+By default, cli commands do not expose themselves to the VSCode extension, as the majority of them are not intended for that sort of operation.  [RESTful API](https://github.com/travetto/travetto/tree/main/module/rest#readme "Declarative api for RESTful APIs with support for the dependency injection module.") does expose a cli target `run:rest` that will show up, to help run/debug a rest application.  Any command can mark itself as being a run target, and will be eligible for running from within the [VSCode plugin](https://marketplace.visualstudio.com/items?itemName=arcsine.travetto-plugin). This is achieved by setting the `runTarget` field on the [@CliCommand](https://github.com/travetto/travetto/tree/main/module/cli/src/decorators.ts#L15) decorator.  This means the target will be visible within the editor tooling.
 
 **Code: Simple Run Target**
 ```typescript
@@ -390,7 +390,7 @@ export interface CliCommandShape {
   /**
    * Setup environment before command runs
    */
-  envInit?(): OrProm<GlobalEnvConfig>;
+  envInit?(): OrProm<EnvInit>;
   /**
    * Extra help
    */
@@ -421,21 +421,20 @@ If the goal is to run a more complex application, which may include depending on
 ```typescript
 import { DependencyRegistry } from '@travetto/di';
 import { CliCommand, CliUtil } from '@travetto/cli';
-import { GlobalEnv } from '@travetto/base';
 
 import { ServerHandle } from '../src/types';
 
 /**
  * Run a rest server as an application
  */
-@CliCommand({ runTarget: true, fields: ['module', 'env'] })
+@CliCommand({ runTarget: true, addModule: true, addEnv: true })
 export class RunRestCommand {
 
   /** IPC debug is enabled */
-  debugIpc = true;
+  debugIpc?: boolean;
 
   /** Should the server be able to run with restart*/
-  canRestart = GlobalEnv.devMode;
+  canRestart?: boolean;
 
   /** Port to run on */
   port?: number;
@@ -455,7 +454,7 @@ export class RunRestCommand {
 }
 ```
 
-As noted in the example above, `fields` is specified in this execution, with support for `module`, and `env`. These env flag is directly tied to the [GlobalEnv](https://github.com/travetto/travetto/tree/main/module/base/src/global-env.ts#L17) flags defined in the [Base](https://github.com/travetto/travetto/tree/main/module/base#readme "Environment config and common utilities for travetto applications.") module. 
+As noted in the example above, `fields` is specified in this execution, with support for `module`, and `env`. These env flag is directly tied to the [GlobalEnv](https://github.com/travetto/travetto/tree/main/module/base/src/global-env.ts#L9) flags defined in the [Base](https://github.com/travetto/travetto/tree/main/module/base#readme "Environment config and common utilities for travetto applications.") module. 
 
 The `module` field is slightly more complex, but is geared towards supporting commands within a monorepo context.  This flag ensures that a module is specified if running from the root of the monorepo, and that the module provided is real, and can run the desired command.  When running from an explicit module folder in the monorepo, the module flag is ignored.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@travetto/cli",
-  "version": "3.4.0-rc.8",
+  "version": "3.4.0",
   "description": "CLI infrastructure for Travetto framework",
   "keywords": [
     "cli",
@@ -29,8 +29,8 @@
     "directory": "module/cli"
   },
   "dependencies": {
-    "@travetto/schema": "^3.4.0-rc.6",
-    "@travetto/terminal": "^3.4.0-rc.0"
+    "@travetto/schema": "^3.4.0",
+    "@travetto/terminal": "^3.4.0"
   },
   "travetto": {
     "displayName": "Command Line Interface"

package/src/decorators.ts

@@ -1,47 +1,34 @@
-import { Class, ClassInstance, ConcreteClass, ConsoleManager, GlobalEnv, defineGlobalEnv } from '@travetto/base';
+import { Class, ClassInstance, ConsoleManager, GlobalEnv, defineEnv } from '@travetto/base';
 import { RootIndex } from '@travetto/manifest';
 import { SchemaRegistry } from '@travetto/schema';
 
-import { CliCommandShape } from './types';
+import { CliCommandShape, CliCommandShapeFields } from './types';
 import { CliCommandRegistry, CliCommandConfigOptions } from './registry';
 import { CliModuleUtil } from './module';
 import { CliUtil } from './util';
 
-type ExtraFields = 'module' | 'env';
-
-const getName = (source: string): string => (source.match(/cli[.](.*)[.]tsx?$/)?.[1] ?? source).replaceAll('_', ':');
-const getMod = (cls: Class): string => RootIndex.getModuleFromSource(RootIndex.getFunctionMetadata(cls)!.source)!.name;
-
 /**
  * Decorator to register a CLI command
  * @augments `@travetto/schema:Schema`
  * @augments `@travetto/cli:CliCommand`
  */
-export function CliCommand({ fields, ...cfg }: { fields?: ExtraFields[] } & CliCommandConfigOptions = {}) {
+export function CliCommand(cfg: CliCommandConfigOptions = {}) {
   return function <T extends CliCommandShape>(target: Class<T>): void {
     const meta = RootIndex.getFunctionMetadata(target);
     if (!meta || meta.abstract) {
       return;
     }
 
-    const name = getName(meta.source);
-    const addEnv = fields?.includes('env');
-    const addModule = fields?.includes('module');
-
-    CliCommandRegistry.registerClass({
-      module: getMod(target),
-      name,
-      // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
-      cls: target as ConcreteClass<T>,
-      ...cfg,
-      preMain: (cmd: CliCommandShape & { env?: string, module?: string }) => {
-        if (addEnv) {
-          defineGlobalEnv({ envName: cmd.env });
+    const addModule = cfg.addModule === true || cfg.fields?.includes('module');
+    const runtimeModule = cfg.runtimeModule ?? (cfg.addModule ? 'current' : undefined);
+    const addEnv = cfg.addEnv ?? cfg.fields?.includes('env');
+    const { commandModule } = CliCommandRegistry.registerClass(target, {
+      hidden: cfg.hidden,
+      preMain: async (cmd) => {
+        if (addEnv && 'env' in cmd && typeof cmd.env === 'string') {
+          defineEnv({ envName: cmd.env });
           ConsoleManager.setDebug(GlobalEnv.debug, GlobalEnv.devMode);
         }
-        if (addModule && cmd.module && cmd.module !== RootIndex.mainModuleName) { // Mono-repo support
-          RootIndex.reinitForModule(cmd.module); // Reinit with specified module
-        }
       }
     });
 
@@ -61,12 +48,26 @@ export function CliCommand({ fields, ...cfg }: { fields?: ExtraFields[] } & CliC
         description: 'Module to run for',
         required: { active: CliUtil.monoRoot }
       });
+    }
 
-      // Register validator for module
+    if (runtimeModule) { // Validate module
       (pendingCls.validators ??= []).push(async item => {
         // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
-        const res = await CliModuleUtil.validateCommandModule(getMod(target), item as { module?: string });
-        return res ? { ...res, kind: 'custom', path: '.' } : res;
+        const { module: mod } = item as CliCommandShapeFields;
+        const runModule = (runtimeModule === 'command' ? commandModule : mod) || RootIndex.mainModuleName;
+
+        // If we need to run as a specific module
+        if (runModule !== RootIndex.mainModuleName) {
+          try {
+            RootIndex.reinitForModule(runModule);
+          } catch (err) {
+            return { source: 'flag', message: `${runModule} is an unknown module`, kind: 'custom', path: '.' };
+          }
+        }
+
+        if (!(await CliModuleUtil.moduleHasDependency(runModule, commandModule))) {
+          return { source: 'flag', message: `${runModule} does not have ${commandModule} as a dependency`, kind: 'custom', path: '.' };
+        }
       });
     }
   };

package/src/execute.ts

@@ -1,5 +1,5 @@
 import { GlobalTerminal } from '@travetto/terminal';
-import { ConsoleManager, defineGlobalEnv, ShutdownManager, GlobalEnv } from '@travetto/base';
+import { ConsoleManager, defineEnv, ShutdownManager, GlobalEnv } from '@travetto/base';
 
 import { HelpUtil } from './help';
 import { CliCommandShape } from './types';
@@ -14,7 +14,7 @@ export class ExecutionManager {
 
   static async #envInit(cmd: CliCommandShape): Promise<void> {
     if (cmd.envInit) {
-      defineGlobalEnv(await cmd.envInit());
+      defineEnv(await cmd.envInit());
       ConsoleManager.setDebug(GlobalEnv.debug, GlobalEnv.devMode);
     }
   }

package/src/module.ts

@@ -1,13 +1,9 @@
 import { IndexedModule, RootIndex } from '@travetto/manifest';
 
 import { CliScmUtil } from './scm';
-import { CliValidationError } from './types';
-import { CliUtil } from './util';
 
 type ModuleGraphEntry = { children: Set<string>, name: string, active: Set<string>, parents?: string[] };
 
-const modError = (message: string): CliValidationError => ({ source: 'flag', message: `module: ${message}` });
-
 /**
  * Simple utilities for understanding modules for CLI use cases
  */
@@ -90,23 +86,14 @@ export class CliModuleUtil {
   }
 
   /**
-   * Validate the module status for a given cli command
+   * Determine if module has a given dependency
    */
-  static async validateCommandModule(selfMod: string, { module: mod }: { module?: string }): Promise<CliValidationError | undefined> {
-    if (CliUtil.monoRoot && mod) {
-      if (!RootIndex.getModule(mod)) {
-        return modError(`${mod} is an unknown module`);
-      } else {
-        if (mod !== selfMod) {
-          RootIndex.reinitForModule(mod);
-        }
-
-        const mods = await this.findModules('all');
-        const graph = this.getDependencyGraph(mods);
-        if (selfMod !== mod && !graph[mod].includes(selfMod)) {
-          return modError(`${mod} does not have ${selfMod} as a dependency`);
-        }
-      }
+  static async moduleHasDependency(modName: string, depModName: string): Promise<boolean> {
+    if (modName === depModName) {
+      return true;
     }
+    const mods = await this.findModules('all');
+    const graph = this.getDependencyGraph(mods);
+    return graph[modName].includes(depModName);
   }
 }

package/src/registry.ts

@@ -5,18 +5,25 @@ import { CliCommandShape } from './types';
 import { CliUnknownCommandError } from './error';
 
 export type CliCommandConfigOptions = {
-  runTarget?: boolean;
   hidden?: boolean;
+  runTarget?: boolean;
+  addModule?: boolean;
+  addEnv?: boolean;
+  runtimeModule?: 'current' | 'command';
+  /** @deprecated */
+  fields?: ('module' | 'env')[];
 };
 
-export type CliCommandConfig = CliCommandConfigOptions & {
+export type CliCommandConfig = {
   name: string;
-  module: string;
+  commandModule: string;
   cls: ConcreteClass<CliCommandShape>;
+  hidden?: boolean;
   preMain?: (cmd: CliCommandShape) => void | Promise<void>;
 };
 
-const CLI_REGEX = /\/cli[.]([^.]+)[.][^.]+?$/;
+const CLI_FILE_REGEX = /\/cli[.](?<name>.*)[.]tsx?$/;
+const getName = (s: string): string => (s.match(CLI_FILE_REGEX)?.groups?.name ?? s).replaceAll('_', ':');
 
 class $CliCommandRegistry {
   #commands = new Map<Class, CliCommandConfig>();
@@ -40,9 +47,9 @@ class $CliCommandRegistry {
       for (const e of RootIndex.find({
         module: m => GlobalEnv.devMode || m.prod,
         folder: f => f === 'support',
-        file: f => f.role === 'std' && CLI_REGEX.test(f.sourceFile)
+        file: f => f.role === 'std' && CLI_FILE_REGEX.test(f.sourceFile)
       })) {
-        all.set(e.outputFile.match(CLI_REGEX)![1].replace(/_/g, ':'), e.import);
+        all.set(getName(e.sourceFile), e.import);
       }
       this.#fileMapping = all;
     }
@@ -52,8 +59,16 @@ class $CliCommandRegistry {
   /**
    * Registers a cli command
    */
-  registerClass(cfg: CliCommandConfig): void {
-    this.#commands.set(cfg.cls, cfg);
+  registerClass(cls: Class, cfg: Partial<CliCommandConfig>): CliCommandConfig {
+    const source = RootIndex.getFunctionMetadata(cls)!.source;
+    this.#commands.set(cls, {
+      // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+      cls: cls as ConcreteClass,
+      name: getName(source),
+      commandModule: RootIndex.getModuleFromSource(source)!.name,
+      ...cfg,
+    });
+    return this.#commands.get(cls)!;
   }
 
   /**
@@ -68,7 +83,7 @@ class $CliCommandRegistry {
    */
   getName(cmd: CliCommandShape, withModule = false): string | undefined {
     const cfg = this.getConfig(cmd);
-    const prefix = withModule ? `${cfg.module}:` : '';
+    const prefix = withModule ? `${cfg.commandModule}:` : '';
     return `${prefix}${cfg.name}`;
   }
 

package/src/schema.ts

@@ -237,9 +237,11 @@ export class CliCommandSchemaUtil {
     // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
     const cls = cmd.constructor as Class<CliCommandShape>;
 
+    const paramNames = SchemaRegistry.getMethodSchema(cls, 'main').map(x => x.name);
+
     const validators = [
       (): Promise<void> => SchemaValidator.validate(cls, cmd).then(() => { }),
-      (): Promise<void> => SchemaValidator.validateMethod(cls, 'main', args),
+      (): Promise<void> => SchemaValidator.validateMethod(cls, 'main', args, paramNames),
       async (): Promise<void> => {
         const res = await cmd.validate?.(...args);
         if (res) {

package/src/types.ts

@@ -1,4 +1,4 @@
-import { Closeable, GlobalEnvConfig } from '@travetto/base';
+import { Closeable, EnvInit } from '@travetto/base';
 
 type OrProm<T> = T | Promise<T>;
 
@@ -29,7 +29,7 @@ export interface CliCommandShape {
   /**
    * Setup environment before command runs
    */
-  envInit?(): OrProm<GlobalEnvConfig>;
+  envInit?(): OrProm<EnvInit>;
   /**
    * Extra help
    */
@@ -52,6 +52,28 @@ export interface CliCommandShape {
   validate?(...unknownArgs: unknown[]): OrProm<CliValidationError | CliValidationError[] | undefined>;
 }
 
+/**
+ * Command shape common fields
+ */
+export type CliCommandShapeFields = {
+  /**
+   * Environment to run in
+   */
+  env?: string;
+  /**
+   * Should the cli invocation trigger a debug session, via IPC
+   */
+  debugIpc?: boolean;
+  /**
+   * Should the invocation run with auto-restart
+   */
+  canRestart?: boolean;
+  /**
+   * The module to run the command from
+   */
+  module?: string;
+};
+
 /**
  * CLI Command argument/flag shape
  */
@@ -74,7 +96,7 @@ export type CliCommandInput = {
 export type CliCommandSchema = {
   name: string;
   title: string;
-  module: string;
+  commandModule: string;
   runTarget?: boolean;
   description?: string;
   args: CliCommandInput[];

package/src/util.ts

@@ -1,7 +1,7 @@
-import { CompilerClient, Env, ExecUtil, GlobalEnv } from '@travetto/base';
+import { Env, ExecUtil, GlobalEnv } from '@travetto/base';
 import { RootIndex } from '@travetto/manifest';
 
-import { CliCommandShape } from './types';
+import { CliCommandShape, CliCommandShapeFields } from './types';
 import { CliCommandRegistry } from './registry';
 
 export class CliUtil {
@@ -23,7 +23,7 @@ export class CliUtil {
   /**
    * Run a command as restartable, linking into self
    */
-  static runWithRestart<T extends CliCommandShape & { canRestart?: boolean }>(cmd: T): Promise<unknown> | undefined {
+  static runWithRestart<T extends CliCommandShapeFields & CliCommandShape>(cmd: T): Promise<unknown> | undefined {
     const canRestart = cmd.canRestart ??= GlobalEnv.devMode;
 
     if (canRestart === false || Env.isFalse('TRV_CAN_RESTART')) {
@@ -40,50 +40,48 @@ export class CliUtil {
    * Dispatch IPC payload
    */
   static async triggerIpc<T extends CliCommandShape>(action: 'run', cmd: T): Promise<boolean> {
-    if (!process.env.TRV_CLI_IPC) {
+    const ipcUrl = process.env.TRV_CLI_IPC;
+
+    if (!ipcUrl) {
       return false;
     }
 
-    const client = new CompilerClient({});
-
-    const info = await client.getInfo(true);
+    const info = await fetch(ipcUrl).catch(() => ({ ok: false }));
 
-    if (!info) { // Server not running
+    if (!info.ok) { // Server not running
       return false;
     }
 
-    const defaultEnvKeys = new Set(Object.keys(info.env ?? {}));
-    defaultEnvKeys.add('PS1').add('INIT_CWD').add('COLOR').add('LANGUAGE').add('PROFILEHOME').add('_');
-
-    const env = Object.fromEntries(
-      Object.entries(process.env).filter(([k]) =>
-        !defaultEnvKeys.has(k) && !/^(npm_|GTK|GDK|TRV|NODE|GIT|TERM_)/.test(k) && !/VSCODE/.test(k)
-      )
-    );
-
     const cfg = CliCommandRegistry.getConfig(cmd);
     const req = {
       type: `@travetto/cli:${action}`,
-      ipc: process.env.TRV_CLI_IPC,
       data: {
         name: cfg.name,
-        commandModule: cfg.module,
+        commandModule: cfg.commandModule,
         module: RootIndex.manifest.mainModule,
         args: process.argv.slice(3),
-        env
       }
     };
 
     console.log('Triggering IPC request', req);
 
-    await client.sendEvent('custom', req);
-    return true;
+    const defaultEnvKeys = new Set(['PS1', 'INIT_CWD', 'COLOR', 'LANGUAGE', 'PROFILEHOME', '_']);
+    const env = Object.fromEntries(
+      Object.entries(process.env).filter(([k]) =>
+        !defaultEnvKeys.has(k) && !/^(npm_|GTK|GDK|TRV|NODE|GIT|TERM_)/.test(k) && !/VSCODE/.test(k)
+      )
+    );
+
+    Object.assign(req.data, { env });
+
+    const sent = await fetch(ipcUrl, { method: 'POST', body: JSON.stringify(req) });
+    return sent.ok;
   }
 
   /**
    * Debug if IPC available
    */
-  static async debugIfIpc<T extends CliCommandShape & { debugIpc?: boolean }>(cmd: T): Promise<boolean> {
+  static async debugIfIpc<T extends CliCommandShapeFields & CliCommandShape>(cmd: T): Promise<boolean> {
     const canDebug = cmd.debugIpc ??= GlobalEnv.devMode;
     return canDebug !== false && this.triggerIpc('run', cmd);
   }