@travetto/cli 8.0.0-alpha.20 → 8.0.0-alpha.22

package/README.md

@@ -22,34 +22,38 @@ $ trv --help
 Usage:  [options] [command]
 
 Commands:
-  doc               Command line support for generating module docs.
-  doc:angular       Generate documentation into the angular webapp under related/travetto.github.io
-  doc:mapping       Generate module mapping for
-  email:compile     CLI Entry point for running the email server
-  email:editor      The email editor compilation service and output serving
-  email:test        CLI Entry point for running the email server
-  eslint            Command line support for eslint
-  eslint:register   Writes the eslint configuration file
-  model:export      Exports model schemas
-  model:install     Installing models
-  openapi:client    CLI for generating the cli client
-  openapi:spec      CLI for outputting the open api spec to a local file
-  pack              Standard pack support
-  pack:docker       Standard docker support for pack
-  pack:lambda       Standard lambda support for pack
-  pack:zip          Standard zip support for pack
-  repo:exec         Repo execution
-  repo:list         Allows for listing of modules
-  repo:publish      Publish all pending modules
-  repo:version      Version all changed dependencies
-  repo:version-sync Enforces all packages to write out their versions and dependencies
-  run:double        Doubles a number
-  scaffold          Command to run scaffolding
-  service           Allows for running services
-  test              Launch test framework and execute tests
-  test:watch        Invoke the test watcher
-  web:http          Run a web server
-  web:rpc-client    Generate the web-rpc client
+  doc                   Generate documentation outputs from a module `DOC.tsx` entry file.
+  doc:angular           Generate documentation into the angular webapp under related/travetto.github.io
+  doc:mapping           Generate module mapping for
+  email:compile         Compile all email templates into generated runtime artifacts.
+  email:editor          Start the email template editor service for interactive preview and testing.
+  email:test            Render and send a template file to a target recipient for quick validation.
+  eslint                Run ESLint for the workspace or changed files.
+  eslint:register       Generate the workspace ESLint configuration entry file.
+  llm:support:execute   Execute llm-support operations with dry-run by default.
+  llm:support:mcp       Minimal MCP stdio server for llm-support tools.
+  llm:support:plan      Build plan-first execution details for llm-support operations.
+  llm:support:recommend Recommend llm-support bundles, workflows, and operations.
+  llm:support:status    Show llm-support execution coverage status.
+  model:export          Export model definitions for a selected provider and model set.
+  model:install         Install or update model definitions for a selected provider.
+  openapi:client        Generate API clients from an OpenAPI specification using the generator image.
+  openapi:spec          Generate the OpenAPI specification for the selected module.
+  pack                  Build a standard module package artifact.
+  pack:docker           Build container-ready artifacts and optionally publish Docker images.
+  pack:lambda           Build an AWS Lambda-ready zip package using the pack pipeline.
+  pack:zip              Build a deployable zip artifact using the standard pack pipeline.
+  repo:exec             Execute a shell command across workspace modules.
+  repo:list             List workspace modules and their relationships.
+  repo:publish          Publish unpublished workspace modules to the package registry.
+  repo:version          Bump workspace module versions and optionally commit/tag release metadata.
+  repo:version-sync     Synchronize package versions and dependency ranges across the monorepo.
+  run:double            Doubles a number
+  service               Manage development services (start/stop/restart/status) across the workspace.
+  test                  Execute the test framework for targeted files, suites, or methods.
+  test:watch            Start the test watcher for continuous test execution.
+  web:http              Start the configured web HTTP server for a module.
+  web:rpc-client        Generate web-rpc client artifacts from a specified provider or leveraging local config.
 ```
 
 This listing is from the [Travetto](https://travetto.dev) monorepo, and represents the majority of tools that can be invoked from the command line. 
@@ -259,7 +263,7 @@ import { CliCommand } from '@travetto/cli';
 import { Max, Min } from '@travetto/schema';
 
 /**
- * Custom Argument Command
+ * Example command with a custom argument
  */
 @CliCommand()
 export class CustomCommand {
@@ -283,6 +287,8 @@ $ trv custom:arg --help
 
 Usage: custom:arg [options] [volume:number]
 
+Example command with a custom argument
+
 Options:
   -m, --message <string>  The message to send back to the user (default: "hello")
   --help                  display help for command
@@ -311,7 +317,7 @@ import { CliCommand } from '@travetto/cli';
 import { Max, Min } from '@travetto/schema';
 
 /**
- * Custom Argument Command
+ * Example of a command with a custom environment variable argument
  */
 @CliCommand()
 export class CustomCommand {
@@ -334,6 +340,8 @@ $ trv custom:env-arg --help
 
 Usage: custom:env-arg [options] [volume:number]
 
+Example of a command with a custom environment variable argument
+
 Options:
   -t, --text <string>  The message to send back to the user (default: "hello")
   --help               display help for command
@@ -442,7 +450,12 @@ import { Registry } from '@travetto/registry';
 import type { WebHttpServer } from '../src/types.ts';
 
 /**
- * Run a web server
+ * Start the configured web HTTP server for a module.
+ *
+ * Initializes registry and server bindings, supports restart-aware development
+ * flags, and can attempt to clear conflicting port owners in local workflows.
+ *
+ * @example trv web:http -m <MODULE> -p 3000
  */
 @CliCommand()
 export class WebHttpCommand implements CliCommandShape {
@@ -551,12 +564,17 @@ A simple example of the validation can be found in the `doc` command:
 ## CLI - service
 The module provides the ability to start/stop/restart services as [docker](https://www.docker.com/community-edition) containers.  This is meant to be used for development purposes, to minimize the effort of getting an application up and running.  Services can be targeted individually or handled as a group.
 
-**Terminal: Command Service**
+**Terminal: Help for service**
 ```bash
 $ trv service --help
 
 Usage: service [options] <action:restart|start|status|stop> [services...:string]
 
