padrone 1.9.0 → 2.0.0

package/dist/core/create.d.mts

@@ -0,0 +1,63 @@
+import { PadroneSchema } from "../types/schema.mjs";
+import { CommandTypesBase } from "../types/command.mjs";
+import { DefineCommandBuilder, DefineCommandContext, PadroneBuilder, PadroneProgram } from "../types/builder.mjs";
+import { buildReplCompleter } from "./commands.mjs";
+import { HelpCommand } from "../extension/help.mjs";
+import { VersionCommand } from "../extension/version.mjs";
+import { asyncSchema } from "./results.mjs";
+
+//#region src/core/create.d.ts
+/**
+ * Options for configuring which built-in extensions are applied by default.
+ */
+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;
+};
+type PadroneOptions = {
+  builtins?: PadroneBuiltins;
+};
+type DefaultBuiltins = {};
+type BuiltinCommands<B> = [...(B extends {
+  help: false;
+} ? [] : [HelpCommand]), ...(B extends {
+  version: false;
+} ? [] : [VersionCommand])];
+declare function createPadrone<TProgramName extends string, const TBuiltins extends PadroneBuiltins = DefaultBuiltins>(name: TProgramName, options?: {
+  builtins?: TBuiltins;
+}): PadroneProgram<TProgramName, '', '', PadroneSchema<void>, void, BuiltinCommands<TBuiltins>>;
+/**
+ * Identity helper that contextually types a command builder callback while preserving its full return type.
+ * Use this when defining commands in separate files — the parent program retains exact type information
+ * about the subcommand's args, result, and nested commands.
+ *
+ * The builder's context includes `DefineCommandContext` by default (optional `logger`, `tracing`, `progress`).
+ * Override globally via module augmentation on `DefineCommandContext`, or per-command via `.requires()`.
+ *
+ * @example Direct form (most common)
+ * ```ts
+ * export const myCommand = defineCommand((c) =>
+ *   c.arguments(z.object({ name: z.string() }))
+ *    .action((args) => console.log(args.name))
+ * );
+ * ```
+ *
+ * @example With required interceptor context
+ * ```ts
+ * export const adminCommand = defineCommand()
+ *   .requires<{ adminDb: AdminDB }>()
+ *   .define((c) => c.action((_args, ctx) => ctx.context.adminDb.query(...)));
+ * ```
+ */
+declare function defineCommand<TContext = unknown, TOut extends CommandTypesBase = CommandTypesBase>(fn: (builder: PadroneBuilder<string, string, string, PadroneSchema<void>, void, [], any, false, TContext, DefineCommandContext>) => TOut): typeof fn;
+declare function defineCommand(): DefineCommandBuilder;
+//#endregion
+export { PadroneBuiltins, PadroneOptions, createPadrone, defineCommand };
+//# sourceMappingURL=create.d.mts.map

package/dist/core/create.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create.d.mts","names":[],"sources":["../../src/core/create.ts"],"mappings":";;;;;;;;;;;;KA0CY,eAAA;EAAA,kGAEV,IAAA;EAEA,OAAA,YAFA;EAIA,IAAA;EAEA,KAAA,YAEA;EAAA,WAAA,YAIA;EAFA,MAAA,YAMA;EAJA,UAAA,YAIW;EAFX,KAAA,YAKwB;EAHxB,WAAA;AAAA;AAAA,KAGU,cAAA;EAAmB,QAAA,GAAW,eAAe;AAAA;AAAA,KAGpD,eAAA;AAAA,KAEA,eAAA,WAA0B,CAAA;EAAY,IAAA;AAAA,UAAsB,WAAA,QAAmB,CAAA;EAAY,OAAA;AAAA,UAAyB,cAAA;AAAA,iBAEzG,aAAA,sDAAmE,eAAA,GAAkB,eAAA,EACnG,IAAA,EAAM,YAAA,EACN,OAAA;EAAY,QAAA,GAAW,SAAA;AAAA,IACtB,cAAA,CAAe,YAAA,UAAsB,aAAA,cAA2B,eAAA,CAAgB,SAAA;;;;;;;;;AALoD;AAEvI;;;;;;;;;;;;;;iBAkOgB,aAAA,kCAA+C,gBAAA,GAAmB,gBAAA,EAChF,EAAA,GAAK,OAAA,EAAS,cAAA,yBAAuC,aAAA,8BAA2C,QAAA,EAAU,oBAAA,MAA0B,IAAA,UAC5H,EAAA;AAAA,iBACM,aAAA,IAAiB,oBAAoB"}

package/dist/core/create.mjs

