@travetto/cli 3.4.5 → 3.4.7

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#L15) decorator
+   *  The class must use the [@CliCommand](https://github.com/travetto/travetto/tree/main/module/cli/src/decorators.ts#L16) 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#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.
+[@CliCommand](https://github.com/travetto/travetto/tree/main/module/cli/src/decorators.ts#L16) 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#L16) 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#L15) supports the following data types for flags:
+The [@CliCommand](https://github.com/travetto/travetto/tree/main/module/cli/src/decorators.ts#L16) 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
@@ -359,8 +359,36 @@ $ MESSAGE=CuStOm trv custom:env-arg 7
 CuStOm
 ```
 
+## Flag File Support
+Sometimes its also convenient, especially with commands that support a variety of flags, to provide easy access to pre-defined sets of flags.  Flag files represent a snapshot of command line arguments and flags, as defined in a file.  When referenced, these inputs are essentially injected into the command line as if the user had typed them manually.
+
+**Code: Example Flag File**
+```bash
+--host localhost
+--port 3306
+--username app
+```
+
+As you can see in this file, it provides easy access to predefine the host, port, and user flags.
+
+**Code: Using a Flag File**
+```bash
+npx trv call:db +=base --password <custom>
+```
+
+The flag files can be included in one of a few ways:
+   *  `+=<name>` - This translates into $`<mod>/support/<name>.flags`, which is a convenient shorthand.
+   *  `+=<mod>/path/file.flags` - This is a path-related file that will be resolved from the module's location.
+   *  `+=/path/file.flags` - This is an absolute path that will be read from the root of the file system.
+Ultimately, after resolution, the content of these files will be injected inline within the location.
+
+**Code: Final arguments after Flag File resolution**
+```bash
+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.  [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.
+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#L16) decorator.  This means the target will be visible within the editor tooling.
 
 **Code: Simple Run Target**
 ```typescript
@@ -382,19 +410,23 @@ export class RunCommand {
 
 **Code: Anatomy of a Command**
 ```typescript
-export interface CliCommandShape {
+export interface CliCommandShape<T extends unknown[] = unknown[]> {
   /**
    * Action target of the command
    */
-  main(...args: unknown[]): OrProm<RunResponse>;
+  main(...args: T): OrProm<RunResponse>;
   /**
-   * Setup environment before command runs
+   * Run before main runs
    */
-  envInit?(): OrProm<EnvInit>;
+  preMain?(): OrProm<void>;
   /**
    * Extra help
    */
   help?(): OrProm<string[]>;
+  /**
+   * Run before help is displayed
+   */
+  preHelp?(): OrProm<void>;
   /**
    * Is the command active/eligible for usage
    */
@@ -402,15 +434,15 @@ export interface CliCommandShape {
   /**
    * Run before binding occurs
    */
-  initialize?(): OrProm<void>;
+  preBind?(): OrProm<void>;
   /**
    * Run before validation occurs
    */
-  finalize?(unknownArgs: string[]): OrProm<void>;
+  preValidate?(): OrProm<void>;
   /**
    * Validation method
    */
-  validate?(...unknownArgs: unknown[]): OrProm<CliValidationError | CliValidationError[] | undefined>;
+  validate?(...args: T): OrProm<CliValidationError | CliValidationError[] | undefined>;
 }
 ```
 
@@ -420,7 +452,7 @@ If the goal is to run a more complex application, which may include depending on
 **Code: Simple Run Target**
 ```typescript
 import { DependencyRegistry } from '@travetto/di';
-import { CliCommand, CliUtil } from '@travetto/cli';
+import { CliCommand, CliCommandShape, CliUtil } from '@travetto/cli';
 
 import { ServerHandle } from '../src/types';
 
@@ -428,7 +460,7 @@ import { ServerHandle } from '../src/types';
  * Run a rest server as an application
  */
 @CliCommand({ runTarget: true, addModule: true, addEnv: true })
-export class RunRestCommand {
+export class RunRestCommand implements CliCommandShape {
 
   /** IPC debug is enabled */
   debugIpc?: boolean;
@@ -439,8 +471,10 @@ export class RunRestCommand {
   /** Port to run on */
   port?: number;
 
-  envInit(): Record<string, string | number | boolean> {
-    return this.port ? { REST_PORT: `${this.port}` } : {};
+  preMain(): void {
+    if (this.port) {
+      process.env.REST_PORT = `${this.port}`;
+    }
   }
 
   async main(): Promise<ServerHandle | void> {
@@ -479,7 +513,7 @@ A simple example of the validation can be found in the `doc` command:
 
 **Code: Simple Validation Example**
 ```typescript
-async validate(...args: unknown[]): Promise<CliValidationError | undefined> {
+async validate(): Promise<CliValidationError | undefined> {
     const docFile = path.resolve(this.input);
     if (!(await fs.stat(docFile).catch(() => false))) {
       return { message: `input: ${this.input} does not exist`, source: 'flag' };

package/__index__.ts

@@ -8,4 +8,5 @@ export * from './src/help';
 export * from './src/color';
 export * from './src/module';
 export * from './src/scm';
+export * from './src/parse';
 export * from './src/util';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@travetto/cli",
-  "version": "3.4.5",
+  "version": "3.4.7",
   "description": "CLI infrastructure for Travetto framework",
   "keywords": [
     "cli",
@@ -29,7 +29,7 @@
     "directory": "module/cli"
   },
   "dependencies": {
-    "@travetto/schema": "^3.4.3",
+    "@travetto/schema": "^3.4.4",
     "@travetto/terminal": "^3.4.0"
   },
   "travetto": {

package/src/decorators.ts

@@ -1,4 +1,4 @@
-import { Class, ClassInstance, ConsoleManager, GlobalEnv, defineEnv } from '@travetto/base';
+import { Class, ClassInstance, defineEnv } from '@travetto/base';
 import { RootIndex } from '@travetto/manifest';
 import { SchemaRegistry } from '@travetto/schema';
 
@@ -6,6 +6,7 @@ import { CliCommandShape, CliCommandShapeFields } from './types';
 import { CliCommandRegistry, CliCommandConfigOptions } from './registry';
 import { CliModuleUtil } from './module';
 import { CliUtil } from './util';
+import { CliParseUtil } from './parse';
 
 /**
  * Decorator to register a CLI command
@@ -27,7 +28,6 @@ export function CliCommand(cfg: CliCommandConfigOptions = {}) {
       preMain: async (cmd) => {
         if (addEnv && 'env' in cmd && typeof cmd.env === 'string') {
           defineEnv({ envName: cmd.env });
-          ConsoleManager.setDebug(GlobalEnv.debug, GlobalEnv.devMode);
         }
       }
     });
@@ -38,13 +38,14 @@ export function CliCommand(cfg: CliCommandConfigOptions = {}) {
       SchemaRegistry.registerPendingFieldConfig(target, 'env', String, {
         aliases: ['e'],
         description: 'Application environment',
+        default: 'dev',
         required: { active: false }
       });
     }
 
     if (addModule) {
       SchemaRegistry.registerPendingFieldConfig(target, 'module', String, {
-        aliases: ['m', 'env.TRV_MODULE'],
+        aliases: ['m', CliParseUtil.toEnvField('TRV_MODULE')],
         description: 'Module to run for',
         required: { active: CliUtil.monoRoot }
       });
@@ -86,7 +87,7 @@ export function CliFlag(cfg: { name?: string, short?: string, desc?: string, fil
       aliases.push(cfg.short.startsWith('-') ? cfg.short : `-${cfg.short}`);
     }
     if (cfg.envVars) {
-      aliases.push(...cfg.envVars.map(v => `env.${v}`));
+      aliases.push(...cfg.envVars.map(CliParseUtil.toEnvField));
     }
     if (typeof prop === 'string') {
       SchemaRegistry.registerPendingFieldFacet(target.constructor, prop, {

package/src/execute.ts

@@ -1,53 +1,67 @@
 import { GlobalTerminal } from '@travetto/terminal';
-import { ConsoleManager, defineEnv, ShutdownManager, GlobalEnv } from '@travetto/base';
+import { ConsoleManager, GlobalEnv } from '@travetto/base';
 
 import { HelpUtil } from './help';
-import { CliCommandShape } from './types';
+import { CliCommandShape, RunResponse } from './types';
 import { CliCommandRegistry } from './registry';
 import { CliCommandSchemaUtil } from './schema';
 import { CliUnknownCommandError, CliValidationResultError } from './error';
+import { CliParseUtil } from './parse';
+import { CliUtil } from './util';
 
 /**
  * Execution manager
  */
 export class ExecutionManager {
 
-  static async #envInit(cmd: CliCommandShape): Promise<void> {
-    if (cmd.envInit) {
-      defineEnv(await cmd.envInit());
-      ConsoleManager.setDebug(GlobalEnv.debug, GlobalEnv.devMode);
-    }
-  }
-
-  /**
-   * Run help
-   */
-  static async help(cmd: CliCommandShape, args: string[]): Promise<void> {
-    await cmd.initialize?.();
-    await this.#envInit(cmd);
-    console.log!(await HelpUtil.renderHelp(cmd));
-  }
-
   /**
    * Run the given command object with the given arguments
    */
-  static async command(cmd: CliCommandShape, args: string[]): Promise<void> {
-    const known = await CliCommandSchemaUtil.bindAndValidateArgs(cmd, args);
-    await this.#envInit(cmd);
+  static async #runCommand(cmd: CliCommandShape, args: string[]): Promise<RunResponse> {
+    const schema = await CliCommandSchemaUtil.getSchema(cmd);
+    const state = await CliParseUtil.parse(schema, args);
     const cfg = CliCommandRegistry.getConfig(cmd);
-    await cfg?.preMain?.(cmd);
 
-    const result = await cmd.main(...known);
+    CliParseUtil.setState(cmd, state);
+
+    await cmd.preBind?.();
+    const known = await CliCommandSchemaUtil.bindInput(cmd, state);
+
+    await cmd.preValidate?.();
+    await CliCommandSchemaUtil.validate(cmd, known);
 
-    // Listen to result if non-empty
-    if (result !== undefined && result !== null) {
-      if ('close' in result) {
-        ShutdownManager.onShutdown(result, result); // Tie shutdown into app close
+    await cfg.preMain?.(cmd);
+    await cmd.preMain?.();
+    ConsoleManager.setDebug(GlobalEnv.debug, GlobalEnv.devMode);
+    return cmd.main(...known);
+  }
+
+  /**
+   * On error, handle response
+   */
+  static async #onError(command: CliCommandShape | undefined, err: unknown): Promise<void> {
+    process.exitCode ||= 1; // Trigger error state
+    switch (true) {
+      case !(err instanceof Error): {
+        throw err;
+      }
+      case command && err instanceof CliValidationResultError: {
+        console.error!(await HelpUtil.renderValidationError(command, err));
+        console.error!(await HelpUtil.renderCommandHelp(command));
+        break;
+      }
+      case err instanceof CliUnknownCommandError: {
+        if (err.help) {
+          console.error!(err.help);
+        } else {
+          console.error!(err.defaultMessage, '\n');
+          console.error!(await HelpUtil.renderAllHelp(''));
+        }
+        break;
       }
-      if ('wait' in result) {
-        await result.wait(); // Wait for close signal
-      } else if ('on' in result) {
-        await new Promise<void>(res => result.on('close', res)); // Wait for callback
+      default: {
+        console.error!(err);
+        console.error!();
       }
     }
   }
@@ -59,38 +73,25 @@ export class ExecutionManager {
   static async run(argv: string[]): Promise<void> {
     await GlobalTerminal.init();
 
-    const [, , cmd, ...args] = argv;
-    if (!cmd || /^(-h|--help)$/.test(cmd)) {
-      console.info!(await HelpUtil.renderHelp());
-    } else {
-      let command: CliCommandShape | undefined;
-      try {
-        // Load a single command
-        command = (await CliCommandRegistry.getInstance(cmd, true));
-        if (args.some(a => /^(-h|--help)$/.test(a))) {
-          await this.help(command, args);
-        } else {
-          await this.command(command, args);
-        }
-      } catch (err) {
-        process.exitCode ||= 1; // Trigger error state
-        if (!(err instanceof Error)) {
-          throw err;
-        } else if (err instanceof CliValidationResultError) {
-          console.error!(await HelpUtil.renderValidationError(command!, err));
-          console.error!(await HelpUtil.renderHelp(command));
-        } else if (err instanceof CliUnknownCommandError) {
-          if (err.help) {
-            console.error!(err.help);
-          } else {
-            console.error!(err.defaultMessage, '\n');
-            console.error!(await HelpUtil.renderAllHelp(''));
-          }
-        } else {
-          console.error!(err);
-          console.error!();
-        }
+    let command: CliCommandShape | undefined;
+    try {
+      const { cmd, args, help } = await CliParseUtil.getArgs(argv);
+
+      if (!cmd) {
+        console.info!(await HelpUtil.renderAllHelp());
+        return;
+      }
+
+      // Load a single command
+      command = await CliCommandRegistry.getInstance(cmd, true);
+      if (help) {
+        console.log!(await HelpUtil.renderCommandHelp(command));
+      } else {
+        const result = await this.#runCommand(command, args);
+        await CliUtil.listenForResponse(result);
       }
+    } catch (err) {
+      await this.#onError(command, err);
     }
   }
 }

package/src/help.ts

@@ -25,7 +25,7 @@ export class HelpUtil {
   static async renderCommandHelp(command: CliCommandShape): Promise<string> {
     const commandName = CliCommandRegistry.getName(command);
 
-    command.initialize?.();
+    await command.preHelp?.();
 
     // Ensure finalized
     const { flags, args } = await CliCommandSchemaUtil.getSchema(command);
@@ -126,13 +126,6 @@ export class HelpUtil {
     return lines.map(x => x.trimEnd()).join('\n');
   }
 
-  /**
-   * Render help
-   */
-  static async renderHelp(command?: CliCommandShape): Promise<string> {
-    return command ? this.renderCommandHelp(command) : this.renderAllHelp();
-  }
-
   /**
    * Render validation error to a string
    */

package/src/parse.ts

@@ -0,0 +1,231 @@
+import fs from 'fs/promises';
+
+import { RootIndex, path } from '@travetto/manifest';
+import { CliCommandInput, CliCommandSchema, CliCommandShape } from './types';
+
+type ParsedFlag = { type: 'flag', input: string, array?: boolean, fieldName: string, value?: unknown };
+type ParsedArg = { type: 'arg', input: string, array?: boolean, index: number };
+type ParsedUnknown = { type: 'unknown', input: string };
+type ParsedInput = ParsedUnknown | ParsedFlag | ParsedArg;
+
+export type ParsedState = {
+  inputs: string[];
+  all: ParsedInput[];
+  flags: ParsedFlag[];
+  unknown: string[];
+};
+
+const RAW_SEP = '--';
+const VALID_FLAG = /^-{1,2}[a-z]/i;
+const HELP_FLAG = /^-h|--help$/;
+const LONG_FLAG_WITH_EQ = /^--[a-z][^= ]+=\S+/i;
+const CONFIG_PRE = '+=';
+const ENV_PRE = 'env.';
+const ParsedⲐ = Symbol.for('@travetto/cli:parsed');
+const SPACE = new Set([32, 7, 13, 10]);
+
+const isBoolFlag = (x?: CliCommandInput): boolean => x?.type === 'boolean' && !x.array;
+
+const getInput = (cfg: { field?: CliCommandInput, rawText?: string, input: string, index?: number, value?: string }): ParsedInput => {
+  const { field, input, rawText = input, value, index } = cfg;
+  if (!field) {
+    return { type: 'unknown', input: rawText };
+  } else if (!field.flagNames?.length) {
+    return { type: 'arg', input: field ? input : rawText ?? input, array: field.array, index: index! };
+  } else {
+    return {
+      type: 'flag',
+      fieldName: field.name,
+      array: field.array,
+      input: field ? input : rawText ?? input,
+      value: value ?? (isBoolFlag(field) ? !input.startsWith('--no-') : undefined)
+    };
+  }
+};
+
+/**
+ * Parsing support for the cli
+ */
+export class CliParseUtil {
+
+  static toEnvField(k: string): string {
+    return `${ENV_PRE}${k}`;
+  }
+
+  static readToken(text: string, start = 0): { next: number, value?: string } {
+    const collected: number[] = [];
+    let i = start;
+    let done = false;
+    let quote: number | undefined;
+    let escaped = false;
+    outer: for (; i < text.length; i += 1) {
+      const ch = text.charCodeAt(i);
+      const space = SPACE.has(ch);
+      if (escaped) {
+        escaped = false;
+        collected.push(ch);
+      } else if (done && !space) {
+        break outer;
+      } else if (!quote && space) {
+        done = true;
+      } else {
+        switch (ch) {
+          case 92: /* Backslash */ escaped = true; break;
+          case 39: /* Single quote */ case 34: /* Double quote */
+            if (quote === ch) { // End quote
+              quote = undefined;
+            } else if (!quote) {
+              quote = ch;
+            } else {
+              collected.push(ch);
+            }
+            break;
+          default: collected.push(ch);
+        }
+      }
+    }
+    return { next: i, value: collected.length ? String.fromCharCode(...collected) : undefined };
+  }
+
+  /**
+   * Read configuration file given flag
+   */
+  static async readFlagFile(flag: string): Promise<string[]> {
+    const key = flag.replace(CONFIG_PRE, '');
+    const mod = RootIndex.mainModuleName;
+
+    // We have a file
+    const rel = (key.includes('/') ? key : `@/support/pack.${key}.flags`)
+      .replace('@@/', `${RootIndex.manifest.workspacePath}/`)
+      .replace('@/', `${mod}/`)
+      .replace(/^(@[^\/]+\/[^\/]+)/, (_, imp) => {
+        const val = RootIndex.getModule(imp);
+        if (!val) {
+          throw new Error(`Unknown module file: ${key}, unable to proceed`);
+        }
+        return val.sourcePath;
+      });
+
+    const file = path.resolve(rel);
+
+    if (!await fs.stat(file).catch(() => false)) {
+      throw new Error(`Missing flag file: ${key}, unable to proceed`);
+    }
+
+    const data = await fs.readFile(file, 'utf8');
+    const args: string[] = [];
+    let token: { next: number, value?: string } = { next: 0 };
+    while (token.next < data.length) {
+      token = this.readToken(data, token.next);
+      if (token.value !== undefined) {
+        args.push(token.value);
+      }
+    }
+    return args;
+  }
+
+  /**
+   * Parse args to extract command from argv along with other params.  Will skip
+   * argv[0] and argv[1] if equal to process.argv[0:2]
+   */
+  static async getArgs(argv: string[]): Promise<{ cmd?: string, args: string[], help?: boolean }> {
+    let offset = 0;
+    if (argv[0] === process.argv[0] && argv[1] === process.argv[1]) {
+      offset = 2;
+    }
+    const out = argv.slice(offset);
+    const max = out.includes(RAW_SEP) ? out.indexOf(RAW_SEP) : out.length;
+    const valid = out.slice(0, max);
+    const cmd = valid.length > 0 && !valid[0].startsWith('-') ? valid[0] : undefined;
+    const helpIdx = valid.findIndex(x => HELP_FLAG.test(x));
+    const args = [];
+    for (const item of out.slice(cmd ? 1 : 0)) {
+      if (item.startsWith(CONFIG_PRE)) {
+        args.push(...await this.readFlagFile(item));
+      } else {
+        args.push(item);
+      }
+    }
+    args.push(...out.slice(max));
+    const res = { cmd, args, help: helpIdx >= 0 };
+    return res;
+  }
+
+  /**
+   * Parse inputs to command
+   */
+  static async parse(schema: CliCommandSchema, inputs: string[]): Promise<ParsedState> {
+    const flagMap = new Map<string, CliCommandInput>(
+      schema.flags.flatMap(f => (f.flagNames ?? []).map(name => [name, f]))
+    );
+
+    const out: ParsedInput[] = [];
+
+    // Load env vars to front
+    for (const field of schema.flags) {
+      for (const envName of field.envVars ?? []) {
+        if (envName in process.env) {
+          const value: string = process.env[envName]!;
+          if (field.array) {
+            out.push(...value.split(/\s*,\s*/g).map(v => getInput({ field, input: `${ENV_PRE}${envName}`, value: v })));
+          } else {
+            out.push(getInput({ field, input: `${ENV_PRE}${envName}`, value }));
+          }
+        }
+      }
+    }
+
+    let argIdx = 0;
+
+    for (let i = 0; i < inputs.length; i += 1) {
+      const input = inputs[i];
+
+      if (input === RAW_SEP) { // Raw separator
+        out.push(...inputs.slice(i + 1).map(x => getInput({ input: x })));
+        break;
+      } else if (LONG_FLAG_WITH_EQ.test(input)) {
+        const [k, ...v] = input.split('=');
+        const field = flagMap.get(k);
+        out.push(getInput({ field, rawText: input, input: k, value: v.join('=') }));
+      } else if (VALID_FLAG.test(input)) { // Flag
+        const field = flagMap.get(input);
+        const next = inputs[i + 1];
+        if ((next && (VALID_FLAG.test(next) || next === RAW_SEP)) || isBoolFlag(field)) {
+          out.push(getInput({ field, input }));
+        } else {
+          out.push(getInput({ field, input, value: next }));
+          i += 1;
+        }
+      } else {
+        const field = schema.args[argIdx];
+        out.push(getInput({ field, input, index: argIdx }));
+        // Move argIdx along if not in a vararg situation
+        if (!field?.array) {
+          argIdx += 1;
+        }
+      }
+    }
+
+    // Store for later, if needed
+    return {
+      inputs,
+      all: out,
+      unknown: out.filter((x): x is ParsedUnknown => x.type === 'unknown').map(x => x.input),
+      flags: out.filter((x): x is ParsedFlag => x.type === 'flag')
+    };
+  }
+
+  /**
+   * Get parse state from the command
+   */
+  static getState(cmd: CliCommandShape & { [ParsedⲐ]?: ParsedState }): ParsedState | undefined {
+    return cmd[ParsedⲐ];
+  }
+
+  /**
+   * Set state for a command
+   */
+  static setState(cmd: CliCommandShape & { [ParsedⲐ]?: ParsedState }, state: ParsedState): void {
+    cmd[ParsedⲐ] = state;
+  }
+}

package/src/schema.ts

@@ -4,36 +4,13 @@ import { BindUtil, FieldConfig, SchemaRegistry, SchemaValidator, ValidationResul
 import { CliCommandRegistry } from './registry';
 import { CliCommandInput, CliCommandSchema, CliCommandShape } from './types';
 import { CliValidationResultError } from './error';
+import { ParsedState } from './parse';
 
-const VALID_FLAG = /^-{1,2}[a-z]/i;
 const LONG_FLAG = /^--[a-z][^= ]+/i;
-const LONG_FLAG_WITH_EQ = /^--[a-z][^= ]+=\S+/i;
 const SHORT_FLAG = /^-[a-z]/i;
 
-type ParsedInput =
-  { type: 'unknown', input: string } |
-  { type: 'arg', input: string, array?: boolean, index: number } |
-  { type: 'flag', input: string, array?: boolean, fieldName: string, value?: unknown };
-
 const isBoolFlag = (x?: CliCommandInput): boolean => x?.type === 'boolean' && !x.array;
 
-const getInput = (cfg: { field?: CliCommandInput, rawText?: string, input: string, index?: number, value?: string }): ParsedInput => {
-  const { field, input, rawText = input, value, index } = cfg;
-  if (!field) {
-    return { type: 'unknown', input: rawText };
-  } else if (!field.flagNames?.length) {
-    return { type: 'arg', input: field ? input : rawText ?? input, array: field.array, index: index! };
-  } else {
-    return {
-      type: 'flag',
-      fieldName: field.name,
-      array: field.array,
-      input: field ? input : rawText ?? input,
-      value: value ?? (isBoolFlag(field) ? !input.startsWith('--no-') : undefined)
-    };
-  }
-};
-
 function fieldToInput(x: FieldConfig): CliCommandInput {
   const type = x.type === Date ? 'date' :
     x.type === Boolean ? 'boolean' :
@@ -136,71 +113,13 @@ export class CliCommandSchemaUtil {
   }
 
   /**
-   * Parse inputs to command
-   */
-  static async parse<T extends CliCommandShape>(cls: Class<T>, inputs: string[]): Promise<ParsedInput[]> {
-    const schema = await this.getSchema(cls);
-    const flagMap = new Map<string, CliCommandInput>(
-      schema.flags.flatMap(f => (f.flagNames ?? []).map(name => [name, f]))
-    );
-
-    const out: ParsedInput[] = [];
-
-    // Load env vars to front
-    for (const field of schema.flags) {
-      for (const envName of field.envVars ?? []) {
-        if (envName in process.env) {
-          const value: string = process.env[envName]!;
-          if (field.array) {
-            out.push(...value.split(/\s*,\s*/g).map(v => getInput({ field, input: `env.${envName}`, value: v })));
-          } else {
-            out.push(getInput({ field, input: `env.${envName}`, value }));
-          }
-        }
-      }
-    }
-
-    let argIdx = 0;
-
-    for (let i = 0; i < inputs.length; i += 1) {
-      const input = inputs[i];
-
-      if (input === '--') { // Raw separator
-        out.push(...inputs.slice(i + 1).map(x => getInput({ input: x })));
-        break;
-      } else if (LONG_FLAG_WITH_EQ.test(input)) {
-        const [k, ...v] = input.split('=');
-        const field = flagMap.get(k);
-        out.push(getInput({ field, rawText: input, input: k, value: v.join('=') }));
-      } else if (VALID_FLAG.test(input)) { // Flag
-        const field = flagMap.get(input);
-        const next = inputs[i + 1];
-        if ((next && (VALID_FLAG.test(next) || next === '--')) || isBoolFlag(field)) {
-          out.push(getInput({ field, input }));
-        } else {
-          out.push(getInput({ field, input, value: next }));
-          i += 1;
-        }
-      } else {
-        const field = schema.args[argIdx];
-        out.push(getInput({ field, input, index: argIdx }));
-        // Move argIdx along if not in a vararg situation
-        if (!field?.array) {
-          argIdx += 1;
-        }
-      }
-    }
-
-    return out;
-  }
-
-  /**
-   * Bind arguments to command
+   * Bind parsed inputs to command
    */
-  static async bindFlags<T extends CliCommandShape>(cmd: T, args: ParsedInput[]): Promise<void> {
+  static async bindInput<T extends CliCommandShape>(cmd: T, state: ParsedState): Promise<unknown[]> {
     const template: Partial<T> = {};
+    const bound: unknown[] = [];
 
-    for (const arg of args) {
+    for (const arg of state.all) {
       switch (arg.type) {
         case 'flag': {
           // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
@@ -213,6 +132,15 @@ export class CliCommandSchemaUtil {
             // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
             template[key] = value as unknown as T[typeof key];
           }
+          break;
+        }
+        case 'arg': {
+          if (arg.array) {
+            // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+            ((bound[arg.index] ??= []) as unknown[]).push(arg.input);
+          } else {
+            bound[arg.index] = arg.input;
+          }
         }
       }
     }
@@ -220,35 +148,9 @@ export class CliCommandSchemaUtil {
     // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
     const cls = cmd.constructor as Class<CliCommandShape>;
     BindUtil.bindSchemaToObject(cls, cmd, template);
-  }
-
-  /**
-   * Produce the arguments into the final argument set
-   */
-  static async bindArgs(cmd: CliCommandShape, inputs: ParsedInput[]): Promise<unknown[]> {
-    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
-    const cls = cmd.constructor as Class<CliCommandShape>;
-    const bound: unknown[] = [];
-    for (const input of inputs) {
-      if (input.type === 'arg') {
-        if (input.array) {
-          // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
-          ((bound[input.index] ??= []) as unknown[]).push(input.input);
-        } else {
-          bound[input.index] = input.input;
-        }
-      }
-    }
     return BindUtil.coerceMethodParams(cls, 'main', bound);
   }
 
-  /**
-   * Get the unused arguments
-   */
-  static getUnusedArgs(args: ParsedInput[]): string[] {
-    return args.filter(x => x.type === 'unknown').map(x => x.input);
-  }
-
   /**
    * Validate command shape with the given arguments
    */
@@ -284,19 +186,4 @@ export class CliCommandSchemaUtil {
     }
     return cmd;
   }
-
-  /**
-   * Bind and validate a command with a given set of arguments
-   */
-  static async bindAndValidateArgs(cmd: CliCommandShape, args: string[]): Promise<unknown[]> {
-    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
-    const cls = cmd.constructor as Class;
-    await cmd.initialize?.();
-    const parsed = await this.parse(cls, args);
-    await this.bindFlags(cmd, parsed);
-    const known = await this.bindArgs(cmd, parsed);
-    await cmd.finalize?.(this.getUnusedArgs(parsed));
-    await this.validate(cmd, known);
-    return known;
-  }
 }

package/src/types.ts

@@ -1,8 +1,8 @@
-import { Closeable, EnvInit } from '@travetto/base';
+import { Closeable } from '@travetto/base';
 
 type OrProm<T> = T | Promise<T>;
 
-type RunResponse = { wait(): Promise<unknown> } | { on(event: 'close', cb: Function): unknown } | Closeable | void | undefined;
+export type RunResponse = { wait(): Promise<unknown> } | { on(event: 'close', cb: Function): unknown } | Closeable | void | undefined;
 
 /**
  * Constrained version of Schema's Validation Error
@@ -21,19 +21,23 @@ export type CliValidationError = {
 /**
  * CLI Command Contract
  */
-export interface CliCommandShape {
+export interface CliCommandShape<T extends unknown[] = unknown[]> {
   /**
    * Action target of the command
    */
-  main(...args: unknown[]): OrProm<RunResponse>;
+  main(...args: T): OrProm<RunResponse>;
   /**
-   * Setup environment before command runs
+   * Run before main runs
    */
-  envInit?(): OrProm<EnvInit>;
+  preMain?(): OrProm<void>;
   /**
    * Extra help
    */
   help?(): OrProm<string[]>;
+  /**
+   * Run before help is displayed
+   */
+  preHelp?(): OrProm<void>;
   /**
    * Is the command active/eligible for usage
    */
@@ -41,15 +45,15 @@ export interface CliCommandShape {
   /**
    * Run before binding occurs
    */
-  initialize?(): OrProm<void>;
+  preBind?(): OrProm<void>;
   /**
    * Run before validation occurs
    */
-  finalize?(unknownArgs: string[]): OrProm<void>;
+  preValidate?(): OrProm<void>;
   /**
    * Validation method
    */
-  validate?(...unknownArgs: unknown[]): OrProm<CliValidationError | CliValidationError[] | undefined>;
+  validate?(...args: T): OrProm<CliValidationError | CliValidationError[] | undefined>;
 }
 
 /**

package/src/util.ts

@@ -1,7 +1,7 @@
-import { Env, ExecUtil, GlobalEnv } from '@travetto/base';
-import { RootIndex } from '@travetto/manifest';
+import { Env, ExecUtil, GlobalEnv, ShutdownManager } from '@travetto/base';
+import { RootIndex, path } from '@travetto/manifest';
 
-import { CliCommandShape, CliCommandShapeFields } from './types';
+import { CliCommandShape, CliCommandShapeFields, RunResponse } from './types';
 import { CliCommandRegistry } from './registry';
 
 export class CliUtil {
@@ -16,8 +16,15 @@ export class CliUtil {
    * Get a simplified version of a module name
    * @returns
    */
-  static getSimpleModuleName(name = RootIndex.mainModuleName): string {
-    return name.replace(/[\/]/, '_').replace(/@/, '');
+  static getSimpleModuleName(placeholder: string, module?: string): string {
+    const simple = (module ?? RootIndex.mainModuleName).replace(/[\/]/, '_').replace(/@/, '');
+    if (!simple) {
+      return placeholder;
+    } else if (!module && this.monoRoot) {
+      return placeholder;
+    } else {
+      return placeholder.replace('<module>', simple);
+    }
   }
 
   /**
@@ -92,4 +99,21 @@ export class CliUtil {
   static async writeAndEnsureComplete(data: unknown, channel: 'stdout' | 'stderr' = 'stdout'): Promise<void> {
     return await new Promise(r => process[channel].write(typeof data === 'string' ? data : JSON.stringify(data, null, 2), () => r()));
   }
+
+  /**
+   * Listen for a run response to finish
+   */
+  static async listenForResponse(result: RunResponse): Promise<void> {
+    // Listen to result if non-empty
+    if (result !== undefined && result !== null) {
+      if ('close' in result) {
+        ShutdownManager.onShutdown(result, result); // Tie shutdown into app close
+      }
+      if ('wait' in result) {
+        await result.wait(); // Wait for close signal
+      } else if ('on' in result) {
+        await new Promise<void>(res => result.on('close', res)); // Wait for callback
+      }
+    }
+  }
 }

package/support/cli.main.ts

@@ -1,7 +1,7 @@
 import fs from 'fs/promises';
 
 import { ShutdownManager } from '@travetto/base';
-import { CliCommandShape, CliCommand, CliValidationError } from '@travetto/cli';
+import { CliCommandShape, CliCommand, CliValidationError, CliParseUtil } from '@travetto/cli';
 import { path, RootIndex } from '@travetto/manifest';
 
 /**
@@ -10,8 +10,6 @@ import { path, RootIndex } from '@travetto/manifest';
 @CliCommand({ hidden: true })
 export class MainCommand implements CliCommandShape {
 
-  #unknownArgs?: string[];
-
   async #getImport(fileOrImport: string): Promise<string | undefined> {
     // If referenced file exists
     let file = fileOrImport;
@@ -29,15 +27,12 @@ export class MainCommand implements CliCommandShape {
     }
   }
 
-  finalize(unknownArgs?: string[] | undefined): void | Promise<void> {
-    this.#unknownArgs = unknownArgs;
-  }
-
   async main(fileOrImport: string, args: string[] = []): Promise<void> {
     try {
       const imp = await this.#getImport(fileOrImport);
       const mod = await import(imp!);
-      await ShutdownManager.exitWithResponse(await mod.main(...args, ...this.#unknownArgs ?? []));
+
+      await ShutdownManager.exitWithResponse(await mod.main(...args, ...CliParseUtil.getState(this)?.unknown ?? []));
     } catch (err) {
       await ShutdownManager.exitWithResponse(err, true);
     }