@travetto/cli 8.0.0-alpha.7 → 8.0.0-alpha.9

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/registry/decorator.ts#L27) decorator
+   *  The class must use the [@CliCommand](https://github.com/travetto/travetto/tree/main/module/cli/src/registry/decorator.ts#L20) decorator
 
 **Code: Basic Command**
 ```typescript
@@ -94,7 +94,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/registry/decorator.ts#L27) is a wrapper for [@Schema](https://github.com/travetto/travetto/tree/main/module/schema/src/decorator/schema.ts#L19), and so every class that uses the [@CliCommand](https://github.com/travetto/travetto/tree/main/module/cli/src/registry/decorator.ts#L27) decorator is now a full [@Schema](https://github.com/travetto/travetto/tree/main/module/schema/src/decorator/schema.ts#L19) 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/registry/decorator.ts#L20) is a wrapper for [@Schema](https://github.com/travetto/travetto/tree/main/module/schema/src/decorator/schema.ts#L19), and so every class that uses the [@CliCommand](https://github.com/travetto/travetto/tree/main/module/cli/src/registry/decorator.ts#L20) decorator is now a full [@Schema](https://github.com/travetto/travetto/tree/main/module/schema/src/decorator/schema.ts#L19) class. The fields of the class represent the flags that are available to the command.
 
 **Code: Basic Command with Flag**
 ```typescript
@@ -131,7 +131,7 @@ $ trv basic:flag --loud
 HELLO
 ```
 
-The [@CliCommand](https://github.com/travetto/travetto/tree/main/module/cli/src/registry/decorator.ts#L27) supports the following data types for flags:
+The [@CliCommand](https://github.com/travetto/travetto/tree/main/module/cli/src/registry/decorator.ts#L20) supports the following data types for flags:
    *  Boolean values
    *  Number values. The [@Integer](https://github.com/travetto/travetto/tree/main/module/schema/src/decorator/input.ts#L172), [@Float](https://github.com/travetto/travetto/tree/main/module/schema/src/decorator/input.ts#L179), [@Precision](https://github.com/travetto/travetto/tree/main/module/schema/src/decorator/input.ts#L165), [@Min](https://github.com/travetto/travetto/tree/main/module/schema/src/decorator/input.ts#L99) and [@Max](https://github.com/travetto/travetto/tree/main/module/schema/src/decorator/input.ts#L110) decorators help provide additional validation.
    *  String values. [@MinLength](https://github.com/travetto/travetto/tree/main/module/schema/src/decorator/input.ts#L99), [@MaxLength](https://github.com/travetto/travetto/tree/main/module/schema/src/decorator/input.ts#L110), [@Match](https://github.com/travetto/travetto/tree/main/module/schema/src/decorator/input.ts#L90) and [@Enum](https://github.com/travetto/travetto/tree/main/module/schema/src/decorator/input.ts#L64) provide additional constraints
@@ -390,7 +390,7 @@ npx trv call:db --host localhost --port 3306 --username app --password <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.  [Web API](https://github.com/travetto/travetto/tree/main/module/web#readme "Declarative support for creating Web Applications") does expose a cli target `web:http` that will show up, to help run/debug a web 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/registry/decorator.ts#L27) 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.  [Web API](https://github.com/travetto/travetto/tree/main/module/web#readme "Declarative support for creating Web Applications") does expose a cli target `web:http` that will show up, to help run/debug a web 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/registry/decorator.ts#L20) decorator.  This means the target will be visible within the editor tooling.
 
 **Code: Simple Run Target**
 ```typescript
@@ -460,7 +460,7 @@ export class WebHttpCommand implements CliCommandShape {
   profile: string[];
 
   @CliRestartOnChangeFlag()
-  restartOnChange: boolean = true;
+  restartOnChange: boolean = Runtime.localDevelopment;
 
   @CliDebugIpcFlag()
   debugIpc?: boolean;

package/bin/trv.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 // @ts-check
+import '@travetto/runtime/support/patch.js';
 import '@travetto/compiler/bin/hook.js';
 const { invoke } = await import('@travetto/compiler/support/invoke.ts');
 await invoke('exec', ['@travetto/cli/support/entry.trv.ts', ...process.argv.slice(2)]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@travetto/cli",
-  "version": "8.0.0-alpha.7",
+  "version": "8.0.0-alpha.9",
   "type": "module",
   "description": "CLI infrastructure for Travetto framework",
   "keywords": [
@@ -29,8 +29,8 @@
     "directory": "module/cli"
   },
   "dependencies": {
-    "@travetto/schema": "^8.0.0-alpha.4",
-    "@travetto/terminal": "^8.0.0-alpha.4"
+    "@travetto/schema": "^8.0.0-alpha.5",
+    "@travetto/terminal": "^8.0.0-alpha.5"
   },
   "travetto": {
     "displayName": "Command Line Interface",

package/src/execute.ts

@@ -1,4 +1,4 @@
-import { ConsoleManager, Runtime, ShutdownManager, Util } from '@travetto/runtime';
+import { ConsoleManager, getClass, Runtime, ShutdownManager, Util } from '@travetto/runtime';
 
 import { HelpUtil } from './help.ts';
 import { CliCommandRegistryIndex } from './registry/registry-index.ts';
@@ -11,20 +11,32 @@ import type { CliCommandShape } from './types.ts';
  */
 export class ExecutionManager {
 
-  /**
-   * Execute the command line
-   * @param args
-   */
-  static async run(argv: string[]): Promise<void> {
+  /** Command Execution */
+  static async execute(instance: CliCommandShape, args: unknown[]): Promise<void> {
+    const config = CliCommandRegistryIndex.get(getClass(instance));
+
+    for (const item of config.preMain) {
+      await item.handler(instance);
+    }
+
+    // Wait 50ms to allow stdout to flush on shutdown
+    ShutdownManager.signal.addEventListener('abort', () => Util.blockingTimeout(50));
+    ConsoleManager.debug(Runtime.debug);
+    await instance.main(...args);
+  }
+
+  /** Extract configuration and show help as needed */
+  static async getExecutionCommand(argv: string[]): Promise<(() => Promise<void>) | undefined> {
     let command: CliCommandShape | undefined;
 
     const { cmd, args, help } = CliParseUtil.getArgs(argv);
     if (!cmd) {
-      return console.info!(await HelpUtil.renderAllHelp());
+      console.info!(await HelpUtil.renderAllHelp());
+      return;
     }
 
     try {
-      const [{ instance, schema, config }] = await CliCommandRegistryIndex.load([cmd]);
+      const [{ instance, schema }] = await CliCommandRegistryIndex.load([cmd]);
       command = instance;
       const fullArgs = await CliParseUtil.expandArgs(schema, args);
 
@@ -35,22 +47,28 @@ export class ExecutionManager {
       await instance.finalize?.(help);
 
       if (help) {
-        return console.log!(await HelpUtil.renderCommandHelp(instance));
+        console.log!(await HelpUtil.renderCommandHelp(instance));
+        return;
       }
 
       await CliCommandSchemaUtil.validate(command, boundArgs);
 
-      // Wait 50ms to allow stdout to flush on shutdown
-      ShutdownManager.signal.addEventListener('abort', () => Util.blockingTimeout(50));
-
-      for (const preMain of config.preMain ?? []) {
-        await preMain(instance);
-      }
-
-      ConsoleManager.debug(Runtime.debug);
-      await instance.main(...boundArgs);
+      return this.execute.bind(this, instance, boundArgs);
     } catch (error) {
       await HelpUtil.renderError(error, cmd, command);
+    }
+  }
+
+  /**
+   * Execute the command line
+   * @param args
+   */
+  static async run(argv: string[]): Promise<void> {
+    try {
+      const execute = await this.getExecutionCommand(argv);
+      await execute?.();
+    } catch (error) {
+      console.error!(error);
     } finally {
       await ShutdownManager.shutdown();
     }

package/src/help.ts

@@ -175,7 +175,7 @@ ${{ identifier: install }}
     process.exitCode ??= 1;
     if (error instanceof ValidationResultError) {
       console.error!(this.renderValidationError(error));
-    } else if (Error.isError(error)) {
+    } else if (error instanceof Error) {
       console.error!(cliTpl`${{ failure: error.stack }}\n`);
     }
     if (command) {

package/src/registry/decorator.ts

@@ -10,13 +10,6 @@ import { CliUtil } from '../util.ts';
 type CliCommandConfigOptions = { runTarget?: boolean };
 type CliFlagOptions = { full?: string, short?: string, envVars?: string[] };
 
-function runBeforeMain<T>(cls: Class, handler: (item: T) => (unknown | Promise<unknown>), runTarget?: boolean): void {
-  CliCommandRegistryIndex.getForRegister(cls).register({
-    runTarget,
-    preMain: [async (cmd): Promise<void> => { await handler(castTo(cmd)); }]
-  });
-}
-
 /**
  * Decorator to register a CLI command
  *
@@ -72,9 +65,7 @@ export function CliProfilesFlag(config: CliFlagOptions = {}) {
       description: 'Application profiles'
     });
 
-    runBeforeMain(cls, (cmd: typeof instance) =>
-      Env.TRV_PROFILES.set([...cmd[property] ?? [], ...(Env.TRV_PROFILES.list ?? [])])
-    );
+    CliCommandRegistryIndex.registerPreMain<typeof instance>(cls, 1, cmd => Env.TRV_PROFILES.add(...cmd[property] ?? []));
   };
 };
 
@@ -103,12 +94,8 @@ export function CliModuleFlag(config: CliFlagOptions & { scope?: 'current' | 'co
         const runModule = (config.scope === 'command' ? commandModule : providedModule) || Runtime.main.name;
 
         // If we need to run as a specific module
-        if (runModule !== Runtime.main.name) {
-          try {
-            RuntimeIndex.reinitForModule(runModule);
-          } catch {
-            return { source: 'flag', message: `${runModule} is an unknown module`, kind: 'custom', path: property };
-          }
+        if (runModule !== Runtime.main.name && RuntimeIndex.getModule(runModule) === undefined) {
+          return { source: 'flag', message: `${runModule} is an unknown module`, kind: 'custom', path: property };
         }
 
         if (!(await CliModuleUtil.moduleHasDependency(runModule, commandModule))) {
@@ -116,6 +103,15 @@ export function CliModuleFlag(config: CliFlagOptions & { scope?: 'current' | 'co
         }
       }],
     });
+
+    CliCommandRegistryIndex.registerPreMain<typeof instance>(cls, 5, cmd => {
+      const typed: (typeof cmd) & { [property]?: string } = castTo(cmd);
+      const providedModule = typed[property];
+      const runModule = (config.scope === 'command' ? commandModule : providedModule) || Runtime.main.name;
+      if (runModule !== Runtime.main.name) {
+        RuntimeIndex.reinitForModule(runModule);
+      }
+    });
   };
 }
 
@@ -127,17 +123,15 @@ export function CliModuleFlag(config: CliFlagOptions & { scope?: 'current' | 'co
 export function CliRestartOnChangeFlag(config: CliFlagOptions = {}) {
   return function <K extends string, T extends Partial<Record<K, boolean>>>(instance: T, property: K): void {
     const cls = getClass(instance);
+    if (Runtime.production) { return; }
+
     SchemaRegistryIndex.getForRegister(cls).registerField(property, {
       ...CliParseUtil.buildAliases(config),
       description: 'Should the invocation automatically restart on source changes'
     });
 
-    runBeforeMain(cls,
-      (cmd: typeof instance) => {
-        if (Runtime.production) { return; }
-        return CliUtil.runWithRestartOnChange(cmd[property]);
-      }, true
-    );
+    CliCommandRegistryIndex.getForRegister(cls).register({ runTarget: true });
+    CliCommandRegistryIndex.registerPreMain<typeof instance>(cls, 20, cmd => CliUtil.runWithRestartOnChange(cmd[property]));
   };
 }
 
@@ -148,19 +142,18 @@ export function CliRestartOnChangeFlag(config: CliFlagOptions = {}) {
  */
 export function CliDebugIpcFlag(config: CliFlagOptions = {}) {
   return function <K extends string, T extends Partial<Record<K, boolean>>>(instance: T, property: K): void {
+    if (Runtime.production) { return; }
+
     const cls = getClass(instance);
     SchemaRegistryIndex.getForRegister(cls).registerField(property, {
       ...CliParseUtil.buildAliases(config, Env.TRV_DEBUG_IPC.key),
       description: 'Should the invocation automatically restart on source changes'
     });
 
-    runBeforeMain(cls,
-      (cmd: typeof instance & CliCommandShape) => {
-        if (Runtime.production) { return; }
-        const cliConfig = CliCommandRegistryIndex.get(cls);
-        return cmd[property] && CliUtil.runWithDebugIpc(cliConfig.name);
-      },
-      true
-    );
+    CliCommandRegistryIndex.getForRegister(cls).register({ runTarget: true });
+    CliCommandRegistryIndex.registerPreMain<typeof instance>(cls, 10, cmd => {
+      const cliConfig = CliCommandRegistryIndex.get(cls);
+      return cmd[property] && CliUtil.runWithDebugIpc(cliConfig.name);
+    });
   };
 }

package/src/registry/registry-adapter.ts

@@ -29,7 +29,7 @@ export class CliCommandRegistryAdapter implements RegistryAdapter<CliCommandConf
     this.#cls = cls;
   }
 
-  finalize(): void {
+  finalize(parent?: CliCommandConfig): void {
     // Add help command
     const schema = SchemaRegistryIndex.getConfig(this.#cls);
 
@@ -75,6 +75,13 @@ export class CliCommandRegistryAdapter implements RegistryAdapter<CliCommandConf
         aliases.push(`--no-${long}`);
       }
     }
+
+    if (parent) {
+      this.#config.preMain = [...this.#config.preMain, ...parent?.preMain ?? []];
+    }
+
+    // Sort
+    this.#config.preMain = this.#config.preMain.toSorted((left, right) => left.priority - right.priority);
   }
 
   get(): CliCommandConfig {

package/src/registry/registry-index.ts

@@ -1,8 +1,8 @@
-import { type Class, getClass, getParentClass, isClass, Runtime, RuntimeIndex } from '@travetto/runtime';
+import { type Any, type Class, getClass, getParentClass, isClass, Runtime, RuntimeIndex } from '@travetto/runtime';
 import { type RegistryAdapter, type RegistryIndex, RegistryIndexStore, Registry } from '@travetto/registry';
 import { type SchemaClassConfig, SchemaRegistryIndex } from '@travetto/schema';
 
-import type { CliCommandConfig, CliCommandShape } from '../types.ts';
+import type { CliCommandConfig, CliCommandShape, PreMainHandler } from '../types.ts';
 import { CliCommandRegistryAdapter } from './registry-adapter.ts';
 
 const CLI_FILE_REGEX = /\/cli[.](?<name>.{0,100}?)([.]tsx?)?$/;
@@ -28,6 +28,10 @@ export class CliCommandRegistryIndex implements RegistryIndex {
     return this.#instance.load(names);
   }
 
+  static registerPreMain<T = Any>(cls: Class, priority: number, handler: PreMainHandler<T>['handler']): void {
+    CliCommandRegistryIndex.getForRegister(cls).register({ preMain: [{ handler, priority }] });
+  }
+
   #fileMapping: Map<string, string>;
   #instanceMapping: Map<string, CliCommandShape> = new Map();
 

package/src/types.ts

@@ -1,4 +1,4 @@
-import type { Class } from '@travetto/runtime';
+import type { Any, Class } from '@travetto/runtime';
 
 type OrProm<T> = T | Promise<T>;
 type ParsedFlag = { type: 'flag', input: string, array?: boolean, fieldName: string, value?: unknown };
@@ -32,7 +32,7 @@ export interface CliCommandShape {
   help?(): OrProm<string[]>;
 }
 
-type PreMainHandler = (cmd: CliCommandShape) => (unknown | Promise<unknown>);
+export type PreMainHandler<T extends Any = Any> = { priority: number, handler: (cmd: T) => Any };
 
 /**
  * CLI Command schema shape
@@ -41,5 +41,5 @@ export interface CliCommandConfig {
   cls: Class<CliCommandShape>;
   name: string;
   runTarget?: boolean;
-  preMain?: PreMainHandler[];
+  preMain: PreMainHandler[];
 }

package/src/util.ts

@@ -2,11 +2,12 @@ import { spawn, type ChildProcess } from 'node:child_process';
 
 import { RuntimeError, JSONUtil, Env, ExecUtil, Runtime, ShutdownManager, Util, WatchUtil } from '@travetto/runtime';
 
-const IPC_ALLOWED_ENV = new Set(['NODE_OPTIONS']);
-const IPC_INVALID_ENV = new Set(['PS1', 'INIT_CWD', 'COLOR', 'LANGUAGE', 'PROFILEHOME', '_']);
-const validEnv = (key: string): boolean => IPC_ALLOWED_ENV.has(key) || (
-  !IPC_INVALID_ENV.has(key) && !/^(npm_|GTK|GDK|TRV|NODE|GIT|TERM_)/.test(key) && !/VSCODE/.test(key)
-);
+const IPC_VALID_ENV = new Set(['NODE_OPTIONS', 'PATH', Env.DEBUG.key, Env.NODE_ENV.key]);
+const IPC_INVALID_ENV = new Set([
+  Env.TRV_CLI_IPC, Env.TRV_DEBUG_IPC, Env.TRV_DEBUG_BREAK, Env.TRV_MANIFEST, Env.TRV_MODULE, Env.TRV_RESTART_TARGET
+].map(item => item.key));
+const validEnv = ([key]: [key: string, value: unknown]): boolean =>
+  IPC_VALID_ENV.has(key) || (key.startsWith('TRV_') && !IPC_INVALID_ENV.has(key));
 
 export class CliUtil {
   /**
@@ -14,8 +15,7 @@ export class CliUtil {
    */
   static getSimpleModuleName(placeholder: string, module?: string): string {
     const simple = (module ?? Runtime.main.name).replace(/[\/]/, '_').replace(/@/, '');
-    const targetModule = !simple || (!module && Runtime.monoRoot) ? '<module>' : simple;
-    return placeholder.replace('<module>', targetModule);
+    return simple ? placeholder.replace('<module>', simple) : placeholder;
   }
 
   /**
@@ -37,7 +37,7 @@ export class CliUtil {
 
     process
       .on('SIGINT', () => ShutdownManager.shutdownChild(child!, { mode: 'exit' }))
-      .on('message', msg => child?.send?.(msg!));
+      .on('message', message => child?.send?.(message!));
 
     const env = { ...process.env, ...Env.TRV_RESTART_TARGET.export(true) };
 
@@ -78,32 +78,32 @@ export class CliUtil {
       return; // Server not running, run normal
     }
 
-    const env: Record<string, string> = {};
     const request = {
       type: '@travetto/cli:run',
       data: {
         name,
-        env,
+        env: Object.fromEntries(Object.entries(process.env).filter(validEnv)),
         cwd: process.cwd(),
         args: process.argv.slice(3),
       }
     };
-    console.log('Triggering IPC request', request);
 
-    Object.entries(process.env).forEach(([key, value]) => validEnv(key) && (env[key] = value!));
+    console.log('Triggering IPC request', request);
     const sent = await doFetch({ method: 'POST', body: JSONUtil.toUTF8(request) });
 
     if (!sent.ok) {
       throw new RuntimeError(`IPC Request failed: ${sent.status} ${await sent.text()}`);
     }
+
+    await ShutdownManager.shutdown({ mode: 'exit' });
   }
 
   /**
    * Write data to channel and ensure its flushed before continuing
    */
   static async writeAndEnsureComplete(data: unknown, channel: 'stdout' | 'stderr' = 'stdout'): Promise<void> {
-    return await new Promise(resolve => process[channel].write(typeof data === 'string' ? data :
-      JSONUtil.toUTF8Pretty(data), () => resolve()));
+    await new Promise<unknown>(resolve => process[channel].write(typeof data === 'string' ? data :
+      JSONUtil.toUTF8Pretty(data), resolve));
   }
 
   /**

package/support/cli.service.ts

@@ -45,15 +45,15 @@ export class CliServiceCommand implements CliCommandShape {
     const jobs = all.map(async (descriptor, i) => {
       const identifier = descriptor.name.padEnd(maxName);
       const type = `${descriptor.version}`.padStart(maxVersion - 3).padEnd(maxVersion);
-      let msg: string;
+      let message: string;
       for await (const [valueType, value] of new ServiceRunner(descriptor).action(action)) {
         const details = { [valueType === 'message' ? 'subtitle' : valueType]: value };
-        queue.add({ idx: i, text: msg = cliTpl`${{ identifier }} ${{ type }} ${details}` });
+        queue.add({ idx: i, text: message = cliTpl`${{ identifier }} ${{ type }} ${details}` });
         if (valueType === 'failure') {
-          failureMessages.push(msg);
+          failureMessages.push(message);
         }
       }
-      queue.add({ idx: i, done: true, text: msg! });
+      queue.add({ idx: i, done: true, text: message! });
     });
 
     Promise.all(jobs).then(() => Util.queueMacroTask()).then(() => queue.close());

package/support/entry.trv.ts

@@ -1,4 +1,4 @@
 // @trv-no-transform
-import '@travetto/runtime/support/polyfill.js';
+import '@travetto/runtime/support/patch.js';
 import { ExecutionManager } from '@travetto/cli';
 ExecutionManager.run(process.argv);