@@ -0,0 +1,230 @@
+import { commandSymbol, findCommandByName, lazyResolver, mergeCommands, repathCommandTree, resolveCommand } from "./commands.mjs";
+import { hasInteractiveConfig, isAsyncBranded, makeThenable, noop, withPromiseDrain } from "./results.mjs";
+import { toRegisteredInterceptor } from "./interceptors.mjs";
+import { padroneAutoOutput } from "../extension/auto-output.mjs";
+import { padroneColor } from "../extension/color.mjs";
+import { RoutingError } from "./errors.mjs";
+import { parseCommand } from "./validate.mjs";
+import { padroneHelp } from "../extension/help.mjs";
+import { padroneInteractive } from "../extension/interactive.mjs";
+import { padroneRepl } from "../extension/repl.mjs";
+import { padroneSignalHandling } from "../extension/signal.mjs";
+import { padroneStdin } from "../extension/stdin.mjs";
+import { padroneSuggestions } from "../extension/suggestions.mjs";
+import { padroneVersion } from "../extension/version.mjs";
+import { createWrapHandler } from "../feature/wrap.mjs";
+import { collectInterceptors, errorResultWithSignal, execCommand } from "./exec.mjs";
+import { createProgramMethods } from "./program-methods.mjs";
+//#region src/core/create.ts
+function createPadrone(name, options) {
+	let builder = createPadroneBuilder({
+		name,
+		path: "",
+		commands: []
+	});
+	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;
+}
+function createPadroneBuilder(inputCommand) {
+	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) => parseCommand(input, existingCommand, findCommandByName);
+	const collectInterceptorsFn = (cmd) => collectInterceptors(cmd, existingCommand);
+	const execCtx = {
+		rootCommand: existingCommand,
+		builder: void 0,
+		parseCommandFn,
+		collectInterceptorsFn
+	};
+	const evalCommand = (input, evalOptions) => {
+		try {
+			const result = execCommand(input, execCtx, evalOptions, "soft", evalOptions?.caller ?? "eval");
+			if (result instanceof Promise) return withPromiseDrain(result.catch((err) => errorResultWithSignal(err)));
+			return makeThenable(result);
+		} catch (err) {
+			return makeThenable(errorResultWithSignal(err));
+		}
+	};
+	const builder = {
+		extend(extension) {
+			return extension(builder);
+		},
+		configure(config) {
+			return createPadroneBuilder({
+				...existingCommand,
+				...config
+			});
+		},
+		runtime(runtimeConfig) {
+			return createPadroneBuilder({
+				...existingCommand,
+				runtime: {
+					...existingCommand.runtime,
+					...runtimeConfig
+				}
+			});
+		},
+		async() {
+			return createPadroneBuilder({
+				...existingCommand,
+				isAsync: true
+			});
+		},
+		context(transform) {
+			if (!transform) return createPadroneBuilder({ ...existingCommand });
+			const existing = existingCommand.contextTransform;
+			const composed = existing ? (ctx) => transform(existing(ctx)) : transform;
+			return createPadroneBuilder({
+				...existingCommand,
+				contextTransform: composed
+			});
+		},
+		arguments(schema, meta) {
+			const resolvedArgs = typeof schema === "function" ? schema(existingCommand.argsSchema) : schema;
+			const isAsync = existingCommand.isAsync || isAsyncBranded(resolvedArgs) || hasInteractiveConfig(meta);
+			return createPadroneBuilder({
+				...existingCommand,
+				argsSchema: resolvedArgs,
+				meta,
+				isAsync
+			});
+		},
+		action(handler = noop) {
+			const baseHandler = existingCommand.action ?? noop;
+			return createPadroneBuilder({
+				...existingCommand,
+				action: (args, ctx) => handler(args, ctx, baseHandler)
+			});
+		},
+		wrap(config) {
+			const handler = createWrapHandler(config, existingCommand.argsSchema, existingCommand.meta?.positional);
+			return createPadroneBuilder({
+				...existingCommand,
+				action: handler
+			});
+		},
+		command(nameOrNames, builderFn) {
+			const name = Array.isArray(nameOrNames) ? nameOrNames[0] : nameOrNames;
+			const aliases = Array.isArray(nameOrNames) && nameOrNames.length > 1 ? nameOrNames.slice(1) : void 0;
+			const existingSubcommand = existingCommand.commands?.find((c) => c.name === name);
+			if (existingSubcommand) resolveCommand(existingSubcommand);
+			const initialCommand = existingSubcommand ? {
+				...existingSubcommand,
+				aliases: aliases ?? existingSubcommand.aliases,
+				parent: existingCommand
+			} : {
+				name,
+				path: existingCommand.path ? `${existingCommand.path} ${name}` : name,
+				aliases,
+				parent: existingCommand,
+				"~types": {}
+			};
+			if (builderFn) {
+				const lazyCmd = { ...initialCommand };
+				lazyCmd[lazyResolver] = (target) => {
+					const savedParent = target.parent;
+					const commandObj = builderFn(createPadroneBuilder(target))?.[commandSymbol] ?? target;
+					const mergedCommandObj = existingSubcommand ? mergeCommands(existingSubcommand, commandObj) : commandObj;
+					Object.assign(target, mergedCommandObj);
+					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
+				});
+			}
+			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
+			});
+		},
+		mount(nameOrNames, program, options) {
+			const name = Array.isArray(nameOrNames) ? nameOrNames[0] : nameOrNames;
+			const aliases = Array.isArray(nameOrNames) && nameOrNames.length > 1 ? nameOrNames.slice(1) : void 0;
+			const programCommand = program[commandSymbol];
+			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) => existing(options.context(ctx)) : options.context;
+			}
+			const existingSubcommand = existingCommand.commands?.find((c) => c.name === name);
+			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
+			});
+		},
+		intercept(metaOrFn, factory) {
+			const registered = toRegisteredInterceptor(metaOrFn, factory);
+			return createPadroneBuilder({
+				...existingCommand,
+				interceptors: [...existingCommand.interceptors ?? [], registered]
+			});
+		},
+		...createProgramMethods(execCtx, evalCommand),
+		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": {},
+		[commandSymbol]: existingCommand
+	};
+	execCtx.builder = builder;
+	return builder;
+}
+function defineCommand(fn) {
+	if (fn) return fn;
+	const builder = {
+		requires: () => builder,
+		define: (f) => f
+	};
+	return builder;
+}
+//#endregion
+export { createPadrone, createPadroneBuilder, defineCommand };
+
+//# sourceMappingURL=create.mjs.map

