feat: add typed context injection for interceptors (.provides/.requires)

Interceptors can now inject strongly-typed context into the pipeline via
.provides<T>() and declare context dependencies via .requires<T>().
Context flows through start-phase next({ context }) and merges with
user-defined context in action handlers. Compile-time rejection when
required context is not satisfied.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: KurtGokhan

.changeset/context-interceptors.md

@@ -0,0 +1,5 @@
+---
+'padrone': minor
+---
+
+Add typed context injection for interceptors. Interceptors can declare provided context via `.provides<T>()` and required context via `.requires<T>()` on `defineInterceptor()`. Action handlers see the full merged context type. `.intercept()` rejects interceptors whose required context is not satisfied at compile time.

packages/padrone/src/core/exec.ts

@@ -147,13 +147,13 @@ export function execCommand(
   const rootRegistered = rootCommand.interceptors ?? [];
   const rootInterceptors = resolveRegisteredInterceptors(rootRegistered, factoryCache);
 
-  const runPipeline = (signal: AbortSignal) => {
+  const runPipeline = (signal: AbortSignal, pipelineContext: unknown) => {
     // ── Phase 1: Parse ──────────────────────────────────────────────────
     const parseCtx: InterceptorParseContext = {
       input: resolvedInput,
       command: rootCommand,
       signal,
-      context: initialContext,
+      context: pipelineContext,
       runtime,
       program: ctx.builder,
       caller,
@@ -170,7 +170,7 @@ export function execCommand(
       pipelineState.rawArgs = parsed.rawArgs;
       pipelineState.positionalArgs = parsed.positionalArgs;
       const commandInterceptors = resolveRegisteredInterceptors(collectInterceptorsFn(command), factoryCache);
-      const context = resolveContext(command, initialContext);
+      const context = resolveContext(command, pipelineContext);
 
       // ── Phase 2: Validate ───────────────────────────────────────────
       const validateCtx: InterceptorValidateContext = {

packages/padrone/src/core/interceptors.ts

@@ -40,6 +40,9 @@ export function defineInterceptor<TArgs = unknown, TResult = unknown>(
   if (meta.id !== undefined) (factory as any).id = meta.id;
   if (meta.order !== undefined) (factory as any).order = meta.order;
   if (meta.disabled !== undefined) (factory as any).disabled = meta.disabled;
+  // No-ops at runtime — purely type-level casts for context-providing/requiring interceptors.
+  (factory as any).provides = () => factory;
+  (factory as any).requires = () => factory;
   return factory as PadroneInterceptorFn<TArgs, TResult>;
 }
 
@@ -168,7 +171,7 @@ export function wrapWithLifecycle<T>(
   interceptors: ResolvedInterceptor[],
   command: AnyPadroneCommand,
   input: string | undefined,
-  pipeline: (signal: AbortSignal) => T | Promise<T>,
+  pipeline: (signal: AbortSignal, context: unknown) => T | Promise<T>,
   wrapErrorResult?: (result: unknown) => T,
   signal?: AbortSignal,
   context?: unknown,
@@ -183,10 +186,11 @@ export function wrapWithLifecycle<T>(
   const hasShutdown = interceptors.some((p) => p.shutdown);
 
   // Fast path: no lifecycle interceptors
-  if (!hasStart && !hasError && !hasShutdown) return pipeline(signal ?? defaultSignal);
-  // Mutable ref: start-phase interceptors can override the signal (e.g., signal extension),
-  // and the override propagates to error/shutdown contexts.
+  if (!hasStart && !hasError && !hasShutdown) return pipeline(signal ?? defaultSignal, context);
+  // Mutable refs: start-phase interceptors can override signal and context (e.g., signal extension, auth),
+  // and the overrides propagate to error/shutdown contexts.
   let effectiveSignal = signal ?? defaultSignal;
+  let effectiveContext = context;
 
   const runShutdown = (error?: unknown, result?: unknown) => {
     if (!hasShutdown) return;
@@ -196,7 +200,7 @@ export function wrapWithLifecycle<T>(
       error,
       result,
       signal: effectiveSignal,
-      context,
+      context: effectiveContext,
       runtime: runtime!,
       program: program!,
       caller,
@@ -219,7 +223,7 @@ export function wrapWithLifecycle<T>(
       input,
       error,
       signal: effectiveSignal,
-      context,
+      context: effectiveContext,
       runtime: runtime!,
       program: program!,
       caller,
@@ -248,7 +252,7 @@ export function wrapWithLifecycle<T>(
   const startCtx: InterceptorStartContext = {
     command,
     signal: effectiveSignal,
-    context,
+    context: effectiveContext,
     runtime: runtime!,
     program: program!,
     input,
@@ -259,11 +263,12 @@ export function wrapWithLifecycle<T>(
     result = (
       hasStart
         ? runInterceptorChain('start', interceptors, startCtx, (ctx) => {
-            // Capture the (possibly overridden) signal so error/shutdown phases see the same instance.
+            // Capture overrides from start-phase interceptors so downstream phases see them.
             effectiveSignal = ctx.signal;
-            return pipeline(ctx.signal);
+            effectiveContext = ctx.context;
+            return pipeline(ctx.signal, ctx.context);
           })
-        : pipeline(effectiveSignal)
+        : pipeline(effectiveSignal, effectiveContext)
     ) as T | Promise<T>;
   } catch (e) {
     return runError(e);

packages/padrone/src/index.ts

@@ -63,6 +63,8 @@ export type {
   AnyPadroneProgram,
   AsyncPadroneSchema,
   CommandTypesBase,
+  ExtractInterceptorContext,
+  ExtractInterceptorRequires,
   GetArgsMeta,
   InterceptorBaseContext,
   InterceptorErrorContext,
@@ -82,6 +84,7 @@ export type {
   PadroneBuilder,
   PadroneCommand,
   PadroneCommandResult,
+  PadroneContextInterceptor,
   PadroneDrainResult,
   PadroneExtension,
   PadroneInterceptor,
@@ -92,5 +95,13 @@ export type {
 } from './types/index.ts';
 export type { AsyncStreamMeta } from './util/stream.ts';
 export { asyncStream } from './util/stream.ts';
-export type { InferArgsInput, InferArgsOutput, InferCommand, InferContext } from './util/type-helpers.ts';
+export type {
+  InferArgsInput,
+  InferArgsOutput,
+  InferCommand,
+  InferContext,
+  InferContextProvided,
+  InferInterceptorContext,
+  InferInterceptorRequires,
+} from './util/type-helpers.ts';
 export type { Drained } from './util/type-utils.ts';