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

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @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

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.41",
+  "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.41",
-    "@ontrails/core": "^1.0.0-beta.41",
+    "@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
 // ---------------------------------------------------------------------------
@@ -224,87 +232,6 @@ const rootCommandFor = (command: Command): Command => {
 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,
@@ -313,17 +240,6 @@ const isVariadicOptionValue = (
   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>;
@@ -506,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;
@@ -999,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>();