package/dist/core/create.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"create.mjs","names":[],"sources":["../../src/core/create.ts"],"sourcesContent":["import { padroneAutoOutput } from '../extension/auto-output.ts';\nimport { padroneColor } from '../extension/color.ts';\nimport type { HelpCommand } from '../extension/help.ts';\nimport { padroneHelp } from '../extension/help.ts';\nimport { padroneInteractive } from '../extension/interactive.ts';\nimport { padroneRepl } from '../extension/repl.ts';\nimport { padroneSignalHandling } from '../extension/signal.ts';\nimport { padroneStdin } from '../extension/stdin.ts';\nimport { padroneSuggestions } from '../extension/suggestions.ts';\nimport type { VersionCommand } from '../extension/version.ts';\nimport { padroneVersion } from '../extension/version.ts';\nimport { createWrapHandler } from '../feature/wrap.ts';\nimport type {\n  AnyPadroneCommand,\n  AnyPadroneProgram,\n  CommandTypesBase,\n  DefineCommandBuilder,\n  DefineCommandContext,\n  InterceptorFactory,\n  InterceptorMeta,\n  PadroneBuilder,\n  PadroneCommand,\n  PadroneInterceptorFn,\n  PadroneProgram,\n  PadroneSchema,\n  RegisteredInterceptor,\n} from '../types/index.ts';\nimport { commandSymbol, findCommandByName, lazyResolver, mergeCommands, repathCommandTree, resolveCommand } from './commands.ts';\nimport { RoutingError } from './errors.ts';\nimport type { ExecContext } from './exec.ts';\nimport { collectInterceptors, errorResultWithSignal, execCommand } from './exec.ts';\nimport { toRegisteredInterceptor } from './interceptors.ts';\nimport { createProgramMethods } from './program-methods.ts';\nimport { hasInteractiveConfig, isAsyncBranded, makeThenable, noop, withPromiseDrain } from './results.ts';\nimport { parseCommand } from './validate.ts';\n\nexport { buildReplCompleter } from './commands.ts';\nexport { asyncSchema } from './results.ts';\n\n/**\n * Options for configuring which built-in extensions are applied by default.\n */\nexport type PadroneBuiltins = {\n  /** Enable `help` command, `--help` / `-h` flags, and default help display. Defaults to `true`. */\n  help?: boolean;\n  /** Enable `version` command and `--version` / `-v` / `-V` flags. Defaults to `true`. */\n  version?: boolean;\n  /** Enable `repl` command and `--repl` flag. Defaults to `true`. */\n  repl?: boolean;\n  /** Enable `--color` / `--no-color` flag support. Defaults to `true`. */\n  color?: boolean;\n  /** Enable \"Did you mean?\" suggestions for unknown commands and options. Defaults to `true`. */\n  suggestions?: boolean;\n  /** Enable signal handling (SIGINT, SIGTERM, SIGHUP). Defaults to `true`. */\n  signal?: boolean;\n  /** Enable automatic result output for `cli()`. Defaults to `true`. */\n  autoOutput?: boolean;\n  /** Enable stdin piping support. Defaults to `true`. */\n  stdin?: boolean;\n  /** Enable interactive prompting for missing arguments. Defaults to `true`. */\n  interactive?: boolean;\n};\n\nexport type PadroneOptions = { builtins?: PadroneBuiltins };\n\n// biome-ignore lint/complexity/noBannedTypes: empty object signals \"all defaults enabled\"\ntype DefaultBuiltins = {};\n\ntype BuiltinCommands<B> = [...(B extends { help: false } ? [] : [HelpCommand]), ...(B extends { version: false } ? [] : [VersionCommand])];\n\nexport function createPadrone<TProgramName extends string, const TBuiltins extends PadroneBuiltins = DefaultBuiltins>(\n  name: TProgramName,\n  options?: { builtins?: TBuiltins },\n): PadroneProgram<TProgramName, '', '', PadroneSchema<void>, void, BuiltinCommands<TBuiltins>> {\n  let builder: any = createPadroneBuilder({ name, path: '', commands: [] } as any);\n\n  const b = options?.builtins;\n  if (b?.help !== false) builder = builder.extend(padroneHelp());\n  if (b?.version !== false) builder = builder.extend(padroneVersion());\n  if (b?.repl !== false) builder = builder.extend(padroneRepl());\n  if (b?.color !== false) builder = builder.extend(padroneColor());\n  if (b?.suggestions !== false) builder = builder.extend(padroneSuggestions());\n  if (b?.signal !== false) builder = builder.extend(padroneSignalHandling());\n  if (b?.autoOutput !== false) builder = builder.extend(padroneAutoOutput());\n  if (b?.stdin !== false) builder = builder.extend(padroneStdin());\n  if (b?.interactive !== false) builder = builder.extend(padroneInteractive());\n\n  return builder as any;\n}\n\nexport function createPadroneBuilder<TBuilder extends PadroneProgram = PadroneProgram>(\n  inputCommand: AnyPadroneCommand,\n): TBuilder & { [commandSymbol]: AnyPadroneCommand } {\n  // Re-parent direct subcommands so getCommandRuntime walks to the current root,\n  // not a stale parent from before .runtime()/.configure()/etc.\n  const existingCommand =\n    inputCommand.commands?.length && inputCommand.commands.some((c) => c.parent && c.parent !== inputCommand)\n      ? {\n          ...inputCommand,\n          commands: inputCommand.commands.map((c) => (c.parent && c.parent !== inputCommand ? { ...c, parent: inputCommand } : c)),\n        }\n      : inputCommand;\n\n  const parseCommandFn = (input: string | undefined) => parseCommand(input, existingCommand, findCommandByName);\n  const collectInterceptorsFn = (cmd: AnyPadroneCommand) => collectInterceptors(cmd, existingCommand);\n\n  // Execution context shared by exec and program methods.\n  // `builder` is assigned after the builder object is created (forward ref resolved at runtime only).\n  const execCtx: ExecContext = {\n    rootCommand: existingCommand,\n    builder: undefined as any,\n    parseCommandFn,\n    collectInterceptorsFn,\n  };\n\n  const evalCommand: AnyPadroneProgram['eval'] = (input, evalOptions) => {\n    try {\n      const result = execCommand(input as string, execCtx, evalOptions, 'soft', evalOptions?.caller ?? 'eval');\n      if (result instanceof Promise) return withPromiseDrain(result.catch((err: unknown) => errorResultWithSignal(err))) as any;\n      return makeThenable(result);\n    } catch (err) {\n      return makeThenable(errorResultWithSignal(err)) as any;\n    }\n  };\n\n  const programMethods = createProgramMethods(execCtx, evalCommand);\n\n  const builder = {\n    extend(extension: (builder: any) => any) {\n      return extension(builder);\n    },\n    configure(config) {\n      return createPadroneBuilder({ ...existingCommand, ...config }) as any;\n    },\n    runtime(runtimeConfig) {\n      return createPadroneBuilder({ ...existingCommand, runtime: { ...existingCommand.runtime, ...runtimeConfig } }) as any;\n    },\n    async() {\n      return createPadroneBuilder({ ...existingCommand, isAsync: true }) as any;\n    },\n    context(transform?: (ctx: unknown) => unknown) {\n      if (!transform) return createPadroneBuilder({ ...existingCommand }) as any;\n      const existing = existingCommand.contextTransform;\n      const composed = existing ? (ctx: unknown) => transform(existing(ctx)) : transform;\n      return createPadroneBuilder({ ...existingCommand, contextTransform: composed }) as any;\n    },\n    arguments(schema, meta) {\n      const resolvedArgs = typeof schema === 'function' ? schema(existingCommand.argsSchema as any) : schema;\n      const isAsync = existingCommand.isAsync || isAsyncBranded(resolvedArgs) || hasInteractiveConfig(meta);\n      return createPadroneBuilder({ ...existingCommand, argsSchema: resolvedArgs, meta, isAsync }) as any;\n    },\n    action(handler = noop) {\n      const baseHandler = existingCommand.action ?? noop;\n      return createPadroneBuilder({\n        ...existingCommand,\n        action: (args: any, ctx: any) => (handler as any)(args, ctx, baseHandler),\n      }) as any;\n    },\n    wrap(config) {\n      const handler = createWrapHandler(config, existingCommand.argsSchema as any, existingCommand.meta?.positional);\n      return createPadroneBuilder({ ...existingCommand, action: handler }) as any;\n    },\n    command(nameOrNames: string | readonly string[], builderFn?: (builder: any) => any) {\n      const name = Array.isArray(nameOrNames) ? nameOrNames[0] : nameOrNames;\n      const aliases = Array.isArray(nameOrNames) && nameOrNames.length > 1 ? (nameOrNames.slice(1) as string[]) : undefined;\n\n      const existingSubcommand = existingCommand.commands?.find((c) => c.name === name) as AnyPadroneCommand | undefined;\n      if (existingSubcommand) resolveCommand(existingSubcommand);\n\n      const initialCommand: AnyPadroneCommand = existingSubcommand\n        ? { ...existingSubcommand, aliases: aliases ?? existingSubcommand.aliases, parent: existingCommand }\n        : ({\n            name,\n            path: existingCommand.path ? `${existingCommand.path} ${name}` : name,\n            aliases,\n            parent: existingCommand,\n            '~types': {} as any,\n          } satisfies PadroneCommand);\n\n      if (builderFn) {\n        const lazyCmd: AnyPadroneCommand = { ...initialCommand };\n        (lazyCmd as any)[lazyResolver] = (target: AnyPadroneCommand) => {\n          const savedParent = target.parent;\n          const b = createPadroneBuilder(target);\n          const commandObj = ((builderFn(b as any) as unknown as typeof b)?.[commandSymbol] as AnyPadroneCommand) ?? target;\n          const mergedCommandObj = existingSubcommand ? mergeCommands(existingSubcommand, commandObj) : commandObj;\n          Object.assign(target, mergedCommandObj);\n          // Restore parent: mergeCommands copies the existing command's parent which may be stale\n          // (e.g. when an extension is applied twice, the merged parent predates re-parenting).\n          target.parent = savedParent;\n        };\n\n        const commands = existingCommand.commands || [];\n        const existingIndex = commands.findIndex((c) => c.name === name);\n        const updatedCommands =\n          existingIndex >= 0\n            ? [...commands.slice(0, existingIndex), lazyCmd, ...commands.slice(existingIndex + 1)]\n            : [...commands, lazyCmd];\n\n        return createPadroneBuilder({ ...existingCommand, commands: updatedCommands }) as any;\n      }\n\n      const commands = existingCommand.commands || [];\n      const existingIndex = commands.findIndex((c) => c.name === name);\n      const updatedCommands =\n        existingIndex >= 0\n          ? [...commands.slice(0, existingIndex), initialCommand, ...commands.slice(existingIndex + 1)]\n          : [...commands, initialCommand];\n\n      return createPadroneBuilder({ ...existingCommand, commands: updatedCommands }) as any;\n    },\n\n    mount(nameOrNames: string | readonly string[], program: unknown, options?: { context?: (ctx: unknown) => unknown }) {\n      const name = Array.isArray(nameOrNames) ? nameOrNames[0] : nameOrNames;\n      const aliases = Array.isArray(nameOrNames) && nameOrNames.length > 1 ? (nameOrNames.slice(1) as string[]) : undefined;\n\n      const programCommand = (program as any)[commandSymbol] as AnyPadroneCommand | undefined;\n      if (!programCommand) throw new RoutingError('Cannot mount: not a valid Padrone program');\n\n      const remounted = repathCommandTree(programCommand, name, existingCommand.path || '', existingCommand);\n      remounted.aliases = aliases;\n\n      if (options?.context) {\n        const existing = remounted.contextTransform;\n        remounted.contextTransform = existing ? (ctx: unknown) => existing(options.context!(ctx)) : options.context;\n      }\n\n      const existingSubcommand = existingCommand.commands?.find((c) => c.name === name) as AnyPadroneCommand | undefined;\n      const mergedCommandObj = existingSubcommand ? mergeCommands(existingSubcommand, remounted) : remounted;\n\n      const commands = existingCommand.commands || [];\n      const existingIndex = commands.findIndex((c) => c.name === name);\n      const updatedCommands =\n        existingIndex >= 0\n          ? [...commands.slice(0, existingIndex), mergedCommandObj, ...commands.slice(existingIndex + 1)]\n          : [...commands, mergedCommandObj];\n\n      return createPadroneBuilder({ ...existingCommand, commands: updatedCommands }) as any;\n    },\n\n    intercept(metaOrFn: InterceptorMeta | PadroneInterceptorFn<any, any, any>, factory?: InterceptorFactory<any, any, any>) {\n      const registered: RegisteredInterceptor = toRegisteredInterceptor(metaOrFn, factory);\n      return createPadroneBuilder({\n        ...existingCommand,\n        interceptors: [...(existingCommand.interceptors ?? []), registered],\n      }) as any;\n    },\n\n    ...programMethods,\n\n    get info() {\n      return {\n        name: existingCommand.name,\n        title: existingCommand.title,\n        description: existingCommand.description,\n        version: existingCommand.version,\n        examples: existingCommand.examples,\n        deprecated: existingCommand.deprecated,\n        commands: (existingCommand.commands ?? []).map((c) => c.name),\n      };\n    },\n\n    '~types': {} as any,\n\n    [commandSymbol]: existingCommand,\n  } satisfies AnyPadroneProgram & { [commandSymbol]: AnyPadroneCommand } as any;\n\n  // Fix forward reference: execCtx.builder needs to reference the builder after it's created\n  execCtx.builder = builder;\n\n  return builder as TBuilder & { [commandSymbol]: AnyPadroneCommand };\n}\n\n/**\n * Identity helper that contextually types a command builder callback while preserving its full return type.\n * Use this when defining commands in separate files — the parent program retains exact type information\n * about the subcommand's args, result, and nested commands.\n *\n * The builder's context includes `DefineCommandContext` by default (optional `logger`, `tracing`, `progress`).\n * Override globally via module augmentation on `DefineCommandContext`, or per-command via `.requires()`.\n *\n * @example Direct form (most common)\n * ```ts\n * export const myCommand = defineCommand((c) =>\n *   c.arguments(z.object({ name: z.string() }))\n *    .action((args) => console.log(args.name))\n * );\n * ```\n *\n * @example With required interceptor context\n * ```ts\n * export const adminCommand = defineCommand()\n *   .requires<{ adminDb: AdminDB }>()\n *   .define((c) => c.action((_args, ctx) => ctx.context.adminDb.query(...)));\n * ```\n */\nexport function defineCommand<TContext = unknown, TOut extends CommandTypesBase = CommandTypesBase>(\n  fn: (builder: PadroneBuilder<string, string, string, PadroneSchema<void>, void, [], any, false, TContext, DefineCommandContext>) => TOut,\n): typeof fn;\nexport function defineCommand(): DefineCommandBuilder;\nexport function defineCommand(fn?: any): any {\n  if (fn) return fn;\n  const builder: DefineCommandBuilder = {\n    requires: () => builder as any,\n    define: (f: any) => f,\n  };\n  return builder;\n}\n"],"mappings":"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"}

