padrone 1.8.0 → 1.8.2

package/dist/test.d.mts

@@ -1,4 +1,4 @@
-import { p as AnyPadroneCommand, yt as PadroneRuntime } from "./index-C2n3k4e8.mjs";
+import { bt as PadroneRuntime, p as AnyPadroneCommand } from "./index-D-Dpz7l_.mjs";
 
 //#region src/feature/test.d.ts
 /**

package/dist/zod.d.mts

@@ -1,4 +1,4 @@
-import { lt as PadroneSchema } from "./index-C2n3k4e8.mjs";
+import { ut as PadroneSchema } from "./index-D-Dpz7l_.mjs";
 import * as z from "zod/v4";
 
 //#region src/schema/zod.d.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "padrone",
-  "version": "1.8.0",
+  "version": "1.8.2",
   "description": "Create type-safe, interactive CLI apps with Zod schemas",
   "license": "MIT",
   "type": "module",

package/src/cli/link.ts

@@ -8,6 +8,8 @@ import { detectShell, getRcFile, type ShellType, writeToRcFile } from '../util/s
 export const linkSchema = z.object({
   entry: z.string().optional().describe('Entry file (auto-detected from package.json bin field)'),
   name: z.string().optional().describe('Command name (auto-detected from package.json)'),
+  script: z.string().optional().describe('Use a package.json script instead of bin entry (e.g. "start", "dev")'),
+  pm: z.enum(['bun', 'npm', 'pnpm', 'yarn']).optional().describe('Package manager to use (auto-detected from lockfile)'),
   list: z.boolean().optional().default(false).describe('List all linked programs'),
   setup: z.boolean().optional().default(false).describe('Add ~/.padrone/bin to PATH in shell config'),
 });
@@ -58,6 +60,8 @@ export interface DetectedEntry {
   name: string;
   /** Full run command prefix parsed from scripts (e.g. "bun --conditions=padrone@dev") */
   runPrefix?: string;
+  /** When set, the shim should run this script via the package manager instead of the entry directly */
+  scriptCommand?: string;
 }
 
 function parseRunPrefix(script: string, entryRelative: string, dir: string): string | undefined {
@@ -74,12 +78,21 @@ function parseRunPrefix(script: string, entryRelative: string, dir: string): str
   return undefined;
 }
 
