@ontrails/commander 1.0.0-beta.32 → 1.0.0-beta.41

package/CHANGELOG.md

@@ -1,5 +1,46 @@
 # @ontrails/commander
 
+## 1.0.0-beta.41
+
+## 1.0.0-beta.40
+
+### Patch Changes
+
+- [`4030698`](https://github.com/outfitter-dev/trails/commit/40306984467625844564f0f84156530d7118a79c): Keep structured input on nested child commands from being reinterpreted as a
+  bare child-name positional fallback, while preserving schema-authored
+  `inputJson` flags as ordinary trail input, including through the public Trails
+  CLI. Optional numeric flags now consume negative values with Commander's own
+  parsing semantics, and variadic flags consume every following value, before
+  nested command routing is resolved.
+
+## 1.0.0-beta.39
+
+### Patch Changes
+
+- [`f42ca6e`](https://github.com/outfitter-dev/trails/commit/f42ca6e40b29155acec446e5bf44e52e014466bd): Hard cutover: the CLI consumes `cli` bindings from the app-authored surfaces overlay. Scalar bindings behave identically to the removed cliAliases (parity-tested) — the binding name splits on `.` into a transparent synonym command path for exactly one trail. List bindings arrive as command groups: each expanded member trail gets a group-prefixed route that dispatches the member trail with its identity preserved, and a singleton list stays a group. Expansion is fail-fast boundary validation: a scalar binding resolving to zero or multiple trails, or a group with an empty member union, is a `ValidationError` naming the binding. `DeriveTopoGraphOptions.cliAliases`, the `cliAliases`/`trailsCliAliases` app-module export convention, and the per-kind compile lift are deleted; `deriveCliCommands`/`createProgram` take `overlays` instead of `aliases`, and both topo-graph derivation pipelines expand the same bindings through one shared helper so runtime CLI routes and lock routes come from one semantic. A leftover legacy export is now a Warden error (`no-legacy-cli-alias-export`) naming the `surfaceOverlay({ cli: { ... } })` rewrite.
+
+  This is a breaking API removal shipped under the lockstep beta patch convention (pre-1.0 hard-cutover posture, zero external adoption); the removed options have no deprecation window by design.
+
+## 1.0.0-beta.38
+
+## 1.0.0-beta.37
+
+## 1.0.0-beta.36
+
+## 1.0.0-beta.35
+
+## 1.0.0-beta.34
+
+## 1.0.0-beta.33
+
+### Patch Changes
+
+- [`945cb4b`](https://github.com/outfitter-dev/trails/commit/945cb4b0bef40ddb098c2a3816f9adad6f135410): Honor explicit structured input values over CLI flag defaults when commands merge
+  `--input-json` or `--input` payloads.
+
+  Commander now forwards user-supplied flag metadata so explicit flag values that
+  match a default still keep normal CLI precedence over structured input.
+
 ## 1.0.0-beta.32
 
 ### Patch Changes

package/package.json

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

package/src/surface.ts

@@ -4,8 +4,8 @@
 
 import type {
   BaseSurfaceOptions,
-  CliCommandAliasInput,
   Layer,
+  OverlayEnvelopeLike,
   ResourceOverrideMap,
   Topo,
   TrailContextInit,
@@ -28,9 +28,6 @@ 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;
@@ -38,6 +35,12 @@ export interface CreateProgramOptions extends BaseSurfaceOptions {
   readonly layers?: readonly Layer[] | undefined;
   readonly name?: string | undefined;
   readonly onResult?: ((ctx: ActionResultContext) => Promise<void>) | undefined;
+  /**
+   * App-authored overlay envelopes (conventionally the app module's
+   * `trailsOverlays` export); the `surfaces` envelope's `cli` bindings
+   * project synonym and command-group routes onto the program.
+   */
+  readonly overlays?: readonly OverlayEnvelopeLike[] | undefined;
   readonly presets?: CliFlag[][] | undefined;
   readonly resources?: ResourceOverrideMap | undefined;
   readonly resolveInput?: InputResolver | undefined;
@@ -93,7 +96,6 @@ export const createProgram = (
   options: CreateProgramOptions = {}
 ) => {
   const commandsResult = deriveCliCommands(graph, {
-    aliases: options.aliases,
     configValues: options.configValues,
     createContext: options.createContext,
     exclude: options.exclude,
@@ -101,6 +103,7 @@ export const createProgram = (
     intent: options.intent,
     layers: options.layers,
     onResult: options.onResult ?? defaultOnResult,
+    overlays: options.overlays,
     presets: options.presets,
     resolveInput: options.resolveInput,
     resolvePermitFromToken: options.resolvePermitFromToken,

package/src/to-commander.ts

@@ -84,6 +84,8 @@ const buildRepeatableArrayParser =
     return [...(Array.isArray(previous) ? previous : []), parsed];
   };
 
+const structuredInputOptions = new WeakSet<Option>();
+
 /** Apply common modifiers (choices, default, arg parser) to a Commander Option. */
 const applyOptionModifiers = (opt: Option, flag: CliFlag): void => {
   if (isRepeatableArrayFlag(flag)) {
@@ -107,6 +109,9 @@ const applyOptionModifiers = (opt: Option, flag: CliFlag): void => {
 /** Build Commander Option(s) from a CliFlag. Returns one or two options. */
 const buildOptions = (flag: CliFlag): Option[] => {
   const opt = new Option(buildFlagString(flag), flag.description);
+  if (flag.role === 'structured-input') {
+    structuredInputOptions.add(opt);
+  }
   applyOptionModifiers(opt, flag);
   const valueAliasOptions = (flag.valueAliases ?? []).map(
     (alias) =>
@@ -198,6 +203,199 @@ const INHERITED_SURFACE_OPTION_KEYS = new Set([
   'trace',
   'watch',
 ]);
+const commandPathCommands = (command: Command): readonly Command[] => {
+  const commands: Command[] = [];
+  let current: Command | null = command;
+  while (current !== null && current.parent !== null) {
+    commands.push(current);
+    current = current.parent;
+  }
+  return commands.toReversed();
+};
+
+const rootCommandFor = (command: Command): Command => {
+  let root = command;
+  while (root.parent !== null) {
+    root = root.parent;
+  }
+  return root;
+};
+
+const invocationArgsFor = (command: Command): readonly string[] =>
+  rootCommandFor(command).args;
+
+const visibleOptionsFor = (command: Command): readonly Option[] => {
+  const commands: Command[] = [];
+  let current: Command | null = command;
+  while (current !== null) {
+    commands.push(current);
+    current = current.parent;
+  }
+  return commands.toReversed().flatMap((owner) => owner.options);
+};
+
+interface InvocationOptionMatch {
+  readonly inlineValue: boolean;
+  readonly option: Option;
+}
+
+const findShortOption = (
+  options: readonly Option[],
+  short: string
+): Option | undefined => options.find((candidate) => candidate.short === short);
+
+const invocationOptionMatches = (
+  options: readonly Option[],
+  token: string
+): readonly InvocationOptionMatch[] => {
+  const exact = options.filter(
+    (option) => token === option.long || token === option.short
+  );
+  if (exact.length > 0) {
+    return exact.map((option) => ({ inlineValue: false, option }));
+  }
+
+  const longWithValue = options.filter(
+    (option) =>
+      option.long !== undefined &&
+      (option.required || option.optional) &&
+      token.startsWith(`${option.long}=`)
+  );
+  if (longWithValue.length > 0) {
+    return longWithValue.map((option) => ({ inlineValue: true, option }));
+  }
+
+  if (token.length <= 2 || token[0] !== '-' || token[1] === '-') {
+    return [];
+  }
+
+  const matches: InvocationOptionMatch[] = [];
+  let group = token.slice(1);
+  while (group.length > 0) {
+    const option = findShortOption(options, `-${group[0]}`);
+    if (option === undefined) {
+      break;
+    }
+    const inlineValue =
+      (option.required || option.optional) && group.length > 1;
+    matches.push({ inlineValue, option });
+    if (option.required || option.optional) {
+      break;
+    }
+    group = group.slice(1);
+  }
+  return matches;
+};
+
+const isNegativeNumberArg = (command: Command, token: string): boolean => {
+  if (!/^-(\d+|\d*\.\d+)(e[+-]?\d+)?$/.test(token)) {
+    return false;
+  }
+
+  for (
+    let current: Command | null = command;
+    current !== null;
+    current = current.parent
+  ) {
+    if (current.options.some((option) => /^-\d$/.test(option.short ?? ''))) {
+      return false;
+    }
+  }
+
+  return true;
+};
+
+const isVariadicOptionValue = (
+  command: Command,
+  option: Option | undefined,
+  token: string
+): boolean =>
+  option !== undefined &&
+  (!token.startsWith('-') || isNegativeNumberArg(command, token));
+
+const optionConsumesFollowingValue = (
+  command: Command,
+  match: InvocationOptionMatch,
+  nextToken: string | undefined
+): boolean =>
+  !match.inlineValue &&
+  (match.option.required ||
+    (match.option.optional &&
+      nextToken !== undefined &&
+      (!nextToken.startsWith('-') || isNegativeNumberArg(command, nextToken))));
+
+interface InvocationScan {
+  readonly pathEnd: number | undefined;
+  readonly structuredInputIndexes: ReadonlySet<number>;
+}
+
+const scanInvocation = (command: Command): InvocationScan => {
+  const rawArgs = invocationArgsFor(command);
+  const pathCommands = commandPathCommands(command);
+  const structuredInputIndexes = new Set<number>();
+  let activeCommand = rootCommandFor(command);
+  let activeVariadicOption: Option | undefined;
+  let optionsEnded = false;
+  let pathEnd: number | undefined;
+  let pathOffset = 0;
+  for (let index = 0; index < rawArgs.length; index += 1) {
+    const token = rawArgs[index];
+    if (token === undefined) {
+      continue;
+    }
+    if (!optionsEnded && token === '--') {
+      optionsEnded = true;
+      activeVariadicOption = undefined;
+      continue;
+    }
+    if (isVariadicOptionValue(command, activeVariadicOption, token)) {
+      continue;
+    }
+    activeVariadicOption = undefined;
+    const optionMatches = optionsEnded
+      ? []
+      : invocationOptionMatches(visibleOptionsFor(activeCommand), token);
+    const finalOptionMatch = optionMatches.at(-1);
+    if (finalOptionMatch !== undefined) {
+      if (
+        optionMatches.some((match) => structuredInputOptions.has(match.option))
+      ) {
+        structuredInputIndexes.add(index);
+      }
+      activeVariadicOption =
+        finalOptionMatch.option.variadic && !finalOptionMatch.inlineValue
+          ? finalOptionMatch.option
+          : undefined;
+      if (
+        optionConsumesFollowingValue(
+          command,
+          finalOptionMatch,
+          rawArgs[index + 1]
+        )
+      ) {
+        index += 1;
+      }
+      continue;
+    }
+    const nextPathCommand = pathCommands[pathOffset];
+    if (nextPathCommand?.name() === token) {
+      activeCommand = nextPathCommand;
+      pathOffset += 1;
+      if (pathOffset === pathCommands.length) {
+        pathEnd = index;
+      }
+    }
+  }
+  return { pathEnd, structuredInputIndexes };
+};
+
+const hasStructuredInputAfterCommandPath = (command: Command): boolean => {
+  const { pathEnd, structuredInputIndexes } = scanInvocation(command);
+  if (pathEnd === undefined) {
+    return false;
+  }
+  return [...structuredInputIndexes].some((index) => index > pathEnd);
+};
 
 const hasUserSuppliedOptionOutside = (
   sourceCommand: Command,
@@ -217,6 +415,28 @@ const hasAnyPositionalValue = (
   parsedArgs: Readonly<Record<string, unknown>>
 ): boolean => cmd.args.some((arg) => parsedArgs[arg.name] !== undefined);
 
+const hasUserSuppliedStructuredInput = (
+  command: Command,
+  fallback?: BareChildFallback | undefined,
+  ownOptionsOnly = false
+): boolean => {
+  for (const option of command.options) {
+    if (!structuredInputOptions.has(option)) {
+      continue;
+    }
+    const name = option.attributeName();
+    const source = ownOptionsOnly
+      ? command.getOptionValueSource(name)
+      : command.getOptionValueSourceWithGlobals(name);
+    if (source !== undefined && source !== 'default' && source !== 'implied') {
+      return (
+        fallback === undefined || hasStructuredInputAfterCommandPath(command)
+      );
+    }
+  }
+  return false;
+};
+
 const getActionTarget = (fallbackTarget: Command, actionArgs: unknown[]) => {
   const candidate = actionArgs.at(-1);
   return candidate instanceof Command ? candidate : fallbackTarget;
@@ -510,12 +730,15 @@ const maybeUseBareChildFallback = (
   readonly parsedFlags: Record<string, unknown>;
   readonly userSuppliedFlagKeys: ReadonlySet<string>;
 } => {
-  const hasParentOnlySignal = fallback
-    ? hasUserSuppliedOptionOutside(fallback.parentTarget, target)
-    : false;
+  const hasParentOnlySignal =
+    fallback !== undefined &&
+    (hasUserSuppliedOptionOutside(fallback.parentTarget, target) ||
+      (hasUserSuppliedStructuredInput(fallback.parentTarget, undefined, true) &&
+        !hasStructuredInputAfterCommandPath(target)));
   if (
     !fallback ||
     hasAnyPositionalValue(cmd, parsedArgs) ||
+    hasUserSuppliedStructuredInput(target, fallback) ||
     hasUserSuppliedOptionOutside(target, fallback.parentTarget) ||
     (fallback.requiresParentSignal && !hasParentOnlySignal)
   ) {
@@ -581,7 +804,12 @@ const wireAction = (
         action.parsedFlags,
         action.userSuppliedFlagKeys
       );
-      await action.command.execute(action.parsedArgs, parsedFlags);
+      await action.command.execute(action.parsedArgs, parsedFlags, undefined, {
+        userSuppliedFlagKeys: getCanonicalUserSuppliedFlagKeys(
+          action.command.flags,
+          action.userSuppliedFlagKeys
+        ),
+      });
     } catch (error: unknown) {
       handleError(
         error,