@travetto/cli 7.0.0-rc.4 → 7.0.0

package/README.md

@@ -59,7 +59,7 @@ This module also has a tight integration with the [VSCode plugin](https://market
 At it's heart, a cli command is the contract defined by what flags, and what arguments the command supports. Within the framework this requires three criteria to be met:
    *  The file must be located in the `support/` folder, and have a name that matches `cli.*.ts`
    *  The file must be a class that has a main method
-   *  The class must use the [@CliCommand](https://github.com/travetto/travetto/tree/main/module/cli/src/registry/decorator.ts#L85) decorator
+   *  The class must use the [@CliCommand](https://github.com/travetto/travetto/tree/main/module/cli/src/registry/decorator.ts#L98) decorator
 
 **Code: Basic Command**
 ```typescript
@@ -94,7 +94,7 @@ Examples of mappings:
 The pattern is that underscores(_) translate to colons (:), and the `cli.` prefix, and `.ts` suffix are dropped.
 
 ## Binding Flags
-[@CliCommand](https://github.com/travetto/travetto/tree/main/module/cli/src/registry/decorator.ts#L85) is a wrapper for [@Schema](https://github.com/travetto/travetto/tree/main/module/schema/src/decorator/schema.ts#L19), and so every class that uses the [@CliCommand](https://github.com/travetto/travetto/tree/main/module/cli/src/registry/decorator.ts#L85) decorator is now a full [@Schema](https://github.com/travetto/travetto/tree/main/module/schema/src/decorator/schema.ts#L19) class. The fields of the class represent the flags that are available to the command.
+[@CliCommand](https://github.com/travetto/travetto/tree/main/module/cli/src/registry/decorator.ts#L98) is a wrapper for [@Schema](https://github.com/travetto/travetto/tree/main/module/schema/src/decorator/schema.ts#L19), and so every class that uses the [@CliCommand](https://github.com/travetto/travetto/tree/main/module/cli/src/registry/decorator.ts#L98) decorator is now a full [@Schema](https://github.com/travetto/travetto/tree/main/module/schema/src/decorator/schema.ts#L19) class. The fields of the class represent the flags that are available to the command.
 
 **Code: Basic Command with Flag**
 ```typescript
@@ -131,7 +131,7 @@ $ trv basic:flag --loud
 HELLO
 ```
 
-The [@CliCommand](https://github.com/travetto/travetto/tree/main/module/cli/src/registry/decorator.ts#L85) supports the following data types for flags:
+The [@CliCommand](https://github.com/travetto/travetto/tree/main/module/cli/src/registry/decorator.ts#L98) supports the following data types for flags:
    *  Boolean values
    *  Number values. The [@Integer](https://github.com/travetto/travetto/tree/main/module/schema/src/decorator/input.ts#L166), [@Float](https://github.com/travetto/travetto/tree/main/module/schema/src/decorator/input.ts#L173), [@Precision](https://github.com/travetto/travetto/tree/main/module/schema/src/decorator/input.ts#L159), [@Min](https://github.com/travetto/travetto/tree/main/module/schema/src/decorator/input.ts#L93) and [@Max](https://github.com/travetto/travetto/tree/main/module/schema/src/decorator/input.ts#L104) decorators help provide additional validation.
    *  String values. [@MinLength](https://github.com/travetto/travetto/tree/main/module/schema/src/decorator/input.ts#L93), [@MaxLength](https://github.com/travetto/travetto/tree/main/module/schema/src/decorator/input.ts#L104), [@Match](https://github.com/travetto/travetto/tree/main/module/schema/src/decorator/input.ts#L84) and [@Enum](https://github.com/travetto/travetto/tree/main/module/schema/src/decorator/input.ts#L58) provide additional constraints
@@ -213,9 +213,9 @@ export class BasicCommand {
 
 **Terminal: Basic Command**
 ```bash
-$ trv basic:arglist -h
+$ trv basic:arg-list -h
 
-Usage: basic:arglist [options] <volumes...:number>
+Usage: basic:arg-list [options] <volumes...:number>
 
 Options:
   -r, --reverse
@@ -224,19 +224,19 @@ Options:
 
 **Terminal: Basic Arg List**
 ```bash
-$ trv basic:arglist 10 5 3 9 8 1
+$ trv basic:arg-list 10 5 3 9 8 1
 
 1 3 5 8 9 10
 ```
 
 **Terminal: Basic Arg List with Invalid Number**
 ```bash
-$ trv basic:arglist 10 5 3 9 20 1
+$ trv basic:arg-list 10 5 3 9 20 1
 
 Execution failed:
  * Argument volumes[4] is greater than (10)
 
-Usage: basic:arglist [options] <volumes...:number>
+Usage: basic:arg-list [options] <volumes...:number>
 
 Options:
   -r, --reverse
@@ -245,7 +245,7 @@ Options:
 
 **Terminal: Basic Arg List with Reverse**
 ```bash
-$ trv basic:arglist -r 10 5 3 9 8 1
+$ trv basic:arg-list -r 10 5 3 9 8 1
 
 10 9 8 5 3 1
 ```
@@ -390,7 +390,7 @@ npx trv call:db --host localhost --port 3306 --username app --password <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.  [Web API](https://github.com/travetto/travetto/tree/main/module/web#readme "Declarative support for creating Web Applications") does expose a cli target `web:http` that will show up, to help run/debug a web 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/registry/decorator.ts#L85) decorator.  This means the target will be visible within the editor tooling.
+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.  [Web API](https://github.com/travetto/travetto/tree/main/module/web#readme "Declarative support for creating Web Applications") does expose a cli target `web:http` that will show up, to help run/debug a web 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/registry/decorator.ts#L98) decorator.  This means the target will be visible within the editor tooling.
 
 **Code: Simple Run Target**
 ```typescript
@@ -472,7 +472,7 @@ import type { WebHttpServer } from '../src/types.ts';
 /**
  * Run a web server
  */
-@CliCommand({ runTarget: true, with: { debugIpc: true, restartForDev: true, module: true, env: true } })
+@CliCommand({ runTarget: true, with: { debugIpc: 'optional', restartOnChange: true, module: true, env: true } })
 export class WebHttpCommand implements CliCommandShape {
 
   /** Port to run on */
@@ -502,7 +502,7 @@ export class WebHttpCommand implements CliCommandShape {
 }
 ```
 
-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 [Runtime](https://github.com/travetto/travetto/tree/main/module/runtime/src/context.ts#L13) `name` defined in the [Runtime](https://github.com/travetto/travetto/tree/main/module/runtime#readme "Runtime 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 [Runtime](https://github.com/travetto/travetto/tree/main/module/runtime/src/context.ts#L12) `name` defined in the [Runtime](https://github.com/travetto/travetto/tree/main/module/runtime#readme "Runtime 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.
 
@@ -550,13 +550,13 @@ Options:
 Available Services
 --------------------
  * dynamodb@3.1.0
- * elasticsearch@9.2.1
+ * elasticsearch@9.2.3
  * firestore@latest
  * mongodb@8.2
  * mysql@9.5
  * postgresql@18.1
  * redis@8.4
- * s3@4.10.0
+ * s3@4.11.0
 ```
 
 A sample of all services available to the entire framework:
@@ -568,13 +568,13 @@ $ trv service status
 Service          Version    Status
 -------------------------------------------------
 dynamodb           3.1.0    Running 93af422e793a
-elasticsearch      9.2.1    Running ed76ee063d13
+elasticsearch      9.2.3    Running ed76ee063d13
 firestore         latest    Running feec2e5e95b4
 mongodb              8.2    Running 5513eba6734e
 mysql                9.5    Running 307bc66d442a
 postgresql          18.1    Running e78291e71040
 redis                8.4    Running 77ba279b4e30
-s3                4.10.0    Running fdacfc55b9e3
+s3                4.11.0    Running fdacfc55b9e3
 ```
 
 ### Defining new Services

package/bin/trv.js

@@ -1,7 +1,4 @@
 #!/usr/bin/env node
-
-globalThis.__entry_point__ = __filename;
-
 // @ts-check
-require('@travetto/compiler/bin/entry.common.js')
-  .load(operations => operations.exec('@travetto/cli/support/entry.trv.js'));
+import { load } from '@travetto/compiler/bin/entry.common.js';
+load(operations => operations.exec('@travetto/cli/support/entry.trv.js'));

package/package.json

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

package/src/registry/decorator.ts

@@ -1,4 +1,4 @@
-import { Class, ClassInstance, Env, Runtime, RuntimeIndex, describeFunction, getClass } from '@travetto/runtime';
+import { Class, ClassInstance, Env, Runtime, RuntimeIndex, TypedObject, castTo, describeFunction, getClass } from '@travetto/runtime';
 import { SchemaFieldConfig, SchemaRegistryIndex, ValidationError } from '@travetto/schema';
 
 import { CliCommandShape } from '../types.ts';
@@ -18,19 +18,23 @@ type CliCommandConfigOptions = {
     /** Module to run for */
     module?: boolean;
     /** Should debug invocation trigger via ipc */
-    debugIpc?: boolean;
-    /** Should restart on code change */
-    restartForDev?: boolean;
+    debugIpc?: boolean | 'optional';
+    /** Should restart on source change */
+    restartOnChange?: boolean | 'optional';
   };
 };
 
-const FIELD_CONFIG: {
-  name: keyof Exclude<CliCommandConfigOptions['with'], undefined>;
+type WithConfig = Required<Exclude<CliCommandConfigOptions['with'], undefined>>;
+type WithHandler<K extends keyof WithConfig> = (config?: WithConfig[K]) => ({
+  name: K;
   field: Partial<SchemaFieldConfig>;
-  run: (cmd: Cmd) => (Promise<unknown> | unknown);
-}[] =
-  [
-    {
+  run?: (cmd: Cmd) => (Promise<unknown> | unknown);
+} | undefined)
+
+const FIELD_CONFIG: { [K in keyof WithConfig]: WithHandler<K> } = {
+  env: (config) => {
+    if (!config) return;
+    return {
       name: 'env',
       run: cmd => Env.TRV_ENV.set(cmd.env || Runtime.env),
       field: {
@@ -39,10 +43,12 @@ const FIELD_CONFIG: {
         description: 'Application environment',
         required: { active: false },
       },
-    },
-    {
+    }
+  },
+  module: (config) => {
+    if (!config) return;
+    return {
       name: 'module',
-      run: (): void => { },
       field: {
         type: String,
         aliases: ['-m', CliParseUtil.toEnvField(Env.TRV_MODULE.key)],
@@ -50,36 +56,43 @@ const FIELD_CONFIG: {
         specifiers: ['module'],
         required: { active: Runtime.monoRoot },
       },
-    },
-    {
+    }
+  },
+  debugIpc: (config) => {
+    if (!config) return;
+    return {
       name: 'debugIpc',
-      run: cmd => CliUtil.debugIfIpc(cmd).then((executed) => executed && process.exit(0)),
+      run: cmd => CliUtil.runWithDebugIpc(cmd).then((executed) => executed && process.exit(0)),
       field: {
         type: Boolean,
-        aliases: ['-di'],
+        aliases: ['-di', CliParseUtil.toEnvField(Env.TRV_DEBUG_IPC.key)],
         description: 'Should debug invocation trigger via ipc',
-        default: true,
+        default: config !== 'optional',
         required: { active: false },
       },
-    },
-    {
-      name: 'restartForDev',
-      run: cmd => CliUtil.runWithRestartOnCodeChanges(cmd),
+    };
+  },
+  restartOnChange: (config) => {
+    if (!config) return;
+    return {
+      name: 'restartOnChange',
+      run: cmd => CliUtil.runWithRestartOnChange(cmd),
       field: {
         type: Boolean,
-        aliases: ['-cr'],
+        aliases: ['-rc', CliParseUtil.toEnvField(Env.TRV_RESTART_ON_CHANGE.key)],
         description: 'Should the invocation automatically restart on source changes',
-        default: Runtime.envType === 'development',
+        default: config !== 'optional' && Runtime.envType === 'development',
         required: { active: false },
       },
-    }
-  ];
+    };
+  }
+};
 
 /**
  * Decorator to register a CLI command
  *
  * @augments `@travetto/schema:Schema`
- * @example main
+ * @example method:main
  * @kind decorator
  */
 export function CliCommand(config: CliCommandConfigOptions = {}) {
@@ -91,13 +104,13 @@ export function CliCommand(config: CliCommandConfigOptions = {}) {
       return;
     }
 
-    const VALID_FIELDS = FIELD_CONFIG.filter(field => !!config.with?.[field.name]);
+    const VALID_FIELDS = TypedObject.keys(FIELD_CONFIG).map((name) => FIELD_CONFIG[name](castTo(config.with?.[name]))).filter(x => !!x);
 
     CliCommandRegistryIndex.getForRegister(target).register({
       runTarget: config.runTarget,
       preMain: async (cmd: Cmd) => {
         for (const field of VALID_FIELDS) {
-          await field.run(cmd);
+          await field.run?.(cmd);
         }
       }
     });
@@ -105,7 +118,8 @@ export function CliCommand(config: CliCommandConfigOptions = {}) {
     const commandModule = description.module;
 
     for (const { name, field: { type, ...field } } of VALID_FIELDS) {
-      adapter.registerField(name, field, { type });
+      adapter.registerField(name, { type }, field);
+      Object.defineProperty(target.prototype, name, { value: field.default, writable: true });
     }
 
     const runtimeModule = config.runtimeModule ?? (config.with?.module ? 'current' : undefined);

package/src/registry/registry-index.ts

@@ -80,7 +80,6 @@ export class CliCommandRegistryIndex implements RegistryIndex {
     const uninitialized = filtered
       .filter(cls => !this.store.finalized(cls));
 
-
     // Initialize any uninitialized commands
     if (uninitialized.length) {
       // Ensure processed

package/src/trv.d.ts

@@ -8,8 +8,12 @@ declare module '@travetto/runtime' {
      */
     TRV_CLI_IPC: string;
     /** 
-     * Determines (assuming the operation supports it), that restart behavior can trigger  
+     * Overrides behavior for allowing restart on changes 
      */
-    TRV_CAN_RESTART: boolean;
+    TRV_RESTART_ON_CHANGE: boolean;
+    /** 
+     * Overrides behavior for triggering debug session via IPC
+     */
+    TRV_DEBUG_IPC: boolean;
   }
 }

package/src/types.ts

@@ -90,7 +90,7 @@ export type CliCommandShapeFields = {
   /**
    * Should the invocation run with auto-restart on source changes
    */
-  restartForDev?: boolean;
+  restartOnChange?: boolean;
   /**
    * The module to run the command from
    */

package/src/util.ts

@@ -37,9 +37,8 @@ export class CliUtil {
   /**
    * Run a command as restartable, linking into self
    */
-  static async runWithRestartOnCodeChanges<T extends CliCommandShapeFields & CliCommandShape>(cmd: T, config?: RunWithRestartOptions): Promise<boolean> {
-
-    if (Env.TRV_CAN_RESTART.isFalse || cmd.restartForDev !== true) {
+  static async runWithRestartOnChange<T extends CliCommandShapeFields & CliCommandShape>(cmd: T, config?: RunWithRestartOptions): Promise<boolean> {
+    if (cmd.restartOnChange !== true) {
       process.on('message', event => isCodeRestart(event) && process.exit(event.code));
       return false;
     }
@@ -48,7 +47,7 @@ export class CliUtil {
     let exhaustedRestarts = false;
     let subProcess: ChildProcess | undefined;
 
-    const env = { ...process.env, ...Env.TRV_CAN_RESTART.export(false) };
+    const env = { ...process.env, ...Env.TRV_RESTART_ON_CHANGE.export(false) };
     const maxRetries = config?.maxRetriesPerMinute ?? 5;
     const relayInterrupt = config?.relayInterrupt ?? true;
     const restarts: number[] = [];
@@ -92,7 +91,6 @@ export class CliUtil {
       restarts.push(Date.now());
     }
 
-
     if (exhaustedRestarts) {
       console.error(`Bailing, due to ${maxRetries} restarts in under 10s`);
     }
@@ -104,8 +102,8 @@ export class CliUtil {
   /**
    * Dispatch IPC payload
    */
-  static async triggerIpc<T extends CliCommandShape>(action: 'run', cmd: T): Promise<boolean> {
-    if (!Env.TRV_CLI_IPC.isSet) {
+  static async runWithDebugIpc<T extends CliCommandShapeFields & CliCommandShape>(cmd: T): Promise<boolean> {
+    if (cmd.debugIpc !== true || !Env.TRV_CLI_IPC.isSet) {
       return false;
     }
 
@@ -117,7 +115,7 @@ export class CliUtil {
 
     const env: Record<string, string> = {};
     const request = {
-      type: `@travetto/cli:${action}`,
+      type: `@travetto/cli:run`,
       data: {
         name: cmd._cfg!.name,
         env,
@@ -134,13 +132,6 @@ export class CliUtil {
     return sent.ok;
   }
 
-  /**
-   * Debug if IPC available
-   */
-  static async debugIfIpc<T extends CliCommandShapeFields & CliCommandShape>(cmd: T): Promise<boolean> {
-    return cmd.debugIpc === true && this.triggerIpc('run', cmd);
-  }
-
   /**
    * Write data to channel and ensure its flushed before continuing
    */

package/support/cli.cli_schema.ts

@@ -7,7 +7,6 @@ import { CliCommandRegistryIndex } from '../src/registry/registry-index.ts';
 import { CliUtil } from '../src/util.ts';
 import { CliSchemaExportUtil } from '../src/schema-export.ts';
 
-
 /**
  * Generates the schema for all CLI operations
  */