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

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @ontrails/commander
 
+## 1.0.0-beta.43
+
+### Patch Changes
+
+- [`88a6a62`](https://github.com/outfitter-dev/trails/commit/88a6a62a9e9e230ca6d368fa78dc3ece6c816204): Complete the v1 classification-first cutover from projection/project vocabulary
+  to derive/derived for contract-owned fact production and render/rendered for
+  surface presentation. Public type, helper, rule, relation, and report names move
+  without compatibility aliases; ordinary repository/project nouns remain
+  explicit preserves or structured review inventory.
+
+## 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.43",
   "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.43",
+    "@ontrails/core": "^1.0.0-beta.43",
     "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/surface.ts

@@ -38,7 +38,7 @@ export interface CreateProgramOptions extends BaseSurfaceOptions {
   /**
    * 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.
+   * render synonym and command-group routes onto the program.
    */
   readonly overlays?: readonly OverlayEnvelopeLike[] | undefined;
   readonly presets?: CliFlag[][] | undefined;

package/src/to-commander.ts

@@ -4,12 +4,12 @@
 
 import {
   isTrailsError,
-  projectPublicSurfaceError,
+  renderPublicSurfaceError,
   redactErrorContext,
   redactErrorString,
   ValidationError,
 } from '@ontrails/core';
-import type { SurfaceErrorProjection } from '@ontrails/core';
+import type { SurfaceErrorRendering } from '@ontrails/core';
 import type { CliCommand, CliFlag } from '@ontrails/cli';
 import {
   applyCliFlagValueAliases,
@@ -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;
@@ -590,7 +511,7 @@ const collectPermitScopeLines = (
 /**
  * Collect operator-facing detail lines for an execution error.
  *
- * The public surface projection intentionally drops structured context, but
+ * The public surface rendering 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.
@@ -621,7 +542,7 @@ const collectErrorContext = (
 interface CliErrorEnvelope {
   readonly ok: false;
   readonly context?: Record<string, unknown> | undefined;
-  readonly error: SurfaceErrorProjection;
+  readonly error: SurfaceErrorRendering;
   readonly details?: readonly string[] | undefined;
 }
 
@@ -659,12 +580,12 @@ const handleError = (
   userSuppliedFlagKeys: ReadonlySet<string>
 ): void => {
   const err = error instanceof Error ? error : new Error(String(error));
-  const projection = projectPublicSurfaceError('cli', err);
+  const rendering = renderPublicSurfaceError('cli', err);
   const context = collectErrorContext(err);
   const details = collectErrorDetailLines(err);
   const mode = structuredErrorMode(flags, topoName, userSuppliedFlagKeys);
   if (mode === undefined) {
-    process.stderr.write(`Error: ${projection.message}\n`);
+    process.stderr.write(`Error: ${rendering.message}\n`);
     for (const line of details) {
       process.stderr.write(`  ${line}\n`);
     }
@@ -672,14 +593,14 @@ const handleError = (
     writeStructuredError(
       {
         ...(context === undefined ? {} : { context }),
-        error: projection,
+        error: rendering,
         ...(details.length === 0 ? {} : { details }),
         ok: false,
       },
       mode
     );
   }
-  process.exit(projection.code);
+  process.exit(rendering.code);
 };
 
 const collectDisallowedAncestorOptions = (
@@ -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>();