runspec-node 0.17.0 → 0.19.0

package/src/errors.ts

@@ -41,6 +41,54 @@ export function formatOutOfRange(value: number, range: [number, number], name: s
   ].join('\n');
 }
 
+export function formatInvalidPattern(value: string, pattern: string, name: string): string {
+  return [
+    `✗  Invalid value for --${name}: ${JSON.stringify(value)}`,
+    `   Expected: a value matching pattern ${JSON.stringify(pattern)}`,
+    `   Got: ${JSON.stringify(value)}`,
+  ].join('\n');
+}
+
+export function formatTooShort(value: string, minLength: number, name: string): string {
+  return [
+    `✗  Value too short for --${name}: ${JSON.stringify(value)}`,
+    `   Expected: at least ${minLength} character${minLength === 1 ? '' : 's'}`,
+    `   Got: ${value.length}`,
+  ].join('\n');
+}
+
+export function formatTooLong(value: string, maxLength: number, name: string): string {
+  return [
+    `✗  Value too long for --${name}: ${JSON.stringify(value)}`,
+    `   Expected: at most ${maxLength} character${maxLength === 1 ? '' : 's'}`,
+    `   Got: ${value.length}`,
+  ].join('\n');
+}
+
+export function formatInvalidItems(
+  name: string,
+  total: number,
+  failures: Array<[number, unknown, string]>,
+): string {
+  const header = `--${name}: ${failures.length} of ${total} item(s) failed validation:`;
+  const blocks = failures.map(([index, value, reason]) => {
+    const detail = reason
+      .split('\n')
+      .map((line) => '     ' + line)
+      .join('\n');
+    return `   • item ${index} (${JSON.stringify(value)}):\n${detail}`;
+  });
+  return header + '\n\n' + blocks.join('\n\n');
+}
+
+export function formatMissingCommand(runnablePath: string, availableCommands: string[]): string {
+  return [
+    `✗  '${runnablePath}' requires a command.`,
+    `   Available commands: ${availableCommands.join(', ')}`,
+    `\n   Run '${runnablePath} <command> --help' for details.`,
+  ].join('\n');
+}
+
 export function formatUnknownArg(name: string, knownArgs: string[]): string {
   const lines = [
     `✗  Unknown argument: --${name}`,

package/src/loader.ts

@@ -58,6 +58,7 @@ function normaliseScript(name: string, raw: Record<string, unknown>): ScriptSpec
     autonomy: raw['autonomy'] as string | undefined,
     autonomyReason: raw['autonomy-reason'] as string | undefined,
     output: raw['output'] as string | undefined,
+    requireCommand: (raw['require-command'] as boolean | undefined) ?? false,
     args: normaliseArgs((raw['args'] ?? {}) as Record<string, unknown>),
     groups: normaliseGroups((raw['groups'] ?? {}) as Record<string, unknown>),
     commands: normaliseCommands((raw['commands'] ?? {}) as Record<string, Record<string, unknown>>),
@@ -84,6 +85,9 @@ function normaliseArg(name: string, raw: Record<string, unknown>): ArgSpec {
     description: raw['description'] as string | undefined,
     options: raw['options'] as string[] | undefined,
     range: raw['range'] as [number, number] | undefined,
+    pattern: raw['pattern'] as string | undefined,
+    minLength: raw['min-length'] as number | undefined,
+    maxLength: raw['max-length'] as number | undefined,
     multiple: (raw['multiple'] as boolean | undefined) ?? false,
     delimiter: raw['delimiter'] as string | undefined,
     short: raw['short'] as string | undefined,

package/src/models.ts

@@ -19,6 +19,9 @@ export interface ArgSpec {
   description?: string;
   options?: string[];
   range?: [number, number];
+  pattern?: string; // regex the value must fully match (str only)
+  minLength?: number; // minimum string length (str only)
+  maxLength?: number; // maximum string length (str only)
   multiple?: boolean;
   delimiter?: string;
   short?: string;
@@ -48,6 +51,7 @@ export interface ScriptSpec {
   autonomyReason?: string;
   output?: string;
   serve?: boolean | string[];
+  requireCommand?: boolean;
   args: Record<string, ArgSpec>;
   groups: Record<string, GroupSpec>;
   commands: Record<string, ScriptSpec>;

package/src/parser.ts

@@ -4,7 +4,7 @@ import { loadRaw } from './loader';
 import { inferScript, effectiveAutonomy } from './inference';
 import { coerce } from './types';
 import { validateArgs, validateGroups, raiseIfErrors } from './validator';
-import { RunSpecError } from './errors';
+import { RunSpecError, formatMissingCommand } from './errors';
 import { configureLogging } from './logging_setup';
 import type { ParsedArgs, ScriptSpec, ArgSpec } from './models';
 
@@ -13,10 +13,12 @@ export interface ParseOptions {
   argv?: string[];
   cwd?: string;
   configPath?: string;
+  /** Internal: enforce `require-command` (real CLI parsing). loadSpec sets false. */
+  _enforceRequiredCommand?: boolean;
 }
 
 export function parse(opts: ParseOptions = {}): ParsedArgs {
-  const { scriptName, argv: argvOverride, cwd, configPath: configPathOverride } = opts;
+  const { scriptName, argv: argvOverride, cwd, configPath: configPathOverride, _enforceRequiredCommand = true } = opts;
 
   const { configPath } = configPathOverride ? { configPath: configPathOverride } : findConfig(cwd);
   const raw = loadRaw(configPath);
@@ -76,18 +78,35 @@ export function parse(opts: ParseOptions = {}): ParsedArgs {
   let activeScript = rawScript;
   let commandPath: string[] = [];
 
-  const commands = rawScript.commands ?? {};
-  if (Object.keys(commands).length > 0 && argv.length > 0 && argv[0] in commands) {
-    commandPath = [argv[0]];
-    activeScript = commands[argv[0]];
+  // Walk into nested subcommands as long as argv[0] matches a declared command.
+  while (argv.length > 0) {
+    const cmds = activeScript.commands ?? {};
+    if (Object.keys(cmds).length === 0 || !(argv[0] in cmds)) break;
+    commandPath.push(argv[0]);
+    activeScript = cmds[argv[0]];
     argv = argv.slice(1);
   }
 
   if (argv.includes('--help') || argv.includes('-h')) {
-    printHelp(name, activeScript, commandPath.length > 0 ? commandPath[commandPath.length - 1] : undefined);
+    printHelp(name, activeScript, commandPath);
     process.exit(0);
   }
 
+  // Enforce require-command on the resolved leaf: if the deepest matched node
+  // still requires a command and has commands, none was chosen at that level.
+  // Checking the leaf (not commandPath.length) enforces at every nesting depth.
+  // Skipped by loadSpec — introspection/emit must not be blocked. Runs after
+  // --help so `<name> --help` still lists the commands.
+  if (
+    _enforceRequiredCommand &&
+    activeScript.requireCommand &&
+    Object.keys(activeScript.commands ?? {}).length > 0
+  ) {
+    throw new RunSpecError(
+      formatMissingCommand([name, ...commandPath].join(' '), Object.keys(activeScript.commands)),
+    );
+  }
+
   let parsedValues = parseArgv(argv, activeScript.args ?? {});
   parsedValues = applyEnv(parsedValues, activeScript.args ?? {}, name);
   parsedValues = applyDefaults(parsedValues, activeScript.args ?? {});
@@ -142,7 +161,7 @@ export function parse(opts: ParseOptions = {}): ParsedArgs {
 }
 
 export function loadSpec(opts: ParseOptions = {}): ParsedArgs {
-  return parse({ ...opts, argv: [] });
+  return parse({ ...opts, argv: [], _enforceRequiredCommand: false });
 }
 
 function inferFromArgv(): string {
@@ -295,28 +314,56 @@ function coerceValues(parsed: Record<string, unknown>, argSpecs: Record<string,
   return result;
 }
 
-export function printHelp(name: string, script: ScriptSpec, command?: string): void {
-  const fullName = command ? `${name} ${command}` : name;
+export function printHelp(name: string, script: ScriptSpec, commandPath: string[] = []): void {
+  const fullName = [name, ...commandPath].join(' ');
   const args = script.args ?? {};
+  const commands = script.commands ?? {};
 
-  const usageParts = [fullName];
-  for (const [argName, spec] of Object.entries(args)) {
+  // Partition args into flags, positionals, and rest (mirrors Python's _print_help).
+  const entries = Object.entries(args);
+  const positionalArgs = entries
+    .filter(([, s]) => s.position !== undefined)
+    .sort(([, a], [, b]) => (a.position ?? 0) - (b.position ?? 0));
+  const restArgs = entries.filter(([, s]) => s.type === 'rest');
+  const flagArgs = entries.filter(([, s]) => s.position === undefined && s.type !== 'rest');
+
+  // Choices render their options inline; other types render as <type>.
+  const argToken = (spec: typeof args[string]): string =>
+    spec.options ? `<${spec.options.join('|')}>` : `<${spec.type ?? 'str'}>`;
+
+  // Usage line — order: name [flags] [positionals] [<command>] [-- <rest>...]
+  // Rest stays last because '--' terminates argument parsing.
+  const usageParts: string[] = [fullName];
+  for (const [argName, spec] of flagArgs) {
     const flag = `--${argName}`;
-    if (spec.type === 'flag') {
-      usageParts.push(`[${flag}]`);
-    } else if (spec.required) {
-      usageParts.push(`${flag} <${spec.type ?? 'str'}>`);
-    } else {
-      usageParts.push(`[${flag} <${spec.type ?? 'str'}>]`);
-    }
+    if (spec.type === 'flag') usageParts.push(`[${flag}]`);
+    else if (spec.required) usageParts.push(`${flag} ${argToken(spec)}`);
+    else usageParts.push(`[${flag} ${argToken(spec)}]`);
+  }
+  for (const [argName, spec] of positionalArgs) {
+    usageParts.push(spec.required ? `<${argName}>` : `[<${argName}>]`);
+  }
+  if (Object.keys(commands).length > 0) usageParts.push('<command>');
+  for (const [argName] of restArgs) {
+    usageParts.push(`[-- <${argName}>...]`);
   }
 
   console.log(`Usage: ${usageParts.join(' ')}`);
   if (script.description) console.log(`\n${script.description}`);
 
+  // Commands section
+  if (Object.keys(commands).length > 0) {
+    console.log(script.requireCommand ? '\nCommands (required):' : '\nCommands:');
+    const cmdCol = Math.max(...Object.keys(commands).map((c) => c.length)) + 2;
+    for (const [cmdName, cmdSpec] of Object.entries(commands)) {
+      const desc = cmdSpec.description ?? '';
+      console.log(`  ${cmdName.padEnd(cmdCol)} ${desc}`);
+    }
+  }
+
   if (Object.keys(args).length > 0) {
     console.log('\nArguments:');
-    for (const [argName, spec] of Object.entries(args)) {
+    for (const [argName, spec] of entries) {
       const flag = `  --${argName}`;
       const parts: string[] = [];
       if (spec.type === 'flag') parts.push('flag');
@@ -335,5 +382,8 @@ export function printHelp(name: string, script: ScriptSpec, command?: string): v
     if (script.autonomyReason) console.log(`  ${script.autonomyReason}`);
   }
 
+  if (Object.keys(commands).length > 0) {
+    console.log(`\nRun '${fullName} <command> --help' for focused help on a command.`);
+  }
   console.log('\n  -h, --help    Show this message and exit');
 }

package/src/types.ts

@@ -1,6 +1,12 @@
 import * as path from 'path';
 import type { ArgSpec } from './models';
-import { formatInvalidChoice } from './errors';
+import {
+  formatInvalidChoice,
+  formatInvalidPattern,
+  formatTooShort,
+  formatTooLong,
+  formatInvalidItems,
+} from './errors';
 
 export type TypeCoercer = (value: unknown, spec: ArgSpec) => unknown;
 
@@ -18,6 +24,25 @@ export function coerce(value: unknown, spec: ArgSpec): unknown {
       `Unknown type '${typeName}' for argument '${spec.name}'. Registered types: ${[...registry.keys()].sort().join(', ')}\nRegister custom types with registerType().`,
     );
   }
+  // Multiple-valued args coerce and validate each item independently and return
+  // a list. The arg's type (and its pattern / length / range / choice checks)
+  // applies per item. `rest` manages its own list, so it is excluded.
+  if (spec.multiple && typeName !== 'rest') {
+    const items = Array.isArray(value) ? value : [value];
+    const out: unknown[] = [];
+    const failures: Array<[number, unknown, string]> = [];
+    items.forEach((item, i) => {
+      try {
+        out.push(coercer(item, spec));
+      } catch (e) {
+        failures.push([i + 1, item, (e as Error).message]);
+      }
+    });
+    if (failures.length > 0) {
+      throw new Error(formatInvalidItems(spec.name ?? '?', items.length, failures));
+    }
+    return out;
+  }
   try {
     return coercer(value, spec);
   } catch (e) {
@@ -31,8 +56,11 @@ export function listTypes(): string[] {
   return [...registry.keys()].sort();
 }
 
-function coerceStr(value: unknown): string {
-  return String(value);
+function coerceStr(value: unknown, spec: ArgSpec): string {
+  const coerced = String(value);
+  checkLength(coerced, spec);
+  checkPattern(coerced, spec);
+  return coerced;
 }
 
 function coerceInt(value: unknown, spec: ArgSpec): number {
@@ -87,6 +115,26 @@ function checkRange(value: number, spec: ArgSpec): void {
   }
 }
 
+// String-only validation (str coercer). Mirrors Python's _check_length/_check_pattern.
+function checkLength(value: string, spec: ArgSpec): void {
+  if (spec.minLength !== undefined && value.length < spec.minLength) {
+    throw new Error(formatTooShort(value, spec.minLength, spec.name ?? '?'));
+  }
+  if (spec.maxLength !== undefined && value.length > spec.maxLength) {
+    throw new Error(formatTooLong(value, spec.maxLength, spec.name ?? '?'));
+  }
+}
+
+function checkPattern(value: string, spec: ArgSpec): void {
+  if (spec.pattern === undefined) return;
+  // (?:…) anchoring reproduces Python's re.fullmatch even when the pattern
+  // contains a top-level alternation (plain ^p$ would mis-bind `a|b`).
+  const regex = new RegExp(`^(?:${spec.pattern})$`);
+  if (!regex.test(value)) {
+    throw new Error(formatInvalidPattern(value, spec.pattern, spec.name ?? '?'));
+  }
+}
+
 registerType('str', coerceStr);
 registerType('int', coerceInt);
 registerType('float', coerceFloat);

package/tests/test_emit_schema.test.ts

@@ -0,0 +1,32 @@
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { loadRaw } from '../src/loader';
+import { inferScript } from '../src/inference';
+import { buildSchema } from '../src/cli';
+
+function schemaFor(toml: string, name: string): Record<string, unknown> {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'runspec-emit-test-'));
+  const file = path.join(dir, 'runspec.toml');
+  fs.writeFileSync(file, toml);
+  const raw = loadRaw(file);
+  const script = inferScript(raw.runnables[name], raw.config.autonomyDefault);
+  return buildSchema(name, script, 'mcp');
+}
+
+test('string validation fields emit to JSON Schema', () => {
+  const schema = schemaFor(
+    `
+[greet]
+[greet.args]
+slug = {type = "str", pattern = "[a-z]+-[0-9]+", min-length = 3, max-length = 10}
+`,
+    'greet',
+  );
+  const props = (schema['inputSchema'] as Record<string, Record<string, unknown>>)['properties'];
+  const slug = (props as Record<string, Record<string, unknown>>)['slug'];
+  expect(slug['type']).toBe('string');
+  expect(slug['pattern']).toBe('[a-z]+-[0-9]+');
+  expect(slug['minLength']).toBe(3);
+  expect(slug['maxLength']).toBe(10);
+});

package/tests/test_integration.test.ts

@@ -171,6 +171,26 @@ describe('complex.toml', () => {
     const run = inferred.commands['run'];
     expect(run.autonomyReason).toBe('Writes output files and may call external APIs');
   });
+
+  test('run subcommand: label has pattern / min-length / max-length', () => {
+    const raw = loadRaw(COMPLEX);
+    const inferred = inferScript(raw.runnables['pipeline'], raw.config.autonomyDefault);
+    const label = inferred.commands['run'].args['label'];
+    expect(label.type).toBe('str');
+    expect(label.pattern).toBe('[a-z][a-z0-9-]+');
+    expect(label.minLength).toBe(3);
+    expect(label.maxLength).toBe(32);
+  });
+
+  test('db runnable: require-command with subcommands', () => {
+    const raw = loadRaw(COMPLEX);
+    const db = raw.runnables['db'];
+    expect(db.requireCommand).toBe(true);
+    expect(db.commands['migrate']).toBeDefined();
+    expect(db.commands['seed']).toBeDefined();
+    // Defaults to false where unset.
+    expect(raw.runnables['pipeline'].requireCommand).toBe(false);
+  });
 });
 
 // ── cross-fixture: inference rules ────────────────────────────────────────────

package/tests/test_loader.test.ts

@@ -106,6 +106,39 @@ workers = {default = 4, range = [1, 32]}
   expect(raw.runnables['greet'].args['workers'].range).toEqual([1, 32]);
 });
 
+test('normalises pattern / min-length / max-length fields', () => {
+  const dir = tmpDir();
+  const file = path.join(dir, 'runspec.toml');
+  fs.writeFileSync(file, `
+[greet]
+description = "hi"
+
+[greet.args]
+slug = {type = "str", pattern = "[a-z]+-[0-9]+", min-length = 3, max-length = 10}
+`);
+  const raw = loadRaw(file);
+  const slug = raw.runnables['greet'].args['slug'];
+  expect(slug.pattern).toBe('[a-z]+-[0-9]+');
+  expect(slug.minLength).toBe(3);
+  expect(slug.maxLength).toBe(10);
+});
+
+test('normalises require-command on a runnable', () => {
+  const dir = tmpDir();
+  const file = path.join(dir, 'runspec.toml');
+  fs.writeFileSync(file, `
+[db]
+require-command = true
+
+[db.commands.migrate]
+description = "run migrations"
+`);
+  const raw = loadRaw(file);
+  expect(raw.runnables['db'].requireCommand).toBe(true);
+  // Defaults to false when absent.
+  expect(raw.runnables['db'].commands['migrate'].requireCommand).toBe(false);
+});
+
 test('normalises group fields', () => {
   const dir = tmpDir();
   const file = path.join(dir, 'runspec.toml');

package/tests/test_parser.test.ts

@@ -1,7 +1,7 @@
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
-import { parse } from '../src/parser';
+import { parse, loadSpec } from '../src/parser';
 
 function makeTmpConfig(toml: string): string {
   const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'runspec-parser-test-'));
@@ -65,3 +65,177 @@ describe('env resolution', () => {
     expect(args['quality']).toBe(85);
   });
 });
+
+// ── help display ──────────────────────────────────────────────────────────────
+
+describe('help display', () => {
+  let logSpy: jest.SpyInstance;
+  let exitSpy: jest.SpyInstance;
+  let output: string[];
+
+  beforeEach(() => {
+    output = [];
+    logSpy = jest.spyOn(console, 'log').mockImplementation((...args) => {
+      output.push(args.join(' '));
+    });
+    exitSpy = jest.spyOn(process, 'exit').mockImplementation((() => {
+      throw new Error('__exit__');
+    }) as never);
+  });
+
+  afterEach(() => {
+    logSpy.mockRestore();
+    exitSpy.mockRestore();
+  });
+
+  const runHelp = (toml: string, name: string, argv: string[]): string => {
+    const configPath = makeTmpConfig(toml);
+    try {
+      parse({ scriptName: name, argv, configPath });
+    } catch (e) {
+      if ((e as Error).message !== '__exit__') throw e;
+    }
+    return output.join('\n');
+  };
+
+  test('usage line renders <command> after parent args', () => {
+    const toml = `
+[pipeline]
+description = "Run a pipeline"
+[pipeline.args]
+verbose = {type = "flag"}
+config  = {type = "path"}
+[pipeline.commands.run]
+description = "Run it"
+`;
+    const out = runHelp(toml, 'pipeline', ['--help']);
+    const usage = out.split('\n').find((l) => l.startsWith('Usage:'))!;
+    expect(usage.indexOf('--verbose')).toBeLessThan(usage.indexOf('<command>'));
+    expect(usage.indexOf('--config')).toBeLessThan(usage.indexOf('<command>'));
+    expect(usage.trimEnd().endsWith('<command>')).toBe(true);
+    expect(out).toContain('Commands:');
+    expect(out).toContain('run');
+  });
+
+  test('nested subcommands resolve to full path in usage', () => {
+    const toml = `
+[outer]
+[outer.commands.inner]
+[outer.commands.inner.commands.deep]
+description = "Deepest"
+[outer.commands.inner.commands.deep.args]
+bar = {type = "str", required = true}
+`;
+    const out = runHelp(toml, 'outer', ['inner', 'deep', '--help']);
+    expect(out).toContain('Usage: outer inner deep');
+    expect(out).toContain('--bar');
+    expect(out).toContain('Deepest');
+  });
+
+  test('choice options render inline in usage', () => {
+    const toml = `
+[greet]
+[greet.args]
+fmt = {type = "choice", options = ["text", "json", "xml"], default = "text"}
+`;
+    const out = runHelp(toml, 'greet', ['--help']);
+    expect(out).toContain('[--fmt <text|json|xml>]');
+  });
+
+  test('usage places <command> before -- <rest>', () => {
+    const toml = `
+[multi]
+[multi.args]
+host  = {type = "str", position = 1}
+extra = {type = "rest"}
+[multi.commands.run]
+description = "Run it"
+`;
+    const out = runHelp(toml, 'multi', ['--help']);
+    const usage = out.split('\n').find((l) => l.startsWith('Usage:'))!;
+    expect(usage.indexOf('<host>')).toBeLessThan(usage.indexOf('<command>'));
+    expect(usage.indexOf('<command>')).toBeLessThan(usage.indexOf('-- <extra>'));
+  });
+});
+
+// ── require-command ─────────────────────────────────────────────────────────────
+
+describe('require-command', () => {
+  const DB_TOML = `
+[db]
+require-command = true
+[db.commands.migrate]
+[db.commands.seed]
+`;
+
+  test('no command errors and lists commands', () => {
+    const configPath = makeTmpConfig(DB_TOML);
+    let msg = '';
+    try {
+      parse({ scriptName: 'db', argv: [], configPath });
+      throw new Error('expected parse to throw');
+    } catch (e) {
+      msg = (e as Error).message;
+    }
+    expect(msg).toContain('requires a command');
+    expect(msg).toContain('migrate');
+    expect(msg).toContain('seed');
+  });
+
+  test('valid command passes', () => {
+    const configPath = makeTmpConfig(DB_TOML);
+    const args = parse({ scriptName: 'db', argv: ['migrate'], configPath });
+    expect(args.runspec_command_path).toEqual(['migrate']);
+    expect(args.runspec_command).toBe('migrate');
+  });
+
+  test('nested requirement enforced at each depth', () => {
+    const toml = `
+[app]
+require-command = true
+[app.commands.db]
+require-command = true
+[app.commands.db.commands.migrate]
+`;
+    const configPath = makeTmpConfig(toml);
+    // Choosing the intermediate command isn't enough — db itself requires one.
+    expect(() => parse({ scriptName: 'app', argv: ['db'], configPath })).toThrow(/requires a command/);
+    // Going all the way down satisfies it.
+    const args = parse({ scriptName: 'app', argv: ['db', 'migrate'], configPath });
+    expect(args.runspec_command_path).toEqual(['db', 'migrate']);
+  });
+
+  test('backward compatible: commands without require-command run at root', () => {
+    const toml = `
+[tool]
+[tool.commands.run]
+`;
+    const configPath = makeTmpConfig(toml);
+    const args = parse({ scriptName: 'tool', argv: [], configPath });
+    expect(args.runspec_command_path).toEqual([]);
+  });
+
+  test('loadSpec bypasses enforcement', () => {
+    const configPath = makeTmpConfig(DB_TOML);
+    const spec = loadSpec({ scriptName: 'db', configPath });
+    expect(spec.runspec_command_path).toEqual([]);
+  });
+
+  test('--help still works at a required level', () => {
+    const configPath = makeTmpConfig(DB_TOML);
+    const output: string[] = [];
+    const logSpy = jest.spyOn(console, 'log').mockImplementation((...a) => { output.push(a.join(' ')); });
+    const exitSpy = jest.spyOn(process, 'exit').mockImplementation((() => { throw new Error('__exit__'); }) as never);
+    try {
+      parse({ scriptName: 'db', argv: ['--help'], configPath });
+    } catch (e) {
+      if ((e as Error).message !== '__exit__') throw e;
+    } finally {
+      logSpy.mockRestore();
+      exitSpy.mockRestore();
+    }
+    const out = output.join('\n');
+    expect(out).toContain('Commands (required):');
+    expect(out).toContain('migrate');
+  });
+});