@travetto/cli 8.0.0-alpha.0 → 8.0.0-alpha.1

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#L98) decorator
+   *  The class must use the [@CliCommand](https://github.com/travetto/travetto/tree/main/module/cli/src/registry/decorator.ts#L27) 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#L98) 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#L98) 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#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.
 
 **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#L98) supports the following data types for flags:
+The [@CliCommand](https://github.com/travetto/travetto/tree/main/module/cli/src/registry/decorator.ts#L27) 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#L98) 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#L27) decorator.  This means the target will be visible within the editor tooling.
 
 **Code: Simple Run Target**
 ```typescript
@@ -412,47 +412,19 @@ export class RunCommand {
 
 **Code: Anatomy of a Command**
 ```typescript
-export interface CliCommandShape<T extends unknown[] = unknown[]> {
-  /**
-   * Parsed state
-   */
-  _parsed?: ParsedState;
-  /**
-   * Config
-   */
-  _cfg?: CliCommandConfig;
+export interface CliCommandShape {
   /**
    * Action target of the command
    */
-  main(...args: T): OrProm<undefined | void>;
+  main(...args: unknown[]): OrProm<undefined | void>;
   /**
    * Run before main runs
    */
-  preMain?(): OrProm<void>;
+  finalize?(help?: boolean): OrProm<void>;
   /**
    * Extra help
    */
   help?(): OrProm<string[]>;
-  /**
-   * Run before help is displayed
-   */
-  preHelp?(): OrProm<void>;
-  /**
-   * Is the command active/eligible for usage
-   */
-  isActive?(): boolean;
-  /**
-   * Run before binding occurs
-   */
-  preBind?(): OrProm<void>;
-  /**
-   * Run before validation occurs
-   */
-  preValidate?(): OrProm<void>;
-  /**
-   * Validation method
-   */
-  validate?(...args: T): OrProm<CliValidationError | CliValidationError[] | undefined>;
 }
 ```
 
@@ -463,7 +435,7 @@ If the goal is to run a more complex application, which may include depending on
 ```typescript
 import { Runtime, toConcrete } from '@travetto/runtime';
 import { DependencyRegistryIndex } from '@travetto/di';
-import { CliCommand, type CliCommandShape } from '@travetto/cli';
+import { CliCommand, CliDebugIpcFlag, CliModuleFlag, CliProfilesFlag, CliRestartOnChangeFlag, type CliCommandShape } from '@travetto/cli';
 import { NetUtil } from '@travetto/web';
 import { Registry } from '@travetto/registry';
 
@@ -472,7 +444,7 @@ import type { WebHttpServer } from '../src/types.ts';
 /**
  * Run a web server
  */
-@CliCommand({ runTarget: true, with: { debugIpc: 'optional', restartOnChange: true, module: true, profiles: true } })
+@CliCommand()
 export class WebHttpCommand implements CliCommandShape {
 
   /** Port to run on */
@@ -481,7 +453,19 @@ export class WebHttpCommand implements CliCommandShape {
   /** Kill conflicting port owner */
   killConflict?: boolean = Runtime.localDevelopment;
 
-  preMain(): void {
+  @CliModuleFlag({ short: 'm' })
+  module: string;
+
+  @CliProfilesFlag()
+  profile: string[];
+
+  @CliRestartOnChangeFlag()
+  restartOnChange: boolean = true;
+
+  @CliDebugIpcFlag()
+  debugIpc?: boolean;
+
+  finalize(): void {
     if (this.port) {
       process.env.WEB_HTTP_PORT = `${this.port}`;
     }
@@ -512,32 +496,56 @@ As noted in the example above, `fields` is specified in this execution, with sup
 The `module` field is slightly more complex, but is geared towards supporting commands within a monorepo context.  This flag ensures that a module is specified if running from the root of the monorepo, and that the module provided is real, and can run the desired command.  When running from an explicit module folder in the monorepo, the module flag is ignored.
 
 ### Custom Validation
-In addition to dependency injection, the command contract also allows for a custom validation function, which will have access to bound command (flags, and args) as well as the unknown arguments. When a command implements this method, any [CliValidationError](https://github.com/travetto/travetto/tree/main/module/cli/src/types.ts#L20) errors that are returned will be shared with the user, and fail to invoke the `main` method.
+In addition to dependency injection, the command contract also allows for a custom validation function, which will have access to bound command (flags, and args) as well as the unknown arguments. When a command implements this method, any [ValidationError](https://github.com/travetto/travetto/tree/main/module/schema/src/validate/types.ts#L10) errors that are returned will be shared with the user, and fail to invoke the `main` method.
 
-**Code: CliValidationError**
+**Code: ValidationError**
 ```typescript
-export interface CliValidationError {
+export interface ValidationError {
   /**
    * The error message
    */
   message: string;
   /**
-   * Source of validation
+   * The object path of the error
    */
-  source?: 'flag' | 'arg' | 'custom';
-};
+  path: string;
+  /**
+   * The kind of validation
+   */
+  kind: ValidationKind;
+  /**
+   * The value provided
+   */
+  value?: unknown;
+  /**
+   * Regular expression to match
+   */
+  regex?: string;
+  /**
+   * Number to compare against
+   */
+  limit?: NumericLikeIntrinsic;
+  /**
+   * The type of the field
+   */
+  type?: string;
+  /**
+   * Source of the error
+   */
+  source?: string;
+}
 ```
 
 A simple example of the validation can be found in the `doc` command:
 
 **Code: Simple Validation Example**
 ```typescript
-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' };
-    }
+@Validator(async (cmd) => {
+  const docFile = path.resolve(cmd.input);
+  if (!(await fs.stat(docFile).catch(() => false))) {
+    return { message: `input: ${cmd.input} does not exist`, path: 'input', source: 'flag', kind: 'invalid' };
   }
+})
 ```
 
 ## CLI - service

package/package.json

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

package/src/error.ts

@@ -1,7 +1,8 @@
 import { RuntimeError, Runtime } from '@travetto/runtime';
+import type { ValidationError } from '@travetto/schema';
 
 import { cliTpl } from './color.ts';
-import type { CliValidationError, CliCommandShape } from './types.ts';
+import type { CliCommandShape } from './types.ts';
 
 const COMMAND_PACKAGE = [
   [/^test(:watch)?$/, 'test', false],
@@ -48,10 +49,10 @@ ${{ identifier: install }}
 /**
  * Provides a basic error wrapper for cli validation issues
  */
-export class CliValidationResultError extends RuntimeError<{ errors: CliValidationError[] }> {
+export class CliValidationResultError extends RuntimeError<{ errors: ValidationError[] }> {
   command: CliCommandShape;
 
-  constructor(command: CliCommandShape, errors: CliValidationError[]) {
+  constructor(command: CliCommandShape, errors: ValidationError[]) {
     super('', { details: { errors } });
     this.command = command;
   }

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';
@@ -36,9 +36,9 @@ export class ExecutionManager {
     const [{ instance: command, schema }] = await CliCommandRegistryIndex.load([cmd]);
     const fullArgs = await CliParseUtil.expandArgs(schema, args);
 
-    const state = command._parsed = await CliParseUtil.parse(schema, fullArgs);
+    const state = await CliParseUtil.parse(schema, fullArgs);
+    CliParseUtil.setState(command, state);
 
-    await command.preBind?.();
     const boundArgs = CliCommandSchemaUtil.bindInput(command, state);
     return { command, boundArgs };
   }
@@ -47,11 +47,13 @@ export class ExecutionManager {
   static async #runCommand(cmd: string, args: string[]): Promise<void> {
     const { command, boundArgs } = await this.#bindCommand(cmd, args);
 
-    await command.preValidate?.();
     await CliCommandSchemaUtil.validate(command, boundArgs);
+    const config = CliCommandRegistryIndex.get(getClass(command));
 
-    await command._cfg!.preMain?.(command);
-    await command.preMain?.();
+    for (const preMain of config.preMain ?? []) {
+      await preMain(command);
+    }
+    await command.finalize?.();
 
     ConsoleManager.debug(Runtime.debug);
     await command.main(...boundArgs);

package/src/help.ts

@@ -31,7 +31,7 @@ export class HelpUtil {
     const { name: commandName } = CliCommandRegistryIndex.get(getClass(command));
     const args = schema.methods.main?.parameters ?? [];
 
-    await command.preHelp?.();
+    await command.finalize?.(true);
 
     // Ensure finalized
 

package/src/parse.ts

@@ -20,6 +20,8 @@ export const isBoolFlag = (value?: SchemaInputConfig): boolean => value?.type ==
 
 export type AliasesParseResult = Record<'long' | 'short' | 'raw' | 'env', string[]>;
 
+const STATE_SYMBOL = Symbol();
+
 /**
  * Parsing support for the cli
  */
@@ -238,4 +240,34 @@ export class CliParseUtil {
       return result;
     }, { long: [], short: [], raw: [], env: [] });
   }
+
+  /**
+   * Build aliases for a schema config
+   */
+  static buildAliases(config: { full?: string, short?: string, envVars?: string[] }, ...extraEnvVars: string[]): Partial<SchemaFieldConfig> {
+    const envVars = [...config.envVars ?? [], ...extraEnvVars];
+    return {
+      aliases: [
+        ...(config.full ? [config.full.startsWith('-') ? config.full : `--${config.full}`] : []),
+        ...(config.short ? [config.short.startsWith('-') ? config.short : `-${config.short}`] : []),
+        ...(envVars.length ? envVars.map(CliParseUtil.toEnvField) : [])
+      ]
+    };
+  }
+
+  /**
+   * Get the state from an object
+   */
+  static getState<T extends object>(item: T): ParsedState | undefined {
+    const local: T & { [STATE_SYMBOL]?: ParsedState } = item;
+    return local[STATE_SYMBOL];
+  }
+
+  /**
+   * Set the state
+   */
+  static setState<T extends object>(item: T, state: ParsedState): void {
+    const local: T & { [STATE_SYMBOL]?: ParsedState } = item;
+    local[STATE_SYMBOL] = state;
+  }
 }

package/src/registry/decorator.ts

@@ -1,5 +1,5 @@
-import { type Class, type ClassInstance, Env, Runtime, RuntimeIndex, TypedObject, castTo, describeFunction, getClass } from '@travetto/runtime';
-import { type SchemaFieldConfig, SchemaRegistryIndex, type ValidationError } from '@travetto/schema';
+import { type Class, type ClassInstance, Env, Runtime, RuntimeIndex, castTo, describeFunction, getClass } from '@travetto/runtime';
+import { SchemaRegistryIndex, type ValidationError } from '@travetto/schema';
 
 import type { CliCommandShape } from '../types.ts';
 import { CliCommandRegistryIndex } from './registry-index.ts';
@@ -7,86 +7,15 @@ import { CliModuleUtil } from '../module.ts';
 import { CliParseUtil } from '../parse.ts';
 import { CliUtil } from '../util.ts';
 
-type Cmd = CliCommandShape & { profiles?: string[] };
-
-type CliCommandConfigOptions = {
-  runTarget?: boolean;
-  runtimeModule?: 'current' | 'command';
-  with?: {
-    /** Application environment */
-    profiles?: boolean;
-    /** Module to run for */
-    module?: boolean;
-    /** Should debug invocation trigger via ipc */
-    debugIpc?: boolean | 'optional';
-    /** Should restart on source change */
-    restartOnChange?: boolean | 'optional';
-  };
-};
+type CliCommandConfigOptions = { runTarget?: boolean };
+type CliFlagOptions = { full?: string, short?: string, envVars?: string[] };
 
-type WithConfig = Required<Exclude<CliCommandConfigOptions['with'], undefined>>;
-type WithHandler<K extends keyof WithConfig> = (config?: WithConfig[K]) => ({
-  name: K;
-  field: Partial<SchemaFieldConfig>;
-  run?: (cmd: Cmd) => (Promise<unknown> | unknown);
-} | undefined);
-
-const FIELD_CONFIG: { [K in keyof WithConfig]: WithHandler<K> } = {
-  profiles: (config) => {
-    if (!config) { return; }
-    return {
-      name: 'profiles',
-      run: cmd => cmd.profiles && Env.TRV_PROFILES.set([...cmd.profiles, ...(Env.TRV_PROFILES.list ?? [])]),
-      field: {
-        type: String,
-        aliases: ['--profile', '--profiles', CliParseUtil.toEnvField(Env.TRV_PROFILES.key)],
-        description: 'Application profiles',
-        required: { active: false },
-      },
-    };
-  },
-  module: (config) => {
-    if (!config) { return; }
-    return {
-      name: 'module',
-      field: {
-        type: String,
-        aliases: ['-m', CliParseUtil.toEnvField(Env.TRV_MODULE.key)],
-        description: 'Module to run for',
-        specifiers: ['module'],
-        required: { active: Runtime.monoRoot },
-      },
-    };
-  },
-  debugIpc: (config) => {
-    if (!config) { return; }
-    return {
-      name: 'debugIpc',
-      run: cmd => CliUtil.runWithDebugIpc(cmd),
-      field: {
-        type: Boolean,
-        aliases: ['-di', CliParseUtil.toEnvField(Env.TRV_DEBUG_IPC.key)],
-        description: 'Should debug invocation trigger via ipc',
-        default: config !== 'optional',
-        required: { active: false },
-      },
-    };
-  },
-  restartOnChange: (config) => {
-    if (!config) { return; }
-    return {
-      name: 'restartOnChange',
-      run: cmd => CliUtil.runWithRestartOnChange(cmd),
-      field: {
-        type: Boolean,
-        aliases: ['-rc'],
-        description: 'Should the invocation automatically restart on source changes',
-        default: config !== 'optional' && Runtime.localDevelopment,
-        required: { active: false },
-      },
-    };
-  }
-};
+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
@@ -97,70 +26,139 @@ const FIELD_CONFIG: { [K in keyof WithConfig]: WithHandler<K> } = {
  */
 export function CliCommand(config: CliCommandConfigOptions = {}) {
   return function <T extends CliCommandShape>(target: Class<T>): void {
-    const adapter = SchemaRegistryIndex.getForRegister(target);
-    const description = describeFunction(target) ?? {};
-
-    if (!target.Ⲑid || description.abstract) {
-      return;
+    if (target.Ⲑid && !describeFunction(target)?.abstract) {
+      CliCommandRegistryIndex.getForRegister(target).register(config);
     }
+  };
+}
 
-    const VALID_FIELDS = TypedObject.keys(FIELD_CONFIG).map((name) => FIELD_CONFIG[name](castTo(config.with?.[name]))).filter(x => !!x);
+/**
+ * Decorator to register a CLI command flag
+ * @augments `@travetto/schema:Input`
+ * @kind decorator
+ */
+export function CliFlag(config: CliFlagOptions) {
+  return function (instance: ClassInstance, property: string): void {
+    SchemaRegistryIndex.getForRegister(getClass(instance))
+      .registerField(property, CliParseUtil.buildAliases(config));
+  };
+}
 
-    CliCommandRegistryIndex.getForRegister(target).register({
-      runTarget: config.runTarget,
-      preMain: async (cmd: Cmd) => {
-        for (const field of VALID_FIELDS) {
-          await field.run?.(cmd);
-        }
-      }
+/**
+ * Decorator to register a CLI command file flag
+ * @augments `@travetto/schema:Input`
+ * @kind decorator
+ */
+export function CliFileFlag(config: CliFlagOptions & { fileExtensions: string[] }) {
+  return function (instance: ClassInstance, property: string): void {
+    SchemaRegistryIndex.getForRegister(getClass(instance)).registerField(property, {
+      ...CliParseUtil.buildAliases(config),
+      specifiers: ['file', ...config.fileExtensions.map(ext => `ext:${ext.replace(/[*.]/g, '')}`)]
     });
+  };
+}
 
-    const commandModule = description.module;
+/**
+ * Registers a flag to support profiles via the `TRV_PROFILES` environment variable
+ * @augments `@travetto/schema:Input`
+ * @kind decorator
+ */
+export function CliProfilesFlag(config: CliFlagOptions = {}) {
+  return function <K extends string>(instance: Partial<Record<K, string[]>>, property: K): void {
+    const cls = getClass(instance);
+    SchemaRegistryIndex.getForRegister(cls).registerField(property, {
+      ...CliParseUtil.buildAliases(config, Env.TRV_PROFILES.key),
+      required: { active: false },
+      description: 'Application profiles'
+    });
 
-    for (const { name, field: { type, ...field } } of VALID_FIELDS) {
-      adapter.registerField(name, { type }, field);
-      Object.defineProperty(target.prototype, name, { value: field.default, writable: true });
-    }
+    runBeforeMain(cls, (cmd: typeof instance) =>
+      Env.TRV_PROFILES.set([...cmd[property] ?? [], ...(Env.TRV_PROFILES.list ?? [])])
+    );
+  };
+};
 
-    const runtimeModule = config.runtimeModule ?? (config.with?.module ? 'current' : undefined);
+/**
+ * Registers a flag to support targeting a specific module
+ * @augments `@travetto/schema:Input`
+ * @kind decorator
+ */
+export function CliModuleFlag(config: CliFlagOptions & { scope?: 'current' | 'command' } = { scope: 'current' }) {
+  return function <K extends string>(instance: Partial<Record<K, string>>, property: K): void {
+    const cls = getClass(instance);
+    const description = describeFunction(cls) ?? {};
+    const commandModule = description.module;
 
-    if (runtimeModule) { // Validate module
-      adapter.register({
-        validators: [async ({ module }): Promise<ValidationError | undefined> => {
-          const runModule = (runtimeModule === 'command' ? commandModule : module) || Runtime.main.name;
+    SchemaRegistryIndex.getForRegister(cls).registerField(property, {
+      ...CliParseUtil.buildAliases(config, Env.TRV_MODULE.key),
+      description: 'Module to run for',
+      specifiers: ['module'],
+      required: { active: Runtime.monoRoot },
+    });
 
-          // 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: '.' };
-            }
+    SchemaRegistryIndex.getForRegister(cls).register({
+      validators: [async (cmd: CliCommandShape): Promise<ValidationError | undefined> => {
+        const typed: (typeof cmd) & { [property]?: string } = castTo(cmd);
+        const providedModule = typed[property];
+        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 (!(await CliModuleUtil.moduleHasDependency(runModule, commandModule))) {
-            return { source: 'flag', message: `${runModule} does not have ${commandModule} as a dependency`, kind: 'custom', path: '.' };
-          }
-        }],
-      });
-    }
+        if (!(await CliModuleUtil.moduleHasDependency(runModule, commandModule))) {
+          return { source: 'flag', message: `${runModule} does not have ${commandModule} as a dependency`, kind: 'custom', path: property };
+        }
+      }],
+    });
   };
 }
 
 /**
- * Decorator to register a CLI command flag
+ * Registers a flag to support restarting on source changes
  * @augments `@travetto/schema:Input`
  * @kind decorator
  */
-export function CliFlag(config: { full?: string, short?: string, fileExtensions?: string[], envVars?: string[] } = {}) {
-  return function (instance: ClassInstance, property: string): void {
-    const aliases = [
-      ...(config.full ? [config.full.startsWith('-') ? config.full : `--${config.full}`] : []),
-      ...(config.short ? [config.short.startsWith('-') ? config.short : `-${config.short}`] : []),
-      ...(config.envVars ? config.envVars.map(CliParseUtil.toEnvField) : [])
-    ];
-    const specifiers = config.fileExtensions?.length ? ['file', ...config.fileExtensions.map(ext => `ext:${ext.replace(/[*.]/g, '')}`)] : [];
-
-    SchemaRegistryIndex.getForRegister(getClass(instance)).registerField(property, { aliases, specifiers });
+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);
+    SchemaRegistryIndex.getForRegister(cls).registerField(property, {
+      ...CliParseUtil.buildAliases(config),
+      description: 'Should the invocation automatically restart on source changes',
+      default: Runtime.localDevelopment,
+      required: { active: false },
+    });
+
+    runBeforeMain(cls, (cmd: typeof instance) => CliUtil.runWithRestartOnChange(cmd[property]), true);
+  };
+}
+
+/**
+ * Registers a flag to support debugging invocations triggered via IPC
+ * @augments `@travetto/schema:Input`
+ * @kind decorator
+ */
+export function CliDebugIpcFlag(config: CliFlagOptions = {}) {
+  return function <K extends string, T extends Partial<Record<K, boolean>>>(instance: T, property: K): void {
+    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 },
+    });
+
+    runBeforeMain(cls,
+      (cmd: typeof instance & CliCommandShape) => {
+        const cliConfig = CliCommandRegistryIndex.get(cls);
+        return cmd[property] && CliUtil.runWithDebugIpc(cliConfig.name);
+      },
+      true
+    );
   };
 }

package/src/registry/registry-adapter.ts

@@ -11,6 +11,16 @@ const getName = (name: string): string => (name.match(CLI_FILE_REGEX)?.groups?.n
 const stripDashes = (flag?: string): string | undefined => flag?.replace(/^-+/, '');
 const toFlagName = (field: string): string => field.replace(/([a-z])([A-Z])/g, (_, left: string, right: string) => `${left}-${right.toLowerCase()}`);
 
+function combineClasses(base: CliCommandConfig, ...configs: Partial<CliCommandConfig>[]): CliCommandConfig {
+  for (const config of configs) {
+    base.runTarget = config.runTarget ?? base.runTarget;
+    if (config.preMain) {
+      base.preMain = [...base.preMain ?? [], ...config.preMain ?? []];
+    }
+  }
+  return base;
+}
+
 export class CliCommandRegistryAdapter implements RegistryAdapter<CliCommandConfig> {
   #cls: Class;
   #config: CliCommandConfig;
@@ -76,17 +86,14 @@ 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) };
-    Object.assign(this.#config, ...configs);
-    return this.#config;
+    this.#config ??= { cls: this.#cls, name: getName(metadata.import), preMain: [], runTarget: true };
+    return combineClasses(this.#config, ...configs);
   }
 
   /**
    * Get instance of the command
    */
   getInstance(): CliCommandShape {
-    const instance: CliCommandShape = classConstruct(this.#cls);
-    instance._cfg = this.#config;
-    return instance;
+    return classConstruct(this.#cls);
   }
 }

package/src/registry/registry-index.ts

@@ -92,9 +92,6 @@ export class CliCommandRegistryIndex implements RegistryIndex {
         continue;
       }
       const result = config.getInstance();
-      if (result.isActive !== undefined && !result.isActive()) {
-        continue;
-      }
       this.#instanceMapping.set(name, result);
       return result;
     }

package/src/schema.ts

@@ -1,19 +1,30 @@
 import { castKey, castTo, getClass } from '@travetto/runtime';
-import { BindUtil, SchemaRegistryIndex, SchemaValidator, ValidationResultError } from '@travetto/schema';
+import { BindUtil, SchemaRegistryIndex, SchemaValidator, ValidationResultError, type ValidationError } from '@travetto/schema';
 
-import type { ParsedState, CliCommandShape, CliValidationError } from './types.ts';
+import type { ParsedState, CliCommandShape } from './types.ts';
 import { CliValidationResultError } from './error.ts';
 
-const getSource = (source: string | undefined, def: CliValidationError['source']): CliValidationError['source'] => {
+const getSource = (source: string | undefined, defaultSource: ValidationError['source']): ValidationError['source'] => {
   switch (source) {
     case 'custom':
     case 'arg':
     case 'flag': return source;
-    case undefined: return def;
+    case undefined: return defaultSource;
     default: return 'custom';
   }
 };
 
+const transformErrors = (source: 'arg' | 'flag', error: unknown): ValidationError[] => {
+  if (error instanceof CliValidationResultError || error instanceof ValidationResultError) {
+    return error.details.errors.map(value => ({ source: getSource(value.source, source), ...value }));
+  } else {
+    throw error;
+  }
+};
+
+const transformArgErrors = (error: unknown): ValidationError[] => transformErrors('arg', error);
+const transformFlagErrors = (error: unknown): ValidationError[] => transformErrors('flag', error);
+
 /**
  * Allows binding describing/binding inputs for commands
  */
@@ -59,27 +70,12 @@ export class CliCommandSchemaUtil {
     const cls = getClass(cmd);
     const paramNames = SchemaRegistryIndex.get(cls).getMethod('main').parameters.map(config => config.name!);
 
-    const validators = [
-      (): Promise<void> => SchemaValidator.validate(cls, cmd).then(() => { }),
-      (): Promise<void> => SchemaValidator.validateMethod(cls, 'main', args, paramNames),
-      async (): Promise<void> => {
-        const result = await cmd.validate?.(...args);
-        if (result) {
-          throw new CliValidationResultError(cmd, Array.isArray(result) ? result : [result]);
-        }
-      },
-    ];
-
-    const SOURCES = ['flag', 'arg', 'custom'] as const;
-
-    const results = validators.map((validator, i) => validator().catch(error => {
-      if (!(error instanceof CliValidationResultError) && !(error instanceof ValidationResultError)) {
-        throw error;
-      }
-      return error.details.errors.map(value => ({ ...value, source: getSource(value.source, SOURCES[i]) }));
-    }));
+    const results = await Promise.all([
+      SchemaValidator.validate(cls, cmd).then(() => [], transformFlagErrors),
+      SchemaValidator.validateMethod(cls, 'main', args, paramNames).then(() => [], transformArgErrors),
+    ]);
 
-    const errors = (await Promise.all(results)).flatMap(result => (result ?? []));
+    const errors = results.flat();
     if (errors.length) {
       throw new CliValidationResultError(cmd, errors);
     }

package/src/types.ts

@@ -13,89 +13,26 @@ export type ParsedState = {
   unknown: string[];
 };
 
-/**
- * Constrained version of Schema's Validation Error
- * @concrete
- */
-export interface CliValidationError {
-  /**
-   * The error message
-   */
-  message: string;
-  /**
-   * Source of validation
-   */
-  source?: 'flag' | 'arg' | 'custom';
-};
-
 /**
  * CLI Command Contract
  * @concrete
  */
-export interface CliCommandShape<T extends unknown[] = unknown[]> {
-  /**
-   * Parsed state
-   */
-  _parsed?: ParsedState;
-  /**
-   * Config
-   */
-  _cfg?: CliCommandConfig;
+export interface CliCommandShape {
   /**
    * Action target of the command
    */
-  main(...args: T): OrProm<undefined | void>;
+  main(...args: unknown[]): OrProm<undefined | void>;
   /**
    * Run before main runs
    */
-  preMain?(): OrProm<void>;
+  finalize?(help?: boolean): OrProm<void>;
   /**
    * Extra help
    */
   help?(): OrProm<string[]>;
-  /**
-   * Run before help is displayed
-   */
-  preHelp?(): OrProm<void>;
-  /**
-   * Is the command active/eligible for usage
-   */
-  isActive?(): boolean;
-  /**
-   * Run before binding occurs
-   */
-  preBind?(): OrProm<void>;
-  /**
-   * Run before validation occurs
-   */
-  preValidate?(): OrProm<void>;
-  /**
-   * Validation method
-   */
-  validate?(...args: T): OrProm<CliValidationError | CliValidationError[] | undefined>;
 }
 
-/**
- * Command shape common fields
- */
-export type CliCommandShapeFields = {
-  /**
-   * Profiles to run the application under
-   */
-  profiles?: string[];
-  /**
-   * Should the cli invocation trigger a debug session, via IPC
-   */
-  debugIpc?: boolean;
-  /**
-   * Should the invocation run with auto-restart on source changes
-   */
-  restartOnChange?: boolean;
-  /**
-   * The module to run the command from
-   */
-  module?: string;
-};
+type PreMainHandler = (cmd: CliCommandShape) => (unknown | Promise<unknown>);
 
 /**
  * CLI Command schema shape
@@ -104,5 +41,5 @@ export interface CliCommandConfig {
   cls: Class<CliCommandShape>;
   name: string;
   runTarget?: boolean;
-  preMain?: (cmd: CliCommandShape) => void | Promise<void>;
+  preMain?: PreMainHandler[];
 }

package/src/util.ts

@@ -2,8 +2,6 @@ import { spawn, type ChildProcess } from 'node:child_process';
 
 import { RuntimeError, JSONUtil, Env, ExecUtil, Runtime, ShutdownManager, Util, WatchUtil } from '@travetto/runtime';
 
-import type { CliCommandShape, CliCommandShapeFields } from './types.ts';
-
 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) || (
@@ -16,24 +14,19 @@ export class CliUtil {
    */
   static getSimpleModuleName(placeholder: string, module?: string): string {
     const simple = (module ?? Runtime.main.name).replace(/[\/]/, '_').replace(/@/, '');
-    if (!simple) {
-      return placeholder;
-    } else if (!module && Runtime.monoRoot) {
-      return placeholder;
-    } else {
-      return placeholder.replace('<module>', simple);
-    }
+    const targetModule = !simple || (!module && Runtime.monoRoot) ? '<module>' : simple;
+    return placeholder.replace('<module>', targetModule);
   }
 
   /**
    * Run a command as restartable, linking into self
    */
-  static async runWithRestartOnChange<T extends CliCommandShapeFields>(cmd: T): Promise<void> {
+  static async runWithRestartOnChange(restartOnChange?: boolean): Promise<void> {
     if (Env.TRV_RESTART_TARGET.isTrue) {
       Env.TRV_RESTART_TARGET.clear();
       ShutdownManager.disableInterrupt();
       return;
-    } else if (cmd.restartOnChange !== true) {
+    } else if (restartOnChange !== true) {
       return; // Not restarting, run normal
     }
 
@@ -72,13 +65,14 @@ export class CliUtil {
   /**
    * Dispatch IPC payload
    */
-  static async runWithDebugIpc<T extends CliCommandShapeFields & CliCommandShape>(cmd: T): Promise<void> {
-    if (cmd.debugIpc !== true || !Env.TRV_CLI_IPC.isSet) {
+  static async runWithDebugIpc(name: string): Promise<void> {
+    if (!Env.TRV_CLI_IPC.isSet) {
       return; // Not debugging, run normal
     }
 
-    const info = await fetch(Env.TRV_CLI_IPC.value!).catch(() => ({ ok: false }));
+    const doFetch = fetch.bind(null, Env.TRV_CLI_IPC.value!);
 
+    const info = await doFetch().catch(() => ({ ok: false }));
     if (!info.ok) {
       return; // Server not running, run normal
     }
@@ -87,16 +81,16 @@ export class CliUtil {
     const request = {
       type: '@travetto/cli:run',
       data: {
-        name: cmd._cfg!.name,
+        name,
         env,
-        module: cmd.module ?? Runtime.main.name,
+        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!));
-    const sent = await fetch(Env.TRV_CLI_IPC.value!, { method: 'POST', body: JSONUtil.toUTF8(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()}`);

package/support/bin/util.ts

@@ -0,0 +1,16 @@
+import { RuntimeIndex, Runtime } from '@travetto/runtime';
+import type { ServiceDescriptor } from '../../__index__.ts';
+
+export async function getServices(services: string[]): Promise<ServiceDescriptor[]> {
+  return (await Promise.all(
+    RuntimeIndex.find({
+      module: module => module.roles.includes('std'),
+      folder: folder => folder === 'support',
+      file: file => /support\/service[.]/.test(file.sourceFile)
+    })
+      .map(file => Runtime.importFrom<{ service: ServiceDescriptor }>(file.import).then(value => value.service))
+  ))
+    .filter(file => !!file)
+    .filter(file => services?.length ? services.includes(file.name) : true)
+    .toSorted((a, b) => a.name.localeCompare(b.name));
+}

package/support/cli.cli_schema.ts

@@ -1,12 +1,29 @@
 import { Env } from '@travetto/runtime';
-import { IsPrivate } from '@travetto/schema';
+import { IsPrivate, MethodValidator, type ValidationError } from '@travetto/schema';
 
 import { CliCommand } from '../src/registry/decorator.ts';
-import type { CliCommandShape, CliValidationError } from '../src/types.ts';
+import type { CliCommandShape } from '../src/types.ts';
 import { CliCommandRegistryIndex } from '../src/registry/registry-index.ts';
 import { CliUtil } from '../src/util.ts';
 import { CliSchemaExportUtil } from '../src/schema-export.ts';
 
+async function nameValidator(names?: string[]): Promise<ValidationError | undefined> {
+  if (!names || names.length === 0) {
+    return;
+  }
+  const resolved = await CliCommandRegistryIndex.load(names);
+  const invalid = names.find(name => !resolved.find(result => result.command === name));
+
+  if (invalid) {
+    return {
+      source: 'arg',
+      kind: 'invalid',
+      path: 'names',
+      message: `name: ${invalid} is not a valid cli command`
+    };
+  }
+}
+
 /**
  * Generates the schema for all CLI operations
  */
@@ -14,25 +31,11 @@ import { CliSchemaExportUtil } from '../src/schema-export.ts';
 @IsPrivate()
 export class CliSchemaCommand implements CliCommandShape {
 
-  async validate(names?: string[]): Promise<CliValidationError | undefined> {
-    if (!names || names.length === 0) {
-      return;
-    }
-    const resolved = await CliCommandRegistryIndex.load(names);
-    const invalid = names.find(name => !resolved.find(result => result.command === name));
-
-    if (invalid) {
-      return {
-        source: 'arg',
-        message: `name: ${invalid} is not a valid cli command`
-      };
-    }
-  }
-
-  preMain(): void {
+  finalize(): void {
     Env.DEBUG.set(false);
   }
 
+  @MethodValidator(nameValidator)
   async main(names?: string[]): Promise<void> {
     const resolved = await CliCommandRegistryIndex.load(names);
 

package/support/cli.main.ts

@@ -1,6 +1,14 @@
 import { JSONUtil, Runtime } from '@travetto/runtime';
-import { type CliCommandShape, CliCommand, type CliValidationError, type ParsedState } from '@travetto/cli';
-import { Ignore, IsPrivate } from '@travetto/schema';
+import { type CliCommandShape, CliCommand, CliParseUtil } from '@travetto/cli';
+import { IsPrivate, MethodValidator, type ValidationError } from '@travetto/schema';
+
+async function validateMain(fileOrImport: string): Promise<ValidationError | undefined> {
+  try {
+    await Runtime.importFrom(fileOrImport);
+  } catch {
+    return { message: `Unknown file: ${fileOrImport}`, source: 'arg', kind: 'invalid', path: 'fileOrImport' };
+  }
+};
 
 /**
  * Allows for running of main entry points
@@ -9,22 +17,13 @@ import { Ignore, IsPrivate } from '@travetto/schema';
 @IsPrivate()
 export class MainCommand implements CliCommandShape {
 
-  @Ignore()
-  _parsed: ParsedState;
-
-  async validate(fileOrImport: string): Promise<CliValidationError | undefined> {
-    try {
-      await Runtime.importFrom(fileOrImport);
-    } catch {
-      return { message: `Unknown file: ${fileOrImport}` };
-    }
-  }
-
+  @MethodValidator(validateMain)
   async main(fileOrImport: string, args: string[] = []): Promise<void> {
+    const parsed = CliParseUtil.getState(this);
     let result: unknown;
     try {
       const module = await Runtime.importFrom<{ main(..._: unknown[]): Promise<unknown> }>(fileOrImport);
-      result = await module.main(...args, ...this._parsed.unknown);
+      result = await module.main(...args, ...parsed?.unknown ?? []);
     } catch (error) {
       result = error;
       process.exitCode = Math.max(process.exitCode ? +process.exitCode : 1, 1);

package/support/cli.service.ts

@@ -1,8 +1,18 @@
-import { type CliCommandShape, CliCommand, cliTpl, type CliValidationError } from '@travetto/cli';
+import { type CliCommandShape, CliCommand, cliTpl } from '@travetto/cli';
 import { Terminal } from '@travetto/terminal';
-import { AsyncQueue, Runtime, RuntimeIndex, Util } from '@travetto/runtime';
+import { AsyncQueue, Util } from '@travetto/runtime';
+import { MethodValidator, type ValidationError } from '@travetto/schema';
 
-import { ServiceRunner, type ServiceDescriptor, type ServiceAction } from '../src/service.ts';
+import { ServiceRunner, type ServiceAction } from '../src/service.ts';
+import { getServices } from './bin/util.ts';
+
+async function validateService(action: ServiceAction, services: string[]): Promise<ValidationError | undefined> {
+  const all = await getServices(services);
+
+  if (!all.length) {
+    return { message: 'No services found', source: 'arg', kind: 'invalid', path: 'services' };
+  }
+}
 
 /**
  * Allows for running services
@@ -10,30 +20,8 @@ import { ServiceRunner, type ServiceDescriptor, type ServiceAction } from '../sr
 @CliCommand()
 export class CliServiceCommand implements CliCommandShape {
 
-  async #getServices(services: string[]): Promise<ServiceDescriptor[]> {
-    return (await Promise.all(
-      RuntimeIndex.find({
-        module: module => module.roles.includes('std'),
-        folder: folder => folder === 'support',
-        file: file => /support\/service[.]/.test(file.sourceFile)
-      })
-        .map(file => Runtime.importFrom<{ service: ServiceDescriptor }>(file.import).then(value => value.service))
-    ))
-      .filter(file => !!file)
-      .filter(file => services?.length ? services.includes(file.name) : true)
-      .toSorted((a, b) => a.name.localeCompare(b.name));
-  }
-
-  async validate(action: ServiceAction, services: string[]): Promise<CliValidationError | undefined> {
-    const all = await this.#getServices(services);
-
-    if (!all.length) {
-      return { message: 'No services found' };
-    }
-  }
-
   async help(): Promise<string[]> {
-    const all = await this.#getServices([]);
+    const all = await getServices([]);
     return [
       cliTpl`${{ title: 'Available Services' }}`,
       '-'.repeat(20),
@@ -41,8 +29,9 @@ export class CliServiceCommand implements CliCommandShape {
     ];
   }
 
+  @MethodValidator(validateService)
   async main(action: ServiceAction, services: string[] = []): Promise<void> {
-    const all = await this.#getServices(services);
+    const all = await getServices(services);
     const maxName = Math.max(...all.map(service => service.name.length), 'Service'.length) + 3;
     const maxVersion = Math.max(...all.map(service => `${service.version}`.length), 'Version'.length) + 3;
     const maxStatus = 20;