-export function detectEntry(dir: string): DetectedEntry | undefined {
+export function detectEntry(dir: string, options?: { script?: string }): DetectedEntry | undefined {
   const pkgPath = resolve(dir, 'package.json');
   if (!existsSync(pkgPath)) return undefined;
 
   try {
     const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+    const scripts = pkg.scripts as Record<string, string> | undefined;
+
+    // When --script is specified, use the package.json script directly
+    if (options?.script) {
+      const scriptName = options.script;
+      if (!scripts?.[scriptName]) return undefined;
+      const name = pkg.name || basename(dir);
+      return { entry: resolve(dir, 'package.json'), name, scriptCommand: scriptName };
+    }
 
     let entryRelative: string | undefined;
     let name: string | undefined;
@@ -110,7 +123,6 @@ export function detectEntry(dir: string): DetectedEntry | undefined {
 
     // Check start/dev scripts for runtime flags
     let runPrefix: string | undefined;
-    const scripts = pkg.scripts as Record<string, string> | undefined;
     if (scripts) {
       for (const key of ['start', 'dev']) {
         if (scripts[key]) {
@@ -157,30 +169,40 @@ async function setupPath(shell: ShellType): Promise<{ file: string; updated: boo
   return writeToRcFile(rcFile, snippet, PATH_BEGIN_MARKER, PATH_END_MARKER);
 }
 
-function detectRuntime(dir: string): string {
+function detectPackageManager(dir: string): string {
   let current = dir;
   while (true) {
     if (existsSync(resolve(current, 'bun.lock')) || existsSync(resolve(current, 'bun.lockb'))) return 'bun';
-    if (
-      existsSync(resolve(current, 'package-lock.json')) ||
-      existsSync(resolve(current, 'yarn.lock')) ||
-      existsSync(resolve(current, 'pnpm-lock.yaml'))
-    )
-      return 'node';
+    if (existsSync(resolve(current, 'pnpm-lock.yaml'))) return 'pnpm';
+    if (existsSync(resolve(current, 'yarn.lock'))) return 'yarn';
+    if (existsSync(resolve(current, 'package-lock.json'))) return 'npm';
     const parent = dirname(current);
     if (parent === current) break;
     current = parent;
   }
-  return 'node';
+  return 'npm';
+}
+
+function detectRuntime(dir: string): string {
+  const pm = detectPackageManager(dir);
+  return pm === 'bun' ? 'bun' : 'node';
 }
 
-function createShim(name: string, entry: string, dir: string, runPrefix?: string) {
+function createShim(name: string, entry: string, dir: string, runPrefix?: string, scriptCommand?: string, pm?: string) {
   mkdirSync(BIN_DIR, { recursive: true });
   const shimPath = resolve(BIN_DIR, sanitizeBinName(name));
 
-  const prefix = runPrefix ?? detectRuntime(dir);
-
-  const shim = ['#!/usr/bin/env sh', `# Linked by padrone — do not edit`, `${prefix} "${entry}" "$@"`, ''].join('\n');
+  let shim: string;
+  if (scriptCommand) {
+    const resolvedPm = pm ?? detectPackageManager(dir);
+    const cwdFlag = resolvedPm === 'npm' ? `--prefix="${dir}"` : resolvedPm === 'pnpm' ? `--dir="${dir}"` : `--cwd="${dir}"`;
+    shim = ['#!/usr/bin/env sh', `# Linked by padrone — do not edit`, `${resolvedPm} ${cwdFlag} run ${scriptCommand} -- "$@"`, ''].join(
+      '\n',
+    );
+  } else {
+    const prefix = runPrefix ?? detectRuntime(dir);
+    shim = ['#!/usr/bin/env sh', `# Linked by padrone — do not edit`, `${prefix} "${entry}" "$@"`, ''].join('\n');
+  }
 
   writeFileSync(shimPath, shim);
   chmodSync(shimPath, 0o755);
@@ -215,6 +237,7 @@ export async function runLink(args: LinkArgs, ctx: PadroneActionContext) {
   let entry: string;
   let name: string;
   let runPrefix: string | undefined;
+  let scriptCommand: string | undefined;
 
   const resolvedArg = args.entry ? resolve(dir, args.entry) : undefined;
 
@@ -230,15 +253,24 @@ export async function runLink(args: LinkArgs, ctx: PadroneActionContext) {
 
   if (targetDir || !resolvedArg) {
     // Detect entry from the target directory's package.json
-    const detected = detectEntry(targetDir ?? dir);
+    const detected = detectEntry(targetDir ?? dir, { script: args.script });
     if (!detected) {
-      error('Could not detect entry point. Provide an entry file or add a "bin" field to package.json.');
+      if (args.script) {
+        error(`Script "${args.script}" not found in package.json.`);
+      } else {
+        error('Could not detect entry point. Provide an entry file or add a "bin" field to package.json.');
+      }
       process.exit(1);
     }
     entry = detected.entry;
     name = sanitizeBinName(args.name || detected.name);
     runPrefix = detected.runPrefix;
+    scriptCommand = detected.scriptCommand;
   } else {
+    if (args.script) {
+      error('--script cannot be used with an explicit entry file.');
+      process.exit(1);
+    }
     // Explicit file path
     entry = resolvedArg;
     name = sanitizeBinName(args.name || basename(entry).replace(/\.[cm]?[jt]sx?$/, ''));
@@ -250,14 +282,14 @@ export async function runLink(args: LinkArgs, ctx: PadroneActionContext) {
     process.exit(1);
   }
 
-  if (!existsSync(entry)) {
+  if (!scriptCommand && !existsSync(entry)) {
     error(`Entry file not found: ${entry}`);
     process.exit(1);
   }
 
   const entryDir = targetDir ?? (existsSync(resolve(dirname(entry), 'package.json')) ? dirname(entry) : dir);
 
-  createShim(name, entry, entryDir, runPrefix);
+  createShim(name, entry, entryDir, runPrefix, scriptCommand, args.pm);
 
   const links = readLinks();
   links[name] = {
@@ -268,7 +300,7 @@ export async function runLink(args: LinkArgs, ctx: PadroneActionContext) {
   };
   writeLinks(links);
 
-  output(`Linked ${name} → ${entry}`);
+  output(`Linked ${name} → ${scriptCommand ? `${scriptCommand} (script)` : entry}`);
 
   if (!isInPath(BIN_DIR)) {
     if (args.setup) {

package/src/core/exec.ts

@@ -6,6 +6,8 @@ import type {
   InterceptorExecuteResult,
   InterceptorParseContext,
   InterceptorParseResult,
+  InterceptorPipelinePhase,
+  InterceptorRouteContext,
   InterceptorValidateContext,
   InterceptorValidateResult,
   PadroneActionContext,
@@ -15,7 +17,7 @@ import type {
 } from '../types/index.ts';
 import { getCommandRuntime } from './commands.ts';
 import { RoutingError, SignalError, ValidationError } from './errors.ts';
-import { resolveRegisteredInterceptors, runInterceptorChain, wrapWithLifecycle } from './interceptors.ts';
+import { resolveRegisteredInterceptors, runInterceptorChain, wrapWithCommandLifecycle, wrapWithLifecycle } from './interceptors.ts';
 import { errorResult, noop, thenMaybe, warnIfUnexpectedAsync, withDrain } from './results.ts';
 import { buildCommandArgs, formatIssueMessages, validateCommandArgs } from './validate.ts';
 
@@ -143,7 +145,9 @@ export function execCommand(
   const inertSignal = new AbortController().signal;
 
   // Pipeline state accumulated as phases complete — propagated to error/shutdown contexts.
-  const pipelineState: { rawArgs?: Record<string, unknown>; positionalArgs?: string[]; args?: unknown } = {};
+  const pipelineState: { phase: InterceptorPipelinePhase; rawArgs?: Record<string, unknown>; positionalArgs?: string[]; args?: unknown } = {
+    phase: 'start',
+  };
 
   const initialContext = evalOptions?.context;
 
@@ -152,6 +156,7 @@ export function execCommand(
   const factoryCache = new Map<RegisteredInterceptor, ResolvedInterceptor>();
   const rootRegistered = rootCommand.interceptors ?? [];
   const rootInterceptors = resolveRegisteredInterceptors(rootRegistered, factoryCache);
+  const rootInterceptorSet = new Set(rootInterceptors);
 
   const runPipeline = (signal: AbortSignal, pipelineContext: unknown) => {
     // ── Phase 1: Parse ──────────────────────────────────────────────────
@@ -173,72 +178,114 @@ export function execCommand(
     // ── Phases 2 & 3 chained after parse ────────────────────────────────
     const continueAfterParse = (parsed: InterceptorParseResult) => {
       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);
 
-      // ── Phase 2: Validate ───────────────────────────────────────────
-      const validateCtx: InterceptorValidateContext = {
+      // ── Phase 2: Route ──────────────────────────────────────────────
+      const routeCtx: InterceptorRouteContext = {
         ...parseCtx,
         command,
         rawArgs: parsed.rawArgs,
         positionalArgs: parsed.positionalArgs,
         context: context as object,
-        evalInteractive: evalOptions?.interactive,
-      };
-
-      const coreValidate = (validateCtx: InterceptorValidateContext): InterceptorValidateResult | Promise<InterceptorValidateResult> => {
-        const { args: preprocessedArgs, issues } = buildCommandArgs(validateCtx.command, validateCtx.rawArgs, validateCtx.positionalArgs);
-        if (issues) return { args: undefined, argsResult: { issues } as any };
-        const validated = validateCommandArgs(validateCtx.command, preprocessedArgs);
-        return thenMaybe(validated, (v) => v as InterceptorValidateResult);
       };
 
-      const validatedOrPromise = runInterceptorChain('validate', commandInterceptors, validateCtx, coreValidate);
-
-      // ── Phase 3: Execute (or handle validation errors) ──────────────
-      const continueAfterValidate = (v: InterceptorValidateResult) => {
-        pipelineState.args = v.args;
-        if (v.argsResult?.issues) return handleValidationIssues(v.argsResult as StandardSchemaV1.FailureResult, command, errorMode);
+      const routedOrPromise = runInterceptorChain('route', commandInterceptors, routeCtx, () => {});
 
-        const executeCtx: InterceptorExecuteContext = {
-          ...validateCtx,
-          args: v.args,
-        };
+      const continueAfterRoute = () => {
+        pipelineState.phase = 'route';
+        const runValidateAndExecute = () => {
+          // ── Phase 3: Validate ───────────────────────────────────────────
+          const validateCtx: InterceptorValidateContext = {
+            ...parseCtx,
+            command,
+            rawArgs: parsed.rawArgs,
+            positionalArgs: parsed.positionalArgs,
+            context: context as object,
+            evalInteractive: evalOptions?.interactive,
+          };
 
-        const coreExecute = (executeCtx: InterceptorExecuteContext): InterceptorExecuteResult => {
-          const handler = command.action ?? noop;
-          const effectiveRuntime = executeCtx.runtime;
-          const actionCtx: PadroneActionContext = {
-            runtime: effectiveRuntime,
-            command: executeCtx.command,
-            program: ctx.builder as any,
-            signal: executeCtx.signal,
-            context: executeCtx.context,
-            caller,
+          const coreValidate = (
+            validateCtx: InterceptorValidateContext,
+          ): InterceptorValidateResult | Promise<InterceptorValidateResult> => {
+            const { args: preprocessedArgs, issues } = buildCommandArgs(
+              validateCtx.command,
+              validateCtx.rawArgs,
+              validateCtx.positionalArgs,
+            );
+            if (issues) return { args: undefined, argsResult: { issues } as any };
+            const validated = validateCommandArgs(validateCtx.command, preprocessedArgs);
+            return thenMaybe(validated, (v) => v as InterceptorValidateResult);
           };
-          const result = handler(executeCtx.args as any, actionCtx);
-          return { result };
-        };
 
-        const executedOrPromise = runInterceptorChain('execute', commandInterceptors, executeCtx, coreExecute);
+          const validatedOrPromise = runInterceptorChain('validate', commandInterceptors, validateCtx, coreValidate);
+
+          // ── Phase 3: Execute (or handle validation errors) ──────────────
+          const continueAfterValidate = (v: InterceptorValidateResult) => {
+            pipelineState.phase = 'validate';
+            pipelineState.args = v.args;
+            if (v.argsResult?.issues) return handleValidationIssues(v.argsResult as StandardSchemaV1.FailureResult, command, errorMode);
 
-        return thenMaybe(executedOrPromise, (e) => {
-          const finalize = (result: unknown) =>
-            withDrain({
-              command: command as any,
+            const executeCtx: InterceptorExecuteContext = {
+              ...validateCtx,
               args: v.args,
-              argsResult: v.argsResult,
-              result,
+            };
+
+            const coreExecute = (executeCtx: InterceptorExecuteContext): InterceptorExecuteResult => {
+              const handler = command.action ?? noop;
+              const effectiveRuntime = executeCtx.runtime;
+              const actionCtx: PadroneActionContext = {
+                runtime: effectiveRuntime,
+                command: executeCtx.command,
+                program: ctx.builder as any,
+                signal: executeCtx.signal,
+                context: executeCtx.context,
+                caller,
+              };
+              const result = handler(executeCtx.args as any, actionCtx);
+              return { result };
+            };
+
+            pipelineState.phase = 'execute';
+            const executedOrPromise = runInterceptorChain('execute', commandInterceptors, executeCtx, coreExecute);
+
+            return thenMaybe(executedOrPromise, (e) => {
+              const finalize = (result: unknown) =>
+                withDrain({
+                  command: command as any,
+                  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) as any;
+        };
 
-          if (e.result instanceof Promise) return e.result.then(finalize);
-          return finalize(e.result);
-        });
+        return wrapWithCommandLifecycle(
+          commandOnlyInterceptors,
+          command,
+          resolvedInput,
+          runValidateAndExecute,
+          (result) => withDrain({ command: command as any, args: undefined, argsResult: undefined, result }),
+          signal,
+          context,
+          runtime,
+          ctx.builder,
+          caller,
+          pipelineState,
+        );
       };
 
-      return thenMaybe(warnIfUnexpectedAsync(validatedOrPromise, command), continueAfterValidate) as any;
+      return thenMaybe(routedOrPromise, continueAfterRoute) as any;
     };
 
     return thenMaybe(parsedOrPromise, continueAfterParse) as any;

package/src/core/interceptors.ts

@@ -6,6 +6,7 @@ import type {
   InterceptorErrorResult,
   InterceptorFactory,
   InterceptorMeta,
+  InterceptorPipelinePhase,
   InterceptorShutdownContext,
   InterceptorStartContext,
   PadroneInterceptorFn,
@@ -151,7 +152,7 @@ function deduplicateInterceptors(interceptors: ResolvedInterceptor[]): ResolvedI
  * into the context before passing to the next interceptor or core function.
  */
 export function runInterceptorChain<TCtx extends object, TResult>(
-  phase: 'start' | 'parse' | 'validate' | 'execute' | 'error' | 'shutdown',
+  phase: 'start' | 'parse' | 'route' | 'validate' | 'execute' | 'error' | 'shutdown',
   interceptors: ResolvedInterceptor[],
   ctx: TCtx,
   core: (ctx: TCtx) => TResult | Promise<TResult>,
@@ -204,13 +205,15 @@ export function wrapWithLifecycle<T>(
   runtime?: ResolvedPadroneRuntime,
   program?: AnyPadroneProgram,
   caller: 'cli' | 'eval' | 'run' | 'repl' | 'serve' | 'mcp' | 'tool' = 'eval',
-  pipelineState?: { rawArgs?: Record<string, unknown>; positionalArgs?: string[]; args?: unknown },
+  pipelineState?: { phase: InterceptorPipelinePhase; rawArgs?: Record<string, unknown>; positionalArgs?: string[]; args?: unknown },
 ): T | Promise<T> {
   const defaultSignal = typeof AbortSignal !== 'undefined' ? AbortSignal.abort() : (undefined as unknown as AbortSignal);
   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' as const };
+
   // Fast path: no lifecycle interceptors
   if (!hasStart && !hasError && !hasShutdown) return pipeline(signal ?? defaultSignal, context);
   // Mutable refs: start-phase interceptors can override signal and context (e.g., signal extension, auth),
@@ -230,7 +233,7 @@ export function wrapWithLifecycle<T>(
       runtime: runtime!,
       program: program!,
       caller,
-      ...pipelineState,
+      ...effectivePipelineState,
     };
     return runInterceptorChain('shutdown', interceptors, ctx, () => {});
   };
@@ -253,7 +256,7 @@ export function wrapWithLifecycle<T>(
       runtime: runtime!,
       program: program!,
       caller,
-      ...pipelineState,
+      ...effectivePipelineState,
     };
     const errorResult = runInterceptorChain('error', interceptors, ctx, (): InterceptorErrorResult => ({ error }));
     return thenMaybe(errorResult, (er) => {
@@ -306,3 +309,97 @@ export function wrapWithLifecycle<T>(
 
   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.
+ */
+export function wrapWithCommandLifecycle<T>(
+  interceptors: ResolvedInterceptor[],
+  command: AnyPadroneCommand,
+  input: string | undefined,
+  pipeline: () => T | Promise<T>,
+  wrapErrorResult: ((result: unknown) => T) | undefined,
+  signal: AbortSignal,
+  context: unknown,
+  runtime: ResolvedPadroneRuntime,
+  program: AnyPadroneProgram,
+  caller: 'cli' | 'eval' | 'run' | 'repl' | 'serve' | 'mcp' | 'tool',
+  pipelineState: { phase: InterceptorPipelinePhase; rawArgs?: Record<string, unknown>; positionalArgs?: string[]; args?: unknown },
+): T | Promise<T> {
+  const hasError = interceptors.some((p) => p.error);
+  const hasShutdown = interceptors.some((p) => p.shutdown);
+
+  if (!hasError && !hasShutdown) return pipeline();
+
+  const runShutdown = (error?: unknown, result?: unknown) => {
+    if (!hasShutdown) return;
+    const ctx: InterceptorShutdownContext = {
+      command,
+      input,
+      error,
+      result,
+      signal,
+      context: context as object,
+      runtime,
+      program,
+      caller,
+      ...pipelineState,
+    };
+    return runInterceptorChain('shutdown', interceptors, ctx, () => {});
+  };
+
+  const runError = (error: unknown): T | Promise<T> => {
+    if (!hasError) {
+      const s = runShutdown(error);
+      if (s instanceof Promise)
+        return s.then(() => {
+          throw error;
+        });
+      throw error;
+    }
+    const ctx: InterceptorErrorContext = {
+      command,
+      input,
+      error,
+      signal,
+      context: context as object,
+      runtime,
+      program,
+      caller,
+      ...pipelineState,
+    };
+    const errorResult = runInterceptorChain('error', interceptors, ctx, (): InterceptorErrorResult => ({ error }));
+    return thenMaybe(errorResult, (er) => {
+      if (er.error !== undefined) {
+        const s = runShutdown(er.error);
+        return thenMaybe(s as void | Promise<void>, () => {
+          throw er.error;
+        });
+      }
+      const wrapped = wrapErrorResult ? wrapErrorResult(er.result) : (er.result as T);
+      const s = runShutdown(undefined, wrapped);
+      return thenMaybe(s as void | Promise<void>, () => wrapped);
+    });
+  };
+
+  const handleSuccess = (result: T): T | Promise<T> => {
+    const s = runShutdown(undefined, result);
+    if (s instanceof Promise) return s.then(() => result);
+    return result;
+  };
+
+  let result: T | Promise<T>;
+  try {
+    result = pipeline();
+  } catch (e) {
+    return runError(e);
+  }
+
+  if (result instanceof Promise) {
+    return result.then(handleSuccess, runError);
+  }
+
+  return handleSuccess(result);
+}

package/src/extension/auto-output.ts

@@ -3,7 +3,14 @@ import { isAsyncIterator, isIterator } from '../core/results.ts';
 import type { OutputConfig } from '../output/output-indicator.ts';
 import { createOutputIndicator, formatDeclarativeOutput } from '../output/output-indicator.ts';
 import { resolveOutputFormat } from '../output/styling.ts';
-import type { AnyPadroneBuilder, CommandTypesBase, InterceptorExecuteContext, InterceptorExecuteResult } from '../types/index.ts';
+import type {
+  AnyPadroneBuilder,
+  CommandTypesBase,
+  InterceptorErrorContext,
+  InterceptorErrorResult,
+  InterceptorExecuteContext,
+  InterceptorExecuteResult,
+} from '../types/index.ts';
 
 // ── Helpers ─────────────────────────────────────────────────────────────
 
@@ -54,8 +61,20 @@ function outputAndCollect(value: unknown, output: (...args: unknown[]) => void):
 
 const autoOutputMeta = { id: 'padrone:auto-output', name: 'padrone:auto-output', order: -1100 } as const;
 
-function createAutoOutputInterceptor(outputConfig?: OutputConfig) {
+function createAutoOutputInterceptor(outputConfig?: OutputConfig, errorOutput?: boolean) {
   return defineInterceptor(autoOutputMeta, () => ({
+    error(ctx: InterceptorErrorContext, next: () => InterceptorErrorResult | Promise<InterceptorErrorResult>) {
+      const handleResult = (er: InterceptorErrorResult): InterceptorErrorResult => {
+        if (!er.error || errorOutput === false || ctx.caller !== 'cli' || ctx.phase !== 'execute') return er;
+        const message = er.error instanceof Error ? er.error.message : String(er.error);
+        ctx.runtime.error(message);
+        return er;
+      };
+
+      const result = next();
+      if (result instanceof Promise) return result.then(handleResult);
+      return handleResult(result);
+    },
     execute(ctx: InterceptorExecuteContext, next) {
       const outputCtx = resolveOutputFormat(ctx.runtime, ctx.caller);
       const indicator = createOutputIndicator(ctx.runtime.output, outputCtx);
@@ -115,6 +134,12 @@ export type PadroneAutoOutputOptions = {
    * ```
    */
   output?: OutputConfig;
+  /**
+   * Automatically print unhandled errors to stderr in CLI mode.
+   * Skips errors already handled by other extensions (routing, validation, signal).
+   * @default true
+   */
+  errorOutput?: boolean;
 };
 
 /**
@@ -141,6 +166,6 @@ export type PadroneAutoOutputOptions = {
 export function padroneAutoOutput(options?: PadroneAutoOutputOptions): <T extends CommandTypesBase>(builder: T) => T {
   const interceptor = options?.disabled
     ? defineInterceptor({ ...autoOutputMeta, disabled: true }, () => ({}))
-    : createAutoOutputInterceptor(options?.output);
+    : createAutoOutputInterceptor(options?.output, options?.errorOutput);
   return ((builder: AnyPadroneBuilder) => builder.intercept(interceptor)) as any;
 }

package/src/extension/progress-renderer.ts

@@ -265,6 +265,9 @@ export function createTerminalProgress(message: string, options?: PadroneProgres
       }, tickInterval)
     : undefined;
 
+  // Prevent the spinner timer from keeping the process alive on uncaught errors
+  if (timer && typeof timer === 'object' && 'unref' in timer) (timer as NodeJS.Timeout).unref();
+
   render();
 
   const clear = () => {

package/src/extension/progress.ts

@@ -198,7 +198,32 @@ function progressInterceptor(config: string | PadroneProgressConfig) {
             ctx.runtime.error = originalError;
           };
 
-          return next();
+          const onValidationFailure = (error: unknown) => {
+            if (indicator) {
+              cleanup(indicator, msgs!.success, msgs!.error, error, undefined, true);
+              teardown();
+            }
+          };
+
+          const checkResult = (result: any) => {
+            if (result.argsResult?.issues) onValidationFailure(new Error('Validation failed'));
+            return result;
+          };
+
+          let result: any;
+          try {
+            result = next();
+          } catch (err) {
+            onValidationFailure(err);
+            throw err;
+          }
+          if (result instanceof Promise) {
+            return result.then(checkResult, (err: unknown) => {
+              onValidationFailure(err);
+              throw err;
+            });
+          }
+          return checkResult(result);
         },
 
         execute(_ctx, next) {
@@ -259,6 +284,15 @@ function progressInterceptor(config: string | PadroneProgressConfig) {
           onSuccess(result!.result);
           return result;
         },
+
+        shutdown(ctx) {
+          // Safety net: if validate/execute cleanup paths were bypassed (e.g., outer interceptor
+          // threw during execute before reaching this interceptor's execute handler), stop the indicator.
+          if (indicator) {
+            cleanup(indicator, msgs!.success, msgs!.error, ctx.error, ctx.result, !!ctx.error);
+            teardown();
+          }
+        },
       };
     })
     .provides<{ progress: PadroneProgressIndicator }>();

package/src/index.ts

@@ -107,6 +107,7 @@ export type {
   InterceptorParseContext,
   InterceptorParseResult,
   InterceptorPhases,
+  InterceptorRouteContext,
   InterceptorShutdownContext,
   InterceptorStartContext,
   InterceptorValidateContext,

package/src/types/index.ts

@@ -34,6 +34,8 @@ export type {
   InterceptorParseContext,
   InterceptorParseResult,
   InterceptorPhases,
+  InterceptorPipelinePhase,
+  InterceptorRouteContext,
   InterceptorShutdownContext,
   InterceptorStartContext,
   InterceptorValidateContext,