runspec-node 0.17.1 → 0.21.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/index.ts

@@ -1,5 +1,6 @@
 export { parse, loadSpec } from './parser';
 export { registerType, listTypes } from './types';
+export { tsTypeOf } from './inference';
 export { RunSpecError, MissingRequiredArg, InvalidChoice, OutOfRange, UnknownArg, GroupViolation, AutonomyViolation } from './errors';
 export { findConfig } from './finder';
 export { loadRaw } from './loader';

package/src/inference.ts

@@ -4,6 +4,31 @@ import { RunSpecError } from './errors';
 export const AUTONOMY_LEVELS = ['autonomous', 'confirm', 'supervised', 'manual'] as const;
 export const AUTONOMY_RANK = Object.fromEntries(AUTONOMY_LEVELS.map((l, i) => [l, i]));
 
+// Item-type name → its TypeScript type. Mirrors the JSON-Schema type map used
+// by emit; custom (register_type) names fall back to `unknown`.
+const TS_TYPE_NAMES: Record<string, string> = {
+  str: 'string',
+  int: 'number',
+  float: 'number',
+  bool: 'boolean',
+  flag: 'boolean',
+  path: 'string',
+  choice: 'string',
+  rest: 'string[]',
+};
+
+/** The TypeScript type of an arg's parsed value: the item type, suffixed `[]`
+ *  when the arg is `multiple` (`rest` is always `string[]`). `arg.type` itself
+ *  stays the item type — it drives per-item coercion. Pure helper, computed on
+ *  demand from a (typically inferred) ArgSpec; custom registered types fall
+ *  back to `"unknown"`. e.g. `tsTypeOf({type:"str", multiple:true})` → `"string[]"`. */
+export function tsTypeOf(arg: ArgSpec): string {
+  const type = arg.type ?? 'str';
+  if (type === 'rest') return 'string[]';
+  const base = TS_TYPE_NAMES[type] ?? 'unknown';
+  return arg.multiple ? `${base}[]` : base;
+}
+
 export function inferArg(raw: ArgSpec): ArgSpec {
   const result = { ...raw };
   const def = result.default;

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/logging_setup.ts

@@ -16,6 +16,16 @@ const _loggers = new Map<string, Logger>();
 const _handlers: Handler[] = [];
 
 const RUN_SUMMARY_LOGGER = 'runspec.runsummary';
+// Uncaught exceptions are emitted on this dedicated logger so the file handler
+// records them while the console handlers drop them by name — console display is
+// handled explicitly in _handleUncaught (debug-gated).
+const EXCEPTION_LOGGER = 'runspec.exception';
+
+// Directory of the installed runspec-node package — used to filter internal
+// library frames out of the *displayed* compact trace (full trace still hits the file).
+const RUNSPEC_PKG_DIR = __dirname;
+
+let _debug = false; // mirrors the --debug flag; read by _handleUncaught for console rendering
 
 interface CapturedException {
   type: string;
@@ -23,6 +33,20 @@ interface CapturedException {
   traceback: string;
 }
 
+interface ExcFrame {
+  func: string;
+  file: string;
+  line: number | null;
+  code: string | null;
+}
+
+interface ExcStructured {
+  type: string;
+  message: string;
+  module: string | null;
+  frames: ExcFrame[];
+}
+
 interface SummaryState {
   counter: RunSummaryCounter;
   start: bigint;
@@ -83,6 +107,7 @@ interface LogRecord {
   message: string;
   error?: Error;
   extra?: Record<string, unknown>;
+  excStructured?: Record<string, unknown>;
 }
 
 interface Handler {
@@ -145,6 +170,7 @@ function formatJson(record: LogRecord): string {
     message: record.message,
   };
   if (record.error) obj['exc'] = record.error.stack ?? record.error.message;
+  if (record.excStructured) obj['exc_structured'] = record.excStructured;
   if (record.extra) obj['extra'] = record.extra;
   return JSON.stringify(obj);
 }
@@ -183,7 +209,7 @@ class StdoutHandler implements Handler {
 
   emit(record: LogRecord): void {
     if (record.levelNum >= 30) return; // WARNING+ belongs on stderr
-    if (record.loggerName === RUN_SUMMARY_LOGGER) return;
+    if (record.loggerName === RUN_SUMMARY_LOGGER || record.loggerName === EXCEPTION_LOGGER) return;
     try {
       process.stdout.write(formatConsole(record, this.showTracebacks) + '\n');
     } catch {
@@ -204,7 +230,7 @@ class StderrHandler implements Handler {
 
   emit(record: LogRecord): void {
     if (record.levelNum < 30) return;
-    if (record.loggerName === RUN_SUMMARY_LOGGER) return;
+    if (record.loggerName === RUN_SUMMARY_LOGGER || record.loggerName === EXCEPTION_LOGGER) return;
     try {
       process.stderr.write(formatConsole(record, this.showTracebacks) + '\n');
     } catch {
@@ -226,8 +252,8 @@ class RunSummaryCounter implements Handler {
   };
 
   emit(record: LogRecord): void {
-    // Don't count the summary record itself.
-    if (record.loggerName === RUN_SUMMARY_LOGGER) return;
+    // Don't count runspec's own bookkeeping records (summary + uncaught-exception).
+    if (record.loggerName === RUN_SUMMARY_LOGGER || record.loggerName === EXCEPTION_LOGGER) return;
     const label = LEVEL_LABEL[record.levelNum];
     if (label && label in this.counts) {
       this.counts[label]++;
@@ -462,6 +488,99 @@ export function emitRunSummary(): void {
   }
 }
 
+// ── uncaught exceptions ────────────────────────────────────────────────────────
+
+const STACK_FRAME_RE = /^\s*at (?:(.+?) \()?(.+?):(\d+):(\d+)\)?$/;
+
+/**
+ * Parse a V8 stack string into frames, innermost LAST (mirroring Python's
+ * traceback.extract_tb order). `code` is unavailable from a stack string.
+ */
+function parseStackFrames(stack: string): ExcFrame[] {
+  const frames: ExcFrame[] = [];
+  for (const lineStr of stack.split('\n')) {
+    const m = STACK_FRAME_RE.exec(lineStr);
+    if (!m) continue;
+    frames.push({ func: m[1] ?? '<anonymous>', file: m[2], line: parseInt(m[3], 10), code: null });
+  }
+  frames.reverse();
+  return frames;
+}
+
+/** Clean, machine-readable form of an error for the JSON audit / UI tables. */
+function buildExcStructured(err: Error): ExcStructured {
+  const frames = parseStackFrames(err.stack ?? '');
+  const last = frames.length ? frames[frames.length - 1] : null;
+  const module = last ? path.basename(last.file).replace(/\.[^.]+$/, '') : null;
+  return { type: err.name || 'Error', message: err.message || String(err), module, frames };
+}
+
+/**
+ * Neat, aligned, stdlib-only trace for --debug console output. Internal
+ * runspec frames are dropped from the *display* (full trace still hits the
+ * file). Falls back to the full list if filtering empties it.
+ */
+function formatCompactTrace(err: Error, frames: ExcFrame[]): string {
+  const shown = frames.filter((f) => !f.file.includes(RUNSPEC_PKG_DIR));
+  const use = shown.length ? shown : frames;
+  const locs = use.map((f) => `${path.basename(f.file)}:${f.line}`);
+  const width = Math.max(0, ...locs.map((l) => l.length));
+  const lines = [`${err.name || 'Error'}: ${err.message}`, ''];
+  use.forEach((f, i) => {
+    lines.push(`  ${locs[i].padEnd(width)}  ${f.func}`.trimEnd());
+  });
+  return lines.join('\n');
+}
+
+/** Emit the structured exception record straight to the handlers (file keeps it). */
+function emitExceptionRecord(err: Error, structured: ExcStructured): void {
+  if (_handlers.length === 0) return;
+  const record: LogRecord = {
+    ts: new Date(),
+    levelNum: 50,
+    loggerName: EXCEPTION_LOGGER,
+    message: 'uncaught exception',
+    error: err,
+    excStructured: structured as unknown as Record<string, unknown>,
+  };
+  for (const h of _handlers) {
+    try {
+      if (record.levelNum >= h.level) h.emit(record);
+    } catch {
+      // never disrupt
+    }
+  }
+}
+
+/**
+ * Uniform handling for an uncaught error: always write a structured record to
+ * the audit file, feed the run summary (when on), and show a neat compact
+ * trace on the console only with --debug (otherwise a single concise line).
+ * Exported for tests so they can exercise it without triggering process.exit.
+ */
+export function _handleUncaught(err: Error): void {
+  const structured = buildExcStructured(err);
+
+  // Always to the audit file (independent of --debug and of the summary toggle).
+  emitExceptionRecord(err, structured);
+
+  if (_summaryState) {
+    _summaryState.exception = { type: structured.type, message: structured.message, traceback: err.stack ?? '' };
+    _summaryState.exitCode = 1;
+  }
+
+  // Console: full compact trace only with --debug, else a one-liner.
+  try {
+    if (_debug) {
+      process.stderr.write(formatCompactTrace(err, structured.frames) + '\n');
+    } else {
+      process.stderr.write(`ERROR: ${structured.type}: ${structured.message}  (run with --debug for traceback)\n`);
+    }
+  } catch {
+    process.stderr.write((err.stack ?? String(err)) + '\n'); // safety fallback
+  }
+}
+
 function installExitHooks(): void {
   if (_exitHooksInstalled) return;
   _exitHooksInstalled = true;
@@ -469,43 +588,25 @@ function installExitHooks(): void {
   process.on('exit', (code) => {
     if (_summaryState && !_summaryState.emitted) {
       // process.exitCode wins over the explicit exception capture only if
-      // it's non-zero — uncaughtException already set state.exitCode=1.
+      // it's non-zero — _handleUncaught already set state.exitCode=1.
       if (code !== 0 && _summaryState.exitCode === 0) _summaryState.exitCode = code;
       emitRunSummary();
     }
   });
 
   // Skip the crash-handlers under jest — they call process.exit(1), which
-  // would tear down the test runner if any test ever produced an unhandled
-  // rejection. The 'exit' hook above is harmless and still runs.
+  // would tear down the test runner. _handleUncaught is unit-tested directly.
+  // The 'exit' hook above is harmless and still runs.
   if (process.env['JEST_WORKER_ID'] !== undefined) return;
 
   process.on('uncaughtException', (err: Error) => {
-    if (_summaryState) {
-      _summaryState.exception = {
-        type: err.name || 'Error',
-        message: err.message || String(err),
-        traceback: err.stack ?? '',
-      };
-      _summaryState.exitCode = 1;
-    }
-    // Preserve default Node behaviour: print and exit non-zero. The 'exit'
-    // hook above will fire and run emitRunSummary().
-    process.stderr.write((err.stack ?? String(err)) + '\n');
+    _handleUncaught(err);
     process.exit(1);
   });
 
   process.on('unhandledRejection', (reason: unknown) => {
-    if (_summaryState) {
-      const err = reason instanceof Error ? reason : new Error(String(reason));
-      _summaryState.exception = {
-        type: err.name || 'Error',
-        message: err.message || String(reason),
-        traceback: err.stack ?? '',
-      };
-      _summaryState.exitCode = 1;
-    }
-    process.stderr.write(`Unhandled rejection: ${reason instanceof Error ? (reason.stack ?? reason.message) : String(reason)}\n`);
+    const err = reason instanceof Error ? reason : new Error(String(reason));
+    _handleUncaught(err);
     process.exit(1);
   });
 }
@@ -554,6 +655,7 @@ export function configureLogging(opts: ConfigureLoggingOptions): void {
   if (!opts.logCfg || _configured) return;
 
   const debug = opts.debug ?? false;
+  _debug = debug;
   const floor = debug ? LEVEL_NUM['debug'] : LEVEL_NUM['info'];
 
   _handlers.push(new StdoutHandler(floor, debug));
@@ -589,9 +691,13 @@ export function configureLogging(opts: ConfigureLoggingOptions): void {
       user,
       userTarget,
     };
-    installExitHooks();
   }
 
+  // Uncaught-exception handling is always installed (independent of the summary
+  // toggle) so the structured exception record reaches the audit file even when
+  // summary is off. The exit hook only flushes a summary when _summaryState is set.
+  installExitHooks();
+
   _configured = true;
 }
 
@@ -599,6 +705,7 @@ export function configureLogging(opts: ConfigureLoggingOptions): void {
 
 export function _resetForTest(): void {
   _configured = false;
+  _debug = false;
   _loggers.clear();
   _handlers.length = 0;
   _summaryState = null;
@@ -606,4 +713,4 @@ export function _resetForTest(): void {
   // they no-op when _summaryState is null, which is the test-time state.
 }
 
-export { _periodForDate, RUN_SUMMARY_LOGGER };
+export { _periodForDate, RUN_SUMMARY_LOGGER, EXCEPTION_LOGGER, buildExcStructured, formatCompactTrace };

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);
@@ -90,6 +92,21 @@ export function parse(opts: ParseOptions = {}): ParsedArgs {
     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 ?? {});
@@ -144,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 {
@@ -336,7 +353,7 @@ export function printHelp(name: string, script: ScriptSpec, commandPath: string[
 
   // Commands section
   if (Object.keys(commands).length > 0) {
-    console.log('\nCommands:');
+    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 ?? '';

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,48 @@
+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);
+});
+
+test('multiple arg emits array with per-item constraints inside items', () => {
+  const schema = schemaFor(
+    `
+[deploy]
+[deploy.args]
+ticket = {type = "str", multiple = true, pattern = "[A-Z]+-[0-9]+"}
+`,
+    'deploy',
+  );
+  const props = (schema['inputSchema'] as Record<string, Record<string, unknown>>)['properties'];
+  const ticket = (props as Record<string, Record<string, unknown>>)['ticket'];
+  expect(ticket['type']).toBe('array');
+  // The per-item constraint validates each element, so it belongs in items.
+  expect(ticket['items']).toEqual({ type: 'string', pattern: '[A-Z]+-[0-9]+' });
+});

package/tests/test_inference.test.ts

@@ -1,4 +1,4 @@
-import { inferArg, inferScript, effectiveAutonomy, isMoreRestrictive } from '../src/inference';
+import { inferArg, inferScript, effectiveAutonomy, isMoreRestrictive, tsTypeOf } from '../src/inference';
 import { RunSpecError } from '../src/errors';
 import type { ArgSpec, ScriptSpec } from '../src/models';
 
@@ -151,3 +151,31 @@ test('manual is more restrictive than confirm', () => {
 test('autonomous is not more restrictive than confirm', () => {
   expect(isMoreRestrictive('autonomous', 'confirm')).toBe(false);
 });
+
+// ── tsTypeOf (derived value type, computed on demand) ──────────────────────────
+
+test('tsTypeOf: scalar types', () => {
+  expect(tsTypeOf(makeArg({ type: 'str' }))).toBe('string');
+  expect(tsTypeOf(makeArg({ type: 'int' }))).toBe('number');
+  expect(tsTypeOf(makeArg({ type: 'flag' }))).toBe('boolean');
+  expect(tsTypeOf(makeArg({ type: 'path' }))).toBe('string');
+});
+
+test('tsTypeOf: multiple suffixes []', () => {
+  expect(tsTypeOf(makeArg({ type: 'str', multiple: true }))).toBe('string[]');
+  expect(tsTypeOf(makeArg({ type: 'int', multiple: true }))).toBe('number[]');
+});
+
+test('tsTypeOf: rest is string[]', () => {
+  expect(tsTypeOf(makeArg({ type: 'rest' }))).toBe('string[]');
+});
+
+test('tsTypeOf: custom type falls back to unknown', () => {
+  expect(tsTypeOf(makeArg({ type: 'json-file', multiple: true }))).toBe('unknown[]');
+});
+
+test('tsTypeOf works on an inferred ArgSpec; type stays the item type', () => {
+  const arg = inferArg(makeArg({ type: 'str', multiple: true }));
+  expect(arg.type).toBe('str');
+  expect(tsTypeOf(arg)).toBe('string[]');
+});

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 ────────────────────────────────────────────