feat: add DefineCommandContext and defineCommand().requires() for typed interceptor context

Commands defined with defineCommand() now get optional logger, tracing, and progress
context by default via DefineCommandContext (overridable via module augmentation).
Use defineCommand().requires<T>().define(fn) to declare additional context requirements
with compile-time validation when registering via .command().

Author: KurtGokhan

.changeset/define-command-context.md

@@ -0,0 +1,5 @@
+---
+'padrone': minor
+---
+
+Add `DefineCommandContext` interface and `defineCommand().requires()` for typed interceptor context in modular commands. Commands defined with `defineCommand()` now have optional `logger`, `tracing`, and `progress` context by default. Use `defineCommand().requires<T>().define(fn)` for additional context requirements with compile-time validation at `.command()` registration.

packages/padrone/src/core/create.ts

@@ -14,6 +14,8 @@ import type {
   AnyPadroneCommand,
   AnyPadroneProgram,
   CommandTypesBase,
+  DefineCommandBuilder,
+  DefineCommandContext,
   InterceptorFactory,
   InterceptorMeta,
   PadroneBuilder,
@@ -158,7 +160,7 @@ export function createPadroneBuilder<TBuilder extends PadroneProgram = PadronePr
       const handler = createWrapHandler(config, existingCommand.argsSchema as any, existingCommand.meta?.positional);
       return createPadroneBuilder({ ...existingCommand, action: handler }) as any;
     },
