padrone 1.8.2 → 2.0.0

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.mts","names":[],"sources":["../../src/core/errors.ts"],"mappings":";;;KAWY,mBAAA;EAQV,wCANA,QAAA,WAQK;EANL,WAAA,aAqBW;EAnBX,OAAA;EAEA,KAAA,gDAiBgC;EAfhC,KAAA;AAAA;;;;;;;;;;;;;cAeW,YAAA,SAAqB,KAAK;EAAA,SAC5B,QAAA;EAAA,SACA,WAAA;EAAA,SACA,OAAA;EAAA,SACA,KAAA;cAEG,OAAA,UAAiB,OAAA,GAAU,mBAAA;EAmCK;;;;EAtB5C,MAAA;IACE,IAAA;IACA,OAAA;IACA,QAAA;IACA,WAAA;IACA,OAAA;IACA,KAAA;EAAA;AAAA;;;;cAgBS,YAAA,SAAqB,YAAY;cAChC,OAAA,UAAiB,OAAA,GAAU,mBAAA;AAAA;;;;;cAU5B,eAAA,SAAwB,YAAA;EAAA,SAC1B,MAAA;IAAmB,IAAA,GAAO,WAAA;IAAe,OAAA;EAAA;cAEtC,OAAA,UAAiB,MAAA;IAAmB,IAAA,GAAO,WAAA;IAAe,OAAA;EAAA,KAAqB,OAAA,GAAU,mBAAA;EAM5F,MAAA;;;;;;;;;;;;;;;;cAWE,WAAA,SAAoB,YAAY;cAC/B,OAAA,UAAiB,OAAA,GAAU,mBAAA;AAAA;;AAAmB;AAkB5D;;;;;;;;;;cAAa,WAAA,SAAoB,YAAY;cAC/B,OAAA,UAAiB,OAAA,GAAU,mBAAA;AAAA;;;;;cAU5B,WAAA,SAAoB,YAAA;EAAA,SACtB,MAAA,EAAQ,aAAA;cAEL,MAAA,EAAQ,aAAA,EAAe,OAAA;IAAY,KAAA;EAAA;AAAA"}

package/dist/{errors-DA4KzK1M.mjs → core/errors.mjs}

@@ -132,6 +132,6 @@ function signalExitCode(signal) {
 	}[signal] ?? 1;
 }
 //#endregion
-export { SignalError as a, RoutingError as i, ConfigError as n, ValidationError as o, PadroneError as r, signalExitCode as s, ActionError as t };
+export { ActionError, ConfigError, PadroneError, RoutingError, SignalError, ValidationError, signalExitCode };
 
-//# sourceMappingURL=errors-DA4KzK1M.mjs.map
+//# sourceMappingURL=errors.mjs.map

