@travetto/cli 8.0.0-alpha.9 → 8.0.0

package/src/help.ts

@@ -1,72 +1,73 @@
 import util from 'node:util';
 
-import { castKey, getClass, JSONUtil, Runtime } from '@travetto/runtime';
+import { CodecUtil, 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, UNKNOWN_COMMAND } from './registry/registry-index.ts';
 import { CliSchemaExportUtil } from './schema-export.ts';
+import { type CliCommandShape, HELP_FLAG } from './types.ts';
 
-const validationSourceMap: Record<string, string> = {
-  arg: 'Argument',
-  flag: 'Flag'
-};
+const validationSourceMap: Record<string, string> = { arg: 'Argument', flag: 'Flag' };
 
 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),
-]);
+  value === null || value === '' || value === undefined ? undefined : value;
+
+const MODULE_TO_COMMAND = {
+  '@travetto/doc': ['doc'],
+  '@travetto/email-compiler': ['email:compile', 'email:test', 'email:editor'],
+  '@travetto/lint': ['lint', 'lint:register'],
+  '@travetto/model': ['model:install', 'model:export'],
+  '@travetto/openapi': ['openapi:spec', 'openapi:client'],
+  '@travetto/pack': ['pack', 'pack:zip', 'pack:docker'],
+  '@travetto/repo': ['repo:publish', 'repo:version', 'repo:exec', 'repo:list'],
+  '@travetto/test': ['test', 'test:watch', 'test:direct'],
+  '@travetto/web-http': ['web:http'],
+  '@travetto/web-rpc': ['web:rpc-client']
+};
+
+const COMMAND_TO_MODULE = Object.fromEntries(Object.entries(MODULE_TO_COMMAND).flatMap(([k, v]) => v.map(sv => [sv, k])));
 
 /**
  * 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
-   */
-  static async renderCommandHelp(command: CliCommandShape): Promise<string> {
+  /** Get usage help for a command */
+  static getUsageMessage(command: CliCommandShape): string[] {
     const schema = SchemaRegistryIndex.getConfig(getClass(command));
     const { name: commandName } = CliCommandRegistryIndex.get(getClass(command));
-    const args = schema.methods.main?.parameters ?? [];
 
-    // Ensure finalized
+    const usage: string[] = [];
+
+    usage.push(cliTpl`${{ title: 'Usage:' }} ${{ param: commandName }} ${{ input: '[options]' }}`);
 
-    const usage: string[] = [cliTpl`${{ title: 'Usage:' }} ${{ param: commandName }} ${{ input: '[options]' }}`,];
-    for (const field of args) {
-      const type = field.type === String && field.enum && field.enum?.values.length <= 7 ? field.enum?.values?.join('|') : field.type.name.toLowerCase();
+    // Ensure finalized
+    for (const field of schema.methods.main?.parameters ?? []) {
+      const type =
+        field.type === String && field.enum && field.enum?.values.length <= 7
+          ? field.enum?.values?.join('|')
+          : field.type.name.toLowerCase();
       const arg = `${field.name}${field.array ? '...' : ''}:${type}`;
       usage.push(cliTpl`${{ input: field.required?.active !== false ? `<${arg}>` : `[${arg}]` }}`);
     }
 
+    return [usage.join(' '), ''];
+  }
+
+  /** Get description help for a command */
+  static getDescriptionMessage(command: CliCommandShape): string[] {
+    const schema = SchemaRegistryIndex.getConfig(getClass(command));
+    const description: string[] = [];
+
+    if (schema.description) {
+      description.push(cliTpl`${{ title: 'Description:' }}`, ...schema.description.split('\n').map(line => `  ${line}`), '');
+    }
+    return description;
+  }
+
+  /** Get options help for a command */
+  static getOptionsMessage(command: CliCommandShape): string[] {
+    const schema = SchemaRegistryIndex.getConfig(getClass(command));
     const params: string[] = [];
     const descriptions: string[] = [];
 
@@ -75,9 +76,7 @@ ${{ identifier: install }}
       const defaultValue = ifDefined(command[key]) ?? ifDefined(field.default);
       const aliases = (field.aliases ?? [])
         .filter(flag => flag.startsWith('-'))
-        .filter(flag =>
-          (field.type !== Boolean) || ((defaultValue !== true || field.name === 'help') ? !flag.startsWith('--no-') : flag.startsWith('--'))
-        );
+        .filter(flag => field.type !== Boolean || (defaultValue !== true ? !flag.startsWith('--no-') : flag.startsWith('--')));
       let type: string | undefined;
 
       if (field.type === String && field.enum && field.enum.values.length <= 3) {
@@ -86,41 +85,93 @@ ${{ identifier: install }}
         ({ type } = CliSchemaExportUtil.baseInputType(field));
       }
 
-      const param = [
-        cliTpl`${{ param: aliases.join(', ') }}`,
-        ...(type ? [cliTpl`${{ type: `<${type}>` }}`] : []),
-      ];
+      const parameter = [cliTpl`${{ param: aliases.join(', ') }}`, ...(type ? [cliTpl`${{ type: `<${type}>` }}`] : [])];
 
-      params.push(param.join(' '));
-      const desc = [cliTpl`${{ title: field.description }}`];
+      params.push(parameter.join(' '));
+      const parts = [cliTpl`${{ title: field.description }}`];
 
-      if (key !== 'help' && defaultValue !== undefined) {
-        desc.push(cliTpl`(default: ${{ input: JSONUtil.toUTF8(defaultValue) }})`);
+      if (defaultValue !== undefined) {
+        parts.push(cliTpl`(default: ${{ input: JSONUtil.toUTF8(defaultValue) }})`);
       }
-      descriptions.push(desc.join(' '));
+      descriptions.push(parts.join(' '));
     }
 
+    params.push(cliTpl`${{ param: HELP_FLAG }}`);
+    descriptions.push('display help for command');
+
     const paramWidths = params.map(item => util.stripVTControlCharacters(item).length);
     const descWidths = descriptions.map(item => util.stripVTControlCharacters(item).length);
 
     const paramWidth = Math.max(...paramWidths);
     const descWidth = Math.max(...descWidths);
 
-    const helpText = await (command.help?.() ?? []);
-    if (helpText.length && helpText.at(-1) !== '') {
-      helpText.push('');
+    const options: string[] = [
+      cliTpl`${{ title: 'Options:' }}`,
+      ...params.map(
+        (_, i) =>
+          `  ${params[i]}${' '.repeat(paramWidth - paramWidths[i])}  ${descriptions[i].padEnd(descWidth)}${' '.repeat(descWidth - descWidths[i])}`
+      ),
+      ''
+    ];
+    return options;
+  }
+
+  /** Get extended help for a command */
+  static async getExtendedHelpMessage(command: CliCommandShape): Promise<string[]> {
+    const extendedHelpText = await (command.help?.() ?? []);
+    if (extendedHelpText.length && extendedHelpText.at(-1) !== '') {
+      extendedHelpText.push('');
+    }
+    return extendedHelpText;
+  }
+
+  /** Get examples for a command */
+  static getExamplesMessage(command: CliCommandShape): string[] {
+    const schema = SchemaRegistryIndex.getConfig(getClass(command));
+    const examples: string[] = [];
+    if (schema.examples) {
+      examples.push(cliTpl`${{ title: 'Examples:' }}`);
+      for (const example of schema.examples) {
+        for (const line of example.split('\n')) {
+          examples.push(
+            line.trim().startsWith('>')
+              ? cliTpl`    ${{ input: line.substring(line.indexOf('> ') + 2).trim() }}`
+              : cliTpl`  ${{ subtitle: line.trim() }}`
+          );
+        }
+      }
+      examples.push('');
+    }
+    return examples;
+  }
+
+  /** Render the unknown command message */
+  static renderUnknownCommandMessage(command: string): string {
+    const module = COMMAND_TO_MODULE[command];
+    if (module) {
+      return cliTpl`
+${{ title: 'Missing Package' }}\n${'-'.repeat(20)}\nTo use ${{ input: command }} please run:\n
+${{ identifier: Runtime.getInstallCommand(module) }}
+`;
+    } else {
+      return cliTpl`${{ subtitle: 'Unknown command' }}: ${{ input: command }}`;
     }
+  }
 
+  /**
+   * Render command-specific help
+   * @param command
+   */
+  static async renderCommandHelp(command: CliCommandShape): Promise<string> {
     return [
-      usage.join(' '),
-      '',
-      cliTpl`${{ title: 'Options:' }}`,
-      ...params.map((_, i) =>
-        `  ${params[i]}${' '.repeat((paramWidth - paramWidths[i]))}  ${descriptions[i].padEnd(descWidth)}${' '.repeat((descWidth - descWidths[i]))}`
-      ),
-      '',
-      ...helpText
-    ].map(line => line.trimEnd()).join('\n');
+      ...this.getUsageMessage(command),
+      ...this.getDescriptionMessage(command),
+      ...this.getOptionsMessage(command),
+      ...(await this.getExtendedHelpMessage(command)),
+      ...this.getExamplesMessage(command)
+    ]
+      .map(line => line.trimEnd())
+      .join('\n');
   }
 
   /**
@@ -136,11 +187,13 @@ ${{ identifier: install }}
     for (const { command: cmd, schema } of resolved) {
       try {
         if (schema && !schema.private) {
-          rows.push(cliTpl`  ${{ param: cmd.padEnd(maxWidth, ' ') }} ${{ title: schema.description || '' }}`);
+          const description = CodecUtil.readFirstLine(schema.description, '');
+          rows.push(cliTpl`  ${{ param: cmd.padEnd(maxWidth, ' ') }} ${{ title: description }}`);
         }
       } catch (error) {
         if (error instanceof Error) {
-          rows.push(cliTpl`  ${{ param: cmd.padEnd(maxWidth, ' ') }} ${{ failure: error.message.split(/\n/)[0] }}`);
+          const failure = CodecUtil.readFirstLine(error.message);
+          rows.push(cliTpl`  ${{ param: cmd.padEnd(maxWidth, ' ') }} ${{ failure }}`);
         } else {
           throw error;
         }
@@ -166,7 +219,7 @@ ${{ identifier: install }}
         }
         return cliTpl` * ${{ failure: error.message }}`;
       }),
-      '',
+      ''
     ].join('\n');
   }
 
@@ -185,4 +238,4 @@ ${{ identifier: install }}
     }
     console.error!();
   }
-}
+}

package/src/module.ts

@@ -1,15 +1,14 @@
-import { Runtime, RuntimeIndex } from '@travetto/runtime';
 import type { IndexedModule } from '@travetto/manifest';
+import { Runtime, RuntimeIndex } from '@travetto/runtime';
 
 import { CliScmUtil } from './scm.ts';
 
-type ModuleGraphEntry = { children: Set<string>, name: string, active: Set<string>, parents?: string[] };
+type ModuleGraphEntry = { children: Set<string>; name: string; active: Set<string>; parents?: string[] };
 
 /**
  * Simple utilities for understanding modules for CLI use cases
  */
 export class CliModuleUtil {
-
   /**
    * Find modules that changed, and the dependent modules
    * @param fromHash
@@ -34,8 +33,7 @@ export class CliModuleUtil {
       }
     }
 
-    return [...out.values()]
-      .toSorted((a, b) => a.name.localeCompare(b.name));
+    return [...out.values()].toSorted((a, b) => a.name.localeCompare(b.name));
   }
 
   /**
@@ -45,9 +43,10 @@ export class CliModuleUtil {
    * @returns
    */
   static async findModules(mode: 'all' | 'changed' | 'workspace', fromHash?: string, toHash?: string): Promise<IndexedModule[]> {
-    return (mode === 'changed' ?
-      await this.findChangedModulesRecursive(fromHash, toHash, true) :
-      [...RuntimeIndex.getModuleList(mode)].map(name => RuntimeIndex.getModule(name)!)
+    return (
+      mode === 'changed'
+        ? await this.findChangedModulesRecursive(fromHash, toHash, true)
+        : [...RuntimeIndex.getModuleList(mode)].map(name => RuntimeIndex.getModule(name)!)
     ).filter(module => module.sourcePath !== Runtime.workspace.path);
   }
 
@@ -103,7 +102,7 @@ export class CliModuleUtil {
   /**
    * Find changed paths, either files between two git commits, or all folders for changed modules
    */
-  static async findChangedPaths(config: { since?: string, changed?: boolean, logError?: boolean } = {}): Promise<string[]> {
+  static async findChangedPaths(config: { since?: string; changed?: boolean; logError?: boolean } = {}): Promise<string[]> {
     if (config.since) {
       try {
         const files = await CliScmUtil.findChangedFiles(config.since, 'HEAD');
@@ -119,4 +118,4 @@ export class CliModuleUtil {
       return modules.map(module => module.sourcePath);
     }
   }
-}
+}

package/src/parse.ts

@@ -4,13 +4,12 @@ import path from 'node:path';
 import { Runtime } from '@travetto/runtime';
 import type { SchemaClassConfig, SchemaFieldConfig, SchemaInputConfig } from '@travetto/schema';
 
-import type { ParsedState } from './types.ts';
+import { HELP_FLAG, type ParsedState } from './types.ts';
 
 type ParsedInput = ParsedState['all'][number];
 
 const RAW_SEPARATOR = '--';
 const VALID_FLAG = /^-{1,2}[a-z]/i;
-const HELP_FLAG = /^(-h|--help)$/;
 const LONG_FLAG_WITH_EQ = /^--[a-z][^= ]+=\S+/i;
 const CONFIG_PREFIX = '+=';
 const SPACE = new Set([32, 7, 13, 10]);
@@ -26,32 +25,35 @@ const STATE_SYMBOL = Symbol();
  * Parsing support for the cli
  */
 export class CliParseUtil {
-
   static toEnvField(key: string): string {
     return key.startsWith(ENV_PREFIX) ? key : `${ENV_PREFIX}${key}`;
   }
 
-  static readToken(text: string, start = 0): { next: number, value?: string } {
+  static readToken(text: string, start = 0): { next: number; value?: string } {
     const collected: number[] = [];
     let i = start;
     let done = false;
     let quote: number | undefined;
     let escaped = false;
-    outer: for (; i < text.length; i += 1) {
+    for (; i < text.length; i += 1) {
       const ch = text.charCodeAt(i);
       const space = SPACE.has(ch);
       if (escaped) {
         escaped = false;
         collected.push(ch);
       } else if (done && !space) {
-        break outer;
+        break;
       } else if (!quote && space) {
         done = true;
       } else {
         switch (ch) {
-          case 92: /* Backslash */ escaped = true; break;
-          case 39: /* Single quote */ case 34: /* Double quote */
-            if (quote === ch) { // End quote
+          case 92:
+            /* Backslash */ escaped = true;
+            break;
+          case 39: /* Single quote */
+          case 34 /* Double quote */:
+            if (quote === ch) {
+              // End quote
               quote = undefined;
             } else if (!quote) {
               quote = ch;
@@ -59,7 +61,8 @@ export class CliParseUtil {
               collected.push(ch);
             }
             break;
-          default: collected.push(ch);
+          default:
+            collected.push(ch);
         }
       }
     }
@@ -74,10 +77,9 @@ export class CliParseUtil {
     const input = Object.values(schema.fields).find(config => config.specifiers?.includes('module'));
     const envKey = input?.aliases?.filter(alias => alias.startsWith(ENV_PREFIX)).map(alias => alias.replace(ENV_PREFIX, ''))[0] ?? '';
     const flags = new Set(input?.aliases ?? []);
-    const check = (key?: string, value?: string): string | undefined => flags.has(key!) ? value : undefined;
+    const check = (key?: string, value?: string): string | undefined => (flags.has(key!) ? value : undefined);
     return args.reduce(
-      (name, value, i, values) =>
-        (i < separatorIndex ? check(values[i - 1], value) ?? check(...value.split('=')) : undefined) ?? name,
+      (name, value, i, values) => (i < separatorIndex ? (check(values[i - 1], value) ?? check(...value.split('='))) : undefined) ?? name,
       process.env[envKey]
     );
   }
@@ -90,18 +92,20 @@ export class CliParseUtil {
     const overrides = { '@': module ?? Runtime.main.name };
 
     // We have a file
-    const relativePath = (key.includes('/') ? key : `@#support/pack.${key}.flags`)
-      .replace(/^(@[^#]*)#(.*)$/, (_, imp, rest) => `${Runtime.modulePath(imp, overrides)}/${rest}`);
+    const relativePath = (key.includes('/') ? key : `@#support/pack.${key}.flags`).replace(
+      /^(@[^#]*)#(.*)$/,
+      (_, imp, rest) => `${Runtime.modulePath(imp, overrides)}/${rest}`
+    );
 
     const file = path.resolve(relativePath);
 
-    if (!await fs.stat(file, { throwIfNoEntry: false })) {
+    if (!(await fs.stat(file, { throwIfNoEntry: false }))) {
       throw new Error(`Missing flag file: ${key}, unable to proceed`);
     }
 
     const data = await fs.readFile(file, 'utf8');
     const args: string[] = [];
-    let token: { next: number, value?: string } = { next: 0 };
+    let token: { next: number; value?: string } = { next: 0 };
     while (token.next < data.length) {
       token = this.readToken(data, token.next);
       if (token.value !== undefined) {
@@ -115,7 +119,7 @@ export class CliParseUtil {
    * Parse args to extract command from argv along with other params.  Will skip
    * argv[0] and argv[1] if equal to process.argv[0:2]
    */
-  static getArgs(argv: string[]): { cmd?: string, args: string[], help?: boolean } {
+  static getArgs(argv: string[]): { cmd?: string; args: string[]; help?: boolean } {
     let offset = 0;
     if (argv[0] === process.argv[0] && argv[1] === process.argv[1]) {
       offset = 2;
@@ -124,9 +128,9 @@ export class CliParseUtil {
     const max = out.includes(RAW_SEPARATOR) ? out.indexOf(RAW_SEPARATOR) : out.length;
     const valid = out.slice(0, max);
     const cmd = valid.length > 0 && !valid[0].startsWith('-') ? valid[0] : undefined;
-    const helpIdx = valid.findIndex(flag => HELP_FLAG.test(flag));
+    const help = valid.includes(HELP_FLAG);
     const args = out.slice(cmd ? 1 : 0);
-    const result = { cmd, args, help: helpIdx >= 0 };
+    const result = { cmd, args, help };
     return result;
   }
 
@@ -136,11 +140,12 @@ export class CliParseUtil {
   static async expandArgs(schema: SchemaClassConfig, args: string[]): Promise<string[]> {
     const separatorIndex = args.includes(RAW_SEPARATOR) ? args.indexOf(RAW_SEPARATOR) : args.length;
     const module = this.getSpecifiedModule(schema, args);
-    return Promise
-      .all(args.map(async (arg, i) =>
-        await (arg.startsWith(CONFIG_PREFIX) && (i < separatorIndex || separatorIndex < 0) ? this.readFlagFile(arg, module) : arg))
+    return Promise.all(
+      args.map(
+        async (arg, i) =>
+          await (arg.startsWith(CONFIG_PREFIX) && (i < separatorIndex || separatorIndex < 0) ? this.readFlagFile(arg, module) : arg)
       )
-      .then(expanded => expanded.flat());
+    ).then(expanded => expanded.flat());
   }
 
   /**
@@ -160,7 +165,9 @@ export class CliParseUtil {
         if (simple in process.env) {
           const value: string = process.env[simple]!;
           if (field.array) {
-            out.push(...value.split(/\s*,\s*/g).map(item => ({ type: 'flag', fieldName: field.name, input: envName, value: item }) as const));
+            out.push(
+              ...value.split(/\s*,\s*/g).map(item => ({ type: 'flag', fieldName: field.name, input: envName, value: item }) as const)
+            );
           } else {
             out.push({ type: 'flag', fieldName: field.name, input: envName, value });
           }
@@ -173,7 +180,8 @@ export class CliParseUtil {
     for (let i = 0; i < inputs.length; i += 1) {
       const input = inputs[i];
 
-      if (input === RAW_SEPARATOR) { // Raw separator
+      if (input === RAW_SEPARATOR) {
+        // Raw separator
         out.push(...inputs.slice(i + 1).map((arg, idx) => ({ type: 'unknown', input: arg, index: argIdx + idx }) as const));
         break;
       } else if (LONG_FLAG_WITH_EQ.test(input)) {
@@ -184,7 +192,8 @@ export class CliParseUtil {
         } else {
           out.push({ type: 'unknown', input });
         }
-      } else if (VALID_FLAG.test(input)) { // Flag
+      } else if (VALID_FLAG.test(input)) {
+        // Flag
         const field = flagMap.get(input);
         if (!field) {
           out.push({ type: 'unknown', input });
@@ -225,27 +234,33 @@ export class CliParseUtil {
    * Parse aliases into categories for registration
    */
   static parseAliases(aliases: string[]): AliasesParseResult {
-    return aliases.reduce<AliasesParseResult>((result, alias) => {
-      if (VALID_FLAG.test(alias)) {
-        if (alias.startsWith('--')) {
-          result.long.push(alias);
+    return aliases.reduce<AliasesParseResult>(
+      (result, alias) => {
+        if (VALID_FLAG.test(alias)) {
+          if (alias.startsWith('--')) {
+            result.long.push(alias);
+          } else {
+            result.short.push(alias);
+          }
+        } else if (alias.startsWith(ENV_PREFIX)) {
+          result.env.push(alias);
         } else {
-          result.short.push(alias);
+          result.raw.push(alias);
         }
-      } else if (alias.startsWith(ENV_PREFIX)) {
-        result.env.push(alias);
-      } else {
-        result.raw.push(alias);
-      }
-      return result;
-    }, { long: [], short: [], raw: [], env: [] });
+        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];
+  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}`] : []),
@@ -270,4 +285,4 @@ export class CliParseUtil {
     const local: T & { [STATE_SYMBOL]?: ParsedState } = item;
     local[STATE_SYMBOL] = state;
   }
-}
+}