package/dist/core/default-runtime.mjs

@@ -0,0 +1,198 @@
+import { readStreamAsText } from "../util/stream.mjs";
+import { REPL_SIGINT } from "./runtime.mjs";
+//#region src/core/default-runtime.ts
+/**
+* Default terminal prompt implementation powered by Enquirer.
+* Lazily imported to avoid loading Enquirer when not needed.
+*/
+async function defaultTerminalPrompt(config) {
+	const Enquirer = (await import("enquirer")).default;
+	const question = {
+		type: config.type,
+		name: config.name,
+		message: config.message
+	};
+	if (config.default !== void 0) question.initial = config.default;
+	if (config.choices) question.choices = config.choices.map((c) => ({
+		name: String(c.value),
+		message: c.label
+	}));
+	return (await Enquirer.prompt(question))[config.name];
+}
+function createTerminalReplSession(config) {
+	let history = config.history ? [...config.history] : [];
+	let currentCompleter = config.completer;
+	return {
+		/** Update the tab completer (e.g. when REPL scope changes). Takes effect on the next question. */
+		set completer(fn) {
+			currentCompleter = fn;
+		},
+		async question(prompt) {
+			const { createInterface } = await import("node:readline");
+			const opts = {
+				input: process.stdin,
+				output: process.stdout,
+				terminal: true,
+				history: [...history],
+				historySize: Math.max(history.length, 1e3)
+			};
+			if (currentCompleter) opts.completer = currentCompleter;
+			const rl = createInterface(opts);
+			return new Promise((resolve) => {
+				let resolved = false;
+				const settle = (value) => {
+					if (resolved) return;
+					resolved = true;
+					rl.close();
+					resolve(value);
+				};
+				rl.question(prompt, (answer) => {
+					if (Array.isArray(rl.history)) history = [...rl.history];
+					settle(answer);
+				});
+				rl.once("SIGINT", () => {
+					process.stdout.write("\n");
+					settle(REPL_SIGINT);
+				});
+				rl.once("close", () => {
+					process.stdout.write("\n");
+					settle(null);
+				});
+			});
+		},
+		close() {}
+	};
+}
+/**
+* Auto-detect interactive mode when not explicitly set.
+* Returns 'disabled' in CI environments or non-TTY contexts, 'supported' otherwise.
+*/
+function detectInteractiveMode() {
+	if (typeof process === "undefined") return "disabled";
+	if (process.env.CI || process.env.CONTINUOUS_INTEGRATION) return "disabled";
+	if (!process.stdout?.isTTY) return "disabled";
+	return "supported";
+}
+/**
+* Creates a default stdin reader from `process.stdin`.
+* Only created when a command actually declares a `stdin` meta field.
+*/
+function createDefaultStdin() {
+	return {
+		get isTTY() {
+			if (typeof process === "undefined") return true;
+			return process.stdin?.isTTY === true;
+		},
+		async text() {
+			if (typeof process === "undefined") return "";
+			return readStreamAsText(process.stdin);
+		},
+		async *lines() {
+			if (typeof process === "undefined") return;
+			const { createInterface } = await import("node:readline");
+			const rl = createInterface({ input: process.stdin });
+			try {
+				for await (const line of rl) yield line;
+			} finally {
+				rl.close();
+			}
+		}
+	};
+}
+/**
+* Default signal listener that wires to `process.on(signal)`.
+* Returns an unsubscribe function that removes all listeners.
+*/
+function defaultOnSignal(callback) {
+	if (typeof process === "undefined") return () => {};
+	const signals = [
+		"SIGINT",
+		"SIGTERM",
+		"SIGHUP"
+	];
+	const handlers = /* @__PURE__ */ new Map();
+	for (const sig of signals) {
+		const handler = () => callback(sig);
+		handlers.set(sig, handler);
+		process.on(sig, handler);
+	}
+	return () => {
+		for (const [sig, handler] of handlers) process.removeListener(sig, handler);
+	};
+}
+/**
+* Creates the default Node.js/Bun runtime.
+*/
+function defaultExit(code) {
+	if (typeof process !== "undefined") process.exit(code);
+	throw new Error(`Exit with code ${code}`);
+}
+function getTerminalInfo() {
+	if (typeof process === "undefined") return void 0;
+	return {
+		get columns() {
+			return process.stdout?.columns;
+		},
+		get isTTY() {
+			return process.stdout?.isTTY === true;
+		}
+	};
+}
+function createDefaultRuntime() {
+	return {
+		output: (...args) => console.log(...args),
+		error: (text) => console.error(text),
+		argv: () => typeof process !== "undefined" ? process.argv.slice(2) : [],
+		env: () => typeof process !== "undefined" ? process.env : {},
+		format: "auto",
+		prompt: defaultTerminalPrompt,
+		interactive: detectInteractiveMode(),
+		onSignal: defaultOnSignal,
+		terminal: getTerminalInfo(),
+		exit: defaultExit
+	};
+}
+/**
+* Returns the stdin abstraction: custom runtime stdin > default process.stdin.
+* Returns `undefined` when no custom stdin is provided and process.stdin is not piped.
+*/
+function resolveStdin(partial) {
+	if (partial?.stdin) return partial.stdin;
+	const defaultStdin = createDefaultStdin();
+	if (defaultStdin.isTTY) return void 0;
+	return defaultStdin;
+}
+/**
+* Like `resolveStdin`, but always returns a stdin source even when it's a TTY.
+* Used for async streams which support interactive (non-piped) input.
+*/
+function resolveStdinAlways(partial) {
+	if (partial?.stdin) return partial.stdin;
+	return createDefaultStdin();
+}
+/**
+* Merges a partial runtime with the default runtime.
+*/
+function resolveRuntime(partial) {
+	const defaults = createDefaultRuntime();
+	if (!partial) return defaults;
+	return {
+		output: partial.output ?? defaults.output,
+		error: partial.error ?? defaults.error,
+		argv: partial.argv ?? defaults.argv,
+		env: partial.env ?? defaults.env,
+		format: partial.format ?? defaults.format,
+		interactive: partial.interactive ?? defaults.interactive,
+		prompt: partial.prompt ?? defaults.prompt,
+		readLine: partial.readLine ?? defaults.readLine,
+		stdin: partial.stdin,
+		theme: partial.theme,
+		onSignal: partial.onSignal ?? defaults.onSignal,
+		terminal: partial.terminal ?? defaults.terminal,
+		exit: partial.exit ?? defaults.exit
+	};
+}
+//#endregion
+export { createDefaultRuntime, createTerminalReplSession, resolveRuntime, resolveStdin, resolveStdinAlways };
+
+//# sourceMappingURL=default-runtime.mjs.map