package/dist/core/errors.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.mjs","names":[],"sources":["../../src/core/errors.ts"],"sourcesContent":["/**\n * Structured error hierarchy for Padrone CLI framework.\n *\n * All Padrone errors extend `PadroneError`, which carries an exit code,\n * optional suggestions, and context about which command/phase produced the error.\n * This allows callers to distinguish user errors (bad input) from bugs (unexpected throws)\n * and to present formatted, actionable error messages.\n */\n\nimport type { PadroneSignal } from './runtime.ts';\n\nexport type PadroneErrorOptions = {\n  /** Process exit code. Defaults to 1. */\n  exitCode?: number;\n  /** Actionable suggestions shown to the user (e.g. \"Use --env production\"). */\n  suggestions?: string[];\n  /** The command path that produced the error (e.g. \"deploy staging\"). */\n  command?: string;\n  /** The phase where the error occurred. */\n  phase?: 'parse' | 'validate' | 'execute' | 'config';\n  /** Original cause for error chaining. */\n  cause?: unknown;\n};\n\n/**\n * Base error class for all Padrone errors.\n * Carries structured metadata for user-friendly formatting and programmatic handling.\n *\n * @example\n * ```ts\n * throw new PadroneError('Something went wrong', {\n *   exitCode: 1,\n *   suggestions: ['Try --help for usage information'],\n * });\n * ```\n */\nexport class PadroneError extends Error {\n  readonly exitCode: number;\n  readonly suggestions: string[];\n  readonly command?: string;\n  readonly phase?: 'parse' | 'validate' | 'execute' | 'config';\n\n  constructor(message: string, options?: PadroneErrorOptions) {\n    super(message, options?.cause ? { cause: options.cause } : undefined);\n    this.name = 'PadroneError';\n    this.exitCode = options?.exitCode ?? 1;\n    this.suggestions = options?.suggestions ?? [];\n    this.command = options?.command;\n    this.phase = options?.phase;\n  }\n\n  /**\n   * Returns a serializable representation of the error,\n   * suitable for non-terminal runtimes (web UIs, APIs, etc.).\n   */\n  toJSON(): {\n    name: string;\n    message: string;\n    exitCode: number;\n    suggestions: string[];\n    command?: string;\n    phase?: string;\n  } {\n    return {\n      name: this.name,\n      message: this.message,\n      exitCode: this.exitCode,\n      suggestions: this.suggestions,\n      command: this.command,\n      phase: this.phase,\n    };\n  }\n}\n\n/**\n * Thrown when command routing fails — unknown command, unexpected arguments, etc.\n */\nexport class RoutingError extends PadroneError {\n  constructor(message: string, options?: PadroneErrorOptions) {\n    super(message, { phase: 'parse', ...options });\n    this.name = 'RoutingError';\n  }\n}\n\n/**\n * Thrown when argument or schema validation fails.\n * Carries the structured issues from the schema validator.\n */\nexport class ValidationError extends PadroneError {\n  readonly issues: readonly { path?: PropertyKey[]; message: string }[];\n\n  constructor(message: string, issues: readonly { path?: PropertyKey[]; message: string }[], options?: PadroneErrorOptions) {\n    super(message, { phase: 'validate', ...options });\n    this.name = 'ValidationError';\n    this.issues = issues;\n  }\n\n  override toJSON() {\n    return {\n      ...super.toJSON(),\n      issues: this.issues.map((i) => ({ path: i.path?.map(String), message: i.message })),\n    };\n  }\n}\n\n/**\n * Thrown when config file loading or validation fails.\n */\nexport class ConfigError extends PadroneError {\n  constructor(message: string, options?: PadroneErrorOptions) {\n    super(message, { phase: 'config', ...options });\n    this.name = 'ConfigError';\n  }\n}\n\n/**\n * Thrown from user action handlers to surface structured errors with exit codes and suggestions.\n * This is the primary error class users should throw from their command actions.\n *\n * @example\n * ```ts\n * throw new ActionError('Missing environment', {\n *   exitCode: 1,\n *   suggestions: ['Use --env production or --env staging'],\n * });\n * ```\n */\nexport class ActionError extends PadroneError {\n  constructor(message: string, options?: PadroneErrorOptions) {\n    super(message, { phase: 'execute', ...options });\n    this.name = 'ActionError';\n  }\n}\n\n/**\n * Thrown when command execution is interrupted by a process signal (SIGINT, SIGTERM, SIGHUP).\n * Carries the signal name and the conventional exit code (128 + signal number).\n */\nexport class SignalError extends PadroneError {\n  readonly signal: PadroneSignal;\n\n  constructor(signal: PadroneSignal, options?: { cause?: unknown }) {\n    super(`Process interrupted by ${signal}`, { exitCode: signalExitCode(signal), cause: options?.cause });\n    this.name = 'SignalError';\n    this.signal = signal;\n  }\n}\n\n/** Maps a signal name to its conventional exit code (128 + signal number). */\nexport function signalExitCode(signal: PadroneSignal): number {\n  const codes: Record<string, number> = { SIGINT: 130, SIGTERM: 143, SIGHUP: 129 };\n  return codes[signal] ?? 1;\n}\n"],"mappings":";;;;;;;;;;;;;AAoCA,IAAa,eAAb,cAAkC,MAAM;CACtC;CACA;CACA;CACA;CAEA,YAAY,SAAiB,SAA+B;EAC1D,MAAM,SAAS,SAAS,QAAQ,EAAE,OAAO,QAAQ,MAAM,IAAI,KAAA,CAAS;EACpE,KAAK,OAAO;EACZ,KAAK,WAAW,SAAS,YAAY;EACrC,KAAK,cAAc,SAAS,eAAe,CAAC;EAC5C,KAAK,UAAU,SAAS;EACxB,KAAK,QAAQ,SAAS;CACxB;;;;;CAMA,SAOE;EACA,OAAO;GACL,MAAM,KAAK;GACX,SAAS,KAAK;GACd,UAAU,KAAK;GACf,aAAa,KAAK;GAClB,SAAS,KAAK;GACd,OAAO,KAAK;EACd;CACF;AACF;;;;AAKA,IAAa,eAAb,cAAkC,aAAa;CAC7C,YAAY,SAAiB,SAA+B;EAC1D,MAAM,SAAS;GAAE,OAAO;GAAS,GAAG;EAAQ,CAAC;EAC7C,KAAK,OAAO;CACd;AACF;;;;;AAMA,IAAa,kBAAb,cAAqC,aAAa;CAChD;CAEA,YAAY,SAAiB,QAA8D,SAA+B;EACxH,MAAM,SAAS;GAAE,OAAO;GAAY,GAAG;EAAQ,CAAC;EAChD,KAAK,OAAO;EACZ,KAAK,SAAS;CAChB;CAEA,SAAkB;EAChB,OAAO;GACL,GAAG,MAAM,OAAO;GAChB,QAAQ,KAAK,OAAO,KAAK,OAAO;IAAE,MAAM,EAAE,MAAM,IAAI,MAAM;IAAG,SAAS,EAAE;GAAQ,EAAE;EACpF;CACF;AACF;;;;AAKA,IAAa,cAAb,cAAiC,aAAa;CAC5C,YAAY,SAAiB,SAA+B;EAC1D,MAAM,SAAS;GAAE,OAAO;GAAU,GAAG;EAAQ,CAAC;EAC9C,KAAK,OAAO;CACd;AACF;;;;;;;;;;;;;AAcA,IAAa,cAAb,cAAiC,aAAa;CAC5C,YAAY,SAAiB,SAA+B;EAC1D,MAAM,SAAS;GAAE,OAAO;GAAW,GAAG;EAAQ,CAAC;EAC/C,KAAK,OAAO;CACd;AACF;;;;;AAMA,IAAa,cAAb,cAAiC,aAAa;CAC5C;CAEA,YAAY,QAAuB,SAA+B;EAChE,MAAM,0BAA0B,UAAU;GAAE,UAAU,eAAe,MAAM;GAAG,OAAO,SAAS;EAAM,CAAC;EACrG,KAAK,OAAO;EACZ,KAAK,SAAS;CAChB;AACF;;AAGA,SAAgB,eAAe,QAA+B;CAE5D,OAAO;EADiC,QAAQ;EAAK,SAAS;EAAK,QAAQ;CAChE,EAAE,WAAW;AAC1B"}

