@travetto/cli 3.3.5 → 3.4.0-rc.0

package/README.md

@@ -420,7 +420,9 @@ If the goal is to run a more complex application, which may include depending on
 **Code: Simple Run Target**
 ```typescript
 import { DependencyRegistry } from '@travetto/di';
-import { CliCommand } from '@travetto/cli';
+import { CliCommand, CliUtil } from '@travetto/cli';
+import { GlobalEnv } from '@travetto/base';
+
 import { ServerHandle } from '../src/types';
 
 /**
@@ -429,6 +431,12 @@ import { ServerHandle } from '../src/types';
 @CliCommand({ runTarget: true, fields: ['module', 'env', 'profile'] })
 export class RunRestCommand {
 
+  /** IPC debug is enabled */
+  debugIpc = true;
+
+  /** Should the server be able to run with restart*/
+  canRestart = GlobalEnv.devMode;
+
   /** Port to run on */
   port?: number;
 
@@ -436,7 +444,11 @@ export class RunRestCommand {
     return this.port ? { REST_PORT: `${this.port}` } : {};
   }
 
-  async main(): Promise<ServerHandle> {
+  async main(): Promise<ServerHandle | void> {
+    if (await CliUtil.debugIfIpc(this) || await CliUtil.runWithRestart(this)) {
+      return;
+    }
+
     const { RestApplication } = await import('../src/application/rest.js');
     return DependencyRegistry.runInstance(RestApplication);
   }

package/bin/trv.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+
+// @ts-check
+import { withContext } from '@travetto/compiler/bin/common.js';
+
+withContext((ctx, compile) => compile(ctx, 'run')).then(load => load?.('@travetto/cli/support/entry.trv.js'));

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@travetto/cli",
-  "version": "3.3.5",
+  "version": "3.4.0-rc.0",
   "description": "CLI infrastructure for Travetto framework",
   "keywords": [
     "cli",
     "travetto",
     "typescript"
   ],
+  "type": "module",
   "homepage": "https://travetto.io",
   "license": "MIT",
   "author": {
@@ -15,17 +16,21 @@
   },
   "files": [
     "__index__.ts",
+    "bin",
     "src",
     "support"
   ],
   "main": "__index__.ts",
+  "bin": {
+    "trv": "bin/trv.js"
+  },
   "repository": {
     "url": "https://github.com/travetto/travetto.git",
     "directory": "module/cli"
   },
   "dependencies": {
-    "@travetto/schema": "^3.3.4",
-    "@travetto/terminal": "^3.3.1"
+    "@travetto/schema": "^3.4.0-rc.0",
+    "@travetto/terminal": "^3.4.0-rc.0"
   },
   "travetto": {
     "displayName": "Command Line Interface"

package/src/decorators.ts

@@ -3,7 +3,7 @@ import { RootIndex } from '@travetto/manifest';
 import { SchemaRegistry } from '@travetto/schema';
 
 import { CliCommandShape } from './types';
-import { CliCommandRegistry } from './registry';
+import { CliCommandRegistry, CliCommandConfigOptions } from './registry';
 import { CliModuleUtil } from './module';
 import { CliUtil } from './util';
 
@@ -17,7 +17,7 @@ const getMod = (cls: Class): string => RootIndex.getModuleFromSource(RootIndex.g
  * @augments `@travetto/schema:Schema`
  * @augments `@travetto/cli:CliCommand`
  */
-export function CliCommand(cfg: { fields?: ExtraFields[], runTarget?: boolean, hidden?: boolean } = {}) {
+export function CliCommand({ fields, ...cfg }: { fields?: ExtraFields[] } & CliCommandConfigOptions = {}) {
   return function <T extends CliCommandShape>(target: Class<T>): void {
     const meta = RootIndex.getFunctionMetadata(target);
     if (!meta || meta.abstract) {
@@ -25,17 +25,16 @@ export function CliCommand(cfg: { fields?: ExtraFields[], runTarget?: boolean, h
     }
 
     const name = getName(meta.source);
-    const addEnv = cfg.fields?.includes('env');
-    const addProfile = cfg.fields?.includes('profile');
-    const addModule = cfg.fields?.includes('module');
+    const addEnv = fields?.includes('env');
+    const addProfile = fields?.includes('profile');
+    const addModule = fields?.includes('module');
 
     CliCommandRegistry.registerClass({
       module: getMod(target),
       name,
       // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
       cls: target as ConcreteClass<T>,
-      hidden: cfg.hidden,
-      runTarget: cfg.runTarget,
+      ...cfg,
       preMain: (cmd: CliCommandShape & { env?: string, profile?: string[], module?: string }) => {
         if (addEnv || addProfile) {
           defineGlobalEnv({

package/src/error.ts

@@ -0,0 +1,63 @@
+import { RootIndex } from '@travetto/manifest';
+
+import { cliTpl } from './color';
+import { CliValidationError } from './types';
+
+const COMMAND_PACKAGE = [
+  [/^test(:watch)?$/, 'test', false],
+  [/^service$/, 'command', true],
+  [/^lint(:register)?$/, 'lint', true],
+  [/^model:(install|export)$/, 'model', true],
+  [/^openapi:(spec|client)$/, 'openapi', true],
+  [/^email:(compile|editor)$/, 'email-compiler', false],
+  [/^pack(:zip|:docker)?$/, 'pack', false],
+  [/^run:rest$/, 'rest', false],
+] as const;
+
+/**
+ * Provides a contract for unknown commands
+ */
+export class CliUnknownCommandError extends Error {
+
+  #getMissingCommandHelp(cmd: string): string | undefined {
+    const matchedCfg = COMMAND_PACKAGE.find(([re]) => re.test(cmd));
+    if (matchedCfg) {
+      const [, pkg, prod] = matchedCfg;
+      let install: string;
+      switch (RootIndex.manifest.packageManager) {
+        case 'npm': install = `npm i ${prod ? '' : '--save-dev '}@travetto/${pkg}`; break;
+        case 'yarn': install = `yarn add ${prod ? '' : '--dev '}@travetto/${pkg}`; break;
+      }
+      return cliTpl`
+${{ title: 'Missing Package' }}\n${'-'.repeat(20)}\nTo use ${{ input: cmd }} please run:\n
+${{ identifier: install }}
+`;
+    }
+  }
+
+  help?: string;
+  cmd: string;
+
+  constructor(cmd: string) {
+    super(`Unknown command: ${cmd}`);
+    this.cmd = cmd;
+    this.help = this.#getMissingCommandHelp(cmd);
+  }
+
+  get defaultMessage(): string {
+    return cliTpl`${{ subtitle: 'Unknown command' }}: ${{ input: this.cmd }}`;
+  }
+}
+
+
+/**
+ * Provides a basic error wrapper for cli validation issues
+ */
+export class CliValidationResultError extends Error {
+  errors: CliValidationError[];
+
+  constructor(errors: CliValidationError[]) {
+    super('');
+    this.errors = errors;
+  }
+}

package/src/execute.ts

@@ -1,13 +1,11 @@
-import { appendFile, mkdir } from 'fs/promises';
-
 import { GlobalTerminal } from '@travetto/terminal';
-import { path } from '@travetto/manifest';
 import { ConsoleManager, defineGlobalEnv, ShutdownManager, GlobalEnv } from '@travetto/base';
 
 import { HelpUtil } from './help';
-import { CliCommandShape, CliValidationResultError } from './types';
+import { CliCommandShape } from './types';
 import { CliCommandRegistry } from './registry';
 import { CliCommandSchemaUtil } from './schema';
+import { CliUnknownCommandError, CliValidationResultError } from './error';
 
 /**
  * Execution manager
@@ -30,13 +28,6 @@ export class ExecutionManager {
     return known;
   }
 
-  static #getAction(cmd: CliCommandShape, args: string[]): 'help' | 'ipc' | 'command' {
-    const cfg = CliCommandRegistry.getConfig(cmd);
-    return args.find(a => /^(-h|--help)$/.test(a)) ?
-      'help' :
-      (process.env.TRV_CLI_IPC && cfg.runTarget) ? 'ipc' : 'command';
-  }
-
   /**
    * Run help
    */
@@ -46,24 +37,6 @@ export class ExecutionManager {
     console.log!(await HelpUtil.renderHelp(cmd));
   }
 
-  /**
-   * Append IPC payload to provided file
-   */
-  static async ipc(cmd: CliCommandShape, args: string[]): Promise<void> {
-    await this.#bindAndValidateArgs(cmd, args);
-    const file = process.env.TRV_CLI_IPC!;
-    const cfg = CliCommandRegistry.getConfig(cmd);
-    const payload = JSON.stringify({
-      type: '@travetto/cli:run', data: {
-        name: cfg.name,
-        module: cfg.module,
-        args: process.argv.slice(3)
-      }
-    });
-    await mkdir(path.dirname(file), { recursive: true });
-    await appendFile(file, `${payload}\n`);
-  }
-
   /**
    * Run the given command object with the given arguments
    */
@@ -103,15 +76,25 @@ export class ExecutionManager {
       try {
         // Load a single command
         command = (await CliCommandRegistry.getInstance(cmd, true));
-        const action = this.#getAction(command, args);
-        await this[action](command, args);
+        if (args.some(a => /^(-h|--help)$/.test(a))) {
+          await this.help(command, args);
+        } else {
+          await this.command(command, args);
+        }
       } catch (err) {
         process.exitCode ||= 1; // Trigger error state
         if (!(err instanceof Error)) {
           throw err;
-        } else if (command && err instanceof CliValidationResultError) {
-          console.error(await HelpUtil.renderValidationError(command, err));
+        } else if (err instanceof CliValidationResultError) {
+          console.error!(await HelpUtil.renderValidationError(command!, err));
           console.error!(await HelpUtil.renderHelp(command));
+        } else if (err instanceof CliUnknownCommandError) {
+          if (err.help) {
+            console.error!(err.help);
+          } else {
+            console.error!(err.defaultMessage, '\n');
+            console.error!(await HelpUtil.renderAllHelp(''));
+          }
         } else {
           console.error!(err);
           console.error!();

package/src/help.ts

@@ -2,9 +2,10 @@ import { Primitive } from '@travetto/base';
 import { stripAnsiCodes } from '@travetto/terminal';
 
 import { cliTpl } from './color';
-import { CliCommandShape, CliValidationResultError } from './types';
+import { CliCommandShape } from './types';
 import { CliCommandRegistry } from './registry';
 import { CliCommandSchemaUtil } from './schema';
+import { CliValidationResultError } from './error';
 
 const validationSourceMap = {
   custom: '',
@@ -21,7 +22,7 @@ export class HelpUtil {
    * Render command-specific help
    * @param command
    */
-  static async #renderCommandHelp(command: CliCommandShape): Promise<string> {
+  static async renderCommandHelp(command: CliCommandShape): Promise<string> {
     const commandName = CliCommandRegistry.getName(command);
 
     command.initialize?.();
@@ -93,7 +94,7 @@ export class HelpUtil {
   /**
    * Render help listing of all commands
    */
-  static async #renderAllHelp(): Promise<string> {
+  static async renderAllHelp(title?: string): Promise<string> {
     const rows: string[] = [];
     const keys = [...CliCommandRegistry.getCommandMapping().keys()].sort((a, b) => a.localeCompare(b));
     const maxWidth = keys.reduce((a, b) => Math.max(a, stripAnsiCodes(b).length), 0);
@@ -116,20 +117,20 @@ export class HelpUtil {
         }
       }
     }
-    return [
-      cliTpl`${{ title: 'Usage:' }}  ${{ param: '[options]' }} ${{ param: '[command]' }}`,
-      '',
-      cliTpl`${{ title: 'Commands:' }}`,
-      ...rows,
-      ''
-    ].map(x => x.trimEnd()).join('\n');
+
+    const lines = [cliTpl`${{ title: 'Commands:' }}`, ...rows, ''];
+
+    if (title === undefined || title) {
+      lines.unshift(title ? cliTpl`${{ title }}` : cliTpl`${{ title: 'Usage:' }}  ${{ param: '[options]' }} ${{ param: '[command]' }}`, '');
+    }
+    return lines.map(x => x.trimEnd()).join('\n');
   }
 
   /**
    * Render help
    */
   static async renderHelp(command?: CliCommandShape): Promise<string> {
-    return command ? this.#renderCommandHelp(command) : this.#renderAllHelp();
+    return command ? this.renderCommandHelp(command) : this.renderAllHelp();
   }
 
   /**

package/src/registry.ts

@@ -1,52 +1,27 @@
 import { Class, ConcreteClass } from '@travetto/base';
 import { RootIndex } from '@travetto/manifest';
 
-import { cliTpl } from './color';
 import { CliCommandShape } from './types';
+import { CliUnknownCommandError } from './error';
 
-type CliCommandConfig = {
+export type CliCommandConfigOptions = {
+  runTarget?: boolean;
+  hidden?: boolean;
+};
+
+export type CliCommandConfig = CliCommandConfigOptions & {
   name: string;
   module: string;
   cls: ConcreteClass<CliCommandShape>;
-  runTarget?: boolean;
-  hidden?: boolean;
   preMain?: (cmd: CliCommandShape) => void | Promise<void>;
 };
 
-const COMMAND_PACKAGE = [
-  [/^test(:watch)?$/, 'test', false],
-  [/^service$/, 'command', true],
-  [/^lint(:register)?$/, 'lint', true],
-  [/^model:(install|export)$/, 'model', true],
-  [/^openapi:(spec|client)$/, 'openapi', true],
-  [/^email:(compile|editor)$/, 'email-compiler', false],
-  [/^pack(:zip|:docker)?$/, 'pack', false],
-] as const;
-
 const CLI_REGEX = /\/cli[.]([^.]+)[.][^.]+?$/;
 
 class $CliCommandRegistry {
   #commands = new Map<Class, CliCommandConfig>();
   #fileMapping: Map<string, string>;
 
-  #getMissingCommandHelp(cmd: string): string {
-    const matchedCfg = COMMAND_PACKAGE.find(([re]) => re.test(cmd));
-    if (matchedCfg) {
-      const [, pkg, prod] = matchedCfg;
-      let install: string;
-      switch (RootIndex.manifest.packageManager) {
-        case 'npm': install = `npm i ${prod ? '' : '--save-dev '}@travetto/${pkg}`; break;
-        case 'yarn': install = `yarn add ${prod ? '' : '--dev '}@travetto/${pkg}`; break;
-      }
-      return cliTpl`
-${{ title: 'Missing Package' }}\n${'-'.repeat(20)}\nTo use ${{ input: cmd }} please run:\n
-${{ identifier: install }}
-`;
-    } else {
-      return `Unknown command: ${cmd}`;
-    }
-  }
-
   #get(cls: Class): CliCommandConfig | undefined {
     return this.#commands.get(cls);
   }
@@ -115,7 +90,7 @@ ${{ identifier: install }}
         return undefined;
       }
     }
-    throw new Error(this.#getMissingCommandHelp(name));
+    throw new CliUnknownCommandError(name);
   }
 }
 

package/src/schema.ts

@@ -1,8 +1,9 @@
 import { Class, ConsoleManager, GlobalEnv } from '@travetto/base';
 import { BindUtil, FieldConfig, SchemaRegistry, SchemaValidator, ValidationResultError } from '@travetto/schema';
-import { CliCommandRegistry } from './registry';
 
-import { CliCommandInput, CliCommandSchema, CliCommandShape, CliValidationResultError } from './types';
+import { CliCommandRegistry } from './registry';
+import { CliCommandInput, CliCommandSchema, CliCommandShape } from './types';
+import { CliValidationResultError } from './error';
 
 function fieldToInput(x: FieldConfig): CliCommandInput {
   const type = x.type === Date ? 'date' :

package/src/types.ts

@@ -18,18 +18,6 @@ export type CliValidationError = {
   source?: 'flag' | 'arg' | 'custom';
 };
 
-/**
- * Provides a basic error wrapper for internal try/catch instanceof
- */
-export class CliValidationResultError extends Error {
-  errors: CliValidationError[];
-
-  constructor(errors: CliValidationError[]) {
-    super('');
-    this.errors = errors;
-  }
-}
-
 /**
  * CLI Command Contract
  */

package/src/util.ts

@@ -1,4 +1,10 @@
-import { RootIndex } from '@travetto/manifest';
+import fs from 'fs/promises';
+
+import { Env, ExecUtil } from '@travetto/base';
+import { path, RootIndex } from '@travetto/manifest';
+
+import { CliCommandShape } from './types';
+import { CliCommandRegistry } from './registry';
 
 export class CliUtil {
   /**
@@ -15,4 +21,56 @@ export class CliUtil {
   static getSimpleModuleName(name = RootIndex.mainModuleName): string {
     return name.replace(/[\/]/, '_').replace(/@/, '');
   }
+
+  /**
+   * Run a command as restartable, linking into self
+   */
+  static runWithRestart<T extends CliCommandShape & { canRestart?: boolean }>(cmd: T): Promise<unknown> | undefined {
+    if (cmd.canRestart !== false && Env.isFalse('TRV_CAN_RESTART')) {
+      delete process.env.TRV_CAN_RESTART;
+      return;
+    }
+    return ExecUtil.spawnWithRestart(process.argv0, process.argv.slice(1), {
+      env: { TRV_DYNAMIC: '1', TRV_CAN_RESTART: '0' },
+      stdio: [0, 1, 2, 'ipc']
+    });
+  }
+
+  /**
+   * Dispatch IPC payload
+   */
+  static async triggerIpc<T extends CliCommandShape>(action: 'run', cmd: T): Promise<boolean> {
+    const file = process.env.TRV_CLI_IPC;
+
+    if (!file) {
+      return false;
+    }
+
+    const cfg = CliCommandRegistry.getConfig(cmd);
+    const payload = JSON.stringify({
+      type: `@travetto/cli:${action}`, data: {
+        name: cfg.name,
+        commandModule: cfg.module,
+        module: RootIndex.manifest.mainModule,
+        args: process.argv.slice(3)
+      }
+    });
+    await fs.mkdir(path.dirname(file), { recursive: true });
+    await fs.appendFile(file, `${payload}\n`);
+    return true;
+  }
+
+  /**
+   * Debug if IPC available
+   */
+  static async debugIfIpc<T extends CliCommandShape & { debugIpc?: boolean }>(cmd: T): Promise<boolean> {
+    return cmd.debugIpc !== false && this.triggerIpc('run', cmd);
+  }
+
+  /**
+   * Write data to channel and ensure its flushed before continuing
+   */
+  static async writeAndEnsureComplete(data: unknown, channel: 'stdout' | 'stderr' = 'stdout'): Promise<void> {
+    return await new Promise(r => process[channel].write(typeof data === 'string' ? data : JSON.stringify(data, null, 2), () => r()));
+  }
 }

package/support/cli.cli_schema.ts

@@ -2,6 +2,7 @@ import { CliCommand } from '../src/decorators';
 import { CliCommandSchema, CliValidationError } from '../src/types';
 import { CliCommandRegistry } from '../src/registry';
 import { CliCommandSchemaUtil } from '../src/schema';
+import { CliUtil } from '../src/util';
 
 /**
  * Generates the schema for all CLI operations
@@ -24,12 +25,14 @@ export class CliSchemaCommand {
   }
 
   async main(name?: string): Promise<void> {
+    let output: unknown = undefined;
     if (name) {
-      console.log(JSON.stringify(await this.#getSchema(name), null, 2));
+      output = await this.#getSchema(name);
     } else {
       const names = [...CliCommandRegistry.getCommandMapping().keys()];
       const schemas = await Promise.all(names.map(x => this.#getSchema(x)));
-      console.log(JSON.stringify(schemas, null, 2));
+      output = schemas;
     }
+    await CliUtil.writeAndEnsureComplete(output);
   }
 }