padrone 1.7.1 → 1.8.1

package/dist/{index-C0Tab27T.d.mts → index-Guyz-CBm.d.mts}

@@ -1,4 +1,4 @@
-import { a as ColorConfig, n as HelpFormat, o as ColorTheme, t as HelpDetail } from "./formatter-DrvhDMrq.mjs";
+import { a as ColorConfig, n as HelpFormat, o as ColorTheme, t as HelpDetail } from "./formatter-CY3KrOEd.mjs";
 import { StandardJSONSchemaV1, StandardSchemaV1 } from "@standard-schema/spec";
 import { Tool } from "ai";
 
@@ -12,6 +12,16 @@ interface PadroneFieldMeta {
   flags?: readonly SingleChar[] | SingleChar;
   /** Multi-character alternative long names. Used with double dash (e.g. `--dry-run` for `--dryRun`). */
   alias?: readonly string[] | string;
+  /**
+   * Custom negative keyword(s) for boolean options. When provided, `--<keyword>` sets this option to `false`.
+   * Disables the default `--no-<option>` negation prefix. Set to `''` or `[]` to only disable the prefix.
+   * @example
+   * ```ts
+   * local: z.boolean().default(true).meta({ negative: 'remote' })
+   * // --remote sets local to false, --no-local is disabled
+   * ```
+   */
+  negative?: readonly string[] | string;
   deprecated?: boolean | string;
   hidden?: boolean;
   examples?: readonly unknown[];
@@ -322,105 +332,6 @@ type ResolvedPadroneRuntime = Required<Omit<PadroneRuntime, 'prompt' | 'interact
  */
 declare const REPL_SIGINT: unique symbol;
 //#endregion
-//#region src/feature/mcp.d.ts
-type PadroneMcpPreferences = {
-  /** Server name. Defaults to the program name. */name?: string; /** Server version. Defaults to the program version. */
-  version?: string;
-  /**
-   * Transport mode.
-   * - `'http'` — Start a Streamable HTTP server (default). Responds with `application/json` or `text/event-stream` based on the client's `Accept` header. Use `port` and `host` to configure.
-   * - `'stdio'` — Communicate over stdin/stdout with newline-delimited JSON.
-   */
-  transport?: 'http' | 'stdio'; /** HTTP port. Defaults to `3000`. Only used with `transport: 'http'`. */
-  port?: number; /** HTTP host. Defaults to `'127.0.0.1'`. Only used with `transport: 'http'`. */
-  host?: string; /** Base path for the MCP endpoint. Defaults to `'/mcp'`. Only used with `transport: 'http'`. */
-  basePath?: string; /** CORS allowed origin. Defaults to `'*'`. Set to a specific origin or `false` to disable CORS headers. Only used with HTTP transports. */
-  cors?: string | false;
-};
-//#endregion
-//#region src/feature/serve.d.ts
-type PadroneServePreferences = {
-  /** Port to listen on. Default: 3000 */port?: number; /** Host to bind to. Default: '127.0.0.1' */
-  host?: string; /** Base path prefix for all routes. Default: '/' */
-  basePath?: string; /** CORS allowed origin. Default: '*'. Set to `false` to disable CORS headers. */
-  cors?: string | false; /** Control built-in utility endpoints. All enabled by default. */
-  builtins?: {
-    /** GET /_health — returns 200 OK. */health?: boolean; /** GET /_help and GET /_help/:command — returns help text. */
-    help?: boolean; /** GET /_schema and GET /_schema/:command — returns JSON Schema. */
-    schema?: boolean; /** GET /_docs — Scalar OpenAPI docs viewer. */
-    docs?: boolean;
-  }; /** Hook to run before each request. Return a Response to short-circuit. */
-  onRequest?: (req: Request) => Response | void | Promise<Response | void>; /** Transform errors into responses. */
-  onError?: (error: unknown, req: Request) => Response;
-};
-//#endregion
-//#region src/feature/wrap.d.ts
-/**
- * Configuration for wrapping an external CLI tool.
- */
-type WrapConfig<TCommandArgs extends PadroneSchema = PadroneSchema, TWrapArgs extends PadroneSchema = TCommandArgs> = {
-  /**
-   * The command to execute (e.g., 'git', 'docker', 'npm').
-   */
-  command: string;
-  /**
-   * Optional fixed arguments that always precede the arguments (e.g., ['commit'] for 'git commit').
-   */
-  args?: string[];
-  /**
-   * Positional argument configuration for the external command.
-   * If not provided, defaults to the wrapping command's positional configuration.
-   */
-  positional?: string[];
-  /**
-   * Whether to inherit stdio streams (stdin, stdout, stderr) from the parent process.
-   * Default: true
-   */
-  inheritStdio?: boolean;
-  /**
-   * Optional schema that transforms command arguments to external CLI arguments.
-   * The schema's input type should match the command arguments, and its output type defines
-   * the arguments expected by the external command.
-   * If not provided, command arguments are passed through as-is.
-   */
-  schema?: TWrapArgs | ((commandArguments: TCommandArgs) => TWrapArgs);
-};
-/**
- * Result from executing a wrapped CLI tool.
- */
-type WrapResult = {
-  /**
-   * The exit code of the process.
-   */
-  exitCode: number;
-  /**
-   * Standard output from the process (only if inheritStdio is false).
-   */
-  stdout?: string;
-  /**
-   * Standard error from the process (only if inheritStdio is false).
-   */
-  stderr?: string;
-  /**
-   * Whether the process exited successfully (exit code 0).
-   */
-  success: boolean;
-};
-//#endregion
-//#region src/output/help.d.ts
-type HelpPreferences = {
-  format?: HelpFormat | 'auto';
-  detail?: HelpDetail;
-  theme?: ColorTheme | ColorConfig; /** Show all global commands and flags in full detail */
-  all?: boolean; /** Terminal width for text wrapping. Defaults to terminal columns or 80. */
-  width?: number; /** Terminal capabilities for auto-detection of ANSI and width. */
-  terminal?: {
-    columns?: number;
-    isTTY?: boolean;
-  }; /** Environment variables for auto-detection (e.g., NO_COLOR, CI). */
-  env?: Record<string, string | undefined>;
-};
-//#endregion
 //#region src/types/schema.d.ts
 /**
  * A schema that supports both validation (StandardSchemaV1) and JSON schema generation (StandardJSONSchemaV1).
@@ -569,6 +480,25 @@ type WithInterceptor<T, TProvides> = T extends {
 } ? T extends {
   run: any;
 } ? PadroneProgram<PN, N, PaN, A, R, C, any, AS, CTX, CTXP & TProvides> : PadroneBuilder<PN, N, PaN, A, R, C, any, AS, CTX, CTXP & TProvides> : T;
+/**
+ * Utility type for extensions that force the builder/program into async mode.
+ * Sets `TAsync` to `true` while preserving all other type params.
+ */
+type WithAsync<T> = T extends {
+  '~types': {
+    programName: infer PN extends string;
+    name: infer N extends string;
+    parentName: infer PaN extends string;
+    argsSchema: infer A extends PadroneSchema;
+    result: infer R;
+    commands: infer C extends [...AnyPadroneCommand[]];
+    async: any;
+    context: infer CTX;
+    contextProvided: infer CTXP;
+  };
+} ? T extends {
+  run: any;
+} ? PadroneProgram<PN, N, PaN, A, R, C, any, true, CTX, CTXP> : PadroneBuilder<PN, N, PaN, A, R, C, any, true, CTX, CTXP> : T;
 type PickCommandByName<TCommands extends AnyPadroneCommand[], TName extends string | AnyPadroneCommand> = TName extends AnyPadroneCommand ? TName : FlattenCommands<TCommands> extends infer Cmd extends AnyPadroneCommand ? Cmd extends AnyPadroneCommand ? TName extends GetCommandPathsAndAliases<Cmd> ? Cmd : never : never : never;
 type FlattenCommands<TCommands extends AnyPadroneCommand[]> = TCommands extends [] ? never : number extends TCommands['length'] ? IsAny<TCommands[number]> extends true ? never : TCommands[number] : TCommands[number] extends infer Cmd extends AnyPadroneCommand ? Cmd | FlattenCommands<Cmd['~types']['commands']> : never;
 /**
@@ -603,9 +533,250 @@ type RepathCommands<TCommands extends [...AnyPadroneCommand[]], TNewParentPath e
 type RepathCommand<TCommand extends AnyPadroneCommand, TNewParentName extends string> = PadroneCommand<TCommand['~types']['name'], TNewParentName, TCommand['~types']['argsSchema'], TCommand['~types']['result'], RepathCommands<TCommand['~types']['commands'], FullCommandName<TCommand['~types']['name'], TNewParentName>>, TCommand['~types']['aliases'], TCommand['~types']['async'], TCommand['~types']['context'], TCommand['~types']['contextProvided']>;
 type PickCommandByPossibleCommands<TCommands extends AnyPadroneCommand[], TCommand extends PossibleCommands<TCommands, true, true> | SafeString> = CommandIsUnknownable<TCommand> extends true ? FlattenCommands<TCommands> : TCommand extends AnyPadroneCommand ? TCommand : TCommand extends string ? TCommand extends GetCommandPathsOrAliases<TCommands> ? PickCommandByName<TCommands, TCommand> : SplitLastSpace<TCommand> extends [infer Prefix extends string, infer Rest] ? IsNever<Rest> extends true ? PickCommandByName<TCommands, Prefix> : PickCommandByPossibleCommands<TCommands, Prefix> : never : never;
 //#endregion
+//#region src/extension/logger.d.ts
+/** Log level values ordered by severity. */
+type PadroneLogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'silent';
+/** Logger instance injected into the command context. */
+type PadroneLogger = {
+  trace: (...args: unknown[]) => void;
+  debug: (...args: unknown[]) => void;
+  info: (...args: unknown[]) => void;
+  warn: (...args: unknown[]) => void;
+  error: (...args: unknown[]) => void; /** The current effective log level. */
+  level: PadroneLogLevel; /** Create a child logger with a prefix label. */
+  child: (label: string) => PadroneLogger;
+};
+/** Configuration for the logger extension. */
+type PadroneLoggerConfig = {
+  /** Minimum log level to output. Defaults to `'info'`. */level?: PadroneLogLevel; /** Prefix prepended to every log message. */
+  prefix?: string; /** Include timestamps in log output. Defaults to `false`. */
+  timestamps?: boolean;
+};
+/** Builder/program type after applying `padroneLogger()`. Adds `{ logger: PadroneLogger }` to the command context. */
+type WithLogger<T> = WithInterceptor<T, {
+  logger: PadroneLogger;
+}>;
+/**
+ * Extension that injects a structured logger into the command context.
+ *
+ * The logger respects a configurable log level threshold, supports prefixed
+ * child loggers, and routes output through the runtime's `output`/`error`
+ * functions so it works in any environment (terminal, test, web).
+ *
+ * Supports CLI flags for runtime level overrides:
+ * - `--trace` → sets level to `trace`
+ * - `--verbose` or `--debug` → sets level to `debug`
+ * - `--silent` or `--quiet` → sets level to `silent`
+ * - `--log-level=<level>` → sets an explicit level (`trace`, `debug`, `info`, `warn`, `error`, `silent`)
+ *
+ * CLI flags take precedence over the programmatic config.
+ *
+ * Provides `{ logger: PadroneLogger }` on the command context.
+ * Access it in action handlers as `ctx.context.logger`.
+ *
+ * Usage:
+ * ```ts
+ * createPadrone('my-cli')
+ *   .extend(padroneLogger({ level: 'info' }))
+ *   .command('sync', (c) =>
+ *     c.action((_args, ctx) => {
+ *       ctx.context.logger.info('starting sync');
+ *       const db = ctx.context.logger.child('db');
+ *       db.debug('connecting...');
+ *     })
+ *   )
+ * ```
+ *
+ * Then run:
+ * ```sh
+ * my-cli sync --verbose      # debug level
+ * my-cli sync --quiet        # silent
+ * my-cli sync --log-level=warn
+ * ```
+ */
+declare function padroneLogger<T extends CommandTypesBase>(config?: PadroneLoggerConfig): (builder: T) => WithLogger<T>;
+//#endregion
+//#region src/extension/tracing.d.ts
+/** Minimal subset of OTEL `SpanStatusCode`. */
+type SpanStatusCode = 0 | 1 | 2;
+/** Minimal subset of OTEL `SpanStatus`. */
+type SpanStatus = {
+  code: SpanStatusCode;
+  message?: string;
+};
+/** Minimal subset of OTEL `Span`. */
+interface OtelSpan {
+  setAttribute(key: string, value: string | number | boolean): this;
+  addEvent(name: string, attributes?: Record<string, string | number | boolean>): this;
+  setStatus(status: SpanStatus): this;
+  recordException(error: unknown): this;
+  end(): void;
+  spanContext(): {
+    traceId: string;
+    spanId: string;
+  };
+}
+/** Minimal subset of OTEL `Tracer`. */
+interface OtelTracer {
+  startSpan(name: string): OtelSpan;
+}
+/** Minimal subset of OTEL `TracerProvider`. */
+interface OtelTracerProvider {
+  getTracer(name: string, version?: string): OtelTracer;
+}
+/** Tracing handle injected into the command context. */
+type PadroneTracer = {
+  /** The underlying OTEL tracer. */tracer: OtelTracer; /** Root span covering the full command execution. */
+  rootSpan: OtelSpan; /** Run `fn` inside a child span that is automatically ended when `fn` returns (or rejects). */
+  span: <T>(name: string, fn: (span: OtelSpan) => T) => T;
+};
+/** Configuration for the tracing extension. */
+type PadroneTracingConfig = {
+  /** OTEL `TracerProvider`. Required — there is no global fallback. */provider: OtelTracerProvider; /** Service / tracer name. Defaults to the CLI program name. */
+  serviceName?: string;
+};
+/** Builder/program type after applying `padroneTracing()`. Adds `{ tracing: PadroneTracer }` to the command context. */
+type WithTracing<T> = WithInterceptor<T, {
+  tracing: PadroneTracer;
+}>;
+/**
+ * Extension that adds OpenTelemetry tracing to command execution.
+ *
+ * Creates a root span for each command invocation and provides a `PadroneTracer`
+ * on the command context for creating child spans in action handlers.
+ *
+ * When used with `padroneLogger()`, the logger automatically emits span events
+ * for each log call — no extra configuration needed. The logger detects the
+ * tracing context and bridges log output to span events.
+ *
+ * Uses minimal OTEL-compatible interfaces — pass any `TracerProvider` that
+ * implements `getTracer()`. Works with `@opentelemetry/api` or compatible
+ * libraries.
+ *
+ * Provides `{ tracing: PadroneTracer }` on the command context.
+ * Access it in action handlers as `ctx.context.tracing`.
+ *
+ * Usage:
+ * ```ts
+ * import { trace } from '@opentelemetry/api';
+ *
+ * createPadrone('my-cli')
+ *   .extend(padroneTracing({ provider: trace.getTracerProvider() }))
+ *   .extend(padroneLogger())
+ *   .command('deploy', (c) =>
+ *     c.action((_args, ctx) => {
+ *       ctx.context.logger.info('deploying');  // also emits a span event
+ *       ctx.context.tracing.span('build', (span) => {
+ *         span.setAttribute('target', 'production');
+ *       });
+ *     })
+ *   )
+ * ```
+ */
+declare function padroneTracing<T extends CommandTypesBase>(config: PadroneTracingConfig): (builder: T) => WithTracing<T>;
+//#endregion
+//#region src/feature/mcp.d.ts
+type PadroneMcpPreferences = {
+  /** Server name. Defaults to the program name. */name?: string; /** Server version. Defaults to the program version. */
+  version?: string;
+  /**
+   * Transport mode.
+   * - `'http'` — Start a Streamable HTTP server (default). Responds with `application/json` or `text/event-stream` based on the client's `Accept` header. Use `port` and `host` to configure.
+   * - `'stdio'` — Communicate over stdin/stdout with newline-delimited JSON.
+   */
+  transport?: 'http' | 'stdio'; /** HTTP port. Defaults to `3000`. Only used with `transport: 'http'`. */
+  port?: number; /** HTTP host. Defaults to `'127.0.0.1'`. Only used with `transport: 'http'`. */
+  host?: string; /** Base path for the MCP endpoint. Defaults to `'/mcp'`. Only used with `transport: 'http'`. */
+  basePath?: string; /** CORS allowed origin. Defaults to `'*'`. Set to a specific origin or `false` to disable CORS headers. Only used with HTTP transports. */
+  cors?: string | false;
+};
+//#endregion
+//#region src/feature/serve.d.ts
+type PadroneServePreferences = {
+  /** Port to listen on. Default: 3000 */port?: number; /** Host to bind to. Default: '127.0.0.1' */
+  host?: string; /** Base path prefix for all routes. Default: '/' */
+  basePath?: string; /** CORS allowed origin. Default: '*'. Set to `false` to disable CORS headers. */
+  cors?: string | false; /** Control built-in utility endpoints. All enabled by default. */
+  builtins?: {
+    /** GET /_health — returns 200 OK. */health?: boolean; /** GET /_help and GET /_help/:command — returns help text. */
+    help?: boolean; /** GET /_schema and GET /_schema/:command — returns JSON Schema. */
+    schema?: boolean; /** GET /_docs — Scalar OpenAPI docs viewer. */
+    docs?: boolean;
+  }; /** Hook to run before each request. Return a Response to short-circuit. */
+  onRequest?: (req: Request) => Response | void | Promise<Response | void>; /** Transform errors into responses. */
+  onError?: (error: unknown, req: Request) => Response;
+};
+//#endregion
+//#region src/feature/wrap.d.ts
+/**
+ * Configuration for wrapping an external CLI tool.
+ */
+type WrapConfig<TCommandArgs extends PadroneSchema = PadroneSchema, TWrapArgs extends PadroneSchema = TCommandArgs> = {
+  /**
+   * The command to execute (e.g., 'git', 'docker', 'npm').
+   */
+  command: string;
+  /**
+   * Optional fixed arguments that always precede the arguments (e.g., ['commit'] for 'git commit').
+   */
+  args?: string[];
+  /**
+   * Positional argument configuration for the external command.
+   * If not provided, defaults to the wrapping command's positional configuration.
+   */
+  positional?: string[];
+  /**
+   * Whether to inherit stdio streams (stdin, stdout, stderr) from the parent process.
+   * Default: true
+   */
+  inheritStdio?: boolean;
+  /**
+   * Optional schema that transforms command arguments to external CLI arguments.
+   * The schema's input type should match the command arguments, and its output type defines
+   * the arguments expected by the external command.
+   * If not provided, command arguments are passed through as-is.
+   */
+  schema?: TWrapArgs | ((commandArguments: TCommandArgs) => TWrapArgs);
+};
+/**
+ * Result from executing a wrapped CLI tool.
+ */
+type WrapResult = {
+  /**
+   * The exit code of the process.
+   */
+  exitCode: number;
+  /**
+   * Standard output from the process (only if inheritStdio is false).
+   */
+  stdout?: string;
+  /**
+   * Standard error from the process (only if inheritStdio is false).
+   */
+  stderr?: string;
+  /**
+   * Whether the process exited successfully (exit code 0).
+   */
+  success: boolean;
+};
+//#endregion
+//#region src/output/help.d.ts
+type HelpPreferences = {
+  format?: HelpFormat | 'auto';
+  detail?: HelpDetail;
+  theme?: ColorTheme | ColorConfig; /** Show all global commands and flags in full detail */
+  all?: boolean; /** Terminal width for text wrapping. Defaults to terminal columns or 80. */
+  width?: number; /** Terminal capabilities for auto-detection of ANSI and width. */
+  terminal?: {
+    columns?: number;
+    isTTY?: boolean;
+  }; /** Environment variables for auto-detection (e.g., NO_COLOR, CI). */
+  env?: Record<string, string | undefined>;
+};
+//#endregion
 //#region src/types/interceptor.d.ts
 /** Base context shared across all interceptor phases within a single execution. */
-type InterceptorBaseContext<TContext = unknown> = {
+type InterceptorBaseContext<TContext = object> = {
   /** The resolved command for this execution. In the parse phase, this is the root program. */command: AnyPadroneCommand; /** The raw CLI input string (undefined when invoked without input). */
   input: string | undefined; /** Cancellation signal that fires when the process receives a termination signal. */
   signal: AbortSignal; /** User-defined context object, resolved through the command's parent chain. */
@@ -615,15 +786,20 @@ type InterceptorBaseContext<TContext = unknown> = {
   caller: PadroneActionContext['caller'];
 };
 /** Context for the parse phase. */
-type InterceptorParseContext<TContext = unknown> = InterceptorBaseContext<TContext>;
+type InterceptorParseContext<TContext = object> = InterceptorBaseContext<TContext>;
 /** Result returned by the parse phase's `next()`. */
 type InterceptorParseResult = {
   command: AnyPadroneCommand;
   rawArgs: Record<string, unknown>;
   positionalArgs: string[];
 };
+/** Context for the route phase. Runs after the target command is resolved, before validation. */
+type InterceptorRouteContext<TContext = object> = InterceptorBaseContext<TContext> & {
+  /** Raw named arguments extracted by the parser. */rawArgs: Record<string, unknown>; /** Positional argument strings extracted by the parser. */
+  positionalArgs: string[];
+};
 /** Context for the validate phase. */
-type InterceptorValidateContext<TContext = unknown> = InterceptorBaseContext<TContext> & {
+type InterceptorValidateContext<TContext = object> = InterceptorBaseContext<TContext> & {
   /** Raw named arguments extracted by the parser. Mutable — modify before `next()` to inject/override values. */rawArgs: Record<string, unknown>; /** Positional argument strings extracted by the parser. */
   positionalArgs: string[]; /** Interactive mode override (set by the interactive extension when `--interactive` / `-i` flag is used). */
   interactive?: boolean; /** Interactive mode preference from eval/cli options. Available for the interactive extension. */
@@ -635,7 +811,7 @@ type InterceptorValidateResult<TArgs = unknown> = {
   argsResult: StandardSchemaV1.Result<TArgs>;
 };
 /** Context for the execute phase. Includes validate context fields (rawArgs, positionalArgs). */
-type InterceptorExecuteContext<TArgs = unknown, TContext = unknown> = InterceptorValidateContext<TContext> & {
+type InterceptorExecuteContext<TArgs = unknown, TContext = object> = InterceptorValidateContext<TContext> & {
   /** Validated arguments that will be passed to the action. Mutable — modify before `next()` to override. */args: TArgs;
 };
 /** Result returned by the execute phase's `next()`. */
@@ -643,9 +819,9 @@ type InterceptorExecuteResult<TResult = unknown> = {
   result: TResult;
 };
 /** Context for the start phase. Runs before parsing, wraps the entire pipeline. */
-type InterceptorStartContext<TContext = unknown> = InterceptorBaseContext<TContext>;
+type InterceptorStartContext<TContext = object> = InterceptorBaseContext<TContext>;
 /** Context for the error phase. Called when the pipeline throws. Includes pipeline state accumulated before the error. */
-type InterceptorErrorContext<TContext = unknown> = InterceptorBaseContext<TContext> & {
+type InterceptorErrorContext<TContext = object> = InterceptorBaseContext<TContext> & {
   /** The error that was thrown. */error: unknown; /** Raw named arguments (available if parse completed). */
   rawArgs?: Record<string, unknown>; /** Positional argument strings (available if parse completed). */
   positionalArgs?: string[]; /** Validated arguments (available if validate completed). */
@@ -657,7 +833,7 @@ type InterceptorErrorResult<TResult = unknown> = {
   result?: TResult;
 };
 /** Context for the shutdown phase. Always runs after the pipeline (success or failure). Includes pipeline state accumulated before completion. */
-type InterceptorShutdownContext<TResult = unknown, TContext = unknown> = InterceptorBaseContext<TContext> & {
+type InterceptorShutdownContext<TResult = unknown, TContext = object> = InterceptorBaseContext<TContext> & {
   /** The error, if the pipeline failed (after error phase processing). */error?: unknown; /** The pipeline result, if it succeeded. */
   result?: TResult; /** Raw named arguments (available if parse completed). */
   rawArgs?: Record<string, unknown>; /** Positional argument strings (available if parse completed). */
@@ -708,13 +884,19 @@ type InterceptorMeta = {
  * - `TArgs` — the validated arguments type (output of the args schema).
  * - `TResult` — the command's return type.
  */
-type InterceptorPhases<TArgs = unknown, TResult = unknown, TContext = unknown> = {
+type InterceptorPhases<TArgs = unknown, TResult = unknown, TContext = object> = {
   /**
    * Runs before the pipeline (parse → validate → execute). `next()` proceeds to the pipeline.
    * Root interceptors only. Use for startup tasks like telemetry, update checks, or global config loading.
    */
   start?: InterceptorPhaseHandler<InterceptorStartContext<TContext>, unknown>; /** Intercepts command routing and raw argument extraction. */
-  parse?: InterceptorPhaseHandler<InterceptorParseContext<TContext>, InterceptorParseResult>; /** Intercepts argument preprocessing and schema validation. Interactive prompting is handled by the interactive extension. */
+  parse?: InterceptorPhaseHandler<InterceptorParseContext<TContext>, InterceptorParseResult>;
+  /**
+   * Runs after the target command is resolved (post-parse), before validation.
+   * Use for per-command setup: authorization, resource loading, logging, etc.
+   * Root and command-level interceptors both participate.
+   */
+  route?: InterceptorPhaseHandler<InterceptorRouteContext<TContext>, void>; /** Intercepts argument preprocessing and schema validation. Interactive prompting is handled by the interactive extension. */
   validate?: InterceptorPhaseHandler<InterceptorValidateContext<TContext>, InterceptorValidateResult<TArgs>, InterceptorValidateResult>; /** Intercepts handler execution. */
   execute?: InterceptorPhaseHandler<InterceptorExecuteContext<TArgs, TContext>, InterceptorExecuteResult<TResult>, InterceptorExecuteResult>;
   /**
@@ -732,7 +914,7 @@ type InterceptorPhases<TArgs = unknown, TResult = unknown, TContext = unknown> =
  * Factory function that creates phase handlers for an interceptor.
  * Called once per command execution — the closure provides typed, scoped cross-phase state across phases.
  */
-type InterceptorFactory<TArgs = unknown, TResult = unknown, TContext = unknown> = () => InterceptorPhases<TArgs, TResult, TContext>;
+type InterceptorFactory<TArgs = unknown, TResult = unknown, TContext = object> = () => InterceptorPhases<TArgs, TResult, TContext>;
 /**
  * A self-contained interceptor value: a factory function with static metadata as own properties.
  * Created via `defineInterceptor(meta, factory)`. This is the distributable form — a single
@@ -741,7 +923,7 @@ type InterceptorFactory<TArgs = unknown, TResult = unknown, TContext = unknown>
  * Also accepted directly by `.intercept()` as the single-argument form.
  * Call `.provides<T>()` to brand it as a context-providing interceptor.
  */
-type PadroneInterceptorFn<TArgs = unknown, TResult = unknown, TContext = unknown> = InterceptorFactory<TArgs, TResult, TContext> & InterceptorMeta & {
+type PadroneInterceptorFn<TArgs = unknown, TResult = unknown, TContext = object> = InterceptorFactory<TArgs, TResult, TContext> & InterceptorMeta & {
   /** Brand this interceptor as providing additional context of type `TProvides`. No-op at runtime; purely a type-level cast. */provides: <TProvides>() => PadroneContextInterceptor<TProvides, TArgs, TResult, TContext>;
   /**
    * Brand this interceptor as requiring context of type `TRequires` to be available.
@@ -757,7 +939,7 @@ type PadroneInterceptorFn<TArgs = unknown, TResult = unknown, TContext = unknown
  *
  * Create with `defineInterceptor(meta, factory)` or pass `(meta, factory)` directly to `.intercept()`.
  */
-type PadroneInterceptor<TArgs = unknown, TResult = unknown, TContext = unknown> = PadroneInterceptorFn<TArgs, TResult, TContext>;
+type PadroneInterceptor<TArgs = unknown, TResult = unknown, TContext = object> = PadroneInterceptorFn<TArgs, TResult, TContext>;
 /**
  * A context-providing interceptor. Carries a phantom `'~context'` brand declaring what it adds
  * to the command context. When registered via `.intercept()`, the builder's context type is
@@ -766,7 +948,7 @@ type PadroneInterceptor<TArgs = unknown, TResult = unknown, TContext = unknown>
  * Created by calling `.provides<T>()` on a `PadroneInterceptorFn`.
  * Chain `.requires<T>()` to also declare context dependencies.
  */
-type PadroneContextInterceptor<TProvides = unknown, TArgs = unknown, TResult = unknown, TContext = unknown> = Omit<PadroneInterceptorFn<TArgs, TResult, TContext>, 'requires'> & InterceptorFactory<TArgs, TResult, TContext> & {
+type PadroneContextInterceptor<TProvides = unknown, TArgs = unknown, TResult = unknown, TContext = object> = Omit<PadroneInterceptorFn<TArgs, TResult, TContext>, 'requires'> & InterceptorFactory<TArgs, TResult, TContext> & {
   /** Phantom brand — declares the context type this interceptor provides. */'~context': TProvides; /** Like `.requires()` on `PadroneInterceptorFn` but preserves the `'~context'` brand. */
   requires: <TRequires>() => PadroneContextInterceptor<TProvides, TArgs, TResult, TContext> & InterceptorRequiresBrand<TRequires>;
 };
@@ -1121,6 +1303,9 @@ type PadroneBuilderMethods<TProgramName extends string, TName extends string, TP
   wrap: <TWrapArgs extends PadroneSchema = TArgs>(config: WrapConfig<TArgs, TWrapArgs>) => BuilderOrProgram<TReturn, TProgramName, TName, TParentName, TArgs, Promise<WrapResult>, TCommands, TParentArgs, TAsync, TContext, TContextProvided>; /** Add or override a subcommand. Pass a builder function to define its schema, action, and nested commands. @category Builder */
   command: {
     <TNameNested extends string, TAliases extends string[] = [], TBuilder extends CommandTypesBase = DefaultCommandBuilder<TProgramName, TNameNested, FullCommandName<TName, TParentName>, TArgs, TCommands, TContext & TContextProvided>>(name: TNameNested | readonly [TNameNested, ...TAliases], builderFn?: (builder: InitialCommandBuilder<TProgramName, TNameNested, FullCommandName<TName, TParentName>, TArgs, TCommands, TContext & TContextProvided>) => TBuilder): BuilderOrProgram<TReturn, TProgramName, TName, TParentName, TArgs, TRes, TCommands extends [] ? [WithAliases<TBuilder['~types']['command'], TAliases>] : AnyPadroneCommand[] extends TCommands ? [WithAliases<TBuilder['~types']['command'], TAliases>] : ReplaceOrAppendCommand<TCommands, TNameNested, WithAliases<TBuilder['~types']['command'], ResolvedAliases<TCommands, TNameNested, TAliases>>>, TParentArgs, TAsync, TContext, TContextProvided>;
+    <TNameNested extends string, TAliases extends string[] = [], TBuilder extends CommandTypesBase = CommandTypesBase, TReq = unknown>(name: TNameNested | readonly [TNameNested, ...TAliases], builderFn: ((builder: any) => TBuilder) & {
+      '~contextRequires': (ctx: TReq) => void;
+    }): TContext & TContextProvided extends TReq ? BuilderOrProgram<TReturn, TProgramName, TName, TParentName, TArgs, TRes, TCommands extends [] ? [WithAliases<TBuilder['~types']['command'], TAliases>] : AnyPadroneCommand[] extends TCommands ? [WithAliases<TBuilder['~types']['command'], TAliases>] : ReplaceOrAppendCommand<TCommands, TNameNested, WithAliases<TBuilder['~types']['command'], ResolvedAliases<TCommands, TNameNested, TAliases>>>, TParentArgs, TAsync, TContext, TContextProvided> : DefineCommandRequiresError;
     <TNameNested extends string, TAliases extends string[] = [], TBuilder extends CommandTypesBase = CommandTypesBase>(name: TNameNested | readonly [TNameNested, ...TAliases], builderFn?: (builder: any) => TBuilder): BuilderOrProgram<TReturn, TProgramName, TName, TParentName, TArgs, TRes, TCommands extends [] ? [WithAliases<TBuilder['~types']['command'], TAliases>] : AnyPadroneCommand[] extends TCommands ? [WithAliases<TBuilder['~types']['command'], TAliases>] : ReplaceOrAppendCommand<TCommands, TNameNested, WithAliases<TBuilder['~types']['command'], ResolvedAliases<TCommands, TNameNested, TAliases>>>, TParentArgs, TAsync, TContext, TContextProvided>;
   }; /** Mount an existing program as a subcommand, optionally transforming the context. @category Builder */
   mount: {
@@ -1175,6 +1360,28 @@ type AnyPadroneProgram = PadroneProgram<string, string, string, any, any, [...An
  * ```
  */
 type PadroneExtension<TIn extends CommandTypesBase = CommandTypesBase, TOut extends CommandTypesBase = TIn> = (builder: TIn) => TOut;
+/**
+ * Default context type for commands defined with `defineCommand()`.
+ * Includes optional context properties provided by common extensions (logger, tracing, progress).
+ *
+ * Override globally via module augmentation to add your application's context:
+ * ```ts
+ * declare module 'padrone' {
+ *   interface DefineCommandContext {
+ *     db: Database;
+ *   }
+ * }
+ * ```
+ */
+interface DefineCommandContext {
+  logger?: PadroneLogger;
+  tracing?: PadroneTracer;
+  progress?: PadroneProgressIndicator;
+}
+/** Error brand returned by `.command()` when a `defineCommand.requires()` context requirement is not satisfied. */
+type DefineCommandRequiresError = {
+  readonly '~error': 'Required context not satisfied. Ensure required interceptors are registered on the program.';
+};
 /**
  * Type for a command builder callback used with `.command()`.
  * Use this when defining commands in separate files where full return type inference isn't needed.
@@ -1192,8 +1399,25 @@ type PadroneExtension<TIn extends CommandTypesBase = CommandTypesBase, TOut exte
  * createPadrone('test').command('my-command', myCommand)
  * ```
  */
-type DefineCommand<TContext = unknown, TParentArgs extends PadroneSchema = PadroneSchema> = (builder: PadroneBuilder<string, string, string, PadroneSchema<void>, void, [], TParentArgs, false, TContext>) => CommandTypesBase;
+type DefineCommand<TContext = unknown, TParentArgs extends PadroneSchema = PadroneSchema> = (builder: PadroneBuilder<string, string, string, PadroneSchema<void>, void, [], TParentArgs, false, TContext, DefineCommandContext>) => CommandTypesBase;
+/**
+ * Builder returned by `defineCommand()` (no-arg form).
+ * Call `.requires<T>()` to declare context dependencies, then `.command()` to provide the builder callback.
+ *
+ * @example
+ * ```ts
+ * const adminCommand = defineCommand()
+ *   .requires<{ adminDb: AdminDB }>()
+ *   .define((c) => c.action((_args, ctx) => ctx.context.adminDb.query(...)));
+ * ```
+ */
+type DefineCommandBuilder<TContextProvided = DefineCommandContext, TBrand = unknown> = {
+  /** Declare context types this command requires. Purely type-level — no runtime effect. */requires: <TRequires>() => DefineCommandBuilder<DefineCommandContext & TRequires, {
+    '~contextRequires': (ctx: TRequires) => void;
+  }>; /** Provide the command builder callback. */
+  define: <TContext = unknown, TOut extends CommandTypesBase = CommandTypesBase>(fn: (builder: PadroneBuilder<string, string, string, PadroneSchema<void>, void, [], any, false, TContext, TContextProvided>) => TOut) => typeof fn & TBrand;
+};
 type DefaultArgs = Record<string, unknown> | void;
 //#endregion
-export { PadroneProgressIndicator as $, InterceptorShutdownContext as A, WithCommand as B, InterceptorExecuteContext as C, InterceptorParseContext as D, InterceptorMeta as E, PadroneInterceptor as F, WrapResult as G, AsyncPadroneSchema as H, PadroneInterceptorFn as I, InteractiveMode as J, PadroneServePreferences as K, Drained as L, InterceptorValidateContext as M, InterceptorValidateResult as N, InterceptorParseResult as O, PadroneContextInterceptor as P, PadroneBarConfig as Q, PickCommandByName as R, InterceptorErrorResult as S, InterceptorFactory as T, PadroneSchema as U, WithInterceptor as V, WrapConfig as W, PadroneBarAnimation as X, InteractivePromptConfig as Y, PadroneBarChar as Z, ExtractInterceptorContext as _, PadroneExtension as a, PadroneSpinnerConfig as at, InterceptorDefBuilder as b, PadroneDrainResult as c, AnyPadroneCommand as d, PadroneProgressOptions as et, CommandTypesBase as f, PadroneProgramMeta as g, PadroneCommand as h, PadroneBuilder as i, PadroneSignal as it, InterceptorStartContext as j, InterceptorPhases as k, PadroneParseResult as l, PadroneActionContext as m, AnyPadroneProgram as n, PadroneProgressUpdate as nt, PadroneProgram as o, PadroneSpinnerPreset as ot, GetArgsMeta as p, PadroneMcpPreferences as q, DefineCommand as r, PadroneRuntime as rt, PadroneCommandResult as s, REPL_SIGINT as st, AnyPadroneBuilder as t, PadroneProgressShow as tt, PadroneReplPreferences as u, ExtractInterceptorRequires as v, InterceptorExecuteResult as w, InterceptorErrorContext as x, InterceptorBaseContext as y, PossibleCommands as z };
-//# sourceMappingURL=index-C0Tab27T.d.mts.map
+export { PadroneLogger as $, InterceptorParseResult as A, RegisteredInterceptor as B, InterceptorErrorContext as C, PadroneSpinnerPreset as Ct, InterceptorFactory as D, InterceptorExecuteResult as E, InterceptorValidateContext as F, OtelSpan as G, WrapResult as H, InterceptorValidateResult as I, PadroneTracer as J, OtelTracer as K, PadroneContextInterceptor as L, InterceptorRouteContext as M, InterceptorShutdownContext as N, InterceptorMeta as O, InterceptorStartContext as P, PadroneLogLevel as Q, PadroneInterceptor as R, InterceptorDefBuilder as S, PadroneSpinnerConfig as St, InterceptorExecuteContext as T, PadroneServePreferences as U, WrapConfig as V, PadroneMcpPreferences as W, WithTracing as X, PadroneTracingConfig as Y, padroneTracing as Z, PadroneCommand as _, PadroneProgressOptions as _t, DefineCommandContext as a, PossibleCommands as at, ExtractInterceptorRequires as b, PadroneRuntime as bt, PadroneProgram as c, WithInterceptor as ct, PadroneParseResult as d, InteractiveMode as dt, PadroneLoggerConfig as et, PadroneReplPreferences as f, InteractivePromptConfig as ft, PadroneActionContext as g, PadroneProgressIndicator as gt, GetArgsMeta as h, PadroneBarConfig as ht, DefineCommandBuilder as i, PickCommandByName as it, InterceptorPhases as j, InterceptorParseContext as k, PadroneCommandResult as l, AsyncPadroneSchema as lt, CommandTypesBase as m, PadroneBarChar as mt, AnyPadroneProgram as n, padroneLogger as nt, PadroneBuilder as o, WithAsync as ot, AnyPadroneCommand as p, PadroneBarAnimation as pt, OtelTracerProvider as q, DefineCommand as r, Drained as rt, PadroneExtension as s, WithCommand as st, AnyPadroneBuilder as t, WithLogger as tt, PadroneDrainResult as u, PadroneSchema as ut, PadroneProgramMeta as v, PadroneProgressShow as vt, InterceptorErrorResult as w, REPL_SIGINT as wt, InterceptorBaseContext as x, PadroneSignal as xt, ExtractInterceptorContext as y, PadroneProgressUpdate as yt, PadroneInterceptorFn as z };
+//# sourceMappingURL=index-Guyz-CBm.d.mts.map