@ontrails/commander 1.0.0-beta.39 → 1.0.0-beta.42

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # @ontrails/commander
 
+## 1.0.0-beta.42
+
+### Patch Changes
+
+- [`454e935`](https://github.com/outfitter-dev/trails/commit/454e935088782a181df89a205c0ff6f2eb936434): Define bounded multiselect argv normalization in the framework CLI model and apply it automatically in the Commander adapter, accepting both contiguous and repeated forms while preserving child routes after the first explicit value.
+
+## 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

package/README.md

@@ -35,6 +35,17 @@ if (commands.isErr()) {
 const program = toCommander(commands.value, { name: 'myapp' });
 ```
 
+## Multiselect flags
+
+Schema fields such as `z.array(z.enum(['cli', 'mcp', 'http']))` derive a bounded multiselect flag. The shared CLI argv normalizer lets adapters accept both contiguous and repeated forms; Commander applies it automatically:
+
+```bash
+myapp create --surfaces cli mcp http
+myapp create --surfaces cli --surfaces mcp --surfaces http
+```
+
+The first matching token after the flag is its explicit value. After that first value, additional collection stops before known child routes or values outside the declared choices. Adopters do not need custom parsing or surface configuration for either form.
+
 ## Installation
 
 ```bash

package/package.json

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

package/src/multiselect-argv.ts

@@ -0,0 +1,182 @@
+import { Command } from 'commander';
+import type { ParseOptions, Option } from 'commander';
+import { normalizeCliArgv } from '@ontrails/cli';
+import type { CliCommand } from '@ontrails/cli';
+
+type EffectiveParseOptions = Omit<ParseOptions, 'from'> & {
+  readonly from?: ParseOptions['from'] | 'eval' | undefined;
+};
+
+export 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);
+};
+
+export interface InvocationOptionMatch {
+  readonly inlineValue: boolean;
+  readonly option: Option;
+}
+
+const findShortOption = (
+  options: readonly Option[],
+  short: string
+): Option | undefined => options.find((candidate) => candidate.short === short);
+
+export 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;
+};
+
+export 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;
+};
+
+export 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))));
+
+const argvUserStart = (
+  parseOptions?: EffectiveParseOptions | undefined
+): number => {
+  if (parseOptions?.from === 'user') {
+    return 0;
+  }
+  if (parseOptions?.from === 'eval') {
+    return 1;
+  }
+  if (parseOptions?.from === 'electron') {
+    const electronProcess = process as NodeJS.Process & {
+      readonly defaultApp?: boolean | undefined;
+    };
+    return electronProcess.defaultApp ? 2 : 1;
+  }
+  return 2;
+};
+
+const effectiveParseOptions = (
+  argv: readonly string[] | undefined,
+  parseOptions: ParseOptions | undefined
+): EffectiveParseOptions | undefined => {
+  if (
+    argv === undefined &&
+    parseOptions?.from === undefined &&
+    process.execArgv.some((arg) =>
+      ['-e', '--eval', '-p', '--print'].includes(arg)
+    )
+  ) {
+    // Commander supports this origin internally but does not publish it in
+    // ParseOptions. Preserve its one-token offset while normalizing argv.
+    return { from: 'eval' };
+  }
+  if (
+    argv === undefined &&
+    parseOptions?.from === undefined &&
+    process.versions['electron'] !== undefined
+  ) {
+    return { from: 'electron' };
+  }
+  return parseOptions;
+};
+
+export class TrailsCommanderProgram extends Command {
+  readonly #commands: readonly CliCommand[];
+
+  constructor(commands: readonly CliCommand[]) {
+    super();
+    this.#commands = commands;
+  }
+
+  #normalizeArgv(
+    argv: readonly string[] | undefined,
+    parseOptions: EffectiveParseOptions | undefined
+  ): readonly string[] {
+    const input = argv ?? process.argv;
+    const start = argvUserStart(parseOptions);
+    return [
+      ...input.slice(0, start),
+      ...normalizeCliArgv(this.#commands, input.slice(start)),
+    ];
+  }
+
+  override parse(argv?: readonly string[], parseOptions?: ParseOptions): this {
+    const options = effectiveParseOptions(argv, parseOptions);
+    const normalized = this.#normalizeArgv(argv, options);
+    return super.parse(normalized, options as ParseOptions | undefined);
+  }
+
+  override parseAsync(
+    argv?: readonly string[],
+    parseOptions?: ParseOptions
+  ): Promise<this> {
+    const options = effectiveParseOptions(argv, parseOptions);
+    const normalized = this.#normalizeArgv(argv, options);
+    return super.parseAsync(normalized, options as ParseOptions | undefined);
+  }
+}

package/src/to-commander.ts

@@ -18,6 +18,14 @@ import {
 } from '@ontrails/cli';
 import { Command, InvalidArgumentError, Option } from 'commander';
 
+import {
+  invocationOptionMatches,
+  isNegativeNumberArg,
+  optionConsumesFollowingValue,
+  TrailsCommanderProgram,
+  visibleOptionsFor,
+} from './multiselect-argv.js';
+
 // ---------------------------------------------------------------------------
 // Options
 // ---------------------------------------------------------------------------
@@ -84,6 +92,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 +117,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 +211,107 @@ 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 isVariadicOptionValue = (
+  command: Command,
+  option: Option | undefined,
+  token: string
+): boolean =>
+  option !== undefined &&
+  (!token.startsWith('-') || isNegativeNumberArg(command, token));
+
+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 +331,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;
@@ -286,8 +422,13 @@ const getUserSuppliedFlagKeys = (
 ): ReadonlySet<string> => {
   const userSupplied = new Set<string>();
   for (const key of getFlagOptionKeys(flags)) {
-    if (isUserSuppliedOption(command, key)) {
-      userSupplied.add(key);
+    let owner: Command | null = command;
+    while (owner !== null) {
+      if (isUserSuppliedOption(owner, key)) {
+        userSupplied.add(key);
+        break;
+      }
+      owner = owner.parent;
     }
   }
   return userSupplied;
@@ -510,12 +651,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)
   ) {
@@ -776,7 +920,7 @@ export const toCommander = (
   options?: ToCommanderOptions
 ): Command => {
   validateCliCommands(commands);
-  const program = new Command();
+  const program = new TrailsCommanderProgram(commands);
   applyOptions(program, options);
   const topoName = options?.topoName ?? options?.name ?? program.name();
   const nodes = new Map<string, CommandNodeState>();