@travetto/cli 8.0.0-alpha.2 → 8.0.0-alpha.20

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
@@ -75,12 +75,12 @@ export class BasicCommand {
 
 **Terminal: Basic Command Help**
 ```bash
-$ trv basic -h
+$ trv basic --help
 
 Usage: basic [options]
 
 Options:
-  -h, --help  display help for command
+  --help  display help for command
 ```
 
 ## Command Naming
@@ -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
@@ -113,13 +113,13 @@ export class BasicCommand {
 
 **Terminal: Basic Command with Flag Help**
 ```bash
-$ trv basic:flag -h
+$ trv basic:flag --help
 
 Usage: basic:flag [options]
 
 Options:
   -l, --loud
-  -h, --help  display help for command
+  --help      display help for command
 ```
 
 As you can see the command now has the support of a basic boolean flag to determine if the response should be loud or not.  The default value here is undefined/false, and so is an opt-in experience.
@@ -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
@@ -158,12 +158,12 @@ export class BasicCommand {
 
 **Terminal: Basic Command**
 ```bash
-$ trv basic:arg -h
+$ trv basic:arg --help
 
 Usage: basic:arg [options] [volume:number]
 
 Options:
-  -h, --help  display help for command
+  --help  display help for command
 ```
 
 **Terminal: Basic Command with Invalid Loud Arg**
@@ -176,7 +176,7 @@ Execution failed:
 Usage: basic:arg [options] [volume:number]
 
 Options:
-  -h, --help  display help for command
+  --help  display help for command
 ```
 
 **Terminal: Basic Command with Loud Arg > 7**
@@ -213,13 +213,13 @@ export class BasicCommand {
 
 **Terminal: Basic Command**
 ```bash
-$ trv basic:arg-list -h
+$ trv basic:arg-list --help
 
 Usage: basic:arg-list [options] <volumes...:number>
 
 Options:
   -r, --reverse
-  -h, --help     display help for command
+  --help         display help for command
 ```
 
 **Terminal: Basic Arg List**
@@ -240,7 +240,7 @@ Usage: basic:arg-list [options] <volumes...:number>
 
 Options:
   -r, --reverse
-  -h, --help     display help for command
+  --help         display help for command
 ```
 
 **Terminal: Basic Arg List with Reverse**
@@ -279,13 +279,13 @@ export class CustomCommand {
 
 **Terminal: Custom Command Help**
 ```bash
-$ trv custom:arg -h
+$ trv custom:arg --help
 
 Usage: custom:arg [options] [volume:number]
 
 Options:
   -m, --message <string>  The message to send back to the user (default: "hello")
-  -h, --help              display help for command
+  --help                  display help for command
 ```
 
 **Terminal: Custom Command Help with overridden Text**
@@ -330,13 +330,13 @@ export class CustomCommand {
 
 **Terminal: Custom Command Help**
 ```bash
-$ trv custom:env-arg -h
+$ trv custom:env-arg --help
 
 Usage: custom:env-arg [options] [volume:number]
 
 Options:
   -t, --text <string>  The message to send back to the user (default: "hello")
-  -h, --help           display help for command
+  --help               display help for command
 ```
 
 **Terminal: Custom Command Help with default Text**
@@ -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;
@@ -542,7 +542,7 @@ A simple example of the validation can be found in the `doc` command:
 ```typescript
 @Validator(async (cmd) => {
   const docFile = path.resolve(cmd.input);
-  if (!(await fs.stat(docFile).catch(() => false))) {
+  if (!(await fs.stat(docFile, { throwIfNoEntry: false }))) {
     return { message: `input: ${cmd.input} does not exist`, path: 'input', source: 'flag', kind: 'invalid' };
   }
 })
@@ -559,18 +559,18 @@ Usage: service [options] <action:restart|start|status|stop> [services...:string]
 
 Options:
   -q, --quiet   (default: false)
-  -h, --help   display help for command
+  --help       display help for command
 
 Available Services
 --------------------
  * dynamodb@3.3.0
- * elasticsearch@9.2.4
+ * elasticsearch@9.2.8
  * firestore@latest
  * mongodb@8.2
  * mysql@9.6
- * postgresql@18.1
+ * postgresql@18.3
  * redis@8.4
- * s3@4.11.0
+ * s3@4.12.4
 ```
 
 A sample of all services available to the entire framework:
@@ -582,13 +582,13 @@ $ trv service status
 Service          Version    Status
 -------------------------------------------------
 dynamodb           3.3.0    Running 93af422e793a
-elasticsearch      9.2.4    Running ed76ee063d13
+elasticsearch      9.2.8    Running ed76ee063d13
 firestore         latest    Running feec2e5e95b4
 mongodb              8.2    Running 5513eba6734e
 mysql                9.6    Running 307bc66d442a
-postgresql          18.1    Running e78291e71040
+postgresql          18.3    Running e78291e71040
 redis                8.4    Running 77ba279b4e30
-s3                4.11.0    Running fdacfc55b9e3
+s3                4.12.4    Running fdacfc55b9e3
 ```
 
 ### Defining new Services

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)]);
+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.2",
+  "version": "8.0.0-alpha.20",
   "type": "module",
   "description": "CLI infrastructure for Travetto framework",
   "keywords": [
@@ -29,8 +29,8 @@
     "directory": "module/cli"
   },
   "dependencies": {
-    "@travetto/schema": "^8.0.0-alpha.1",
-    "@travetto/terminal": "^8.0.0-alpha.1"
+    "@travetto/schema": "^8.0.0-alpha.15",
+    "@travetto/terminal": "^8.0.0-alpha.14"
   },
   "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,29 @@ 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);
+      process.exitCode ??= 1;
     } finally {
       await ShutdownManager.shutdown();
     }

package/src/help.ts

@@ -4,32 +4,29 @@ import { castKey, getClass, JSONUtil, Runtime } from '@travetto/runtime';
 import { SchemaRegistryIndex, ValidationResultError } from '@travetto/schema';
 
 import { cliTpl } from './color.ts';
-import type { CliCommandShape } from './types.ts';
+import { HELP_FLAG, type CliCommandShape } from './types.ts';
 import { CliCommandRegistryIndex, UNKNOWN_COMMAND } from './registry/registry-index.ts';
 import { CliSchemaExportUtil } from './schema-export.ts';
 
-const validationSourceMap: Record<string, string> = {
-  arg: 'Argument',
-  flag: 'Flag'
-};
+const validationSourceMap: Record<string, string> = { arg: 'Argument', flag: 'Flag' };
 
 const ifDefined = <T>(value: T | null | '' | undefined): T | undefined =>
   (value === null || value === '' || value === undefined) ? undefined : value;
 
-const toItem = (name: string, pkg: string, prod?: boolean) => [name, Runtime.getInstallCommand(pkg, prod)] as const;
-
-const INSTALL_COMMANDS = new Map<string, string>([
-  ...['test', 'test:watch', 'test:direct'].map(item => toItem(item, '@travetto/test')),
-  ...['lint', 'lint:register', 'eslint', 'eslint:register'].map(item => toItem(item, '@travetto/eslint')),
-  ...['model:install', 'model:export'].map(item => toItem(item, '@travetto/model', true)),
-  ...['openapi:spec', 'openapi:client'].map(item => toItem(item, '@travetto/openapi', true)),
-  ...['email:compile', 'email:test', 'email:editor'].map(item => toItem(item, '@travetto/email-compiler')),
-  ...['pack', 'pack:zip', 'pack:docker'].map(item => toItem(item, '@travetto/pack')),
-  ...['repo:publish', 'repo:version', 'repo:exec', 'repo:list', 'repo:version-sync'].map(item => toItem(item, '@travetto/repo')),
-  toItem('web:http', '@travetto/web-http', true),
-  toItem('doc', '@travetto/doc'),
-  toItem('web:rpc-client', '@travetto/web-rpc', true),
-]);
+const MODULE_TO_COMMAND = {
+  '@travetto/doc': ['doc'],
+  '@travetto/email-compiler': ['email:compile', 'email:test', 'email:editor'],
+  '@travetto/eslint': ['eslint', 'eslint:register', 'lint', 'lint:register'],
+  '@travetto/model': ['model:install', 'model:export'],
+  '@travetto/openapi': ['openapi:spec', 'openapi:client'],
+  '@travetto/pack': ['pack', 'pack:zip', 'pack:docker'],
+  '@travetto/repo': ['repo:publish', 'repo:version', 'repo:exec', 'repo:list'],
+  '@travetto/test': ['test', 'test:watch', 'test:direct'],
+  '@travetto/web-http': ['web:http'],
+  '@travetto/web-rpc': ['web:rpc-client'],
+};
+
+const COMMAND_TO_MODULE = Object.fromEntries(Object.entries(MODULE_TO_COMMAND).flatMap(([k, v]) => v.map(sv => [sv, k])));
 
 /**
  * Utilities for showing help
@@ -37,15 +34,15 @@ const INSTALL_COMMANDS = new Map<string, string>([
 export class HelpUtil {
 
   /** Render the unknown command message */
-  static renderUnknownCommandMessage(cmd: string): string {
-    const install = INSTALL_COMMANDS.get(cmd);
-    if (install) {
+  static renderUnknownCommandMessage(command: string): string {
+    const module = COMMAND_TO_MODULE[command];
+    if (module) {
       return cliTpl`
-${{ title: 'Missing Package' }}\n${'-'.repeat(20)}\nTo use ${{ input: cmd }} please run:\n
-${{ identifier: install }}
+${{ title: 'Missing Package' }}\n${'-'.repeat(20)}\nTo use ${{ input: command }} please run:\n
+${{ identifier: Runtime.getInstallCommand(module) }}
 `;
     } else {
-      return cliTpl`${{ subtitle: 'Unknown command' }}: ${{ input: cmd }}`;
+      return cliTpl`${{ subtitle: 'Unknown command' }}: ${{ input: command }}`;
     }
   }
 
@@ -58,25 +55,24 @@ ${{ identifier: install }}
     const { name: commandName } = CliCommandRegistryIndex.get(getClass(command));
     const args = schema.methods.main?.parameters ?? [];
 
-    // Ensure finalized
+    const usage = [cliTpl`${{ title: 'Usage:' }} ${{ param: commandName }} ${{ input: '[options]' }}`,];
+    const params: string[] = [];
+    const descriptions: string[] = [];
 
-    const usage: string[] = [cliTpl`${{ title: 'Usage:' }} ${{ param: commandName }} ${{ input: '[options]' }}`,];
+    // Ensure finalized
     for (const field of args) {
       const type = field.type === String && field.enum && field.enum?.values.length <= 7 ? field.enum?.values?.join('|') : field.type.name.toLowerCase();
       const arg = `${field.name}${field.array ? '...' : ''}:${type}`;
       usage.push(cliTpl`${{ input: field.required?.active !== false ? `<${arg}>` : `[${arg}]` }}`);
     }
 
-    const params: string[] = [];
-    const descriptions: string[] = [];
-
     for (const field of Object.values(schema.fields)) {
       const key = castKey<CliCommandShape>(field.name);
       const defaultValue = ifDefined(command[key]) ?? ifDefined(field.default);
       const aliases = (field.aliases ?? [])
         .filter(flag => flag.startsWith('-'))
         .filter(flag =>
-          (field.type !== Boolean) || ((defaultValue !== true || field.name === 'help') ? !flag.startsWith('--no-') : flag.startsWith('--'))
+          (field.type !== Boolean) || (defaultValue !== true ? !flag.startsWith('--no-') : flag.startsWith('--'))
         );
       let type: string | undefined;
 
@@ -86,29 +82,33 @@ ${{ identifier: install }}
         ({ type } = CliSchemaExportUtil.baseInputType(field));
       }
 
-      const param = [
+      const parameter = [
         cliTpl`${{ param: aliases.join(', ') }}`,
         ...(type ? [cliTpl`${{ type: `<${type}>` }}`] : []),
       ];
 
-      params.push(param.join(' '));
-      const desc = [cliTpl`${{ title: field.description }}`];
+      params.push(parameter.join(' '));
+      const parts = [cliTpl`${{ title: field.description }}`];
 
-      if (key !== 'help' && defaultValue !== undefined) {
-        desc.push(cliTpl`(default: ${{ input: JSONUtil.toUTF8(defaultValue) }})`);
+      if (defaultValue !== undefined) {
+        parts.push(cliTpl`(default: ${{ input: JSONUtil.toUTF8(defaultValue) }})`);
       }
-      descriptions.push(desc.join(' '));
+      descriptions.push(parts.join(' '));
     }
 
+    params.push(cliTpl`${{ param: HELP_FLAG }}`);
+    descriptions.push('display help for command');
+
+
     const paramWidths = params.map(item => util.stripVTControlCharacters(item).length);
     const descWidths = descriptions.map(item => util.stripVTControlCharacters(item).length);
 
     const paramWidth = Math.max(...paramWidths);
     const descWidth = Math.max(...descWidths);
 
-    const helpText = await (command.help?.() ?? []);
-    if (helpText.length && helpText.at(-1) !== '') {
-      helpText.push('');
+    const extendedHelpText = await (command.help?.() ?? []);
+    if (extendedHelpText.length && extendedHelpText.at(-1) !== '') {
+      extendedHelpText.push('');
     }
 
     return [
@@ -119,7 +119,7 @@ ${{ identifier: install }}
         `  ${params[i]}${' '.repeat((paramWidth - paramWidths[i]))}  ${descriptions[i].padEnd(descWidth)}${' '.repeat((descWidth - descWidths[i]))}`
       ),
       '',
-      ...helpText
+      ...extendedHelpText
     ].map(line => line.trimEnd()).join('\n');
   }
 
@@ -175,13 +175,13 @@ ${{ identifier: install }}
     process.exitCode ??= 1;
     if (error instanceof ValidationResultError) {
       console.error!(this.renderValidationError(error));
+    } else if (error instanceof Error) {
+      console.error!(cliTpl`${{ failure: error.stack }}\n`);
     }
     if (command) {
       console.error!(await this.renderCommandHelp(command));
     } else if (error === UNKNOWN_COMMAND) {
       console.error!(this.renderUnknownCommandMessage(cmd));
-    } else {
-      console.error!(error);
     }
     console.error!();
   }

package/src/parse.ts

@@ -4,13 +4,12 @@ import path from 'node:path';
 import { Runtime } from '@travetto/runtime';
 import type { SchemaClassConfig, SchemaFieldConfig, SchemaInputConfig } from '@travetto/schema';
 
-import type { ParsedState } from './types.ts';
+import { HELP_FLAG, type ParsedState } from './types.ts';
 
 type ParsedInput = ParsedState['all'][number];
 
 const RAW_SEPARATOR = '--';
 const VALID_FLAG = /^-{1,2}[a-z]/i;
-const HELP_FLAG = /^(-h|--help)$/;
 const LONG_FLAG_WITH_EQ = /^--[a-z][^= ]+=\S+/i;
 const CONFIG_PREFIX = '+=';
 const SPACE = new Set([32, 7, 13, 10]);
@@ -95,7 +94,7 @@ export class CliParseUtil {
 
     const file = path.resolve(relativePath);
 
-    if (!await fs.stat(file).catch(() => false)) {
+    if (!await fs.stat(file, { throwIfNoEntry: false })) {
       throw new Error(`Missing flag file: ${key}, unable to proceed`);
     }
 
@@ -124,9 +123,9 @@ export class CliParseUtil {
     const max = out.includes(RAW_SEPARATOR) ? out.indexOf(RAW_SEPARATOR) : out.length;
     const valid = out.slice(0, max);
     const cmd = valid.length > 0 && !valid[0].startsWith('-') ? valid[0] : undefined;
-    const helpIdx = valid.findIndex(flag => HELP_FLAG.test(flag));
+    const help = valid.includes(HELP_FLAG);
     const args = out.slice(cmd ? 1 : 0);
-    const result = { cmd, args, help: helpIdx >= 0 };
+    const result = { cmd, args, help };
     return result;
   }
 

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,14 +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',
-      default: Runtime.localDevelopment,
-      required: { active: false },
+      description: 'Should the invocation automatically restart on source changes'
     });
 
-    runBeforeMain(cls, (cmd: typeof instance) => CliUtil.runWithRestartOnChange(cmd[property]), true);
+    CliCommandRegistryIndex.getForRegister(cls).register({ runTarget: true });
+    CliCommandRegistryIndex.registerPreMain<typeof instance>(cls, 20, cmd => CliUtil.runWithRestartOnChange(cmd[property]));
   };
 }
 
@@ -145,20 +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',
-      default: Runtime.localDevelopment,
-      required: { active: false },
+      description: 'Should the invocation automatically restart on source changes'
     });
 
-    runBeforeMain(cls,
-      (cmd: typeof instance & CliCommandShape) => {
-        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,22 +29,10 @@ export class CliCommandRegistryAdapter implements RegistryAdapter<CliCommandConf
     this.#cls = cls;
   }
 
-  finalize(): void {
+  // TODO: handle when aliases overlap/conflict
+  finalize(parent?: CliCommandConfig): void {
     // Add help command
     const schema = SchemaRegistryIndex.getConfig(this.#cls);
-
-    // Add help to every command
-    (schema.fields ??= {}).help = {
-      type: Boolean,
-      name: 'help',
-      class: this.#cls,
-      description: 'display help for command',
-      required: { active: false },
-      default: false,
-      access: 'readonly',
-      aliases: ['-h', '--help']
-    };
-
     const used = new Set(Object.values(schema.fields)
       .flatMap(field => field.aliases ?? [])
       .filter(alias => !alias.startsWith(ENV_PREFIX))
@@ -75,6 +63,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 {
@@ -86,7 +81,7 @@ export class CliCommandRegistryAdapter implements RegistryAdapter<CliCommandConf
    */
   register(...configs: Partial<CliCommandConfig>[]): CliCommandConfig {
     const metadata = describeFunction(this.#cls);
-    this.#config ??= { cls: this.#cls, name: getName(metadata.import), preMain: [], runTarget: true };
+    this.#config ??= { cls: this.#cls, name: getName(metadata.import), preMain: [], runTarget: false };
     return combineClasses(this.#config, ...configs);
   }
 

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,6 @@
-import type { Class } from '@travetto/runtime';
+import type { Any, Class } from '@travetto/runtime';
+
+export const HELP_FLAG = '--help';
 
 type OrProm<T> = T | Promise<T>;
 type ParsedFlag = { type: 'flag', input: string, array?: boolean, fieldName: string, value?: unknown };
@@ -32,7 +34,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 +43,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;
   }
 
   /**
@@ -33,10 +33,11 @@ export class CliUtil {
     ShutdownManager.disableInterrupt();
 
     let child: ChildProcess | undefined;
-    void WatchUtil.watchCompilerEvents('file', () => ShutdownManager.shutdownChild(child!, { reason: 'restart', mode: 'exit' }));
+    await WatchUtil.watchCompilerEvents('file', () => ShutdownManager.shutdownChild(child!, { reason: 'restart', mode: 'exit' }));
+
     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) };
 
@@ -77,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);