package/dist/core/exec.mjs

@@ -0,0 +1,191 @@
+import { getCommandRuntime } from "./commands.mjs";
+import { errorResult, noop, thenMaybe, warnIfUnexpectedAsync, withDrain } from "./results.mjs";
+import { resolveRegisteredInterceptors, runInterceptorChain, wrapWithCommandLifecycle, wrapWithLifecycle } from "./interceptors.mjs";
+import { RoutingError, SignalError, ValidationError } from "./errors.mjs";
+import { buildCommandArgs, formatIssueMessages, validateCommandArgs } from "./validate.mjs";
+//#region src/core/exec.ts
+/**
+* Collects registered interceptors from the command's parent chain (root → ... → target).
+* Root/program interceptors come first (outermost), target command's interceptors last (innermost).
+*/
+function collectInterceptors(cmd, rootCommand) {
+	const chain = [];
+	let current = cmd;
+	while (current) {
+		const isTarget = current === cmd;
+		if (!current.parent) {
+			if (rootCommand.interceptors?.length) {
+				const isRootTarget = cmd === rootCommand || !cmd.parent;
+				chain.unshift(isRootTarget ? rootCommand.interceptors : rootCommand.interceptors.filter((i) => i.meta.inherit !== false));
+			}
+		} else if (current.interceptors?.length) chain.unshift(isTarget ? current.interceptors : current.interceptors.filter((i) => i.meta.inherit !== false));
+		current = current.parent;
+	}
+	return chain.flat();
+}
+/** Wraps an error into a result, preserving any signal info from the pipeline. */
+function errorResultWithSignal(err) {
+	const result = errorResult(err);
+	if (err instanceof SignalError) {
+		result.signal = err.signal;
+		result.exitCode = err.exitCode;
+	}
+	return result;
+}
+/** Resolve context by walking the command parent chain and applying transforms from root to target. */
+function resolveContext(command, initialContext) {
+	const chain = [];
+	let current = command;
+	while (current) {
+		chain.unshift(current);
+		current = current.parent;
+	}
+	let resolved = initialContext;
+	for (const cmd of chain) if (cmd.contextTransform) resolved = cmd.contextTransform(resolved);
+	return resolved;
+}
+/** Validate parse result — reject unmatched terms when the command doesn't accept positional args. */
+function validateParseResult(parseResult, rootCommand) {
+	const { command, rawArgs, args, unmatchedTerms } = parseResult;
+	if (unmatchedTerms.length > 0) {
+		if (!(command.meta?.positional && command.meta.positional.length > 0)) {
+			const isRootCommand = command === rootCommand;
+			const commandDisplayName = command.name || command.aliases?.[0] || command.path || "(default)";
+			throw new RoutingError(isRootCommand ? `Unknown command: ${unmatchedTerms[0]}` : `Unexpected arguments for '${commandDisplayName}': ${unmatchedTerms.join(" ")}`, { command: command.path || command.name });
+		}
+	}
+	return {
+		command,
+		rawArgs,
+		positionalArgs: args
+	};
+}
+/** Handle validation issues based on error mode: throw (hard) or return result with issues (soft). */
+function handleValidationIssues(argsResult, command, errorMode) {
+	if (errorMode === "hard") throw new ValidationError(`Validation error:\n${formatIssueMessages(argsResult.issues)}`, argsResult.issues, { command: command.path || command.name });
+	return withDrain({
+		command,
+		args: void 0,
+		argsResult,
+		result: void 0
+	});
+}
+/**
+* Core execution logic shared by eval() and cli().
+* errorMode controls validation error behavior:
+* - 'soft': return result with issues (eval behavior)
+* - 'hard': print error + help and throw (cli-without-input behavior)
+*/
+function execCommand(resolvedInput, ctx, evalOptions, errorMode = "soft", caller = "eval") {
+	const { rootCommand, parseCommandFn, collectInterceptorsFn } = ctx;
+	const baseRuntime = getCommandRuntime(rootCommand);
+	const runtime = evalOptions?.runtime ? Object.assign({}, baseRuntime, Object.fromEntries(Object.entries(evalOptions.runtime).filter(([, v]) => v !== void 0))) : baseRuntime;
+	const inertSignal = new AbortController().signal;
+	const pipelineState = { phase: "start" };
+	const initialContext = evalOptions?.context;
+	const factoryCache = /* @__PURE__ */ new Map();
+	const rootInterceptors = resolveRegisteredInterceptors(rootCommand.interceptors ?? [], factoryCache);
+	const rootInterceptorSet = new Set(rootInterceptors);
+	const runPipeline = (signal, pipelineContext) => {
+		const parseCtx = {
+			input: resolvedInput,
+			command: rootCommand,
+			signal,
+			context: pipelineContext,
+			runtime,
+			program: ctx.builder,
+			caller
+		};
+		const coreParse = (parseCtx) => validateParseResult(parseCommandFn(parseCtx.input), rootCommand);
+		const parsedOrPromise = runInterceptorChain("parse", rootInterceptors, parseCtx, coreParse);
+		const continueAfterParse = (parsed) => {
+			const { command } = parsed;
+			pipelineState.phase = "parse";
+			pipelineState.rawArgs = parsed.rawArgs;
+			pipelineState.positionalArgs = parsed.positionalArgs;
+			const commandInterceptors = resolveRegisteredInterceptors(collectInterceptorsFn(command), factoryCache);
+			const commandOnlyInterceptors = commandInterceptors.filter((i) => !rootInterceptorSet.has(i));
+			const context = resolveContext(command, pipelineContext);
+			const routedOrPromise = runInterceptorChain("route", commandInterceptors, {
+				...parseCtx,
+				command,
+				rawArgs: parsed.rawArgs,
+				positionalArgs: parsed.positionalArgs,
+				context
+			}, () => {});
+			const continueAfterRoute = () => {
+				pipelineState.phase = "route";
+				const runValidateAndExecute = () => {
+					const validateCtx = {
+						...parseCtx,
+						command,
+						rawArgs: parsed.rawArgs,
+						positionalArgs: parsed.positionalArgs,
+						context,
+						evalInteractive: evalOptions?.interactive
+					};
+					const coreValidate = (validateCtx) => {
+						const { args: preprocessedArgs, issues } = buildCommandArgs(validateCtx.command, validateCtx.rawArgs, validateCtx.positionalArgs);
+						if (issues) return {
+							args: void 0,
+							argsResult: { issues }
+						};
+						return thenMaybe(validateCommandArgs(validateCtx.command, preprocessedArgs), (v) => v);
+					};
+					const validatedOrPromise = runInterceptorChain("validate", commandInterceptors, validateCtx, coreValidate);
+					const continueAfterValidate = (v) => {
+						pipelineState.phase = "validate";
+						pipelineState.args = v.args;
+						if (v.argsResult?.issues) return handleValidationIssues(v.argsResult, command, errorMode);
+						const executeCtx = {
+							...validateCtx,
+							args: v.args
+						};
+						const coreExecute = (executeCtx) => {
+							const handler = command.action ?? noop;
+							const actionCtx = {
+								runtime: executeCtx.runtime,
+								command: executeCtx.command,
+								program: ctx.builder,
+								signal: executeCtx.signal,
+								context: executeCtx.context,
+								caller
+							};
+							return { result: handler(executeCtx.args, actionCtx) };
+						};
+						pipelineState.phase = "execute";
+						return thenMaybe(runInterceptorChain("execute", commandInterceptors, executeCtx, coreExecute), (e) => {
+							const finalize = (result) => withDrain({
+								command,
+								args: v.args,
+								argsResult: v.argsResult,
+								result
+							});
+							if (e.result instanceof Promise) return e.result.then(finalize);
+							return finalize(e.result);
+						});
+					};
+					return thenMaybe(warnIfUnexpectedAsync(validatedOrPromise, command), continueAfterValidate);
+				};
+				return wrapWithCommandLifecycle(commandOnlyInterceptors, command, resolvedInput, runValidateAndExecute, (result) => withDrain({
+					command,
+					args: void 0,
+					argsResult: void 0,
+					result
+				}), signal, context, runtime, ctx.builder, caller, pipelineState);
+			};
+			return thenMaybe(routedOrPromise, continueAfterRoute);
+		};
+		return thenMaybe(parsedOrPromise, continueAfterParse);
+	};
+	return wrapWithLifecycle(rootInterceptors, rootCommand, resolvedInput, runPipeline, (result) => withDrain({
+		command: rootCommand,
+		args: void 0,
+		argsResult: void 0,
+		result
+	}), inertSignal, initialContext, runtime, ctx.builder, caller, pipelineState);
+}
+//#endregion
+export { collectInterceptors, errorResultWithSignal, execCommand };
+
+//# sourceMappingURL=exec.mjs.map

