@travetto/cli 3.1.0-rc.0 → 3.1.0-rc.2

package/README.md

@@ -130,9 +130,9 @@ HELLO
 
 The [@CliCommand](https://github.com/travetto/travetto/tree/main/module/cli/src/decorators.ts#L20) supports the following data types for flags:
    *  Boolean values
-   *  Number values. The [@Integer](https://github.com/travetto/travetto/tree/main/module/schema/src/decorator/field.ts#L179), [@Float](https://github.com/travetto/travetto/tree/main/module/schema/src/decorator/field.ts#L185), [@Precision](https://github.com/travetto/travetto/tree/main/module/schema/src/decorator/field.ts#L173), [@Min](https://github.com/travetto/travetto/tree/main/module/schema/src/decorator/field.ts#L114) and [@Max](https://github.com/travetto/travetto/tree/main/module/schema/src/decorator/field.ts#L124) decorators help provide additional validation.
-   *  String values. [@MinLength](https://github.com/travetto/travetto/tree/main/module/schema/src/decorator/field.ts#L114), [@MaxLength](https://github.com/travetto/travetto/tree/main/module/schema/src/decorator/field.ts#L124), [@Match](https://github.com/travetto/travetto/tree/main/module/schema/src/decorator/field.ts#L106) and [@Enum](https://github.com/travetto/travetto/tree/main/module/schema/src/decorator/field.ts#L85) provide additional constraints
-   *  Date values. The [@Min](https://github.com/travetto/travetto/tree/main/module/schema/src/decorator/field.ts#L114) and [@Max](https://github.com/travetto/travetto/tree/main/module/schema/src/decorator/field.ts#L124) decorators help provide additional validation.
+   *  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
+   *  Date values. The [@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 lists. Same as String, but allowing multiple values.
    *  Numeric lists. Same as Number, but allowing multiple values.
 
@@ -168,7 +168,7 @@ Options:
 $ trv basic:arg 20
 
 Execution failed:
- * volume is bigger than (10). [1]
+ * Argument volume is bigger than (10)
 
 Usage: doc/cli.basic:arg [options] [volume:number]
 
@@ -231,7 +231,7 @@ $ trv basic:arglist 10 5 3 9 8 1
 $ trv basic:arglist 10 5 3 9 20 1
 
 Execution failed:
- * volumes[4] is bigger than (10). [1]
+ * Argument volumes[4] is bigger than (10)
 
 Usage: doc/cli.basic:arglist [options] <volumes...:number>
 
@@ -358,7 +358,7 @@ 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).
+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#L20) decorator.  This means the target will be visible within the editor tooling.
 
 **Code: Simple Run Target**
 ```typescript
@@ -376,9 +376,43 @@ export class RunCommand {
 }
 ```
 
-Also, any command name that starts with `run:` (i.e. `support/cli.run_*.ts`), will be opted-in to the run behavior unless explicitly disabled.
-
 ## Advanced Usage
+
+**Code: Anatomy of a Command**
+```typescript
+export interface CliCommandShape {
+  /**
+   * Action target of the command
+   */
+  main(...args: unknown[]): OrProm<RunResponse>;
+  /**
+   * Setup environment before command runs
+   */
+  envInit?(): OrProm<GlobalEnvConfig>;
+  /**
+   * Extra help
+   */
+  help?(): OrProm<string[]>;
+  /**
+   * Is the command active/eligible for usage
+   */
+  isActive?(): boolean;
+  /**
+   * Run before binding occurs
+   */
+  initialize?(): OrProm<void>;
+  /**
+   * Run before validation occurs
+   */
+  finalize?(unknownArgs: string[]): OrProm<void>;
+  /**
+   * Validation method
+   */
+  validate?(...unknownArgs: unknown[]): OrProm<CliValidationError | CliValidationError[] | undefined>;
+}
+```
+
+### Dependency Injection
 If the goal is to run a more complex application, which may include depending on [Dependency Injection](https://github.com/travetto/travetto/tree/main/module/di#readme "Dependency registration/management and injection support."), we can take a look at [RESTful API](https://github.com/travetto/travetto/tree/main/module/rest#readme "Declarative api for RESTful APIs with support for the dependency injection module.")'s target:
 
 **Code: Simple Run Target**
@@ -390,7 +424,7 @@ import { ServerHandle } from '../src/types';
 /**
  * Run a rest server as an application
  */
-@CliCommand({ fields: ['module', 'env', 'profile'] })
+@CliCommand({ runTarget: true, fields: ['module', 'env', 'profile'] })
 export class RunRestCommand {
 
   /** Port to run on */
@@ -410,3 +444,32 @@ export class RunRestCommand {
 As noted in the example above, `fields` is specified in this execution, with support for `module`, `env`, and `profile`. These env and profile flags are directly tied to the GlobalEnv flags defined in the [Base](https://github.com/travetto/travetto/tree/main/module/base#readme "Environment config and common utilities for travetto applications.") module. 
 
 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#L10) errors that are returned will be shared with the user, and fail to invoke the `main` method.
+
+**Code: CliValidationError**
+```typescript
+export type CliValidationError = {
+  /**
+   * The error message
+   */
+  message: string;
+  /**
+   * Source of validation
+   */
+  source?: 'flag' | 'arg' | 'custom';
+};
+```
+
+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> {
+    const docFile = path.resolve(this.input);
+    if (!(await fs.stat(docFile).catch(() => false))) {
+      return { message: `input: ${this.input} does not exist`, source: 'flag' };
+    }
+  }
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@travetto/cli",
-  "version": "3.1.0-rc.0",
+  "version": "3.1.0-rc.2",
   "description": "CLI infrastructure for Travetto framework",
   "keywords": [
     "cli",
@@ -24,7 +24,7 @@
     "directory": "module/cli"
   },
   "dependencies": {
-    "@travetto/schema": "^3.1.0-rc.0",
+    "@travetto/schema": "^3.1.0-rc.2",
     "@travetto/terminal": "^3.1.0-rc.0",
     "@travetto/worker": "^3.1.0-rc.0"
   },

package/src/decorators.ts

@@ -35,7 +35,6 @@ export function CliCommand(cfg: { fields?: ExtraFields[], runTarget?: boolean, h
       // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
       cls: target as ConcreteClass<T>,
       hidden: cfg.hidden,
-      runTarget: cfg.runTarget ?? name.startsWith('run:'),
       preMain: (cmd: CliCommandShape & { env?: string, profile?: string[], module?: string }) => {
         if (addEnv) { defineGlobalEnv({ envName: cmd.env }); }
         if (addProfile) { defineGlobalEnv({ profiles: cmd.profile }); }
@@ -72,10 +71,11 @@ export function CliCommand(cfg: { fields?: ExtraFields[], runTarget?: boolean, h
       });
 
       // Register validator for module
-      (pendingCls.validators ??= []).push(item =>
+      (pendingCls.validators ??= []).push(async item => {
         // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
-        CliModuleUtil.validateCommandModule(getMod(target), item as { module?: string })
-      );
+        const res = await CliModuleUtil.validateCommandModule(getMod(target), item as { module?: string });
+        return res ? { ...res, kind: 'custom', path: '.' } : res;
+      });
     }
   };
 }

package/src/help.ts

@@ -6,6 +6,12 @@ import { CliCommandShape, CliValidationResultError } from './types';
 import { CliCommandRegistry } from './registry';
 import { CliCommandSchemaUtil } from './schema';
 
+const validationSourceMap = {
+  custom: '',
+  arg: 'Argument',
+  flag: 'Flag'
+};
+
 /**
  * Utilities for showing help
  */
@@ -93,12 +99,20 @@ export class HelpUtil {
     const maxWidth = keys.reduce((a, b) => Math.max(a, stripAnsiCodes(b).length), 0);
 
     for (const cmd of keys) {
-      const inst = await CliCommandRegistry.getInstance(cmd);
-      if (inst) {
-        const cfg = await CliCommandRegistry.getConfig(inst);
-        if (!cfg.hidden) {
-          const schema = await CliCommandSchemaUtil.getSchema(inst);
-          rows.push(cliTpl`  ${{ param: cmd.padEnd(maxWidth, ' ') }} ${{ title: schema.title }}`);
+      try {
+        const inst = await CliCommandRegistry.getInstance(cmd);
+        if (inst) {
+          const cfg = await CliCommandRegistry.getConfig(inst);
+          if (!cfg.hidden) {
+            const schema = await CliCommandSchemaUtil.getSchema(inst);
+            rows.push(cliTpl`  ${{ param: cmd.padEnd(maxWidth, ' ') }} ${{ title: schema.title }}`);
+          }
+        }
+      } catch (err) {
+        if (err instanceof Error) {
+          rows.push(cliTpl`  ${{ param: cmd.padEnd(maxWidth, ' ') }} ${{ failure: err.message.split(/\n/)[0] }}`);
+        } else {
+          throw err;
         }
       }
     }
@@ -124,7 +138,9 @@ export class HelpUtil {
   static renderValidationError(cmd: CliCommandShape, err: CliValidationResultError): string {
     return [
       cliTpl`${{ failure: 'Execution failed' }}:`,
-      ...err.errors.map(e => cliTpl` * ${{ failure: e.message }}`),
+      ...err.errors.map(e => e.source && e.source !== 'custom' ?
+        cliTpl` * ${{ identifier: validationSourceMap[e.source] }} ${{ subtitle: e.message }}` :
+        cliTpl` * ${{ failure: e.message }}`),
       '',
     ].join('\n');
   }

package/src/module.ts

@@ -27,7 +27,7 @@ const COLORS = TypedObject.keys(NAMED_COLORS)
 
 const colorize = (val: string, idx: number): string => COLORS[idx % COLORS.length](val);
 
-const modError = (message: string): CliValidationError => ({ kind: 'required', path: 'module', message });
+const modError = (message: string): CliValidationError => ({ source: 'flag', message: `module: ${message}` });
 
 /**
  * Simple utilities for understanding modules for CLI use cases

package/src/schema.ts

@@ -22,6 +22,10 @@ function fieldToInput(x: FieldConfig): CliCommandInput {
   });
 }
 
+const VALID_FLAG = /^-{1,2}[a-z]/i;
+const LONG_FLAG = /^--[a-z]/i;
+const SHORT_FLAG = /^-[a-z]/i;
+
 const isBoolFlag = (x: CliCommandInput): boolean => x.type === 'boolean' && !x.array;
 
 /**
@@ -55,7 +59,7 @@ export class CliCommandSchemaUtil {
     }
 
     const schema = await SchemaRegistry.getViewSchema(cls);
-    const flags = [...Object.values(schema.schema)].filter(v => !v.forMethod).map(fieldToInput);
+    const flags = Object.values(schema.schema).map(fieldToInput);
 
     // Add help command
     flags.push({ name: 'help', flagNames: ['h'], description: 'display help for command', type: 'boolean' });
@@ -64,13 +68,13 @@ export class CliCommandSchemaUtil {
 
     const used = new Set(flags
       .flatMap(f => f.flagNames ?? [])
-      .filter(x => /^-[^-]/.test(x) || x.replaceAll('-', '').length < 3)
+      .filter(x => SHORT_FLAG.test(x) || x.replaceAll('-', '').length < 3)
       .map(x => x.replace(/^-+/, ''))
     );
 
     for (const flag of flags) {
-      let short = (flag.flagNames ?? []).find(x => /^-[^-]/.test(x) || x.replaceAll('-', '').length < 3)?.replace(/^-+/, '');
-      const long = (flag.flagNames ?? []).find(x => /^--[^-]/.test(x) || x.replaceAll('-', '').length > 2)?.replace(/^-+/, '') ??
+      let short = (flag.flagNames ?? []).find(x => SHORT_FLAG.test(x) || x.replaceAll('-', '').length < 3)?.replace(/^-+/, '');
+      const long = (flag.flagNames ?? []).find(x => LONG_FLAG.test(x) || x.replaceAll('-', '').length > 2)?.replace(/^-+/, '') ??
         flag.name.replace(/([a-z])([A-Z])/g, (_, l, r: string) => `${l}-${r.toLowerCase()}`);
       const aliases: string[] = flag.flagNames = [];
 
@@ -123,7 +127,7 @@ export class CliCommandSchemaUtil {
 
     for (const el of schema.args) {
       // Siphon off unrecognized flags, in order
-      while (i < copy.length && copy[i].startsWith('-')) {
+      while (i < copy.length && VALID_FLAG.test(copy[i])) {
         i += 1;
       }
 
@@ -132,7 +136,7 @@ export class CliCommandSchemaUtil {
       } else if (el.array) {
         const sub: string[] = [];
         while (i < copy.length) {
-          if (!copy[i].startsWith('-')) {
+          if (!VALID_FLAG.test(copy[i])) {
             sub.push(copy[i]);
             found[i] = true;
           }
@@ -196,7 +200,7 @@ export class CliCommandSchemaUtil {
       } else if (isBoolFlag(input)) {
         // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
         template[key] = !arg.startsWith('--no') as T[typeof key];
-      } else if (next === undefined || next.startsWith('-')) {
+      } else if (next === undefined || VALID_FLAG.test(next)) {
         // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
         template[key] = null as T[typeof key];
       } else if (input.array) {
@@ -232,16 +236,18 @@ export class CliCommandSchemaUtil {
       async (): Promise<void> => {
         const res = await cmd.validate?.(...args);
         if (res) {
-          throw new ValidationResultError(Array.isArray(res) ? res : [res]);
+          throw new CliValidationResultError(Array.isArray(res) ? res : [res]);
         }
       },
     ];
 
+    const SOURCES = ['flag', 'arg', 'custom'] as const;
+
     const results = validators.map((x, i) => x().catch(err => {
-      if (!(err instanceof ValidationResultError)) {
+      if (!(err instanceof CliValidationResultError) && !(err instanceof ValidationResultError)) {
         throw err;
       }
-      return err.errors.map(v => ({ ...v, message: `${v.message}. [${i}]`, index: i }));
+      return err.errors.map(v => ({ source: SOURCES[i], ...v }));
     }));
 
     const errors = (await Promise.all(results)).flatMap(x => (x ?? []));

package/src/types.ts

@@ -13,13 +13,9 @@ export type CliValidationError = {
    */
   message: string;
   /**
-   * The object path of the error
+   * Source of validation
    */
-  path: string;
-  /**
-   * The kind of validation
-   */
-  kind: string;
+  source?: 'flag' | 'arg' | 'custom';
 };
 
 /**
@@ -65,7 +61,7 @@ export interface CliCommandShape {
   /**
    * Validation method
    */
-  validate?(...args: unknown[]): OrProm<CliValidationError | CliValidationError[] | undefined>;
+  validate?(...unknownArgs: unknown[]): OrProm<CliValidationError | CliValidationError[] | undefined>;
 }
 
 /**

package/support/cli.cli_schema.ts

@@ -17,9 +17,8 @@ export class CliSchemaCommand {
   async validate(name?: string): Promise<CliValidationError | undefined> {
     if (name && !CliCommandRegistry.getCommandMapping().has(name)) {
       return {
-        kind: 'invalid',
-        path: 'name',
-        message: `${name} is not a valid cli command`
+        source: 'arg',
+        message: `name: ${name} is not a valid cli command`
       };
     }
   }

package/support/cli.list.ts

@@ -31,7 +31,7 @@ export class ListModuleCommand implements CliCommandShape {
       }
       case 'json': {
         const outputMap = CliModuleUtil.getDependencyGraph(mods);
-        await write(JSON.stringify(Object.entries(outputMap).map(([name, children]) => ({ name, children })), null, 2));
+        await write(JSON.stringify(Object.entries(outputMap).map(([name, children]) => ({ name, children, local: RootIndex.getModule(name)?.local })), null, 2));
         break;
       }
       case 'graph': {

package/support/cli.main.ts

@@ -25,11 +25,7 @@ export class MainCommand implements CliCommandShape {
   async validate(fileOrImport: string): Promise<CliValidationError | undefined> {
     const imp = await this.#getImport(fileOrImport);
     if (!imp) {
-      return {
-        message: `Unknown file: ${fileOrImport}`,
-        kind: 'required',
-        path: 'fileOrImport'
-      };
+      return { message: `Unknown file: ${fileOrImport}` };
     }
   }