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

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
@@ -550,7 +558,8 @@ $ trv service --help
 Usage: service [options] <action:restart|start|status|stop> [services...:string]
 
 Options:
-  -h, --help  display help for command
+  -q, --quiet   (default: false)
+  -h, --help   display help for command
 
 Available Services
 --------------------

package/__index__.ts

@@ -1,7 +1,6 @@
 import type { } from './src/trv.d.ts';
 export * from './src/types.ts';
 export * from './src/execute.ts';
-export * from './src/error.ts';
 export * from './src/schema.ts';
 export * from './src/schema-export.ts';
 export * from './src/registry/decorator.ts';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@travetto/cli",
-  "version": "8.0.0-alpha.0",
+  "version": "8.0.0-alpha.2",
   "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/execute.ts

@@ -3,7 +3,6 @@ import { ConsoleManager, Runtime, ShutdownManager, Util } from '@travetto/runtim
 import { HelpUtil } from './help.ts';
 import { CliCommandRegistryIndex } from './registry/registry-index.ts';
 import { CliCommandSchemaUtil } from './schema.ts';
-import { CliUnknownCommandError, CliValidationResultError } from './error.ts';
 import { CliParseUtil } from './parse.ts';
 import type { CliCommandShape } from './types.ts';
 
@@ -12,71 +11,46 @@ import type { CliCommandShape } from './types.ts';
  */
 export class ExecutionManager {
 
-  /** Error handler */
-  static async #onError(error: unknown): Promise<void> {
-    process.exitCode ??= 1;
-    if (error instanceof CliValidationResultError) {
-      console.error!(HelpUtil.renderValidationError(error));
-      console.error!(await HelpUtil.renderCommandHelp(error.command));
-    } else if (error instanceof CliUnknownCommandError) {
-      if (error.help) {
-        console.error!(error.help);
-      } else {
-        console.error!(error.defaultMessage, '\n');
-        console.error!(await HelpUtil.renderAllHelp(''));
-      }
-    } else {
-      console.error!(error);
-    }
-    console.error!();
-  }
-
-  /** Bind command  */
-  static async #bindCommand(cmd: string, args: string[]): Promise<{ command: CliCommandShape, boundArgs: unknown[] }> {
-    const [{ instance: command, schema }] = await CliCommandRegistryIndex.load([cmd]);
-    const fullArgs = await CliParseUtil.expandArgs(schema, args);
+  /**
+   * Execute the command line
+   * @param args
+   */
+  static async run(argv: string[]): Promise<void> {
+    let command: CliCommandShape | undefined;
 
-    const state = command._parsed = await CliParseUtil.parse(schema, fullArgs);
+    const { cmd, args, help } = CliParseUtil.getArgs(argv);
+    if (!cmd) {
+      return console.info!(await HelpUtil.renderAllHelp());
+    }
 
-    await command.preBind?.();
-    const boundArgs = CliCommandSchemaUtil.bindInput(command, state);
-    return { command, boundArgs };
-  }
+    try {
+      const [{ instance, schema, config }] = await CliCommandRegistryIndex.load([cmd]);
+      command = instance;
+      const fullArgs = await CliParseUtil.expandArgs(schema, args);
 
-  /** Run command */
-  static async #runCommand(cmd: string, args: string[]): Promise<void> {
-    const { command, boundArgs } = await this.#bindCommand(cmd, args);
+      const state = await CliParseUtil.parse(schema, fullArgs);
+      CliParseUtil.setState(instance, state);
 
-    await command.preValidate?.();
-    await CliCommandSchemaUtil.validate(command, boundArgs);
+      const boundArgs = CliCommandSchemaUtil.bindInput(instance, state);
+      await instance.finalize?.(help);
 
-    await command._cfg!.preMain?.(command);
-    await command.preMain?.();
+      if (help) {
+        return console.log!(await HelpUtil.renderCommandHelp(instance));
+      }
 
-    ConsoleManager.debug(Runtime.debug);
-    await command.main(...boundArgs);
-  }
+      await CliCommandSchemaUtil.validate(command, boundArgs);
 
-  /**
-   * Execute the command line
-   * @param args
-   */
-  static async run(argv: string[]): Promise<void> {
-    try {
       // Wait 50ms to allow stdout to flush on shutdown
       ShutdownManager.signal.addEventListener('abort', () => Util.blockingTimeout(50));
 
-      const { cmd, args, help } = CliParseUtil.getArgs(argv);
-      if (!cmd) {
-        console.info!(await HelpUtil.renderAllHelp());
-      } else if (help) {
-        const { command } = await this.#bindCommand(cmd, args);
-        console.log!(await HelpUtil.renderCommandHelp(command));
-      } else {
-        await this.#runCommand(cmd, args);
+      for (const preMain of config.preMain ?? []) {
+        await preMain(instance);
       }
+
+      ConsoleManager.debug(Runtime.debug);
+      await instance.main(...boundArgs);
     } catch (error) {
-      await this.#onError(error);
+      await HelpUtil.renderError(error, cmd, command);
     } finally {
       await ShutdownManager.shutdown();
     }

package/src/help.ts

@@ -1,12 +1,11 @@
 import util from 'node:util';
 
-import { castKey, getClass, JSONUtil } from '@travetto/runtime';
-import { SchemaRegistryIndex } from '@travetto/schema';
+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 { CliCommandRegistryIndex } from './registry/registry-index.ts';
-import type { CliValidationResultError } from './error.ts';
+import { CliCommandRegistryIndex, UNKNOWN_COMMAND } from './registry/registry-index.ts';
 import { CliSchemaExportUtil } from './schema-export.ts';
 
 const validationSourceMap: Record<string, string> = {
@@ -17,11 +16,39 @@ const validationSourceMap: Record<string, string> = {
 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),
+]);
+
 /**
  * Utilities for showing help
  */
 export class HelpUtil {
 
+  /** Render the unknown command message */
+  static renderUnknownCommandMessage(cmd: string): string {
+    const install = INSTALL_COMMANDS.get(cmd);
+    if (install) {
+      return cliTpl`
+${{ title: 'Missing Package' }}\n${'-'.repeat(20)}\nTo use ${{ input: cmd }} please run:\n
+${{ identifier: install }}
+`;
+    } else {
+      return cliTpl`${{ subtitle: 'Unknown command' }}: ${{ input: cmd }}`;
+    }
+  }
+
   /**
    * Render command-specific help
    * @param command
@@ -31,8 +58,6 @@ export class HelpUtil {
     const { name: commandName } = CliCommandRegistryIndex.get(getClass(command));
     const args = schema.methods.main?.parameters ?? [];
 
-    await command.preHelp?.();
-
     // Ensure finalized
 
     const usage: string[] = [cliTpl`${{ title: 'Usage:' }} ${{ param: commandName }} ${{ input: '[options]' }}`,];
@@ -132,7 +157,7 @@ export class HelpUtil {
   /**
    * Render validation error to a string
    */
-  static renderValidationError(validationError: CliValidationResultError): string {
+  static renderValidationError(validationError: ValidationResultError): string {
     return [
       cliTpl`${{ failure: 'Execution failed' }}:`,
       ...validationError.details.errors.map(error => {
@@ -144,4 +169,20 @@ export class HelpUtil {
       '',
     ].join('\n');
   }
+
+  /** Error handler */
+  static async renderError(error: unknown, cmd: string, command?: CliCommandShape): Promise<void> {
+    process.exitCode ??= 1;
+    if (error instanceof ValidationResultError) {
+      console.error!(this.renderValidationError(error));
+    }
+    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

@@ -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;
+  }
 }