@ontrails/commander 1.0.0-beta.24 → 1.0.0-beta.29

package/CHANGELOG.md

@@ -1,5 +1,54 @@
 # @ontrails/commander
 
+## 1.0.0-beta.29
+
+### Patch Changes
+
+- @ontrails/cli@1.0.0-beta.29
+- @ontrails/core@1.0.0-beta.29
+
+## 1.0.0-beta.28
+
+### Patch Changes
+
+- @ontrails/cli@1.0.0-beta.28
+- @ontrails/core@1.0.0-beta.28
+
+## 1.0.0-beta.27
+
+### Patch Changes
+
+- @ontrails/cli@1.0.0-beta.27
+- @ontrails/core@1.0.0-beta.27
+
+## 1.0.0-beta.26
+
+### Patch Changes
+
+- Updated dependencies [1307568]
+- Updated dependencies [371d19e]
+  - @ontrails/core@1.0.0-beta.26
+  - @ontrails/cli@1.0.0-beta.26
+
+## 1.0.0-beta.25
+
+### Patch Changes
+
+- 60caabf: Render operator-actionable detail lines after CLI execution errors: validation failures list their topo issues (message plus trail id) and permission failures name the required permit scopes with a copyable `--permit` form. Non-internal Trails error context only, passed through the shared redactor; internal errors keep the redacted generic message.
+- dbf4ff4: Emit structured CLI error envelopes for JSON/JSONL command failures and map compile-time Trails DB lock contention to a retryable timeout instead of a generic internal error.
+- f1e6efa: Prevent executable parent command defaults from leaking into nested child commands.
+- a8e4dc3: Clean up the Wayfinder navigation grammar before RC, including explicit pattern/query/file selectors, target-bound dependency and impact flags, drift-first provenance fields, stricter fires declaration diagnostics, and updated operator dogfood coverage.
+- 1d3ae74: Materialize resolved CLI command aliases through the Commander surface while
+  preserving the same trail contract and execution path.
+- Updated dependencies [c36aca9]
+- Updated dependencies [3befcf1]
+- Updated dependencies [f1e6efa]
+- Updated dependencies [a4f9cf6]
+- Updated dependencies [9bcf34e]
+- Updated dependencies [f7d97fc]
+  - @ontrails/core@1.0.0-beta.25
+  - @ontrails/cli@1.0.0-beta.25
+
 ## 1.0.0-beta.24
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ontrails/commander",
-  "version": "1.0.0-beta.24",
+  "version": "1.0.0-beta.29",
   "files": [
     "src/**/*.ts",
     "!src/**/__tests__/**",
@@ -22,8 +22,8 @@
     "clean": "rm -rf dist *.tsbuildinfo"
   },
   "dependencies": {
-    "@ontrails/cli": "^1.0.0-beta.24",
-    "@ontrails/core": "^1.0.0-beta.24",
+    "@ontrails/cli": "^1.0.0-beta.29",
+    "@ontrails/core": "^1.0.0-beta.29",
     "commander": "^14.0.3"
   },
   "peerDependencies": {

package/src/surface.ts

@@ -4,6 +4,7 @@
 
 import type {
   BaseSurfaceOptions,
+  CliCommandAliasInput,
   Layer,
   ResourceOverrideMap,
   Topo,
@@ -27,6 +28,9 @@ import { toCommander } from './to-commander.js';
  * Options for creating Commander CLI surfaces from a Trails topo.
  */
 export interface CreateProgramOptions extends BaseSurfaceOptions {
+  readonly aliases?:
+    | Readonly<Record<string, readonly CliCommandAliasInput[]>>
+    | undefined;
   readonly createContext?:
     | (() => TrailContextInit | Promise<TrailContextInit>)
     | undefined;
@@ -58,6 +62,7 @@ const deriveCommanderOptions = (
 ): ToCommanderOptions => {
   const commanderOpts: ToCommanderOptions = {
     name: options.name ?? graph.name,
+    topoName: graph.name,
   };
   if (options.version !== undefined || graph.version !== undefined) {
     commanderOpts.version = options.version ?? graph.version;
@@ -88,6 +93,7 @@ export const createProgram = (
   options: CreateProgramOptions = {}
 ) => {
   const commandsResult = deriveCliCommands(graph, {
+    aliases: options.aliases,
     configValues: options.configValues,
     createContext: options.createContext,
     exclude: options.exclude,

package/src/to-commander.ts

@@ -2,9 +2,20 @@
  * Adapt framework-agnostic CliCommand[] to a Commander program.
  */
 
-import { projectPublicSurfaceError } from '@ontrails/core';
+import {
+  isTrailsError,
+  projectPublicSurfaceError,
+  redactErrorContext,
+  redactErrorString,
+  ValidationError,
+} from '@ontrails/core';
+import type { SurfaceErrorProjection } from '@ontrails/core';
 import type { CliCommand, CliFlag } from '@ontrails/cli';
-import { applyCliFlagValueAliases, validateCliCommands } from '@ontrails/cli';
+import {
+  applyCliFlagValueAliases,
+  deriveOutputMode,
+  validateCliCommands,
+} from '@ontrails/cli';
 import { Command, InvalidArgumentError, Option } from 'commander';
 
 // ---------------------------------------------------------------------------
@@ -17,6 +28,7 @@ import { Command, InvalidArgumentError, Option } from 'commander';
 export interface ToCommanderOptions {
   description?: string | undefined;
   name?: string | undefined;
+  topoName?: string | undefined;
   version?: string | undefined;
 }
 
@@ -53,8 +65,34 @@ const strictParseNumber = (value: string): number => {
   return n;
 };
 
+const validateChoiceValue = (flag: CliFlag, value: string): void => {
+  if (flag.choices && !flag.choices.includes(value)) {
+    throw new InvalidArgumentError(
+      `Allowed choices are ${flag.choices.join(', ')}.`
+    );
+  }
+};
+
+const isRepeatableArrayFlag = (flag: CliFlag): boolean =>
+  !flag.variadic && (flag.type === 'number[]' || flag.type === 'string[]');
+
+const buildRepeatableArrayParser =
+  (flag: CliFlag) =>
+  (value: string, previous: unknown): readonly (number | string)[] => {
+    const parsed = flag.type === 'number[]' ? strictParseNumber(value) : value;
+    validateChoiceValue(flag, String(parsed));
+    return [...(Array.isArray(previous) ? previous : []), parsed];
+  };
+
 /** Apply common modifiers (choices, default, arg parser) to a Commander Option. */
 const applyOptionModifiers = (opt: Option, flag: CliFlag): void => {
+  if (isRepeatableArrayFlag(flag)) {
+    opt.argParser(buildRepeatableArrayParser(flag));
+    if (flag.default !== undefined) {
+      opt.default(flag.default);
+    }
+    return;
+  }
   if (flag.choices) {
     opt.choices(flag.choices);
   }
@@ -135,6 +173,32 @@ const isUserSuppliedOption = (command: Command, name: string): boolean => {
 const getCommandOptionNames = (command: Command): Set<string> =>
   new Set(command.options.map((option) => option.attributeName()));
 
+const renderCommandPath = (command: Command): string => {
+  const segments: string[] = [];
+  let current: Command | null = command;
+  while (current !== null && current.parent !== null) {
+    segments.push(current.name());
+    current = current.parent;
+  }
+  return segments.toReversed().join(' ');
+};
+
+const renderOptionName = (option: Option): string =>
+  option.long ?? `--${option.attributeName()}`;
+
+const INHERITED_SURFACE_OPTION_KEYS = new Set([
+  'cwd',
+  'devPermit',
+  'json',
+  'jsonl',
+  'output',
+  'permit',
+  'quiet',
+  'token',
+  'trace',
+  'watch',
+]);
+
 const hasUserSuppliedOptionOutside = (
   sourceCommand: Command,
   allowedCommand: Command
@@ -158,23 +222,64 @@ const getActionTarget = (fallbackTarget: Command, actionArgs: unknown[]) => {
   return candidate instanceof Command ? candidate : fallbackTarget;
 };
 
-const getParsedFlags = (command: Command): Record<string, unknown> =>
-  command.optsWithGlobals() as Record<string, unknown>;
+const getParsedFlags = (command: Command): Record<string, unknown> => {
+  const flags = command.optsWithGlobals() as Record<string, unknown>;
+  const commandOptionNames = getCommandOptionNames(command);
+  let { parent } = command;
+  while (parent !== null) {
+    for (const option of parent.options) {
+      const name = option.attributeName();
+      if (commandOptionNames.has(name)) {
+        continue;
+      }
+      if (
+        INHERITED_SURFACE_OPTION_KEYS.has(name) &&
+        isUserSuppliedOption(parent, name)
+      ) {
+        flags[name] = parent.getOptionValue(name);
+      } else {
+        Reflect.deleteProperty(flags, name);
+      }
+    }
+    ({ parent } = parent);
+  }
+  for (const option of command.options) {
+    const name = option.attributeName();
+    if (command.getOptionValueSource(name) !== undefined) {
+      flags[name] = command.getOptionValue(name);
+    }
+  }
+  return flags;
+};
+
+const toOptionKey = (name: string): string =>
+  name.replaceAll(/-([a-zA-Z0-9])/g, (_, ch: string) => ch.toUpperCase());
 
 const getFlagOptionKeys = (flags: readonly CliCommand['flags'][number][]) =>
   new Set(
     flags.flatMap((flag) => [
-      flag.name.replaceAll(/-([a-zA-Z0-9])/g, (_, ch: string) =>
-        ch.toUpperCase()
-      ),
-      ...(flag.valueAliases ?? []).map((alias) =>
-        alias.name.replaceAll(/-([a-zA-Z0-9])/g, (_, ch: string) =>
-          ch.toUpperCase()
-        )
-      ),
+      toOptionKey(flag.name),
+      ...(flag.valueAliases ?? []).map((alias) => toOptionKey(alias.name)),
     ])
   );
 
+const getCanonicalUserSuppliedFlagKeys = (
+  flags: readonly CliCommand['flags'][number][],
+  userSuppliedFlagKeys: ReadonlySet<string>
+): ReadonlySet<string> => {
+  const canonicalKeys = new Set(userSuppliedFlagKeys);
+  for (const flag of flags) {
+    const flagKey = toOptionKey(flag.name);
+    const aliasSelected = (flag.valueAliases ?? []).some((alias) =>
+      userSuppliedFlagKeys.has(toOptionKey(alias.name))
+    );
+    if (aliasSelected) {
+      canonicalKeys.add(flagKey);
+    }
+  }
+  return canonicalKeys;
+};
+
 const getUserSuppliedFlagKeys = (
   command: Command,
   flags: readonly CliCommand['flags'][number][]
@@ -220,19 +325,178 @@ const getFallbackUserSuppliedFlagKeys = (
   return userSupplied;
 };
 
+const collectValidationIssueLines = (
+  context: Readonly<Record<string, unknown>>
+): readonly string[] => {
+  const { issues } = context;
+  if (!Array.isArray(issues)) {
+    return [];
+  }
+  return issues.flatMap((issue) => {
+    if (typeof issue !== 'object' || issue === null) {
+      return [];
+    }
+    const { message, trailId } = issue as {
+      message?: unknown;
+      trailId?: unknown;
+    };
+    if (typeof message !== 'string') {
+      return [];
+    }
+    const suffix = typeof trailId === 'string' ? ` (${trailId})` : '';
+    return [`- ${redactErrorString(message)}${suffix}`];
+  });
+};
+
+const collectPermitScopeLines = (
+  context: Readonly<Record<string, unknown>>
+): readonly string[] => {
+  const candidate = [context['required'], context['missing']].find((value) =>
+    Array.isArray(value)
+  );
+  const scopes = (Array.isArray(candidate) ? candidate : [])
+    .filter((scope): scope is string => typeof scope === 'string')
+    .map((scope) => redactErrorString(scope));
+  if (scopes.length === 0) {
+    return [];
+  }
+  const scopeJson = scopes.map((scope) => JSON.stringify(scope)).join(',');
+  return [
+    `Required scopes: ${scopes.join(', ')}`,
+    `Grant with: --permit '{"id":"<caller-id>","scopes":[${scopeJson}]}'`,
+  ];
+};
+
+/**
+ * Collect operator-facing detail lines for an execution error.
+ *
+ * The public surface projection intentionally drops structured context, but
+ * the CLI is an operator surface: validation issues and permit scope
+ * requirements are what the operator needs to act, so they are re-rendered
+ * here (through the shared redactor) for non-internal Trails errors.
+ */
+const collectErrorDetailLines = (error: Error): readonly string[] => {
+  if (!isTrailsError(error) || error.category === 'internal') {
+    return [];
+  }
+  const context = error.context ?? {};
+  if (error.category === 'validation') {
+    return collectValidationIssueLines(context);
+  }
+  if (error.category === 'permission') {
+    return collectPermitScopeLines(context);
+  }
+  return [];
+};
+
+const collectErrorContext = (
+  error: Error
+): Record<string, unknown> | undefined => {
+  if (!isTrailsError(error) || error.category === 'internal') {
+    return undefined;
+  }
+  return redactErrorContext(error.context);
+};
+
+interface CliErrorEnvelope {
+  readonly ok: false;
+  readonly context?: Record<string, unknown> | undefined;
+  readonly error: SurfaceErrorProjection;
+  readonly details?: readonly string[] | undefined;
+}
+
+type StructuredErrorMode = 'json' | 'jsonl';
+
+const structuredErrorMode = (
+  flags: Readonly<Record<string, unknown>>,
+  topoName: string,
+  userSuppliedFlagKeys: ReadonlySet<string>
+): StructuredErrorMode | undefined => {
+  const modeFlags = { ...flags };
+  if (!userSuppliedFlagKeys.has('output')) {
+    delete modeFlags['output'];
+  }
+  const { mode } = deriveOutputMode(modeFlags, topoName);
+  return mode === 'text' ? undefined : mode;
+};
+
+const writeStructuredError = (
+  envelope: CliErrorEnvelope,
+  mode: StructuredErrorMode
+): void => {
+  process.stderr.write(
+    mode === 'json'
+      ? `${JSON.stringify(envelope, null, 2)}\n`
+      : `${JSON.stringify(envelope)}\n`
+  );
+};
+
 /** Handle execution errors with appropriate exit codes. */
-const handleError = (error: unknown): void => {
+const handleError = (
+  error: unknown,
+  flags: Readonly<Record<string, unknown>>,
+  topoName: string,
+  userSuppliedFlagKeys: ReadonlySet<string>
+): void => {
   const err = error instanceof Error ? error : new Error(String(error));
   const projection = projectPublicSurfaceError('cli', err);
-  process.stderr.write(`Error: ${projection.message}\n`);
+  const context = collectErrorContext(err);
+  const details = collectErrorDetailLines(err);
+  const mode = structuredErrorMode(flags, topoName, userSuppliedFlagKeys);
+  if (mode === undefined) {
+    process.stderr.write(`Error: ${projection.message}\n`);
+    for (const line of details) {
+      process.stderr.write(`  ${line}\n`);
+    }
+  } else {
+    writeStructuredError(
+      {
+        ...(context === undefined ? {} : { context }),
+        error: projection,
+        ...(details.length === 0 ? {} : { details }),
+        ok: false,
+      },
+      mode
+    );
+  }
   process.exit(projection.code);
 };
 
+const collectDisallowedAncestorOptions = (
+  target: Command,
+  allowedFlags: readonly CliCommand['flags'][number][]
+): readonly string[] => {
+  const allowedKeys = getFlagOptionKeys(allowedFlags);
+  const childPath = renderCommandPath(target);
+  const disallowed: string[] = [];
+  let { parent } = target;
+
+  while (parent !== null) {
+    const parentPath = renderCommandPath(parent);
+    for (const option of parent.options) {
+      const name = option.attributeName();
+      if (
+        isUserSuppliedOption(parent, name) &&
+        !allowedKeys.has(name) &&
+        !INHERITED_SURFACE_OPTION_KEYS.has(name)
+      ) {
+        disallowed.push(
+          `${renderOptionName(option)} belongs to "${parentPath}" and is not supported by "${childPath}".`
+        );
+      }
+    }
+    ({ parent } = parent);
+  }
+
+  return disallowed;
+};
+
 interface BareChildFallback {
   readonly argName: string;
   readonly argValue: string;
   readonly parentCommand: CliCommand;
   readonly parentTarget: Command;
+  readonly requiresParentSignal: boolean;
 }
 
 const maybeUseBareChildFallback = (
@@ -246,10 +510,14 @@ const maybeUseBareChildFallback = (
   readonly parsedFlags: Record<string, unknown>;
   readonly userSuppliedFlagKeys: ReadonlySet<string>;
 } => {
+  const hasParentOnlySignal = fallback
+    ? hasUserSuppliedOptionOutside(fallback.parentTarget, target)
+    : false;
   if (
     !fallback ||
     hasAnyPositionalValue(cmd, parsedArgs) ||
-    hasUserSuppliedOptionOutside(target, fallback.parentTarget)
+    hasUserSuppliedOptionOutside(target, fallback.parentTarget) ||
+    (fallback.requiresParentSignal && !hasParentOnlySignal)
   ) {
     return {
       command: cmd,
@@ -275,6 +543,7 @@ const maybeUseBareChildFallback = (
 const wireAction = (
   target: Command,
   cmd: CliCommand,
+  topoName: string,
   fallback?: BareChildFallback | undefined
 ): void => {
   target.action(async (...actionArgs: unknown[]) => {
@@ -291,17 +560,38 @@ const wireAction = (
             parentTarget: actionTarget.parent ?? fallback.parentTarget,
           }
     );
+    let { parsedFlags } = action;
     try {
-      await action.command.execute(
-        action.parsedArgs,
-        applyCliFlagValueAliases(
+      const disallowedAncestorOptions = collectDisallowedAncestorOptions(
+        actionTarget,
+        action.command.flags
+      );
+      if (disallowedAncestorOptions.length > 0) {
+        throw new ValidationError('Unsupported option for this CLI command.', {
+          context: {
+            issues: disallowedAncestorOptions.map((message) => ({
+              message,
+              trailId: action.command.trail.id,
+            })),
+          },
+        });
+      }
+      parsedFlags = applyCliFlagValueAliases(
+        action.command.flags,
+        action.parsedFlags,
+        action.userSuppliedFlagKeys
+      );
+      await action.command.execute(action.parsedArgs, parsedFlags);
+    } catch (error: unknown) {
+      handleError(
+        error,
+        parsedFlags,
+        topoName,
+        getCanonicalUserSuppliedFlagKeys(
           action.command.flags,
-          action.parsedFlags,
           action.userSuppliedFlagKeys
         )
       );
-    } catch (error: unknown) {
-      handleError(error);
     }
   });
 };
@@ -387,22 +677,22 @@ const ensureCommandNode = (
 
 const createBareChildFallback = (
   cmd: CliCommand,
+  path: readonly string[],
   parentState?: CommandNodeState | undefined
 ): BareChildFallback | undefined => {
-  if (!parentState?.cliCommand || cmd.path.length < 2) {
+  if (!parentState?.cliCommand || path.length < 2) {
     return undefined;
   }
 
   const [parentArg] = parentState.cliCommand.args;
   const [childArg] = cmd.args;
-  const childSegment = cmd.path.at(-1);
+  const childSegment = path.at(-1);
   if (
     parentArg === undefined ||
-    childArg === undefined ||
     parentArg.required ||
     parentArg.variadic ||
-    childArg.variadic ||
-    childArg.name !== parentArg.name ||
+    (childArg !== undefined &&
+      (childArg.variadic || childArg.name !== parentArg.name)) ||
     childSegment === undefined
   ) {
     return undefined;
@@ -413,16 +703,19 @@ const createBareChildFallback = (
     argValue: childSegment,
     parentCommand: parentState.cliCommand,
     parentTarget: parentState.command,
+    requiresParentSignal: childArg === undefined,
   };
 };
 
 const applyCliCommand = (
   state: CommandNodeState,
   cmd: CliCommand,
+  path: readonly string[],
+  topoName: string,
   fallback?: BareChildFallback | undefined
 ): void => {
   if (state.executable) {
-    throw new Error(`Duplicate CLI path: ${cmd.path.join(' ')}`);
+    throw new Error(`Duplicate CLI path: ${path.join(' ')}`);
   }
 
   if (cmd.description) {
@@ -436,11 +729,26 @@ const applyCliCommand = (
   addArgs(state.command, cmd, {
     forceOptionalFirstArg: fallback !== undefined,
   });
-  wireAction(state.command, cmd, fallback);
+  wireAction(state.command, cmd, topoName, fallback);
   state.cliCommand = cmd;
   state.executable = true;
 };
 
+const commandRoutes = (cmd: CliCommand) =>
+  cmd.routes ?? [
+    {
+      kind: 'canonical' as const,
+      path: cmd.path,
+      source: 'derived' as const,
+      target: cmd.trail.id,
+    },
+  ];
+
+const commandRouteEntries = (commands: readonly CliCommand[]) =>
+  commands.flatMap((cmd) =>
+    commandRoutes(cmd).map((route) => ({ cmd, path: route.path }))
+  );
+
 /**
  * Convert framework-agnostic CLI commands into a Commander program.
  *
@@ -452,7 +760,10 @@ const applyCliCommand = (
  * const commands = deriveCliCommands(graph);
  * if (commands.isErr()) throw commands.error;
  *
- * const program = toCommander(commands.value, { name: 'demo' });
+ * const program = toCommander(commands.value, {
+ *   name: 'demo',
+ *   topoName: 'demo',
+ * });
  * ```
  */
 export const toCommander = (
@@ -462,17 +773,18 @@ export const toCommander = (
   validateCliCommands(commands);
   const program = new Command();
   applyOptions(program, options);
+  const topoName = options?.topoName ?? options?.name ?? program.name();
   const nodes = new Map<string, CommandNodeState>();
 
-  for (const cmd of commands.toSorted((a, b) =>
+  for (const { cmd, path } of commandRouteEntries(commands).toSorted((a, b) =>
     a.path.length === b.path.length
       ? a.path.join('.').localeCompare(b.path.join('.'))
       : a.path.length - b.path.length
   )) {
-    const state = ensureCommandNode(cmd.path, program, nodes);
-    const parentKey = pathKey(cmd.path.slice(0, -1));
-    const fallback = createBareChildFallback(cmd, nodes.get(parentKey));
-    applyCliCommand(state, cmd, fallback);
+    const state = ensureCommandNode(path, program, nodes);
+    const parentKey = pathKey(path.slice(0, -1));
+    const fallback = createBareChildFallback(cmd, path, nodes.get(parentKey));
+    applyCliCommand(state, cmd, path, topoName, fallback);
   }
 
   return program;