@travetto/cli 8.0.0-alpha.3 → 8.0.0-alpha.30

package/src/service.ts

@@ -1,15 +1,12 @@
 import { spawn } from 'node:child_process';
 import fs from 'node:fs/promises';
-import rl from 'node:readline/promises';
 import net from 'node:net';
+import rl from 'node:readline/promises';
 
 import { ExecUtil, Runtime, RuntimeIndex, TimeUtil, Util } from '@travetto/runtime';
 
 const ports = (value: number | `${number}:${number}`): [number, number] =>
-  typeof value === 'number' ?
-    [value, value] :
-    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
-    value.split(':').map(number => parseInt(number, 10)) as [number, number];
+  typeof value === 'number' ? [value, value] : (value.split(':').map(number => parseInt(number, 10)) as [number, number]);
 
 type BodyCheck = (body: string) => boolean;
 
@@ -23,7 +20,7 @@ export interface ServiceDescriptor {
   privileged?: boolean;
   image: string;
   args?: string[];
-  ready?: { url: string, test?: BodyCheck };
+  ready?: { url: string; test?: BodyCheck };
   volumes?: Record<string, string>;
   env?: Record<string, string>;
   startupTimeout?: number;
@@ -35,37 +32,39 @@ export type ServiceAction = 'start' | 'stop' | 'status' | 'restart';
  * Service runner
  */
 export class ServiceRunner {
-
   /**
    * Find all services
    */
   static async findServices(services: string[]): Promise<ServiceDescriptor[]> {
-    return (await Promise.all(
-      RuntimeIndex.find({
-        module: module => module.roles.includes('std'),
-        folder: folder => folder === 'support',
-        file: file => /support\/service[.]/.test(file.sourceFile)
-      })
-        .map(file => Runtime.importFrom<{ service: ServiceDescriptor }>(file.import).then(value => value.service))
-    ))
+    return (
+      await Promise.all(
+        RuntimeIndex.find({
+          module: module => module.roles.includes('std'),
+          folder: folder => folder === 'support',
+          file: file => /support\/service[.]/.test(file.sourceFile)
+        }).map(file => Runtime.importFrom<{ service: ServiceDescriptor }>(file.import).then(value => value.service))
+      )
+    )
       .filter(file => !!file)
-      .filter(file => services?.length ? services.includes(file.name) : true)
+      .filter(file => (services?.length ? services.includes(file.name) : true))
       .toSorted((a, b) => a.name.localeCompare(b.name));
   }
 
   #descriptor: ServiceDescriptor;
-  constructor(descriptor: ServiceDescriptor) { this.#descriptor = descriptor; }
+  constructor(descriptor: ServiceDescriptor) {
+    this.#descriptor = descriptor;
+  }
 
   async #isRunning(full = false): Promise<boolean> {
     const port = ports(this.#descriptor.port!)[0];
     const start = Date.now();
-    const timeoutMs = TimeUtil.duration(full ? this.#descriptor.startupTimeout ?? 5000 : 100, 'ms');
-    while ((Date.now() - start) < timeoutMs) {
+    const timeoutMs = TimeUtil.duration(full ? (this.#descriptor.startupTimeout ?? 5000) : 100, 'ms');
+    while (Date.now() - start < timeoutMs) {
       try {
         const sock = net.createConnection(port, 'localhost');
-        await new Promise<void>((resolve, reject) =>
-          sock.on('connect', resolve).on('timeout', reject).on('error', reject)
-        ).finally(() => sock.destroy());
+        await new Promise<void>((resolve, reject) => sock.on('connect', resolve).on('timeout', reject).on('error', reject)).finally(() =>
+          sock.destroy()
+        );
 
         if (!this.#descriptor.ready?.url || !full) {
           return true;
@@ -89,7 +88,7 @@ export class ServiceRunner {
     return result.valid;
   }
 
-  async * #pullImage(): AsyncIterable<string> {
+  async *#pullImage(): AsyncIterable<string> {
     const subProcess = spawn('docker', ['pull', this.#descriptor.image], { stdio: [0, 'pipe', 'pipe'] });
     yield* rl.createInterface(subProcess.stdout!);
     await ExecUtil.getResult(subProcess);
@@ -100,13 +99,14 @@ export class ServiceRunner {
       'run',
       '--rm',
       '--detach',
-      ...this.#descriptor.privileged ? ['--privileged'] : [],
-      '--label', `trv-${this.#descriptor.name}`,
+      ...(this.#descriptor.privileged ? ['--privileged'] : []),
+      '--label',
+      `trv-${this.#descriptor.name}`,
       ...Object.entries(this.#descriptor.env ?? {}).flatMap(([key, value]) => ['--env', `${key}=${value}`]),
-      ...this.#descriptor.port ? ['-p', ports(this.#descriptor.port).join(':')] : [],
+      ...(this.#descriptor.port ? ['-p', ports(this.#descriptor.port).join(':')] : []),
       ...Object.entries(this.#descriptor.volumes ?? {}).flatMap(([key, value]) => ['--volume', `${key}:${value}`]),
       this.#descriptor.image,
-      ...this.#descriptor.args ?? [],
+      ...(this.#descriptor.args ?? [])
     ];
 
     for (const item of Object.keys(this.#descriptor.volumes ?? {})) {
@@ -124,13 +124,14 @@ export class ServiceRunner {
     await ExecUtil.getResult(spawn('docker', ['kill', containerId]));
   }
 
-  async * action(operation: ServiceAction): AsyncIterable<['success' | 'failure' | 'message', string]> {
+  async *action(operation: ServiceAction): AsyncIterable<['success' | 'failure' | 'message', string]> {
     try {
       const containerId = await this.#getContainerId();
       const port = this.#descriptor.port ? ports(this.#descriptor.port)[0] : 0;
-      const running = !!containerId && (!port || await this.#isRunning());
+      const running = !!containerId && (!port || (await this.#isRunning()));
 
-      if (running && !containerId) { // We don't own
+      if (running && !containerId) {
+        // We don't own
         return yield [operation === 'status' ? 'message' : 'failure', 'Running but not managed'];
       }
 
@@ -149,7 +150,7 @@ export class ServiceRunner {
       }
 
       if (operation === 'restart' || operation === 'start') {
-        if (!await this.#hasImage()) {
+        if (!(await this.#hasImage())) {
           yield ['message', 'Starting image download'];
           for await (const line of this.#pullImage()) {
             yield ['message', `Downloading: ${line}`];
@@ -162,7 +163,7 @@ export class ServiceRunner {
 
         if (port) {
           yield ['message', `Waiting for ${this.#descriptor.ready?.url ?? 'container'}...`];
-          if (!await this.#isRunning(true)) {
+          if (!(await this.#isRunning(true))) {
             yield ['failure', 'Failed to start service correctly'];
           }
         }
@@ -172,4 +173,4 @@ export class ServiceRunner {
       yield ['failure', 'Failed to start'];
     }
   }
-}
+}

package/src/types.ts

@@ -1,9 +1,11 @@
-import type { Class } from '@travetto/runtime';
+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 };
-type ParsedUnknown = { type: 'unknown', input: string };
+type ParsedFlag = { type: 'flag'; input: string; array?: boolean; fieldName: string; value?: unknown };
+type ParsedArg = { type: 'arg'; input: string; array?: boolean; index: number };
+type ParsedUnknown = { type: 'unknown'; input: string };
 type ParsedInput = ParsedUnknown | ParsedFlag | ParsedArg;
 
 export type ParsedState = {
@@ -32,7 +34,7 @@ export interface CliCommandShape {
   help?(): OrProm<string[]>;
 }
 
-type PreMainHandler = (cmd: CliCommandShape) => (unknown | Promise<unknown>);
+export type PreMainHandler<T extends Any = Any> = { priority: number; handler: (cmd: T) => Any };
 
 /**
  * CLI Command schema shape
@@ -41,5 +43,5 @@ export interface CliCommandConfig {
   cls: Class<CliCommandShape>;
   name: string;
   runTarget?: boolean;
-  preMain?: PreMainHandler[];
-}
+  preMain: PreMainHandler[];
+}

package/src/util.ts

@@ -1,21 +1,21 @@
-import { spawn, type ChildProcess } from 'node:child_process';
+import { type ChildProcess, spawn } from 'node:child_process';
 
-import { RuntimeError, JSONUtil, Env, ExecUtil, Runtime, ShutdownManager, Util, WatchUtil } from '@travetto/runtime';
+import { Env, ExecUtil, JSONUtil, Runtime, RuntimeError, ShutdownManager, Util, WatchUtil } from '@travetto/runtime';
 
-const IPC_ALLOWED_ENV = new Set(['NODE_OPTIONS']);
-const IPC_INVALID_ENV = new Set(['PS1', 'INIT_CWD', 'COLOR', 'LANGUAGE', 'PROFILEHOME', '_']);
-const validEnv = (key: string): boolean => IPC_ALLOWED_ENV.has(key) || (
-  !IPC_INVALID_ENV.has(key) && !/^(npm_|GTK|GDK|TRV|NODE|GIT|TERM_)/.test(key) && !/VSCODE/.test(key)
+const IPC_VALID_ENV = new Set(['NODE_OPTIONS', 'PATH', Env.DEBUG.key, Env.NODE_ENV.key]);
+const IPC_INVALID_ENV = new Set(
+  [Env.TRV_CLI_IPC, Env.TRV_DEBUG_IPC, Env.TRV_DEBUG_BREAK, Env.TRV_MANIFEST, Env.TRV_MODULE, Env.TRV_RESTART_TARGET].map(item => item.key)
 );
+const validEnv = ([key]: [key: string, value: unknown]): boolean =>
+  IPC_VALID_ENV.has(key) || (key.startsWith('TRV_') && !IPC_INVALID_ENV.has(key));
 
 export class CliUtil {
   /**
    * Get a simplified version of a module name
    */
   static getSimpleModuleName(placeholder: string, module?: string): string {
-    const simple = (module ?? Runtime.main.name).replace(/[\/]/, '_').replace(/@/, '');
-    const targetModule = !simple || (!module && Runtime.monoRoot) ? '<module>' : simple;
-    return placeholder.replace('<module>', targetModule);
+    const simple = (module ?? Runtime.main.name).replace(/[/]/, '_').replace(/@/, '');
+    return simple ? placeholder.replace('<module>', simple) : placeholder;
   }
 
   /**
@@ -33,10 +33,9 @@ export class CliUtil {
     ShutdownManager.disableInterrupt();
 
     let child: ChildProcess | undefined;
-    void WatchUtil.watchCompilerEvents('file', () => ShutdownManager.shutdownChild(child!, { reason: 'restart', mode: 'exit' }));
-    process
-      .on('SIGINT', () => ShutdownManager.shutdownChild(child!, { mode: 'exit' }))
-      .on('message', msg => child?.send?.(msg!));
+    await WatchUtil.watchCompilerEvents('file', () => ShutdownManager.shutdownChild(child!, { reason: 'restart', mode: 'exit' }));
+
+    process.on('SIGINT', () => ShutdownManager.shutdownChild(child!, { mode: 'exit' })).on('message', message => child?.send?.(message!));
 
     const env = { ...process.env, ...Env.TRV_RESTART_TARGET.export(true) };
 
@@ -50,12 +49,13 @@ export class CliUtil {
         maxRetries: 5,
         onRetry: async (state, config) => {
           const duration = WatchUtil.computeRestartDelay(state, config);
-          console.error(
-            '[cli-restart] Restarting subprocess due to change...',
-            { waiting: duration, iteration: state.iteration, errorIterations: state.errorIterations || undefined }
-          );
+          console.error('[cli-restart] Restarting subprocess due to change...', {
+            waiting: duration,
+            iteration: state.iteration,
+            errorIterations: state.errorIterations || undefined
+          });
           await Util.nonBlockingTimeout(duration);
-        },
+        }
       }
     );
 
@@ -77,32 +77,31 @@ export class CliUtil {
       return; // Server not running, run normal
     }
 
-    const env: Record<string, string> = {};
     const request = {
       type: '@travetto/cli:run',
       data: {
         name,
-        env,
+        env: Object.fromEntries(Object.entries(process.env).filter(validEnv)),
         cwd: process.cwd(),
-        args: process.argv.slice(3),
+        args: process.argv.slice(3)
       }
     };
-    console.log('Triggering IPC request', request);
 
-    Object.entries(process.env).forEach(([key, value]) => validEnv(key) && (env[key] = value!));
+    console.log('Triggering IPC request', request);
     const sent = await doFetch({ method: 'POST', body: JSONUtil.toUTF8(request) });
 
     if (!sent.ok) {
       throw new RuntimeError(`IPC Request failed: ${sent.status} ${await sent.text()}`);
     }
+
+    await ShutdownManager.shutdown({ mode: 'exit' });
   }
 
   /**
    * 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(resolve => process[channel].write(typeof data === 'string' ? data :
-      JSONUtil.toUTF8Pretty(data), () => resolve()));
+    await new Promise<unknown>(resolve => process[channel].write(typeof data === 'string' ? data : JSONUtil.toUTF8Pretty(data), resolve));
   }
 
   /**
@@ -111,4 +110,4 @@ export class CliUtil {
   static readExtendedOptions(options?: string[]): Record<string, string | boolean> {
     return Object.fromEntries((options ?? [])?.map(option => [...option.split(':'), true]));
   }
-}
+}

package/support/cli.cli_schema.ts

@@ -2,10 +2,10 @@ import { Env } from '@travetto/runtime';
 import { IsPrivate, MethodValidator, type ValidationError } from '@travetto/schema';
 
 import { CliCommand } from '../src/registry/decorator.ts';
-import type { CliCommandShape } from '../src/types.ts';
 import { CliCommandRegistryIndex } from '../src/registry/registry-index.ts';
-import { CliUtil } from '../src/util.ts';
 import { CliSchemaExportUtil } from '../src/schema-export.ts';
+import type { CliCommandShape } from '../src/types.ts';
+import { CliUtil } from '../src/util.ts';
 
 async function nameValidator(names?: string[]): Promise<ValidationError | undefined> {
   if (!names || names.length === 0) {
@@ -25,12 +25,14 @@ 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()
 export class CliSchemaCommand implements CliCommandShape {
-
   finalize(): void {
     Env.DEBUG.set(false);
   }
@@ -39,9 +41,8 @@ export class CliSchemaCommand implements CliCommandShape {
   async main(names?: string[]): Promise<void> {
     const resolved = await CliCommandRegistryIndex.load(names);
 
-    const output = resolved
-      .map(result => CliSchemaExportUtil.exportSchema(result.config.cls));
+    const output = resolved.map(result => CliSchemaExportUtil.exportSchema(result.config.cls));
 
     await CliUtil.writeAndEnsureComplete(output);
   }
-}
+}

package/support/cli.main.ts

@@ -1,5 +1,5 @@
+import { CliCommand, type CliCommandShape, CliParseUtil } from '@travetto/cli';
 import { JSONUtil, Runtime } from '@travetto/runtime';
-import { type CliCommandShape, CliCommand, CliParseUtil } from '@travetto/cli';
 import { IsPrivate, MethodValidator, type ValidationError } from '@travetto/schema';
 
 async function validateMain(fileOrImport: string): Promise<ValidationError | undefined> {
@@ -8,31 +8,35 @@ async function validateMain(fileOrImport: string): Promise<ValidationError | und
   } catch {
     return { message: `Unknown file: ${fileOrImport}`, source: 'arg', kind: 'invalid', path: 'fileOrImport' };
   }
-};
+}
 
 /**
- * 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()
 export class MainCommand implements CliCommandShape {
-
   @MethodValidator(validateMain)
   async main(fileOrImport: string, args: string[] = []): Promise<void> {
     const parsed = CliParseUtil.getState(this);
     let result: unknown;
     try {
       const module = await Runtime.importFrom<{ main(..._: unknown[]): Promise<unknown> }>(fileOrImport);
-      result = await module.main(...args, ...parsed?.unknown ?? []);
+      result = await module.main(...args, ...(parsed?.unknown ?? []));
     } catch (error) {
       result = error;
       process.exitCode = Math.max(process.exitCode ? +process.exitCode : 1, 1);
     }
 
     if (result !== undefined) {
-      if (process.connected) { process.send?.(result); }
-      const payload = typeof result === 'string' ? result : (result instanceof Error ? result.stack : JSONUtil.toUTF8(result));
+      if (process.connected) {
+        process.send?.(result);
+      }
+      const payload = typeof result === 'string' ? result : result instanceof Error ? result.stack : JSONUtil.toUTF8(result);
       process[process.exitCode ? 'stderr' : 'stdout'].write(`${payload}\n`);
     }
   }
-}
+}

package/support/cli.service.ts

@@ -1,11 +1,11 @@
 import { stripVTControlCharacters } from 'node:util';
 
-import { type CliCommandShape, CliCommand, cliTpl } from '@travetto/cli';
-import { Terminal } from '@travetto/terminal';
+import { CliCommand, type CliCommandShape, cliTpl } from '@travetto/cli';
 import { AsyncQueue, Util } from '@travetto/runtime';
 import { MethodValidator, type ValidationError } from '@travetto/schema';
+import { Terminal } from '@travetto/terminal';
 
-import { ServiceRunner, type ServiceAction } from '../src/service.ts';
+import { type ServiceAction, ServiceRunner } from '../src/service.ts';
 
 async function validateService(_: ServiceAction, services: string[]): Promise<ValidationError | undefined> {
   const all = await ServiceRunner.findServices(services);
@@ -16,11 +16,13 @@ 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 {
-
   quiet = false;
 
   async help(): Promise<string[]> {
@@ -38,44 +40,48 @@ export class CliServiceCommand implements CliCommandShape {
     const maxName = Math.max(...all.map(service => service.name.length), 'Service'.length) + 3;
     const maxVersion = Math.max(...all.map(service => `${service.version}`.length), 'Version'.length) + 3;
     const maxStatus = 20;
-    const queue = new AsyncQueue<{ idx: number, text: string, done?: boolean }>();
+    const queue = new AsyncQueue<{ idx: number; text: string; done?: boolean }>();
 
     const failureMessages: string[] = [];
 
     const jobs = all.map(async (descriptor, i) => {
       const identifier = descriptor.name.padEnd(maxName);
       const type = `${descriptor.version}`.padStart(maxVersion - 3).padEnd(maxVersion);
-      let msg: string;
+      let message: string;
       for await (const [valueType, value] of new ServiceRunner(descriptor).action(action)) {
         const details = { [valueType === 'message' ? 'subtitle' : valueType]: value };
-        queue.add({ idx: i, text: msg = cliTpl`${{ identifier }} ${{ type }} ${details}` });
+        queue.add({ idx: i, text: (message = cliTpl`${{ identifier }} ${{ type }} ${details}`) });
         if (valueType === 'failure') {
-          failureMessages.push(msg);
+          failureMessages.push(message);
         }
       }
-      queue.add({ idx: i, done: true, text: msg! });
+      queue.add({ idx: i, done: true, text: message! });
     });
 
-    Promise.all(jobs).then(() => Util.queueMacroTask()).then(() => queue.close());
-
+    Promise.all(jobs)
+      .then(() => Util.queueMacroTask())
+      .then(() => queue.close());
 
     if (this.quiet) {
-      for await (const _ of queue) { }
+      for await (const _ of queue) {
+      }
       if (failureMessages.length) {
         console.error('Failure');
         failureMessages.map(stripVTControlCharacters).map(item => console.error(item));
       }
     } else {
       const term = new Terminal();
-      await term.writer.writeLines([
-        '',
-        cliTpl`${{ title: 'Service'.padEnd(maxName) }} ${{ title: 'Version'.padEnd(maxVersion) }} ${{ title: 'Status' }}`,
-        ''.padEnd(maxName + maxVersion + maxStatus + 3, '-'),
-      ]).commit();
+      await term.writer
+        .writeLines([
+          '',
+          cliTpl`${{ title: 'Service'.padEnd(maxName) }} ${{ title: 'Version'.padEnd(maxVersion) }} ${{ title: 'Status' }}`,
+          ''.padEnd(maxName + maxVersion + maxStatus + 3, '-')
+        ])
+        .commit();
 
       await term.streamList(queue);
     }
 
     process.exitCode = failureMessages.length ? 1 : 0;
   }
-}
+}

package/support/entry.trv.ts

@@ -1,4 +1,5 @@
 // @trv-no-transform
-import '@travetto/runtime/support/polyfill.js';
+import '@travetto/runtime/support/patch.js';
 import { ExecutionManager } from '@travetto/cli';
-ExecutionManager.run(process.argv);
+
+ExecutionManager.run(process.argv);