+Manage development services (start/stop/restart/status) across the workspace.
+
+Services are discovered from registered descriptors and executed with streamed
+terminal feedback, including optional quiet mode.
+
 Options:
   -q, --quiet   (default: false)
   --help       display help for command
@@ -566,7 +584,7 @@ Available Services
  * dynamodb@3.3.0
  * elasticsearch@9.2.8
  * firestore@latest
- * mongodb@8.2
+ * mongodb@8.3
  * mysql@9.6
  * postgresql@18.3
  * redis@8.4
@@ -584,7 +602,7 @@ Service          Version    Status
 dynamodb           3.3.0    Running 93af422e793a
 elasticsearch      9.2.8    Running ed76ee063d13
 firestore         latest    Running feec2e5e95b4
-mongodb              8.2    Running 5513eba6734e
+mongodb              8.3    Running 5513eba6734e
 mysql                9.6    Running 307bc66d442a
 postgresql          18.3    Running e78291e71040
 redis                8.4    Running 77ba279b4e30
@@ -598,12 +616,16 @@ The services are defined as plain typescript files within the framework and can
 ```typescript
 import type { ServiceDescriptor } from '@travetto/cli';
 
-const version = process.env.MONGO_VERSION || '8.2';
+const version = process.env.MONGO_VERSION || '8.3';
 
 export const service: ServiceDescriptor = {
   name: 'mongodb',
   version,
   port: 27017,
-  image: `mongo:${version}`
+  image: `mongo:${version}`,
+  env: {
+    // Temp until mongo image fixes orbstack issue
+    GLIBC_TUNABLES: 'glibc.pthread.rseq=1'
+  }
 };
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@travetto/cli",
-  "version": "8.0.0-alpha.20",
+  "version": "8.0.0-alpha.22",
   "type": "module",
   "description": "CLI infrastructure for Travetto framework",
   "keywords": [
@@ -29,8 +29,8 @@
     "directory": "module/cli"
   },
   "dependencies": {
-    "@travetto/schema": "^8.0.0-alpha.15",
-    "@travetto/terminal": "^8.0.0-alpha.14"
+    "@travetto/schema": "^8.0.0-alpha.17",
+    "@travetto/terminal": "^8.0.0-alpha.16"
   },
   "travetto": {
     "displayName": "Command Line Interface",

package/src/help.ts

@@ -1,6 +1,6 @@
 import util from 'node:util';
 
-import { castKey, getClass, JSONUtil, Runtime } from '@travetto/runtime';
+import { castKey, CodecUtil, getClass, JSONUtil, Runtime } from '@travetto/runtime';
 import { SchemaRegistryIndex, ValidationResultError } from '@travetto/schema';
 
 import { cliTpl } from './color.ts';
@@ -33,38 +33,43 @@ const COMMAND_TO_MODULE = Object.fromEntries(Object.entries(MODULE_TO_COMMAND).f
  */
 export class HelpUtil {
 
-  /** 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> {
+  /** 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 ?? [];
 
-    const usage = [cliTpl`${{ title: 'Usage:' }} ${{ param: commandName }} ${{ input: '[options]' }}`,];
-    const params: string[] = [];
-    const descriptions: string[] = [];
+    const usage: string[] = [];
+
+    usage.push(
+      cliTpl`${{ title: 'Usage:' }} ${{ param: commandName }} ${{ input: '[options]' }}`
+    );
 
     // Ensure finalized
-    for (const field of args) {
+    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}]` }}`);
     }
+    usage.push('');
+    return usage;
+  }
+
+  /** 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[] = [];
 
     for (const field of Object.values(schema.fields)) {
       const key = castKey<CliCommandShape>(field.name);
@@ -106,20 +111,68 @@ ${{ identifier: Runtime.getInstallCommand(module) }}
     const paramWidth = Math.max(...paramWidths);
     const descWidth = Math.max(...descWidths);
 
+    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]))}`
-      ),
-      '',
-      ...extendedHelpText
+      ...this.getUsageMessage(command),
+      ...this.getDescriptionMessage(command),
+      ...this.getOptionsMessage(command),
+      ...await this.getExtendedHelpMessage(command),
+      ...this.getExamplesMessage(command)
     ].map(line => line.trimEnd()).join('\n');
   }
 