package/dist/core/default-runtime.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"default-runtime.mjs","names":[],"sources":["../../src/core/default-runtime.ts"],"sourcesContent":["import { readStreamAsText } from '../util/stream.ts';\nimport type {\n  InteractiveMode,\n  InteractivePromptConfig,\n  PadroneRuntime,\n  PadroneSignal,\n  ReplSessionConfig,\n  ResolvedPadroneRuntime,\n} from './runtime.ts';\nimport { REPL_SIGINT } from './runtime.ts';\n\n/**\n * Default terminal prompt implementation powered by Enquirer.\n * Lazily imported to avoid loading Enquirer when not needed.\n */\nasync function defaultTerminalPrompt(config: InteractivePromptConfig): Promise<unknown> {\n  const Enquirer = (await import('enquirer')).default;\n\n  const question: Record<string, unknown> = {\n    type: config.type,\n    name: config.name,\n    message: config.message,\n  };\n\n  if (config.default !== undefined) {\n    question.initial = config.default;\n  }\n\n  if (config.choices) {\n    question.choices = config.choices.map((c) => ({\n      name: String(c.value),\n      message: c.label,\n    }));\n  }\n\n  const response = (await Enquirer.prompt(question as any)) as Record<string, unknown>;\n  return response[config.name];\n}\n\nexport function createTerminalReplSession(config: ReplSessionConfig) {\n  // History accumulates across per-call interfaces, giving us\n  // up/down arrow navigation without a persistent stdin listener\n  // that would conflict with Enquirer or other stdin consumers.\n  let history: string[] = config.history ? [...config.history] : [];\n  let currentCompleter = config.completer;\n\n  return {\n    /** Update the tab completer (e.g. when REPL scope changes). Takes effect on the next question. */\n    set completer(fn: ((line: string) => [string[], string]) | undefined) {\n      currentCompleter = fn;\n    },\n    async question(prompt: string): Promise<string | typeof REPL_SIGINT | null> {\n      const { createInterface } = await import('node:readline');\n      const opts: Record<string, unknown> = {\n        input: process.stdin,\n        output: process.stdout,\n        terminal: true,\n        history: [...history],\n        historySize: Math.max(history.length, 1000),\n      };\n      if (currentCompleter) {\n        opts.completer = currentCompleter;\n      }\n      const rl = createInterface(opts as any);\n\n      return new Promise((resolve) => {\n        let resolved = false;\n        const settle = (value: string | typeof REPL_SIGINT | null) => {\n          if (resolved) return;\n          resolved = true;\n          rl.close();\n          resolve(value);\n        };\n\n        rl.question(prompt, (answer) => {\n          // Grab updated history (includes the new entry) before closing.\n          if (Array.isArray((rl as any).history)) history = [...(rl as any).history];\n          settle(answer);\n        });\n        // Ctrl+C: cancel current line, print newline, resolve SIGINT sentinel.\n        rl.once('SIGINT', () => {\n          process.stdout.write('\\n');\n          settle(REPL_SIGINT);\n        });\n        // EOF (Ctrl+D) fires close without the question callback.\n        rl.once('close', () => {\n          // Write newline so zsh doesn't show '%' (partial-line indicator).\n          process.stdout.write('\\n');\n          settle(null);\n        });\n      });\n    },\n    close() {\n      // No persistent interface to clean up.\n    },\n  };\n}\n\n/**\n * Auto-detect interactive mode when not explicitly set.\n * Returns 'disabled' in CI environments or non-TTY contexts, 'supported' otherwise.\n */\nfunction detectInteractiveMode(): InteractiveMode {\n  if (typeof process === 'undefined') return 'disabled';\n  if (process.env.CI || process.env.CONTINUOUS_INTEGRATION) return 'disabled';\n  if (!process.stdout?.isTTY) return 'disabled';\n  return 'supported';\n}\n\n/**\n * Creates a default stdin reader from `process.stdin`.\n * Only created when a command actually declares a `stdin` meta field.\n */\nfunction createDefaultStdin(): NonNullable<PadroneRuntime['stdin']> {\n  return {\n    get isTTY() {\n      // process.stdin.isTTY is `true` when interactive terminal, `undefined` when piped/redirected.\n      // Node.js never sets it to `false` — it's either `true` or absent.\n      if (typeof process === 'undefined') return true;\n      return process.stdin?.isTTY === true;\n    },\n    async text() {\n      if (typeof process === 'undefined') return '';\n      return readStreamAsText(process.stdin);\n    },\n    async *lines() {\n      if (typeof process === 'undefined') return;\n      const { createInterface } = await import('node:readline');\n      const rl = createInterface({ input: process.stdin });\n      try {\n        for await (const line of rl) {\n          yield line;\n        }\n      } finally {\n        rl.close();\n      }\n    },\n  };\n}\n\n/**\n * Default signal listener that wires to `process.on(signal)`.\n * Returns an unsubscribe function that removes all listeners.\n */\nfunction defaultOnSignal(callback: (signal: PadroneSignal) => void): () => void {\n  if (typeof process === 'undefined') return () => {};\n  const signals: PadroneSignal[] = ['SIGINT', 'SIGTERM', 'SIGHUP'];\n  const handlers = new Map<PadroneSignal, () => void>();\n  for (const sig of signals) {\n    const handler = () => callback(sig);\n    handlers.set(sig, handler);\n    process.on(sig, handler);\n  }\n  return () => {\n    for (const [sig, handler] of handlers) {\n      process.removeListener(sig, handler);\n    }\n  };\n}\n\n/**\n * Creates the default Node.js/Bun runtime.\n */\nfunction defaultExit(code: number): never {\n  if (typeof process !== 'undefined') process.exit(code);\n  throw new Error(`Exit with code ${code}`);\n}\n\nfunction getTerminalInfo(): PadroneRuntime['terminal'] {\n  if (typeof process === 'undefined') return undefined;\n  return {\n    get columns() {\n      return process.stdout?.columns;\n    },\n    get isTTY() {\n      return process.stdout?.isTTY === true;\n    },\n  };\n}\n\nexport function createDefaultRuntime(): ResolvedPadroneRuntime {\n  return {\n    output: (...args) => console.log(...args),\n    error: (text) => console.error(text),\n    argv: () => (typeof process !== 'undefined' ? process.argv.slice(2) : []),\n    env: () => (typeof process !== 'undefined' ? (process.env as Record<string, string | undefined>) : {}),\n    format: 'auto',\n    prompt: defaultTerminalPrompt,\n    interactive: detectInteractiveMode(),\n    onSignal: defaultOnSignal,\n    terminal: getTerminalInfo(),\n    exit: defaultExit,\n  };\n}\n\n/**\n * Returns the stdin abstraction: custom runtime stdin > default process.stdin.\n * Returns `undefined` when no custom stdin is provided and process.stdin is not piped.\n */\nexport function resolveStdin(partial?: PadroneRuntime): NonNullable<PadroneRuntime['stdin']> | undefined {\n  if (partial?.stdin) return partial.stdin;\n  const defaultStdin = createDefaultStdin();\n  // Only use default stdin if it's actually piped (isTTY === false).\n  // This avoids accidentally blocking on stdin in tests/CI.\n  if (defaultStdin.isTTY) return undefined;\n  return defaultStdin;\n}\n\n/**\n * Like `resolveStdin`, but always returns a stdin source even when it's a TTY.\n * Used for async streams which support interactive (non-piped) input.\n */\nexport function resolveStdinAlways(partial?: PadroneRuntime): NonNullable<PadroneRuntime['stdin']> {\n  if (partial?.stdin) return partial.stdin;\n  return createDefaultStdin();\n}\n\n/**\n * Merges a partial runtime with the default runtime.\n */\nexport function resolveRuntime(partial?: PadroneRuntime): ResolvedPadroneRuntime {\n  const defaults = createDefaultRuntime();\n  if (!partial) return defaults;\n  return {\n    output: partial.output ?? defaults.output,\n    error: partial.error ?? defaults.error,\n    argv: partial.argv ?? defaults.argv,\n    env: partial.env ?? defaults.env,\n    format: partial.format ?? defaults.format,\n    interactive: partial.interactive ?? defaults.interactive,\n    prompt: partial.prompt ?? defaults.prompt,\n    readLine: partial.readLine ?? defaults.readLine,\n    stdin: partial.stdin,\n    theme: partial.theme,\n    onSignal: partial.onSignal ?? defaults.onSignal,\n    terminal: partial.terminal ?? defaults.terminal,\n    exit: partial.exit ?? defaults.exit,\n  };\n}\n"],"mappings":"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"}

