padrone 1.4.0 → 1.6.0

package/src/core/commands.ts

@@ -0,0 +1,373 @@
+import type { AnyPadroneCommand } from '../types/index.ts';
+import { extractSchemaMetadata, getJsonSchema } from './args.ts';
+import { resolveRuntime } from './default-runtime.ts';
+import type { ResolvedPadroneRuntime } from './runtime.ts';
+
+// ---------------------------------------------------------------------------
+// Lazy command resolution
+// ---------------------------------------------------------------------------
+
+export const lazyResolver = Symbol('lazyResolver');
+
+/** Resolves a lazy command in place by calling its stored resolver. No-op if already resolved. */
+export function resolveCommand(cmd: AnyPadroneCommand): AnyPadroneCommand {
+  const resolver = (cmd as any)[lazyResolver];
+  if (resolver) {
+    delete (cmd as any)[lazyResolver];
+    resolver(cmd);
+  }
+  return cmd;
+}
+
+/** Recursively resolves a command and all its descendants. */
+export function resolveAllCommands(cmd: AnyPadroneCommand): void {
+  resolveCommand(cmd);
+  if (cmd.commands) {
+    for (const sub of cmd.commands) resolveAllCommands(sub);
+  }
+}
+
+/** Checks whether a value is a Padrone program/builder. */
+export function isPadroneProgram(value: unknown): value is object {
+  return !!value && typeof value === 'object' && commandSymbol in value;
+}
+
+/** Extracts the underlying command from a program/builder and resolves the full command tree. */
+export function getCommand(program: object): AnyPadroneCommand {
+  const cmd = commandSymbol in program ? ((program as any)[commandSymbol] as AnyPadroneCommand) : (program as AnyPadroneCommand);
+  resolveAllCommands(cmd);
+  return cmd;
+}
+
+export const commandSymbol = Symbol('padrone_command');
+
+/** Config keys that are merged when overriding a command. */
+export const configKeys = ['title', 'description', 'version', 'deprecated', 'hidden', 'mutation', 'needsApproval'] as const;
+
+/**
+ * Merges an existing command with an override.
+ * - Config fields are shallow-merged (new overrides old).
+ * - Action, arguments, meta, config schema, env schema are taken from the override if set.
+ * - Subcommands are recursively merged by name.
+ */
+export function mergeCommands(existing: AnyPadroneCommand, override: AnyPadroneCommand): AnyPadroneCommand {
+  resolveCommand(existing);
+  resolveCommand(override);
+  const merged: AnyPadroneCommand = { ...existing };
+
+  // Merge config fields
+  for (const key of configKeys) {
+    if (override[key] !== undefined) (merged as any)[key] = override[key];
+  }
+
+  // Override fields: take from override if explicitly set (not inherited from existing via spread)
+  if (override.action !== existing.action) merged.action = override.action;
+  if (override.argsSchema !== existing.argsSchema) merged.argsSchema = override.argsSchema;
+  if (override.meta !== existing.meta) merged.meta = override.meta;
+  if (override.isAsync !== existing.isAsync) merged.isAsync = override.isAsync || existing.isAsync;
+  if (override.runtime !== existing.runtime) merged.runtime = override.runtime;
+  if (override.interceptors !== existing.interceptors) merged.interceptors = override.interceptors;
+  if (override.aliases !== existing.aliases) merged.aliases = override.aliases;
+  // Recursively merge subcommands by name
+  if (override.commands) {
+    const baseCommands = [...(existing.commands || [])];
+    for (const overrideChild of override.commands) {
+      const existingIndex = baseCommands.findIndex((c) => c.name === overrideChild.name);
+      if (existingIndex >= 0) {
+        baseCommands[existingIndex] = mergeCommands(baseCommands[existingIndex]!, overrideChild);
+      } else {
+        baseCommands.push(overrideChild);
+      }
+    }
+    merged.commands = baseCommands;
+  }
+
+  return merged;
+}
+
+/**
+ * Resolves the runtime for a command by walking up the parent chain.
+ * Returns a fully resolved runtime with all defaults filled in.
+ */
+export function getCommandRuntime(cmd: AnyPadroneCommand): ResolvedPadroneRuntime {
+  let current: AnyPadroneCommand | undefined = cmd;
+  while (current) {
+    if (current.runtime) return resolveRuntime(current.runtime);
+    current = current.parent;
+  }
+  return resolveRuntime();
+}
+
+/**
+ * Recursively re-paths a command tree under a new parent path, updating parent references.
+ */
+export function repathCommandTree(
+  cmd: AnyPadroneCommand,
+  newName: string,
+  parentPath: string,
+  parent: AnyPadroneCommand,
+): AnyPadroneCommand {
+  resolveCommand(cmd);
+  const newPath = parentPath ? `${parentPath} ${newName}` : newName;
+  const remounted: AnyPadroneCommand = {
+    ...cmd,
+    name: newName,
+    path: newPath,
+    parent,
+    version: undefined,
+  };
+
+  if (cmd.commands?.length) {
+    remounted.commands = cmd.commands.map((child) => repathCommandTree(child, child.name, newPath, remounted));
+  }
+
+  return remounted;
+}
+
+/**
+ * Builds a completer function for the REPL from the command tree.
+ * Completes command names, subcommand names, option names (--foo), and aliases (-f).
+ * Also includes dot-prefixed built-in REPL commands (.exit, .clear, .scope, .help, .history).
+ */
+export function buildReplCompleter(
+  rootCommand: AnyPadroneCommand,
+  builtins: {
+    inScope?: boolean;
+  },
+): (line: string) => [string[], string] {
+  resolveAllCommands(rootCommand);
+  return (line: string): [string[], string] => {
+    const trimmed = line.trimStart();
+    const parts = trimmed.split(/\s+/);
+    const lastPart = parts[parts.length - 1] ?? '';
+
+    // If we're completing a dot-command
+    if (lastPart.startsWith('.')) {
+      const dotCmds = ['.exit', '.clear', '.help', '.history'];
+      if (rootCommand.commands?.some((c) => c.commands?.length) || builtins.inScope) dotCmds.push('.scope');
+      const hits = dotCmds.filter((c) => c.startsWith(lastPart));
+      return [hits.length ? hits : dotCmds, lastPart];
+    }
+
+    // If we're completing an option (starts with -)
+    if (lastPart.startsWith('-')) {
+      // Find which command we're in
+      const commandParts = parts.slice(0, -1).filter((p) => !p.startsWith('-'));
+      let targetCommand = rootCommand;
+      for (const part of commandParts) {
+        resolveCommand(targetCommand);
+        const sub = targetCommand.commands?.find((c) => c.name === part || c.aliases?.includes(part));
+        if (sub) {
+          resolveCommand(sub);
+          targetCommand = sub;
+        } else break;
+      }
+
+      // Get options for this command
+      const options: string[] = [];
+      if (targetCommand.argsSchema) {
+        try {
+          const argsMeta = targetCommand.meta?.fields;
+          const { flags, aliases } = extractSchemaMetadata(targetCommand.argsSchema, argsMeta, targetCommand.meta?.autoAlias);
+          const jsonSchema = getJsonSchema(targetCommand.argsSchema) as Record<string, any>;
+          if (jsonSchema.type === 'object' && jsonSchema.properties) {
+            for (const key of Object.keys(jsonSchema.properties)) {
+              options.push(`--${key}`);
+            }
+            for (const flag of Object.keys(flags)) {
+              options.push(`-${flag}`);
+            }
+            for (const alias of Object.keys(aliases)) {
+              options.push(`--${alias}`);
+            }
+          }
+        } catch {
+          // Ignore schema parsing errors
+        }
+      }
+      // Add global flags
+      options.push('--help', '-h');
+
+      const hits = options.filter((o) => o.startsWith(lastPart));
+      return [hits.length ? hits : options, lastPart];
+    }
+
+    // Completing command names
+    const commandParts = parts.filter((p) => !p.startsWith('-'));
+    // Walk into subcommands for all but the last token
+    let targetCommand = rootCommand;
+    for (let i = 0; i < commandParts.length - 1; i++) {
+      resolveCommand(targetCommand);
+      const sub = targetCommand.commands?.find((c) => c.name === commandParts[i] || c.aliases?.includes(commandParts[i]!));
+      if (sub) {
+        resolveCommand(sub);
+        targetCommand = sub;
+      } else break;
+    }
+
+    const candidates: string[] = [];
+
+    // Add subcommand names and aliases
+    if (targetCommand.commands) {
+      for (const cmd of targetCommand.commands) {
+        if (!cmd.hidden) {
+          candidates.push(cmd.name);
+          if (cmd.aliases) candidates.push(...cmd.aliases);
+        }
+      }
+    }
+
+    // Add dot-commands and `..` shorthand at the root level (relative to current scope)
+    if (targetCommand === rootCommand) {
+      candidates.push('.help', '.exit', '.clear', '.history');
+      if (rootCommand.commands?.some((c) => c.commands?.length) || builtins.inScope) candidates.push('.scope');
+      if (builtins.inScope) candidates.push('..');
+    }
+
+    const hits = candidates.filter((c) => c.startsWith(lastPart));
+    return [hits.length ? hits : candidates, lastPart];
+  };
+}
+
+/**
+ * Computes the Levenshtein edit distance between two strings.
+ */
+function levenshtein(a: string, b: string): number {
+  const m = a.length;
+  const n = b.length;
+  const dp: number[] = Array.from({ length: n + 1 }, (_, i) => i);
+
+  for (let i = 1; i <= m; i++) {
+    let prev = dp[0]!;
+    dp[0] = i;
+    for (let j = 1; j <= n; j++) {
+      const temp = dp[j]!;
+      dp[j] = a[i - 1] === b[j - 1] ? prev : 1 + Math.min(prev, dp[j]!, dp[j - 1]!);
+      prev = temp;
+    }
+  }
+
+  return dp[n]!;
+}
+
+/**
+ * Finds close matches from a list of candidates using Levenshtein distance
+ * and prefix/substring matching (for inputs longer than 3 characters).
+ * Returns up to 3 matching candidate names (raw, unformatted).
+ */
+export function suggestSimilar(input: string, candidates: string[]): string[] {
+  if (candidates.length === 0) return [];
+
+  const lower = input.toLowerCase();
+  const matches: { candidate: string; score: number }[] = [];
+
+  for (const candidate of candidates) {
+    const candidateLower = candidate.toLowerCase();
+    if (candidateLower === lower) continue;
+
+    const dist = levenshtein(lower, candidateLower);
+    const maxLen = Math.max(input.length, candidate.length);
+    const threshold = Math.min(3, Math.max(1, Math.ceil(maxLen * 0.4)));
+
+    if (dist > 0 && dist <= threshold) {
+      matches.push({ candidate, score: dist });
+    } else if (lower.length >= 3) {
+      // Prefix or substring match for longer inputs
+      if (candidateLower.startsWith(lower) || candidateLower.includes(lower)) {
+        matches.push({ candidate, score: threshold + 1 });
+      }
+    }
+  }
+
+  matches.sort((a, b) => a.score - b.score);
+  return matches.slice(0, 3).map((m) => m.candidate);
+}
+
+export function findCommandByName(name: string, commands?: AnyPadroneCommand[]): AnyPadroneCommand | undefined {
+  if (!commands) return undefined;
+
+  const foundByName = commands.find((cmd) => cmd.name === name);
+  if (foundByName) return resolveCommand(foundByName);
+
+  // Check for aliases
+  const foundByAlias = commands.find((cmd) => cmd.aliases?.includes(name));
+  if (foundByAlias) return resolveCommand(foundByAlias);
+
+  for (const cmd of commands) {
+    if (name.startsWith(`${cmd.name} `)) {
+      resolveCommand(cmd);
+      if (cmd.commands) {
+        const subCommandName = name.slice(cmd.name.length + 1);
+        const subCommand = findCommandByName(subCommandName, cmd.commands);
+        if (subCommand) return subCommand;
+      }
+    }
+    // Check aliases for nested commands
+    if (cmd.aliases) {
+      for (const alias of cmd.aliases) {
+        if (name.startsWith(`${alias} `)) {
+          resolveCommand(cmd);
+          if (cmd.commands) {
+            const subCommandName = name.slice(alias.length + 1);
+            const subCommand = findCommandByName(subCommandName, cmd.commands);
+            if (subCommand) return subCommand;
+          }
+        }
+      }
+    }
+  }
+  return undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Shared utilities for MCP and serve
+// ---------------------------------------------------------------------------
+
+export type CollectedEndpoint = { name: string; command: AnyPadroneCommand };
+
+/** Collect all actionable commands recursively. Hidden commands are excluded. */
+export function collectEndpoints(commands: AnyPadroneCommand[] | undefined, prefix: string): CollectedEndpoint[] {
+  if (!commands) return [];
+  const endpoints: CollectedEndpoint[] = [];
+  for (const cmd of commands) {
+    resolveCommand(cmd);
+    if (cmd.hidden) continue;
+    const path = cmd.name ? (prefix ? `${prefix}.${cmd.name}` : cmd.name) : prefix;
+    if (cmd.action || cmd.argsSchema) {
+      endpoints.push({ name: path, command: cmd });
+    }
+    if (cmd.commands?.length) {
+      endpoints.push(...collectEndpoints(cmd.commands, path));
+    }
+  }
+  return endpoints;
+}
+
+/** Build the JSON Schema for a command's arguments. */
+export function buildInputSchema(cmd: AnyPadroneCommand): Record<string, unknown> {
+  if (!cmd.argsSchema) {
+    return { type: 'object', additionalProperties: false };
+  }
+  try {
+    return getJsonSchema(cmd.argsSchema) as Record<string, unknown>;
+  } catch {
+    return { type: 'object', additionalProperties: false };
+  }
+}
+
+/** Serialize a record of args into CLI flag strings. */
+export function serializeArgsToFlags(args: Record<string, unknown>): string[] {
+  const parts: string[] = [];
+  for (const [key, value] of Object.entries(args)) {
+    if (value === undefined) continue;
+    if (typeof value === 'boolean') {
+      parts.push(value ? `--${key}` : `--no-${key}`);
+    } else if (Array.isArray(value)) {
+      for (const v of value) parts.push(`--${key}=${String(v)}`);
+    } else {
+      const strVal = String(value);
+      parts.push(strVal.includes(' ') ? `--${key}="${strVal}"` : `--${key}=${strVal}`);
+    }
+  }
+  return parts;
+}

package/src/core/create.ts

@@ -0,0 +1,268 @@
+import { padroneAutoOutput } from '../extension/auto-output.ts';
+import { padroneColor } from '../extension/color.ts';
+import type { HelpCommand } from '../extension/help.ts';
+import { padroneHelp } from '../extension/help.ts';
+import { padroneInteractive } from '../extension/interactive.ts';
+import { padroneRepl } from '../extension/repl.ts';
+import { padroneSignalHandling } from '../extension/signal.ts';
+import { padroneStdin } from '../extension/stdin.ts';
+import { padroneSuggestions } from '../extension/suggestions.ts';
+import type { VersionCommand } from '../extension/version.ts';
+import { padroneVersion } from '../extension/version.ts';
+import { createWrapHandler } from '../feature/wrap.ts';
+import type {
+  AnyPadroneCommand,
+  AnyPadroneProgram,
+  InterceptorFactory,
+  InterceptorMeta,
+  PadroneCommand,
+  PadroneInterceptorFn,
+  PadroneProgram,
+  PadroneSchema,
+  RegisteredInterceptor,
+} from '../types/index.ts';
+import { commandSymbol, findCommandByName, lazyResolver, mergeCommands, repathCommandTree, resolveCommand } from './commands.ts';
+import { RoutingError } from './errors.ts';
+import type { ExecContext } from './exec.ts';
+import { collectInterceptors, errorResultWithSignal, execCommand } from './exec.ts';
+import { toRegisteredInterceptor } from './interceptors.ts';
+import { createProgramMethods } from './program-methods.ts';
+import { hasInteractiveConfig, isAsyncBranded, makeThenable, noop, withPromiseDrain } from './results.ts';
+import { parseCommand } from './validate.ts';
+
+export { buildReplCompleter } from './commands.ts';
+export { asyncSchema } from './results.ts';
+
+/**
+ * Options for configuring which built-in extensions are applied by default.
+ */
+export type PadroneBuiltins = {
+  /** Enable `help` command, `--help` / `-h` flags, and default help display. Defaults to `true`. */
+  help?: boolean;
+  /** Enable `version` command and `--version` / `-v` / `-V` flags. Defaults to `true`. */
+  version?: boolean;
+  /** Enable `repl` command and `--repl` flag. Defaults to `true`. */
+  repl?: boolean;
+  /** Enable `--color` / `--no-color` flag support. Defaults to `true`. */
+  color?: boolean;
+  /** Enable "Did you mean?" suggestions for unknown commands and options. Defaults to `true`. */
+  suggestions?: boolean;
+  /** Enable signal handling (SIGINT, SIGTERM, SIGHUP). Defaults to `true`. */
+  signal?: boolean;
+  /** Enable automatic result output for `cli()`. Defaults to `true`. */
+  autoOutput?: boolean;
+  /** Enable stdin piping support. Defaults to `true`. */
+  stdin?: boolean;
+  /** Enable interactive prompting for missing arguments. Defaults to `true`. */
+  interactive?: boolean;
+};
+
+export type PadroneOptions = { builtins?: PadroneBuiltins };
+
+// biome-ignore lint/complexity/noBannedTypes: empty object signals "all defaults enabled"
+type DefaultBuiltins = {};
+
+type BuiltinCommands<B> = [...(B extends { help: false } ? [] : [HelpCommand]), ...(B extends { version: false } ? [] : [VersionCommand])];
+
+export function createPadrone<TProgramName extends string, const TBuiltins extends PadroneBuiltins = DefaultBuiltins>(
+  name: TProgramName,
+  options?: { builtins?: TBuiltins },
+): PadroneProgram<TProgramName, '', '', PadroneSchema<void>, void, BuiltinCommands<TBuiltins>> {
+  let builder: any = createPadroneBuilder({ name, path: '', commands: [] } as any);
+
+  const b = options?.builtins;
+  if (b?.help !== false) builder = builder.extend(padroneHelp());
+  if (b?.version !== false) builder = builder.extend(padroneVersion());
+  if (b?.repl !== false) builder = builder.extend(padroneRepl());
+  if (b?.color !== false) builder = builder.extend(padroneColor());
+  if (b?.suggestions !== false) builder = builder.extend(padroneSuggestions());
+  if (b?.signal !== false) builder = builder.extend(padroneSignalHandling());
+  if (b?.autoOutput !== false) builder = builder.extend(padroneAutoOutput());
+  if (b?.stdin !== false) builder = builder.extend(padroneStdin());
+  if (b?.interactive !== false) builder = builder.extend(padroneInteractive());
+
+  return builder as any;
+}
+
+export function createPadroneBuilder<TBuilder extends PadroneProgram = PadroneProgram>(
+  inputCommand: AnyPadroneCommand,
+): TBuilder & { [commandSymbol]: AnyPadroneCommand } {
+  // Re-parent direct subcommands so getCommandRuntime walks to the current root,
+  // not a stale parent from before .runtime()/.configure()/etc.
+  const existingCommand =
+    inputCommand.commands?.length && inputCommand.commands.some((c) => c.parent && c.parent !== inputCommand)
+      ? {
+          ...inputCommand,
+          commands: inputCommand.commands.map((c) => (c.parent && c.parent !== inputCommand ? { ...c, parent: inputCommand } : c)),
+        }
+      : inputCommand;
+
+  const parseCommandFn = (input: string | undefined) => parseCommand(input, existingCommand, findCommandByName);
+  const collectInterceptorsFn = (cmd: AnyPadroneCommand) => collectInterceptors(cmd, existingCommand);
+
+  // Execution context shared by exec and program methods.
+  // `builder` is assigned after the builder object is created (forward ref resolved at runtime only).
+  const execCtx: ExecContext = {
+    rootCommand: existingCommand,
+    builder: undefined as any,
+    parseCommandFn,
+    collectInterceptorsFn,
+  };
+
+  const evalCommand: AnyPadroneProgram['eval'] = (input, evalOptions) => {
+    try {
+      const result = execCommand(input as string, execCtx, evalOptions, 'soft', evalOptions?.caller ?? 'eval');
+      if (result instanceof Promise) return withPromiseDrain(result.catch((err: unknown) => errorResultWithSignal(err))) as any;
+      return makeThenable(result);
+    } catch (err) {
+      return makeThenable(errorResultWithSignal(err)) as any;
+    }
+  };
+
+  const programMethods = createProgramMethods(execCtx, evalCommand);
+
+  const builder = {
+    extend(extension: (builder: any) => any) {
+      return extension(builder);
+    },
+    configure(config) {
+      return createPadroneBuilder({ ...existingCommand, ...config }) as any;
+    },
+    runtime(runtimeConfig) {
+      return createPadroneBuilder({ ...existingCommand, runtime: { ...existingCommand.runtime, ...runtimeConfig } }) as any;
+    },
+    async() {
+      return createPadroneBuilder({ ...existingCommand, isAsync: true }) as any;
+    },
+    context(transform?: (ctx: unknown) => unknown) {
+      if (!transform) return createPadroneBuilder({ ...existingCommand }) as any;
+      const existing = existingCommand.contextTransform;
+      const composed = existing ? (ctx: unknown) => transform(existing(ctx)) : transform;
+      return createPadroneBuilder({ ...existingCommand, contextTransform: composed }) as any;
+    },
+    arguments(schema, meta) {
+      const resolvedArgs = typeof schema === 'function' ? schema(existingCommand.argsSchema as any) : schema;
+      const isAsync = existingCommand.isAsync || isAsyncBranded(resolvedArgs) || hasInteractiveConfig(meta);
+      return createPadroneBuilder({ ...existingCommand, argsSchema: resolvedArgs, meta, isAsync }) as any;
+    },
+    action(handler = noop) {
+      const baseHandler = existingCommand.action ?? noop;
+      return createPadroneBuilder({
+        ...existingCommand,
+        action: (args: any, ctx: any) => (handler as any)(args, ctx, baseHandler),
+      }) as any;
+    },
+    wrap(config) {
+      const handler = createWrapHandler(config, existingCommand.argsSchema as any, existingCommand.meta?.positional);
+      return createPadroneBuilder({ ...existingCommand, action: handler }) as any;
+    },
+    command(nameOrNames, builderFn) {
+      const name = Array.isArray(nameOrNames) ? nameOrNames[0] : nameOrNames;
+      const aliases = Array.isArray(nameOrNames) && nameOrNames.length > 1 ? (nameOrNames.slice(1) as string[]) : undefined;
+
+      const existingSubcommand = existingCommand.commands?.find((c) => c.name === name) as AnyPadroneCommand | undefined;
+      if (existingSubcommand) resolveCommand(existingSubcommand);
+
+      const initialCommand: AnyPadroneCommand = existingSubcommand
+        ? { ...existingSubcommand, aliases: aliases ?? existingSubcommand.aliases, parent: existingCommand }
+        : ({
+            name,
+            path: existingCommand.path ? `${existingCommand.path} ${name}` : name,
+            aliases,
+            parent: existingCommand,
+            '~types': {} as any,
+          } satisfies PadroneCommand);
+
+      if (builderFn) {
+        const lazyCmd: AnyPadroneCommand = { ...initialCommand };
+        (lazyCmd as any)[lazyResolver] = (target: AnyPadroneCommand) => {
+          const savedParent = target.parent;
+          const b = createPadroneBuilder(target);
+          const commandObj = ((builderFn(b as any) as unknown as typeof b)?.[commandSymbol] as AnyPadroneCommand) ?? target;
+          const mergedCommandObj = existingSubcommand ? mergeCommands(existingSubcommand, commandObj) : commandObj;
+          Object.assign(target, mergedCommandObj);
+          // Restore parent: mergeCommands copies the existing command's parent which may be stale
+          // (e.g. when an extension is applied twice, the merged parent predates re-parenting).
+          target.parent = savedParent;
+        };
+
+        const commands = existingCommand.commands || [];
+        const existingIndex = commands.findIndex((c) => c.name === name);
+        const updatedCommands =
+          existingIndex >= 0
+            ? [...commands.slice(0, existingIndex), lazyCmd, ...commands.slice(existingIndex + 1)]
+            : [...commands, lazyCmd];
+
+        return createPadroneBuilder({ ...existingCommand, commands: updatedCommands }) as any;
+      }
+
+      const commands = existingCommand.commands || [];
+      const existingIndex = commands.findIndex((c) => c.name === name);
+      const updatedCommands =
+        existingIndex >= 0
+          ? [...commands.slice(0, existingIndex), initialCommand, ...commands.slice(existingIndex + 1)]
+          : [...commands, initialCommand];
+
+      return createPadroneBuilder({ ...existingCommand, commands: updatedCommands }) as any;
+    },
+
+    mount(nameOrNames: string | readonly string[], program: unknown, options?: { context?: (ctx: unknown) => unknown }) {
+      const name = Array.isArray(nameOrNames) ? nameOrNames[0] : nameOrNames;
+      const aliases = Array.isArray(nameOrNames) && nameOrNames.length > 1 ? (nameOrNames.slice(1) as string[]) : undefined;
+
+      const programCommand = (program as any)[commandSymbol] as AnyPadroneCommand | undefined;
+      if (!programCommand) throw new RoutingError('Cannot mount: not a valid Padrone program');
+
+      const remounted = repathCommandTree(programCommand, name, existingCommand.path || '', existingCommand);
+      remounted.aliases = aliases;
+
+      if (options?.context) {
+        const existing = remounted.contextTransform;
+        remounted.contextTransform = existing ? (ctx: unknown) => existing(options.context!(ctx)) : options.context;
+      }
+
+      const existingSubcommand = existingCommand.commands?.find((c) => c.name === name) as AnyPadroneCommand | undefined;
+      const mergedCommandObj = existingSubcommand ? mergeCommands(existingSubcommand, remounted) : remounted;
+
+      const commands = existingCommand.commands || [];
+      const existingIndex = commands.findIndex((c) => c.name === name);
+      const updatedCommands =
+        existingIndex >= 0
+          ? [...commands.slice(0, existingIndex), mergedCommandObj, ...commands.slice(existingIndex + 1)]
+          : [...commands, mergedCommandObj];
+
+      return createPadroneBuilder({ ...existingCommand, commands: updatedCommands }) as any;
+    },
+
+    intercept(metaOrFn: InterceptorMeta | PadroneInterceptorFn<any, any, any>, factory?: InterceptorFactory<any, any, any>) {
+      const registered: RegisteredInterceptor = toRegisteredInterceptor(metaOrFn, factory);
+      return createPadroneBuilder({
+        ...existingCommand,
+        interceptors: [...(existingCommand.interceptors ?? []), registered],
+      }) as any;
+    },
+
+    ...programMethods,
+
+    get info() {
+      return {
+        name: existingCommand.name,
+        title: existingCommand.title,
+        description: existingCommand.description,
+        version: existingCommand.version,
+        examples: existingCommand.examples,
+        deprecated: existingCommand.deprecated,
+        commands: (existingCommand.commands ?? []).map((c) => c.name),
+      };
+    },
+
+    '~types': {} as any,
+
+    [commandSymbol]: existingCommand,
+  } satisfies AnyPadroneProgram & { [commandSymbol]: AnyPadroneCommand } as any;
+
+  // Fix forward reference: execCtx.builder needs to reference the builder after it's created
+  execCtx.builder = builder;
+
+  return builder as TBuilder & { [commandSymbol]: AnyPadroneCommand };
+}