@@ -136,11 +189,13 @@ ${{ identifier: Runtime.getInstallCommand(module) }}
     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;
         }

package/src/registry/decorator.ts

@@ -84,7 +84,7 @@ export function CliModuleFlag(config: CliFlagOptions & { scope?: 'current' | 'co
       ...CliParseUtil.buildAliases(config, Env.TRV_MODULE.key),
       description: 'Module to run for',
       specifiers: ['module'],
-      required: { active: Runtime.monoRoot },
+      required: { active: Runtime.monoRoot && config.scope !== 'command' },
     });
 
     SchemaRegistryIndex.getForRegister(cls).register({
@@ -147,7 +147,7 @@ export function CliDebugIpcFlag(config: CliFlagOptions = {}) {
     const cls = getClass(instance);
     SchemaRegistryIndex.getForRegister(cls).registerField(property, {
       ...CliParseUtil.buildAliases(config, Env.TRV_DEBUG_IPC.key),
-      description: 'Should the invocation automatically restart on source changes'
+      description: 'Should the invocation support debugging via IPC (e.g. from VSCode)'
     });
 
     CliCommandRegistryIndex.getForRegister(cls).register({ runTarget: true });

package/src/schema-export.ts

@@ -1,7 +1,7 @@
 import { castTo, type Class, describeFunction } from '@travetto/runtime';
 import { type SchemaInputConfig, SchemaRegistryIndex } from '@travetto/schema';
 
-import { CliCommandRegistryIndex } from '../src/registry/registry-index.ts';
+import { CliCommandRegistryIndex } from './registry/registry-index.ts';
 
 /**
  * CLI Command argument/flag shape

package/support/cli.cli_schema.ts

@@ -25,7 +25,10 @@ async function nameValidator(names?: string[]): Promise<ValidationError | undefi
 }
 
 /**
- * Generates the schema for all CLI operations
+ * Exports machine-readable command metadata for automation and tooling.
+ *
+ * Used by editor integrations to discover runnable commands and inputs.
+ * Used by guidance workflows to validate command signatures.
  */
 @CliCommand()
 @IsPrivate()

package/support/cli.main.ts

@@ -11,7 +11,10 @@ async function validateMain(fileOrImport: string): Promise<ValidationError | und
 };
 
 /**
- * Allows for running of main entry points
+ * Execute a module `main()` entrypoint directly.
+ *
+ * This internal command resolves an import/source target, invokes its exported
+ * `main` function, and forwards unknown CLI args to that function.
  */
 @CliCommand()
 @IsPrivate()

package/support/cli.service.ts

@@ -16,7 +16,10 @@ async function validateService(_: ServiceAction, services: string[]): Promise<Va
 }
 
 /**
- * Allows for running services
+ * Manage development services (start/stop/restart/status) across the workspace.
+ *
+ * Services are discovered from registered descriptors and executed with streamed
+ * terminal feedback, including optional quiet mode.
  */
 @CliCommand()
 export class CliServiceCommand implements CliCommandShape {