package/dist/core/exec.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"exec.mjs","names":[],"sources":["../../src/core/exec.ts"],"sourcesContent":["import type { StandardSchemaV1 } from '@standard-schema/spec';\nimport type {\n  AnyPadroneCommand,\n  AnyPadroneProgram,\n  InterceptorExecuteContext,\n  InterceptorExecuteResult,\n  InterceptorParseContext,\n  InterceptorParseResult,\n  InterceptorPipelinePhase,\n  InterceptorRouteContext,\n  InterceptorValidateContext,\n  InterceptorValidateResult,\n  PadroneActionContext,\n  PadroneEvalPreferences,\n  RegisteredInterceptor,\n  ResolvedInterceptor,\n} from '../types/index.ts';\nimport { getCommandRuntime } from './commands.ts';\nimport { RoutingError, SignalError, ValidationError } from './errors.ts';\nimport { resolveRegisteredInterceptors, runInterceptorChain, wrapWithCommandLifecycle, wrapWithLifecycle } from './interceptors.ts';\nimport { errorResult, noop, thenMaybe, warnIfUnexpectedAsync, withDrain } from './results.ts';\nimport { buildCommandArgs, formatIssueMessages, validateCommandArgs } from './validate.ts';\n\nexport type ExecContext = {\n  rootCommand: AnyPadroneCommand;\n  builder: AnyPadroneProgram;\n  parseCommandFn: (input: string | undefined) => {\n    command: AnyPadroneCommand;\n    rawArgs: Record<string, unknown>;\n    args: string[];\n    unmatchedTerms: string[];\n  };\n  collectInterceptorsFn: (cmd: AnyPadroneCommand) => RegisteredInterceptor[];\n};\n\n/**\n * Collects registered interceptors from the command's parent chain (root → ... → target).\n * Root/program interceptors come first (outermost), target command's interceptors last (innermost).\n */\nexport function collectInterceptors(cmd: AnyPadroneCommand, rootCommand: AnyPadroneCommand): RegisteredInterceptor[] {\n  const chain: RegisteredInterceptor[][] = [];\n  let current: AnyPadroneCommand | undefined = cmd;\n  while (current) {\n    const isTarget = current === cmd;\n    if (!current.parent) {\n      if (rootCommand.interceptors?.length) {\n        const isRootTarget = cmd === rootCommand || !cmd.parent;\n        chain.unshift(isRootTarget ? rootCommand.interceptors : rootCommand.interceptors.filter((i) => i.meta.inherit !== false));\n      }\n    } else {\n      if (current.interceptors?.length) {\n        chain.unshift(isTarget ? current.interceptors : current.interceptors.filter((i) => i.meta.inherit !== false));\n      }\n    }\n    current = current.parent;\n  }\n  return chain.flat();\n}\n\n/** Wraps an error into a result, preserving any signal info from the pipeline. */\nexport function errorResultWithSignal(err: unknown) {\n  const result = errorResult(err);\n  if (err instanceof SignalError) {\n    (result as any).signal = err.signal;\n    (result as any).exitCode = err.exitCode;\n  }\n  return result;\n}\n\n/** Resolve context by walking the command parent chain and applying transforms from root to target. */\nfunction resolveContext(command: AnyPadroneCommand, initialContext: unknown): unknown {\n  const chain: AnyPadroneCommand[] = [];\n  let current: AnyPadroneCommand | undefined = command;\n  while (current) {\n    chain.unshift(current);\n    current = current.parent;\n  }\n  let resolved = initialContext;\n  for (const cmd of chain) {\n    if (cmd.contextTransform) resolved = cmd.contextTransform(resolved);\n  }\n  return resolved;\n}\n\n/** Validate parse result — reject unmatched terms when the command doesn't accept positional args. */\nfunction validateParseResult(\n  parseResult: { command: AnyPadroneCommand; rawArgs: Record<string, unknown>; args: string[]; unmatchedTerms: string[] },\n  rootCommand: AnyPadroneCommand,\n): InterceptorParseResult {\n  const { command, rawArgs, args, unmatchedTerms } = parseResult;\n\n  if (unmatchedTerms.length > 0) {\n    const hasPositionalConfig = command.meta?.positional && command.meta.positional.length > 0;\n    if (!hasPositionalConfig) {\n      const isRootCommand = command === rootCommand;\n      const commandDisplayName = command.name || command.aliases?.[0] || command.path || '(default)';\n      const errorMsg = isRootCommand\n        ? `Unknown command: ${unmatchedTerms[0]}`\n        : `Unexpected arguments for '${commandDisplayName}': ${unmatchedTerms.join(' ')}`;\n\n      throw new RoutingError(errorMsg, { command: command.path || command.name });\n    }\n  }\n\n  return { command, rawArgs, positionalArgs: args };\n}\n\n/** Handle validation issues based on error mode: throw (hard) or return result with issues (soft). */\nfunction handleValidationIssues(argsResult: StandardSchemaV1.FailureResult, command: AnyPadroneCommand, errorMode: 'soft' | 'hard') {\n  if (errorMode === 'hard') {\n    const issueMessages = formatIssueMessages(argsResult.issues);\n    throw new ValidationError(`Validation error:\\n${issueMessages}`, argsResult.issues as any, {\n      command: command.path || command.name,\n    });\n  }\n\n  return withDrain({\n    command: command as any,\n    args: undefined,\n    argsResult,\n    result: undefined,\n  });\n}\n\n/**\n * Core execution logic shared by eval() and cli().\n * errorMode controls validation error behavior:\n * - 'soft': return result with issues (eval behavior)\n * - 'hard': print error + help and throw (cli-without-input behavior)\n */\nexport function execCommand(\n  resolvedInput: string | undefined,\n  ctx: ExecContext,\n  evalOptions?: PadroneEvalPreferences,\n  errorMode: 'soft' | 'hard' = 'soft',\n  caller: PadroneActionContext['caller'] = 'eval',\n) {\n  const { rootCommand, parseCommandFn, collectInterceptorsFn } = ctx;\n  const baseRuntime = getCommandRuntime(rootCommand);\n  const runtime = evalOptions?.runtime\n    ? Object.assign({}, baseRuntime, Object.fromEntries(Object.entries(evalOptions.runtime).filter(([, v]) => v !== undefined)))\n    : baseRuntime;\n\n  // Inert signal — the signal extension overrides this via next({ signal }) in the start phase.\n  const inertSignal = new AbortController().signal;\n\n  // Pipeline state accumulated as phases complete — propagated to error/shutdown contexts.\n  const pipelineState: { phase: InterceptorPipelinePhase; rawArgs?: Record<string, unknown>; positionalArgs?: string[]; args?: unknown } = {\n    phase: 'start',\n  };\n\n  const initialContext = evalOptions?.context;\n\n  // Factory resolution cache — ensures each factory is called at most once per execution,\n  // so root interceptor closures are shared when they appear in both root and command chains.\n  const factoryCache = new Map<RegisteredInterceptor, ResolvedInterceptor>();\n  const rootRegistered = rootCommand.interceptors ?? [];\n  const rootInterceptors = resolveRegisteredInterceptors(rootRegistered, factoryCache);\n  const rootInterceptorSet = new Set(rootInterceptors);\n\n  const runPipeline = (signal: AbortSignal, pipelineContext: unknown) => {\n    // ── Phase 1: Parse ──────────────────────────────────────────────────\n    const parseCtx: InterceptorParseContext = {\n      input: resolvedInput,\n      command: rootCommand,\n      signal,\n      context: pipelineContext as object,\n      runtime,\n      program: ctx.builder,\n      caller,\n    };\n\n    const coreParse = (parseCtx: InterceptorParseContext): InterceptorParseResult =>\n      validateParseResult(parseCommandFn(parseCtx.input), rootCommand);\n\n    const parsedOrPromise = runInterceptorChain('parse', rootInterceptors, parseCtx, coreParse);\n\n    // ── Phases 2 & 3 chained after parse ────────────────────────────────\n    const continueAfterParse = (parsed: InterceptorParseResult) => {\n      const { command } = parsed;\n      pipelineState.phase = 'parse';\n      pipelineState.rawArgs = parsed.rawArgs;\n      pipelineState.positionalArgs = parsed.positionalArgs;\n      const commandInterceptors = resolveRegisteredInterceptors(collectInterceptorsFn(command), factoryCache);\n      const commandOnlyInterceptors = commandInterceptors.filter((i) => !rootInterceptorSet.has(i));\n      const context = resolveContext(command, pipelineContext);\n\n      // ── Phase 2: Route ──────────────────────────────────────────────\n      const routeCtx: InterceptorRouteContext = {\n        ...parseCtx,\n        command,\n        rawArgs: parsed.rawArgs,\n        positionalArgs: parsed.positionalArgs,\n        context: context as object,\n      };\n\n      const routedOrPromise = runInterceptorChain('route', commandInterceptors, routeCtx, () => {});\n\n      const continueAfterRoute = () => {\n        pipelineState.phase = 'route';\n        const runValidateAndExecute = () => {\n          // ── Phase 3: Validate ───────────────────────────────────────────\n          const validateCtx: InterceptorValidateContext = {\n            ...parseCtx,\n            command,\n            rawArgs: parsed.rawArgs,\n            positionalArgs: parsed.positionalArgs,\n            context: context as object,\n            evalInteractive: evalOptions?.interactive,\n          };\n\n          const coreValidate = (\n            validateCtx: InterceptorValidateContext,\n          ): InterceptorValidateResult | Promise<InterceptorValidateResult> => {\n            const { args: preprocessedArgs, issues } = buildCommandArgs(\n              validateCtx.command,\n              validateCtx.rawArgs,\n              validateCtx.positionalArgs,\n            );\n            if (issues) return { args: undefined, argsResult: { issues } as any };\n            const validated = validateCommandArgs(validateCtx.command, preprocessedArgs);\n            return thenMaybe(validated, (v) => v as InterceptorValidateResult);\n          };\n\n          const validatedOrPromise = runInterceptorChain('validate', commandInterceptors, validateCtx, coreValidate);\n\n          // ── Phase 3: Execute (or handle validation errors) ──────────────\n          const continueAfterValidate = (v: InterceptorValidateResult) => {\n            pipelineState.phase = 'validate';\n            pipelineState.args = v.args;\n            if (v.argsResult?.issues) return handleValidationIssues(v.argsResult as StandardSchemaV1.FailureResult, command, errorMode);\n\n            const executeCtx: InterceptorExecuteContext = {\n              ...validateCtx,\n              args: v.args,\n            };\n\n            const coreExecute = (executeCtx: InterceptorExecuteContext): InterceptorExecuteResult => {\n              const handler = command.action ?? noop;\n              const effectiveRuntime = executeCtx.runtime;\n              const actionCtx: PadroneActionContext = {\n                runtime: effectiveRuntime,\n                command: executeCtx.command,\n                program: ctx.builder as any,\n                signal: executeCtx.signal,\n                context: executeCtx.context,\n                caller,\n              };\n              const result = handler(executeCtx.args as any, actionCtx);\n              return { result };\n            };\n\n            pipelineState.phase = 'execute';\n            const executedOrPromise = runInterceptorChain('execute', commandInterceptors, executeCtx, coreExecute);\n\n            return thenMaybe(executedOrPromise, (e) => {\n              const finalize = (result: unknown) =>\n                withDrain({\n                  command: command as any,\n                  args: v.args,\n                  argsResult: v.argsResult,\n                  result,\n                });\n\n              if (e.result instanceof Promise) return e.result.then(finalize);\n              return finalize(e.result);\n            });\n          };\n\n          return thenMaybe(warnIfUnexpectedAsync(validatedOrPromise, command), continueAfterValidate) as any;\n        };\n\n        return wrapWithCommandLifecycle(\n          commandOnlyInterceptors,\n          command,\n          resolvedInput,\n          runValidateAndExecute,\n          (result) => withDrain({ command: command as any, args: undefined, argsResult: undefined, result }),\n          signal,\n          context,\n          runtime,\n          ctx.builder,\n          caller,\n          pipelineState,\n        );\n      };\n\n      return thenMaybe(routedOrPromise, continueAfterRoute) as any;\n    };\n\n    return thenMaybe(parsedOrPromise, continueAfterParse) as any;\n  };\n\n  return wrapWithLifecycle(\n    rootInterceptors,\n    rootCommand,\n    resolvedInput,\n    runPipeline,\n    (result) => withDrain({ command: rootCommand, args: undefined, argsResult: undefined, result }),\n    inertSignal,\n    initialContext,\n    runtime,\n    ctx.builder,\n    caller,\n    pipelineState,\n  ) as any;\n}\n"],"mappings":"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"}