-    command(nameOrNames, builderFn) {
+    command(nameOrNames: string | readonly string[], builderFn?: (builder: any) => any) {
       const name = Array.isArray(nameOrNames) ? nameOrNames[0] : nameOrNames;
       const aliases = Array.isArray(nameOrNames) && nameOrNames.length > 1 ? (nameOrNames.slice(1) as string[]) : undefined;
 
@@ -274,28 +276,33 @@ export function createPadroneBuilder<TBuilder extends PadroneProgram = PadronePr
  * Use this when defining commands in separate files — the parent program retains exact type information
  * about the subcommand's args, result, and nested commands.
  *
- * @example
+ * The builder's context includes `DefineCommandContext` by default (optional `logger`, `tracing`, `progress`).
+ * Override globally via module augmentation on `DefineCommandContext`, or per-command via `.requires()`.
+ *
+ * @example Direct form (most common)
  * ```ts
- * // my-command.ts
  * export const myCommand = defineCommand((c) =>
  *   c.arguments(z.object({ name: z.string() }))
  *    .action((args) => console.log(args.name))
  * );
- *
- * // cli.ts
- * createPadrone('test').command('my-command', myCommand)
  * ```
  *
- * @example With context
+ * @example With required interceptor context
  * ```ts
- * export const myCommand = defineCommand<{ db: Database }>((c) =>
- *   c.arguments(z.object({ id: z.string() }))
- *    .action((args, ctx) => ctx.context.db.find(args.id))
- * );
+ * export const adminCommand = defineCommand()
+ *   .requires<{ adminDb: AdminDB }>()
+ *   .define((c) => c.action((_args, ctx) => ctx.context.adminDb.query(...)));
  * ```
  */
 export function defineCommand<TContext = unknown, TOut extends CommandTypesBase = CommandTypesBase>(
-  fn: (builder: PadroneBuilder<string, string, string, PadroneSchema<void>, void, [], any, false, TContext>) => TOut,
-): typeof fn {
-  return fn;
+  fn: (builder: PadroneBuilder<string, string, string, PadroneSchema<void>, void, [], any, false, TContext, DefineCommandContext>) => TOut,
+): typeof fn;
+export function defineCommand(): DefineCommandBuilder;
+export function defineCommand(fn?: any): any {
+  if (fn) return fn;
+  const builder: DefineCommandBuilder = {
+    requires: () => builder as any,
+    define: (f: any) => f,
+  };
+  return builder;
 }

packages/padrone/src/index.ts

@@ -91,6 +91,8 @@ export type {
   AsyncPadroneSchema,
   CommandTypesBase,
   DefineCommand,
+  DefineCommandBuilder,
+  DefineCommandContext,
   ExtractInterceptorContext,
   ExtractInterceptorRequires,
   GetArgsMeta,

packages/padrone/src/types/builder.ts

@@ -1,6 +1,8 @@
 import type { StandardSchemaV1 } from '@standard-schema/spec';
 import type { Tool } from 'ai';
-import type { PadroneRuntime } from '../core/runtime.ts';
+import type { PadroneProgressIndicator, PadroneRuntime } from '../core/runtime.ts';
+import type { PadroneLogger } from '../extension/logger.ts';
+import type { PadroneTracer } from '../extension/tracing.ts';
 import type { PadroneMcpPreferences } from '../feature/mcp.ts';
 import type { PadroneServePreferences } from '../feature/serve.ts';
 import type { WrapConfig, WrapResult } from '../feature/wrap.ts';
@@ -385,6 +387,33 @@ export type PadroneBuilderMethods<
       TContext,
       TContextProvided
     >;
+    // Overload for defineCommand.requires() branded callbacks — validates context requirements
+    <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;
     // Fallback overload: accepts DefineCommand-typed callbacks where the builder type is not structurally compatible
     // (e.g., DefineCommand with unknown context used in a parent with specific context)
     <TNameNested extends string, TAliases extends string[] = [], TBuilder extends CommandTypesBase = CommandTypesBase>(
@@ -723,6 +752,30 @@ export type AnyPadroneProgram = PadroneProgram<string, string, string, any, any,
  */
 export 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;
+ *   }
+ * }
+ * ```
+ */
+export interface DefineCommandContext {
+  logger?: PadroneLogger;
+  tracing?: PadroneTracer;
+  progress?: PadroneProgressIndicator;
+}
+
+/** Error brand returned by `.command()` when a `defineCommand.requires()` context requirement is not satisfied. */
+export 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.
@@ -741,7 +794,27 @@ export type PadroneExtension<TIn extends CommandTypesBase = CommandTypesBase, TO
  * ```
  */
 export type DefineCommand<TContext = unknown, TParentArgs extends PadroneSchema = PadroneSchema> = (
-  builder: PadroneBuilder<string, string, string, PadroneSchema<void>, void, [], TParentArgs, false, TContext>,
+  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(...)));
+ * ```
+ */
+export 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;

packages/padrone/src/types/index.ts

@@ -3,6 +3,8 @@ export type {
   AnyPadroneBuilder,
   AnyPadroneProgram,
   DefineCommand,
+  DefineCommandBuilder,
+  DefineCommandContext,
   PadroneBuilder,
   PadroneBuilderMethods,
   PadroneExtension,

packages/padrone/tests/type.test.ts

@@ -1,7 +1,15 @@
 // biome-ignore-all lint/correctness/noUnusedVariables: This file is for testing TypeScript types, so unused variables are intentional.
 
 import { expectTypeOf, test } from 'bun:test';
-import type { DefineCommand, PadroneBuilder, PadroneProgram, PadroneProgressIndicator } from 'padrone';
+import type {
+  DefineCommand,
+  DefineCommandContext,
+  PadroneBuilder,
+  PadroneLogger,
+  PadroneProgram,
+  PadroneProgressIndicator,
+  PadroneTracer,
+} from 'padrone';
 import { asyncSchema, createPadrone, defineCommand, defineInterceptor, padroneProgress } from 'padrone';
 import * as z from 'zod/v4';
 import { createTasksProgram } from './common.ts';
@@ -465,3 +473,62 @@ test.skip('Types - DefineCommand with extensions', () => {
   const result = program.eval('load --id abc');
   expectTypeOf(result.result).toEqualTypeOf<string | undefined>();
 });
+
+/** This test verifies DefineCommandContext provides optional logger, tracing, progress by default */
+test.skip('Types - DefineCommandContext default context', () => {
+  // DefineCommandContext interface has optional logger, tracing, progress
+  expectTypeOf<DefineCommandContext>().toHaveProperty('logger');
+  expectTypeOf<DefineCommandContext['logger']>().toEqualTypeOf<PadroneLogger | undefined>();
+  expectTypeOf<DefineCommandContext['tracing']>().toEqualTypeOf<PadroneTracer | undefined>();
+  expectTypeOf<DefineCommandContext['progress']>().toEqualTypeOf<PadroneProgressIndicator | undefined>();
+
+  // defineCommand action handler has access to optional logger, tracing, progress
+  defineCommand((c) =>
+    c.action((_args, ctx) => {
+      expectTypeOf(ctx.context.logger).toEqualTypeOf<PadroneLogger | undefined>();
+      expectTypeOf(ctx.context.tracing).toEqualTypeOf<PadroneTracer | undefined>();
+      expectTypeOf(ctx.context.progress).toEqualTypeOf<PadroneProgressIndicator | undefined>();
+    }),
+  );
+
+  // DefineCommand type alias also gets DefineCommandContext
+  const cmd: DefineCommand = (c) =>
+    c.action((_args, ctx) => {
+      expectTypeOf(ctx.context.logger).toEqualTypeOf<PadroneLogger | undefined>();
+    });
+});
+
+/** This test verifies defineCommand().requires().define() brands callbacks and validates at .command() */
+test.skip('Types - defineCommand().requires()', () => {
+  type AdminDB = { query: (sql: string) => string[] };
+
+  // .requires() adds the required type to context and brands the callback
+  const adminCommand = defineCommand()
+    .requires<{ adminDb: AdminDB }>()
+    .define((c) =>
+      c.action((_args, ctx) => {
+        // adminDb is required (not optional)
+        expectTypeOf(ctx.context.adminDb).toEqualTypeOf<AdminDB>();
+        // DefineCommandContext optionals are still available
+        expectTypeOf(ctx.context.logger).toEqualTypeOf<PadroneLogger | undefined>();
+        return { test: 5 };
+      }),
+    );
+
+  // Branded callback has '~contextRequires' phantom property
+  expectTypeOf(adminCommand).toHaveProperty('~contextRequires');
+
+  // Registering on a program that provides the context: no error
+  const adminInterceptor = defineInterceptor({ name: 'admin' }, () => ({
+    execute(_ctx, next) {
+      return next({ context: { adminDb: { query: (sql: string) => [sql] } } });
+    },
+  })).provides<{ adminDb: AdminDB }>();
+
+  const program = createPadrone('test').intercept(adminInterceptor).command('admin', adminCommand);
+  expectTypeOf(program.eval).toBeFunction();
+
+  // Registering on a program WITHOUT the context: returns DefineCommandRequiresError
+  const badProgram = createPadrone('test').command('admin', adminCommand);
+  expectTypeOf(badProgram).toHaveProperty('~error');
+});