@travetto/cli 8.0.0-alpha.10 → 8.0.0-alpha.12

package/README.md

@@ -75,12 +75,12 @@ export class BasicCommand {
 
 **Terminal: Basic Command Help**
 ```bash
-$ trv basic -h
+$ trv basic --help
 
 Usage: basic [options]
 
 Options:
-  -h, --help  display help for command
+  --help  display help for command
 ```
 
 ## Command Naming
@@ -113,13 +113,13 @@ export class BasicCommand {
 
 **Terminal: Basic Command with Flag Help**
 ```bash
-$ trv basic:flag -h
+$ trv basic:flag --help
 
 Usage: basic:flag [options]
 
 Options:
   -l, --loud
-  -h, --help  display help for command
+  --help      display help for command
 ```
 
 As you can see the command now has the support of a basic boolean flag to determine if the response should be loud or not.  The default value here is undefined/false, and so is an opt-in experience.
@@ -158,12 +158,12 @@ export class BasicCommand {
 
 **Terminal: Basic Command**
 ```bash
-$ trv basic:arg -h
+$ trv basic:arg --help
 
 Usage: basic:arg [options] [volume:number]
 
 Options:
-  -h, --help  display help for command
+  --help  display help for command
 ```
 
 **Terminal: Basic Command with Invalid Loud Arg**
@@ -176,7 +176,7 @@ Execution failed:
 Usage: basic:arg [options] [volume:number]
 
 Options:
-  -h, --help  display help for command
+  --help  display help for command
 ```
 
 **Terminal: Basic Command with Loud Arg > 7**
@@ -213,13 +213,13 @@ export class BasicCommand {
 
 **Terminal: Basic Command**
 ```bash
-$ trv basic:arg-list -h
+$ trv basic:arg-list --help
 
 Usage: basic:arg-list [options] <volumes...:number>
 
 Options:
   -r, --reverse
-  -h, --help     display help for command
+  --help         display help for command
 ```
 
 **Terminal: Basic Arg List**
@@ -240,7 +240,7 @@ Usage: basic:arg-list [options] <volumes...:number>
 
 Options:
   -r, --reverse
-  -h, --help     display help for command
+  --help         display help for command
 ```
 
 **Terminal: Basic Arg List with Reverse**
@@ -279,13 +279,13 @@ export class CustomCommand {
 
 **Terminal: Custom Command Help**
 ```bash
-$ trv custom:arg -h
+$ trv custom:arg --help
 
 Usage: custom:arg [options] [volume:number]
 
 Options:
   -m, --message <string>  The message to send back to the user (default: "hello")
-  -h, --help              display help for command
+  --help                  display help for command
 ```
 
 **Terminal: Custom Command Help with overridden Text**
@@ -330,13 +330,13 @@ export class CustomCommand {
 
 **Terminal: Custom Command Help**
 ```bash
-$ trv custom:env-arg -h
+$ trv custom:env-arg --help
 
 Usage: custom:env-arg [options] [volume:number]
 
 Options:
   -t, --text <string>  The message to send back to the user (default: "hello")
-  -h, --help           display help for command
+  --help               display help for command
 ```
 
 **Terminal: Custom Command Help with default Text**
@@ -559,7 +559,7 @@ Usage: service [options] <action:restart|start|status|stop> [services...:string]
 
 Options:
   -q, --quiet   (default: false)
-  -h, --help   display help for command
+  --help       display help for command
 
 Available Services
 --------------------

package/bin/trv.js

@@ -3,4 +3,4 @@
 import '@travetto/runtime/support/patch.js';
 import '@travetto/compiler/bin/hook.js';
 const { invoke } = await import('@travetto/compiler/support/invoke.ts');
-await invoke('exec', ['@travetto/cli/support/entry.trv.ts', ...process.argv.slice(2)]);
+await invoke('exec', '@travetto/cli/support/entry.trv.ts', ...process.argv.slice(2));

package/package.json

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

package/src/help.ts

@@ -4,32 +4,29 @@ 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 { HELP_FLAG, type CliCommandShape } from './types.ts';
 import { CliCommandRegistryIndex, UNKNOWN_COMMAND } from './registry/registry-index.ts';
 import { CliSchemaExportUtil } from './schema-export.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),
-]);
+const MODULE_TO_COMMAND = {
+  '@travetto/doc': ['doc'],
+  '@travetto/email-compiler': ['email:compile', 'email:test', 'email:editor'],
+  '@travetto/eslint': ['eslint', 'eslint:register', '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
@@ -37,15 +34,15 @@ const INSTALL_COMMANDS = new Map<string, string>([
 export class HelpUtil {
 
   /** Render the unknown command message */
-  static renderUnknownCommandMessage(cmd: string): string {
-    const install = INSTALL_COMMANDS.get(cmd);
-    if (install) {
+  static renderUnknownCommandMessage(command: string): string {
+    const module = COMMAND_TO_MODULE[command];
+    if (module) {
       return cliTpl`
-${{ title: 'Missing Package' }}\n${'-'.repeat(20)}\nTo use ${{ input: cmd }} please run:\n
-${{ identifier: install }}
+${{ title: 'Missing Package' }}\n${'-'.repeat(20)}\nTo use ${{ input: command }} please run:\n
+${{ identifier: Runtime.getInstallCommand(module) }}
 `;
     } else {
-      return cliTpl`${{ subtitle: 'Unknown command' }}: ${{ input: cmd }}`;
+      return cliTpl`${{ subtitle: 'Unknown command' }}: ${{ input: command }}`;
     }
   }
 
@@ -58,25 +55,24 @@ ${{ identifier: install }}
     const { name: commandName } = CliCommandRegistryIndex.get(getClass(command));
     const args = schema.methods.main?.parameters ?? [];
 
-    // Ensure finalized
+    const usage = [cliTpl`${{ title: 'Usage:' }} ${{ param: commandName }} ${{ input: '[options]' }}`,];
+    const params: string[] = [];
+    const descriptions: string[] = [];
 
-    const usage: string[] = [cliTpl`${{ title: 'Usage:' }} ${{ param: commandName }} ${{ input: '[options]' }}`,];
+    // Ensure finalized
     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();
       const arg = `${field.name}${field.array ? '...' : ''}:${type}`;
       usage.push(cliTpl`${{ input: field.required?.active !== false ? `<${arg}>` : `[${arg}]` }}`);
     }
 
-    const params: string[] = [];
-    const descriptions: string[] = [];
-
     for (const field of Object.values(schema.fields)) {
       const key = castKey<CliCommandShape>(field.name);
       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('--'))
+          (field.type !== Boolean) || (defaultValue !== true ? !flag.startsWith('--no-') : flag.startsWith('--'))
         );
       let type: string | undefined;
 
@@ -86,29 +82,33 @@ ${{ identifier: install }}
         ({ type } = CliSchemaExportUtil.baseInputType(field));
       }
 
-      const param = [
+      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 extendedHelpText = await (command.help?.() ?? []);
+    if (extendedHelpText.length && extendedHelpText.at(-1) !== '') {
+      extendedHelpText.push('');
     }
 
     return [
@@ -119,7 +119,7 @@ ${{ identifier: install }}
         `  ${params[i]}${' '.repeat((paramWidth - paramWidths[i]))}  ${descriptions[i].padEnd(descWidth)}${' '.repeat((descWidth - descWidths[i]))}`
       ),
       '',
-      ...helpText
+      ...extendedHelpText
     ].map(line => line.trimEnd()).join('\n');
   }
 

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]);
@@ -124,9 +123,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;
   }
 

package/src/registry/registry-adapter.ts

@@ -29,22 +29,10 @@ export class CliCommandRegistryAdapter implements RegistryAdapter<CliCommandConf
     this.#cls = cls;
   }
 
+  // TODO: handle when aliases overlap/conflict
   finalize(parent?: CliCommandConfig): void {
     // Add help command
     const schema = SchemaRegistryIndex.getConfig(this.#cls);
-
-    // Add help to every command
-    (schema.fields ??= {}).help = {
-      type: Boolean,
-      name: 'help',
-      class: this.#cls,
-      description: 'display help for command',
-      required: { active: false },
-      default: false,
-      access: 'readonly',
-      aliases: ['-h', '--help']
-    };
-
     const used = new Set(Object.values(schema.fields)
       .flatMap(field => field.aliases ?? [])
       .filter(alias => !alias.startsWith(ENV_PREFIX))

package/src/types.ts

@@ -1,5 +1,7 @@
 import type { Any, Class } from '@travetto/runtime';
 
+export const HELP_FLAG = '--help';
+
 type OrProm<T> = T | Promise<T>;
 type ParsedFlag = { type: 'flag', input: string, array?: boolean, fieldName: string, value?: unknown };
 type ParsedArg = { type: 'arg', input: string, array?: boolean, index: number };