package/dist/core/errors.d.mts

@@ -0,0 +1,107 @@
+import { PadroneSignal } from "./runtime.mjs";
+
+//#region src/core/errors.d.ts
+type PadroneErrorOptions = {
+  /** Process exit code. Defaults to 1. */exitCode?: number; /** Actionable suggestions shown to the user (e.g. "Use --env production"). */
+  suggestions?: string[]; /** The command path that produced the error (e.g. "deploy staging"). */
+  command?: string; /** The phase where the error occurred. */
+  phase?: 'parse' | 'validate' | 'execute' | 'config'; /** Original cause for error chaining. */
+  cause?: unknown;
+};
+/**
+ * Base error class for all Padrone errors.
+ * Carries structured metadata for user-friendly formatting and programmatic handling.
+ *
+ * @example
+ * ```ts
+ * throw new PadroneError('Something went wrong', {
+ *   exitCode: 1,
+ *   suggestions: ['Try --help for usage information'],
+ * });
+ * ```
+ */
+declare class PadroneError extends Error {
+  readonly exitCode: number;
+  readonly suggestions: string[];
+  readonly command?: string;
+  readonly phase?: 'parse' | 'validate' | 'execute' | 'config';
+  constructor(message: string, options?: PadroneErrorOptions);
+  /**
+   * Returns a serializable representation of the error,
+   * suitable for non-terminal runtimes (web UIs, APIs, etc.).
+   */
+  toJSON(): {
+    name: string;
+    message: string;
+    exitCode: number;
+    suggestions: string[];
+    command?: string;
+    phase?: string;
+  };
+}
+/**
+ * Thrown when command routing fails — unknown command, unexpected arguments, etc.
+ */
+declare class RoutingError extends PadroneError {
+  constructor(message: string, options?: PadroneErrorOptions);
+}
+/**
+ * Thrown when argument or schema validation fails.
+ * Carries the structured issues from the schema validator.
+ */
+declare class ValidationError extends PadroneError {
+  readonly issues: readonly {
+    path?: PropertyKey[];
+    message: string;
+  }[];
+  constructor(message: string, issues: readonly {
+    path?: PropertyKey[];
+    message: string;
+  }[], options?: PadroneErrorOptions);
+  toJSON(): {
+    issues: {
+      path: string[] | undefined;
+      message: string;
+    }[];
+    name: string;
+    message: string;
+    exitCode: number;
+    suggestions: string[];
+    command?: string;
+    phase?: string;
+  };
+}
+/**
+ * Thrown when config file loading or validation fails.
+ */
+declare class ConfigError extends PadroneError {
+  constructor(message: string, options?: PadroneErrorOptions);
+}
+/**
+ * Thrown from user action handlers to surface structured errors with exit codes and suggestions.
+ * This is the primary error class users should throw from their command actions.
+ *
+ * @example
+ * ```ts
+ * throw new ActionError('Missing environment', {
+ *   exitCode: 1,
+ *   suggestions: ['Use --env production or --env staging'],
+ * });
+ * ```
+ */
+declare class ActionError extends PadroneError {
+  constructor(message: string, options?: PadroneErrorOptions);
+}
+/**
+ * Thrown when command execution is interrupted by a process signal (SIGINT, SIGTERM, SIGHUP).
+ * Carries the signal name and the conventional exit code (128 + signal number).
+ */
+declare class SignalError extends PadroneError {
+  readonly signal: PadroneSignal;
+  constructor(signal: PadroneSignal, options?: {
+    cause?: unknown;
+  });
+}
+//#endregion
+export { ActionError, ConfigError, PadroneError, PadroneErrorOptions, RoutingError, SignalError, ValidationError };
+//# sourceMappingURL=errors.d.mts.map