@travetto/cli 7.0.0-rc.5 → 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
@@ -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 */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@travetto/cli",
-  "version": "7.0.0-rc.5",
+  "version": "7.0.0",
   "type": "module",
   "description": "CLI infrastructure for Travetto framework",
   "keywords": [
@@ -29,8 +29,8 @@
     "directory": "module/cli"
   },
   "dependencies": {
-    "@travetto/schema": "^7.0.0-rc.5",
-    "@travetto/terminal": "^7.0.0-rc.5"
+    "@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,30 +56,37 @@ 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
@@ -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/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[] = [];
@@ -103,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;
     }
 
@@ -116,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,
@@ -133,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
    */