@travetto/cli 3.4.0-rc.9 → 3.4.1

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2020 ArcSine Technologies
+Copyright (c) 2023 ArcSine Technologies
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -170,7 +170,7 @@ Options:
 $ trv basic:arg 20
 
 Execution failed:
- * Argument  is bigger than (10)
+ * Argument volume is bigger than (10)
 
 Usage: basic:arg [options] [volume:number]
 
@@ -233,7 +233,7 @@ $ trv basic:arglist 10 5 3 9 8 1
 $ trv basic:arglist 10 5 3 9 20 1
 
 Execution failed:
- * Argument [4] is bigger than (10)
+ * Argument volumes[4] is bigger than (10)
 
 Usage: basic:arglist [options] <volumes...:number>
 
@@ -390,7 +390,7 @@ export interface CliCommandShape {
   /**
    * Setup environment before command runs
    */
-  envInit?(): OrProm<GlobalEnvConfig>;
+  envInit?(): OrProm<EnvInit>;
   /**
    * Extra help
    */
@@ -454,7 +454,7 @@ export class RunRestCommand {
 }
 ```
 
-As noted in the example above, `fields` is specified in this execution, with support for `module`, and `env`. These env flag is directly tied to the [GlobalEnv](https://github.com/travetto/travetto/tree/main/module/base/src/global-env.ts#L17) flags defined in the [Base](https://github.com/travetto/travetto/tree/main/module/base#readme "Environment config and common utilities for travetto applications.") module. 
+As noted in the example above, `fields` is specified in this execution, with support for `module`, and `env`. These env flag is directly tied to the [GlobalEnv](https://github.com/travetto/travetto/tree/main/module/base/src/global-env.ts#L9) 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.
 

package/package.json

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

package/src/decorators.ts

@@ -1,4 +1,4 @@
-import { Class, ClassInstance, ConsoleManager, GlobalEnv, defineGlobalEnv } from '@travetto/base';
+import { Class, ClassInstance, ConsoleManager, GlobalEnv, defineEnv } from '@travetto/base';
 import { RootIndex } from '@travetto/manifest';
 import { SchemaRegistry } from '@travetto/schema';
 
@@ -26,7 +26,7 @@ export function CliCommand(cfg: CliCommandConfigOptions = {}) {
       hidden: cfg.hidden,
       preMain: async (cmd) => {
         if (addEnv && 'env' in cmd && typeof cmd.env === 'string') {
-          defineGlobalEnv({ envName: cmd.env });
+          defineEnv({ envName: cmd.env });
           ConsoleManager.setDebug(GlobalEnv.debug, GlobalEnv.devMode);
         }
       }

package/src/execute.ts

@@ -1,5 +1,5 @@
 import { GlobalTerminal } from '@travetto/terminal';
-import { ConsoleManager, defineGlobalEnv, ShutdownManager, GlobalEnv } from '@travetto/base';
+import { ConsoleManager, defineEnv, ShutdownManager, GlobalEnv } from '@travetto/base';
 
 import { HelpUtil } from './help';
 import { CliCommandShape } from './types';
@@ -14,20 +14,11 @@ export class ExecutionManager {
 
   static async #envInit(cmd: CliCommandShape): Promise<void> {
     if (cmd.envInit) {
-      defineGlobalEnv(await cmd.envInit());
+      defineEnv(await cmd.envInit());
       ConsoleManager.setDebug(GlobalEnv.debug, GlobalEnv.devMode);
     }
   }
 
-  static async #bindAndValidateArgs(cmd: CliCommandShape, args: string[]): Promise<unknown[]> {
-    await cmd.initialize?.();
-    const remainingArgs = await CliCommandSchemaUtil.bindFlags(cmd, args);
-    const [known, unknown] = await CliCommandSchemaUtil.bindArgs(cmd, remainingArgs);
-    await cmd.finalize?.(unknown);
-    await CliCommandSchemaUtil.validate(cmd, known);
-    return known;
-  }
-
   /**
    * Run help
    */
@@ -41,7 +32,7 @@ export class ExecutionManager {
    * Run the given command object with the given arguments
    */
   static async command(cmd: CliCommandShape, args: string[]): Promise<void> {
-    const known = await this.#bindAndValidateArgs(cmd, args);
+    const known = await CliCommandSchemaUtil.bindAndValidateArgs(cmd, args);
     await this.#envInit(cmd);
     const cfg = CliCommandRegistry.getConfig(cmd);
     await cfg?.preMain?.(cmd);

package/src/help.ts

@@ -105,7 +105,7 @@ export class HelpUtil {
         if (inst) {
           const cfg = await CliCommandRegistry.getConfig(inst);
           if (!cfg.hidden) {
-            const schema = await CliCommandSchemaUtil.getSchema(inst);
+            const schema = await CliCommandSchemaUtil.getSchema(cfg.cls);
             rows.push(cliTpl`  ${{ param: cmd.padEnd(maxWidth, ' ') }} ${{ title: schema.title }}`);
           }
         }

package/src/registry.ts

@@ -29,7 +29,7 @@ class $CliCommandRegistry {
   #commands = new Map<Class, CliCommandConfig>();
   #fileMapping: Map<string, string>;
 
-  #get(cls: Class): CliCommandConfig | undefined {
+  getByClass(cls: Class): CliCommandConfig | undefined {
     return this.#commands.get(cls);
   }
 
@@ -75,7 +75,7 @@ class $CliCommandRegistry {
    * Get config for a given instance
    */
   getConfig(cmd: CliCommandShape): CliCommandConfig {
-    return this.#get(this.#getClass(cmd))!;
+    return this.getByClass(this.#getClass(cmd))!;
   }
 
   /**
@@ -97,7 +97,7 @@ class $CliCommandRegistry {
     if (found) {
       const values = Object.values<Class>(await import(found));
       for (const v of values) {
-        const cfg = this.#get(v);
+        const cfg = this.getByClass(v);
         if (cfg) {
           const inst = new cfg.cls();
           if (!inst.isActive || inst.isActive()) {

package/src/schema.ts

@@ -5,14 +5,34 @@ import { CliCommandRegistry } from './registry';
 import { CliCommandInput, CliCommandSchema, CliCommandShape } from './types';
 import { CliValidationResultError } from './error';
 
-function split(args: string[]): [core: string[], extra: string[]] {
-  const restIdx = args.indexOf('--');
-  if (restIdx >= 0) {
-    return [args.slice(0, restIdx), args.slice(restIdx + 1)];
+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 } |
+  { 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, value?: string }): ParsedInput => {
+  const { field, input, rawText = input, value } = cfg;
+  if (!field) {
+    return { type: 'unknown', input: rawText };
+  } else if (!field.flagNames?.length) {
+    return { type: 'arg', input: field ? input : rawText ?? input, array: field.array };
   } else {
-    return [args, []];
+    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' :
@@ -34,12 +54,6 @@ 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;
-
 /**
  * Allows binding describing/binding inputs for commands
  */
@@ -50,10 +64,9 @@ export class CliCommandSchemaUtil {
   /**
    * Get schema for a given command
    */
-  static async getSchema(cmd: CliCommandShape): Promise<CliCommandSchema> {
+  static async getSchema(src: Class | CliCommandShape): Promise<CliCommandSchema> {
     // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
-    const cls = cmd.constructor as Class<CliCommandShape>;
-
+    const cls = 'main' in src ? src.constructor as Class : src;
     if (this.#schemas.has(cls)) {
       return this.#schemas.get(cls)!;
     }
@@ -110,7 +123,7 @@ export class CliCommandSchemaUtil {
     }
 
     const fullSchema = SchemaRegistry.get(cls);
-    const { cls: _cls, preMain: _preMain, ...meta } = CliCommandRegistry.getConfig(cmd);
+    const { cls: _cls, preMain: _preMain, ...meta } = CliCommandRegistry.getByClass(cls)!;
     const cfg: CliCommandSchema = {
       ...meta,
       args: method,
@@ -123,111 +136,107 @@ export class CliCommandSchemaUtil {
   }
 
   /**
-   * Produce the arguments into the final argument set
+   * Parse inputs to command
    */
-  static async bindArgs(cmd: CliCommandShape, args: string[]): Promise<[known: unknown[], unknown: string[]]> {
-    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
-    const cls = cmd.constructor as Class<CliCommandShape>;
-    const [copy, extra] = split(args);
-    const schema = await this.getSchema(cmd);
-    const out: unknown[] = [];
-    const found: boolean[] = copy.map(x => false);
-    let i = 0;
-
-    for (const el of schema.args) {
-      // Siphon off unrecognized flags, in order
-      while (i < copy.length && VALID_FLAG.test(copy[i])) {
-        i += 1;
-      }
+  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[] = [];
 
-      if (i >= copy.length) {
-        out.push(el.array ? [] : undefined);
-      } else if (el.array) {
-        const sub: string[] = [];
-        while (i < copy.length) {
-          if (!VALID_FLAG.test(copy[i])) {
-            sub.push(copy[i]);
-            found[i] = true;
+    // 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;
         }
-        out.push(sub);
       } else {
-        out.push(copy[i]);
-        found[i] = true;
-        i += 1;
+        const field = schema.args[argIdx];
+        out.push(getInput({ field, input }));
+        // Move argIdx along if not in a vararg situation
+        if (!field?.array) {
+          argIdx += 1;
+        }
       }
     }
 
-    const final = [...copy.filter((_, idx) => !found[idx]), ...extra];
-    return [
-      BindUtil.coerceMethodParams(cls, 'main', out, true),
-      final
-    ];
+    return out;
   }
 
   /**
    * Bind arguments to command
    */
-  static async bindFlags<T extends CliCommandShape>(cmd: T, args: string[]): Promise<string[]> {
-    const schema = await this.getSchema(cmd);
-
-    const [base, extra] = split(args);
-    const copy = base.flatMap(k => (k.startsWith('--') && k.includes('=')) ? k.split('=') : [k]);
-
+  static async bindFlags<T extends CliCommandShape>(cmd: T, args: ParsedInput[]): Promise<void> {
     const template: Partial<T> = {};
 
-    const flagMap = new Map<string, CliCommandInput>();
-    for (const flag of schema.flags) {
-      for (const name of flag.flagNames ?? []) {
-        flagMap.set(name, flag);
-      }
-      for (const envName of flag.envVars ?? []) {
-        if (envName in process.env) {
-          let val: string | string[] = process.env[envName]!;
-          if (flag.array) {
-            val = val.split(/\s*,\s*/g);
-          }
+    for (const arg of args) {
+      switch (arg.type) {
+        case 'flag': {
           // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
-          template[flag.name as keyof T] = val as T[keyof T];
+          const key = arg.fieldName as keyof T;
+          const value = arg.value!;
+          if (arg.array) {
+            // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+            ((template[key] as unknown[]) ??= []).push(value);
+          } else {
+            // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+            template[key] = value as unknown as T[typeof key];
+          }
         }
       }
     }
 
-    const out = [];
-    for (let i = 0; i < copy.length; i += 1) {
-      const arg = copy[i];
-      const next = copy[i + 1];
-
-      const input = flagMap.get(arg);
-      // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
-      const key = input?.name as keyof T;
-      if (!input) {
-        out.push(arg);
-      } 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 || VALID_FLAG.test(next)) {
-        // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
-        template[key] = null as T[typeof key];
-      } else if (input.array) {
-        // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
-        const arr = template[key] ??= [] as T[typeof key];
-        // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
-        (arr as unknown[]).push(next);
-        i += 1; // Skip next
-      } else {
-        // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
-        template[key] = next as T[typeof key];
-        i += 1; // Skip next
-      }
-    }
-
     // 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, args: ParsedInput[]): Promise<unknown[]> {
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+    const cls = cmd.constructor as Class<CliCommandShape>;
+    const out = args.filter(x => x.type === 'arg').map(x => x.input);
+    return BindUtil.coerceMethodParams(cls, 'main', out, true);
+  }
 
-    return [...out, '--', ...extra];
+  /**
+   * Get the unused arguments
+   */
+  static getUnusedArgs(args: ParsedInput[]): string[] {
+    return args.filter(x => x.type === 'unknown').map(x => x.input);
   }
 
   /**
@@ -237,9 +246,11 @@ export class CliCommandSchemaUtil {
     // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
     const cls = cmd.constructor as Class<CliCommandShape>;
 
+    const paramNames = SchemaRegistry.getMethodSchema(cls, 'main').map(x => x.name);
+
     const validators = [
       (): Promise<void> => SchemaValidator.validate(cls, cmd).then(() => { }),
-      (): Promise<void> => SchemaValidator.validateMethod(cls, 'main', args),
+      (): Promise<void> => SchemaValidator.validateMethod(cls, 'main', args, paramNames),
       async (): Promise<void> => {
         const res = await cmd.validate?.(...args);
         if (res) {
@@ -263,4 +274,19 @@ 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,4 +1,4 @@
-import { Closeable, GlobalEnvConfig } from '@travetto/base';
+import { Closeable, EnvInit } from '@travetto/base';
 
 type OrProm<T> = T | Promise<T>;
 
@@ -29,7 +29,7 @@ export interface CliCommandShape {
   /**
    * Setup environment before command runs
    */
-  envInit?(): OrProm<GlobalEnvConfig>;
+  envInit?(): OrProm<EnvInit>;
   /**
    * Extra help
    */