package/dist/core/interceptors.d.mts

@@ -0,0 +1,33 @@
+import { InterceptorDefBuilder, InterceptorFactory, InterceptorMeta, PadroneInterceptorFn } from "../types/interceptor.mjs";
+//#region src/core/interceptors.d.ts
+/**
+ * Creates a self-contained interceptor value by attaching static metadata to the factory function.
+ * The returned value can be passed directly to `.intercept()` or exported from a package.
+ *
+ * Two-arg form — define metadata and factory in one call:
+ * ```ts
+ * export const myInterceptor = defineInterceptor(
+ *   { name: 'my-interceptor', order: 10 },
+ *   () => ({
+ *     execute(ctx, next) { return next(); },
+ *   }),
+ * );
+ * ```
+ *
+ * Single-arg form — chain `.requires<T>()` for typed context, then `.factory()`:
+ * ```ts
+ * export const myInterceptor = defineInterceptor({ name: 'with-db' })
+ *   .requires<{ db: DB }>()
+ *   .factory(() => ({
+ *     execute(ctx, next) {
+ *       ctx.context.db; // typed!
+ *       return next();
+ *     },
+ *   }));
+ * ```
+ */
+declare function defineInterceptor<TArgs = unknown, TResult = unknown>(meta: InterceptorMeta, factory: InterceptorFactory<TArgs, TResult>): PadroneInterceptorFn<TArgs, TResult>;
+declare function defineInterceptor(meta: InterceptorMeta): InterceptorDefBuilder;
+//#endregion
+export { defineInterceptor };
+//# sourceMappingURL=interceptors.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"interceptors.d.mts","names":[],"sources":["../../src/core/interceptors.ts"],"mappings":";;;;AA2DA;;;;;;;;;;;;;;;;;;;;;;;;iBAAgB,iBAAA,qCACd,IAAA,EAAM,eAAA,EACN,OAAA,EAAS,kBAAA,CAAmB,KAAA,EAAO,OAAA,IAClC,oBAAA,CAAqB,KAAA,EAAO,OAAA;AAAA,iBACf,iBAAA,CAAkB,IAAA,EAAM,eAAA,GAAkB,qBAAqB"}

package/dist/core/interceptors.mjs

@@ -0,0 +1,253 @@
+import { thenMaybe } from "./results.mjs";
+//#region src/core/interceptors.ts
+function buildInterceptorFn(meta, factory) {
+	Object.defineProperty(factory, "name", {
+		value: meta.name,
+		configurable: true
+	});
+	if (meta.id !== void 0) factory.id = meta.id;
+	if (meta.order !== void 0) factory.order = meta.order;
+	if (meta.disabled !== void 0) factory.disabled = meta.disabled;
+	if (meta.inherit !== void 0) factory.inherit = meta.inherit;
+	factory.provides = () => factory;
+	factory.requires = () => factory;
+	return factory;
+}
+function defineInterceptor(meta, factory) {
+	if (factory) return buildInterceptorFn(meta, factory);
+	const builder = {
+		requires: () => builder,
+		factory: (f) => buildInterceptorFn(meta, f)
+	};
+	return builder;
+}
+/**
+* Normalizes an interceptor input (single-value form or two-arg form) into the internal
+* `RegisteredInterceptor` storage format.
+*/
+function toRegisteredInterceptor(metaOrFn, factory) {
+	if (typeof metaOrFn === "function") return {
+		meta: {
+			name: metaOrFn.name,
+			id: metaOrFn.id,
+			order: metaOrFn.order,
+			disabled: metaOrFn.disabled,
+			inherit: metaOrFn.inherit
+		},
+		factory: metaOrFn
+	};
+	return {
+		meta: metaOrFn,
+		factory
+	};
+}
+/**
+* Resolves registered interceptors by calling their factories and merging the resulting
+* phase handlers with the static metadata. Uses a cache to ensure each factory is called
+* at most once per execution (so root interceptor closures are shared across all phases).
+*/
+function resolveRegisteredInterceptors(registered, cache) {
+	return registered.map((reg) => {
+		let resolved = cache.get(reg);
+		if (!resolved) {
+			resolved = {
+				...reg.meta,
+				...reg.factory()
+			};
+			cache.set(reg, resolved);
+		}
+		return resolved;
+	});
+}
+/**
+* Deduplicates interceptors by `id`. When multiple interceptors share the same `id`,
+* only the last one in the array is kept. Interceptors without an `id` are always kept.
+*/
+function deduplicateInterceptors(interceptors) {
+	if (!interceptors.some((p) => p.id)) return interceptors;
+	const lastIndex = /* @__PURE__ */ new Map();
+	for (let i = 0; i < interceptors.length; i++) {
+		const id = interceptors[i].id;
+		if (id) lastIndex.set(id, i);
+	}
+	return interceptors.filter((p, i) => !p.id || lastIndex.get(p.id) === i);
+}
+/**
+* Runs an interceptor chain for a given phase using the onion/middleware pattern.
+* Interceptors are sorted by `order` (ascending, stable), then composed so that
+* the first interceptor in sorted order is the outermost wrapper.
+* If no interceptors handle this phase, `core` is called directly.
+*
+* Each interceptor's `next()` accepts optional partial overrides that are merged
+* into the context before passing to the next interceptor or core function.
+*/
+function runInterceptorChain(phase, interceptors, ctx, core) {
+	const phaseInterceptors = deduplicateInterceptors(interceptors).filter((p) => p[phase] && !p.disabled);
+	if (phaseInterceptors.length === 0) return core(ctx);
+	phaseInterceptors.sort((a, b) => (a.order ?? 0) - (b.order ?? 0));
+	let next = core;
+	for (let i = phaseInterceptors.length - 1; i >= 0; i--) {
+		const handler = phaseInterceptors[i][phase];
+		const prevNext = next;
+		next = (currentCtx) => handler(currentCtx, (overrides) => {
+			if (!overrides) return prevNext(currentCtx);
+			if (overrides.context != null && typeof overrides.context === "object") overrides = {
+				...overrides,
+				context: Object.assign({}, currentCtx.context, overrides.context)
+			};
+			return prevNext(Object.assign({}, currentCtx, overrides));
+		});
+	}
+	return next(ctx);
+}
+/**
+* Wraps a pipeline with start → error → shutdown lifecycle hooks.
+* - `start` interceptors wrap the pipeline (onion pattern, root interceptors only).
+* - On error: `error` interceptors run (can transform/suppress the error).
+* - Always: `shutdown` interceptors run (success or failure).
+*/
+function wrapWithLifecycle(interceptors, command, input, pipeline, wrapErrorResult, signal, context, runtime, program, caller = "eval", pipelineState) {
+	const defaultSignal = typeof AbortSignal !== "undefined" ? AbortSignal.abort() : void 0;
+	const hasStart = interceptors.some((p) => p.start);
+	const hasError = interceptors.some((p) => p.error);
+	const hasShutdown = interceptors.some((p) => p.shutdown);
+	const effectivePipelineState = pipelineState ?? { phase: "start" };
+	if (!hasStart && !hasError && !hasShutdown) return pipeline(signal ?? defaultSignal, context);
+	let effectiveSignal = signal ?? defaultSignal;
+	let effectiveContext = context;
+	const runShutdown = (error, result) => {
+		if (!hasShutdown) return;
+		return runInterceptorChain("shutdown", interceptors, {
+			command,
+			input,
+			error,
+			result,
+			signal: effectiveSignal,
+			context: effectiveContext,
+			runtime,
+			program,
+			caller,
+			...effectivePipelineState
+		}, () => {});
+	};
+	const runError = (error) => {
+		if (!hasError) {
+			const s = runShutdown(error);
+			if (s instanceof Promise) return s.then(() => {
+				throw error;
+			});
+			throw error;
+		}
+		return thenMaybe(runInterceptorChain("error", interceptors, {
+			command,
+			input,
+			error,
+			signal: effectiveSignal,
+			context: effectiveContext,
+			runtime,
+			program,
+			caller,
+			...effectivePipelineState
+		}, () => ({ error })), (er) => {
+			if (er.error !== void 0) return thenMaybe(runShutdown(er.error), () => {
+				throw er.error;
+			});
+			const wrapped = wrapErrorResult ? wrapErrorResult(er.result) : er.result;
+			return thenMaybe(runShutdown(void 0, wrapped), () => wrapped);
+		});
+	};
+	const handleSuccess = (result) => {
+		const s = runShutdown(void 0, result);
+		if (s instanceof Promise) return s.then(() => result);
+		return result;
+	};
+	const startCtx = {
+		command,
+		signal: effectiveSignal,
+		context: effectiveContext,
+		runtime,
+		program,
+		input,
+		caller
+	};
+	let result;
+	try {
+		result = hasStart ? runInterceptorChain("start", interceptors, startCtx, (ctx) => {
+			effectiveSignal = ctx.signal;
+			effectiveContext = ctx.context;
+			return pipeline(ctx.signal, ctx.context);
+		}) : pipeline(effectiveSignal, effectiveContext);
+	} catch (e) {
+		return runError(e);
+	}
+	if (result instanceof Promise) return result.then(handleSuccess, runError);
+	return handleSuccess(result);
+}
+/**
+* Wraps a command-level pipeline (validate + execute) with error → shutdown lifecycle hooks.
+* Unlike `wrapWithLifecycle`, this has no `start` phase and uses the resolved command context.
+* Only interceptors exclusive to the command chain (not in root) should be passed here.
+*/
+function wrapWithCommandLifecycle(interceptors, command, input, pipeline, wrapErrorResult, signal, context, runtime, program, caller, pipelineState) {
+	const hasError = interceptors.some((p) => p.error);
+	const hasShutdown = interceptors.some((p) => p.shutdown);
+	if (!hasError && !hasShutdown) return pipeline();
+	const runShutdown = (error, result) => {
+		if (!hasShutdown) return;
+		return runInterceptorChain("shutdown", interceptors, {
+			command,
+			input,
+			error,
+			result,
+			signal,
+			context,
+			runtime,
+			program,
+			caller,
+			...pipelineState
+		}, () => {});
+	};
+	const runError = (error) => {
+		if (!hasError) {
+			const s = runShutdown(error);
+			if (s instanceof Promise) return s.then(() => {
+				throw error;
+			});
+			throw error;
+		}
+		return thenMaybe(runInterceptorChain("error", interceptors, {
+			command,
+			input,
+			error,
+			signal,
+			context,
+			runtime,
+			program,
+			caller,
+			...pipelineState
+		}, () => ({ error })), (er) => {
+			if (er.error !== void 0) return thenMaybe(runShutdown(er.error), () => {
+				throw er.error;
+			});
+			const wrapped = wrapErrorResult ? wrapErrorResult(er.result) : er.result;
+			return thenMaybe(runShutdown(void 0, wrapped), () => wrapped);
+		});
+	};
+	const handleSuccess = (result) => {
+		const s = runShutdown(void 0, result);
+		if (s instanceof Promise) return s.then(() => result);
+		return result;
+	};
+	let result;
+	try {
+		result = pipeline();
+	} catch (e) {
+		return runError(e);
+	}
+	if (result instanceof Promise) return result.then(handleSuccess, runError);
+	return handleSuccess(result);
+}
+//#endregion
+export { defineInterceptor, resolveRegisteredInterceptors, runInterceptorChain, toRegisteredInterceptor, wrapWithCommandLifecycle, wrapWithLifecycle };
+
+//# sourceMappingURL=interceptors.mjs.map