padrone 1.7.0 → 1.8.0

package/src/core/validate.ts

@@ -51,8 +51,8 @@ export function parseCommand(input: string | undefined, rootCommand: AnyPadroneC
   const argsMeta = curCommand.meta?.fields;
   const schemaMetadata = curCommand.argsSchema
     ? extractSchemaMetadata(curCommand.argsSchema, argsMeta, curCommand.meta?.autoAlias)
-    : { flags: {}, aliases: {} };
-  const { flags, aliases } = schemaMetadata;
+    : { flags: {}, aliases: {}, negatives: {}, customNegation: new Set<string>() };
+  const { flags, aliases, negatives, customNegation } = schemaMetadata;
 
   const arrayArguments = new Set<string>();
   if (curCommand.argsSchema) {
@@ -77,6 +77,10 @@ export function parseCommand(input: string | undefined, rootCommand: AnyPadroneC
       key = [flags[arg.key[0]!]!];
     } else if (arg.type === 'named' && arg.key.length === 1 && aliases[arg.key[0]!]) {
       key = [aliases[arg.key[0]!]!];
+    } else if (arg.type === 'named' && arg.key.length === 1 && negatives[arg.key[0]!]) {
+      // Negative keyword: --remote sets local to false
+      setNestedValue(rawArgs, [negatives[arg.key[0]!]!], false);
+      continue;
     } else {
       key = arg.key;
     }
@@ -84,6 +88,12 @@ export function parseCommand(input: string | undefined, rootCommand: AnyPadroneC
     const rootKey = key[0]!;
 
     if (arg.type === 'named' && arg.negated) {
+      // Skip --no- prefix negation for args with custom negation
+      if (customNegation.has(rootKey)) {
+        // Treat as unknown: put it back as `no-<key>` so detectUnknownArgs catches it
+        setNestedValue(rawArgs, [`no-${key.join('.')}`], false);
+        continue;
+      }
       setNestedValue(rawArgs, key, false);
       continue;
     }
@@ -132,8 +142,9 @@ export function buildCommandArgs(
   command: AnyPadroneCommand,
   rawArgs: Record<string, unknown>,
   positionalArgs: string[],
-): Record<string, unknown> {
+): { args: Record<string, unknown>; issues?: StandardSchemaV1.Issue[] } {
   let preprocessedArgs = preprocessArgs(rawArgs, { flags: {}, aliases: {} });
+  let issues: StandardSchemaV1.Issue[] | undefined;
 
   const positionalConfig = command.meta?.positional ? parsePositionalConfig(command.meta.positional) : [];
 
@@ -143,6 +154,13 @@ export function buildCommandArgs(
       const { name, variadic } = positionalConfig[i]!;
       if (argIndex >= positionalArgs.length) break;
 
+      // Detect ambiguity: same arg provided both positionally and as a named option
+      if (name in preprocessedArgs) {
+        issues ??= [];
+        issues.push({ path: [name], message: `Ambiguous argument "${name}": provided both positionally and as a named option` });
+        continue;
+      }
+
       if (variadic) {
         const remainingPositionals = positionalConfig.slice(i + 1);
         const nonVariadicAfter = remainingPositionals.filter((p) => !p.variadic).length;
@@ -163,7 +181,7 @@ export function buildCommandArgs(
     preprocessedArgs = coerceArgs(preprocessedArgs, command.argsSchema);
   }
 
-  return preprocessedArgs;
+  return { args: preprocessedArgs, issues };
 }
 
 /**
@@ -180,9 +198,9 @@ export function checkUnknownArgs(command: AnyPadroneCommand, preprocessedArgs: R
   }
 
   const argsMeta = command.meta?.fields;
-  const { flags, aliases } = extractSchemaMetadata(command.argsSchema, argsMeta, command.meta?.autoAlias);
+  const { flags, aliases, negatives } = extractSchemaMetadata(command.argsSchema, argsMeta, command.meta?.autoAlias);
 
-  return detectUnknownArgs(preprocessedArgs, command.argsSchema, flags, aliases);
+  return detectUnknownArgs(preprocessedArgs, command.argsSchema, flags, aliases, negatives);
 }
 
 /**
@@ -241,7 +259,8 @@ export function coreValidateForParse(
   rawArgs: Record<string, unknown>,
   positionalArgs: string[],
 ): InterceptorValidateResult | Promise<InterceptorValidateResult> {
-  const preprocessedArgs = buildCommandArgs(command, rawArgs, positionalArgs);
+  const { args: preprocessedArgs, issues } = buildCommandArgs(command, rawArgs, positionalArgs);
+  if (issues) return { args: undefined, argsResult: { issues } as any };
   const validated = validateCommandArgs(command, preprocessedArgs);
   return thenMaybe(validated, (v) => v as InterceptorValidateResult);
 }

package/src/extension/auto-output.ts

@@ -88,7 +88,7 @@ function createAutoOutputInterceptor(outputConfig?: OutputConfig) {
         return { result: collected };
       };
 
-      const executedOrPromise = next({ context: { ...(ctx.context as any), output: indicator } });
+      const executedOrPromise = next({ context: { output: indicator } });
       if (executedOrPromise instanceof Promise) return executedOrPromise.then(handleResult);
       return handleResult(executedOrPromise);
     },

package/src/extension/config.ts

@@ -4,6 +4,7 @@ import { ConfigError } from '../core/errors.ts';
 import { defineInterceptor } from '../core/interceptors.ts';
 import { thenMaybe } from '../core/results.ts';
 import type { AnyPadroneBuilder, CommandTypesBase, InterceptorValidateContext } from '../types/index.ts';
+import type { WithAsync } from '../util/type-utils.ts';
 import { getRootCommand } from '../util/utils.ts';
 
 // ── Types ────────────────────────────────────────────────────────────────
@@ -189,7 +190,7 @@ function loadConfig(
  *   }))
  * ```
  */
-export function padroneConfig(options?: PadroneConfigOptions): <T extends CommandTypesBase>(builder: T) => T {
+export function padroneConfig(options?: PadroneConfigOptions): <T extends CommandTypesBase>(builder: T) => WithAsync<T> {
   if (options?.disabled) {
     const disabled = defineInterceptor({ id: 'padrone:config', name: 'padrone:config', order: -999, disabled: true }, () => ({}));
     return ((builder: AnyPadroneBuilder) => builder.intercept(disabled)) as any;

package/src/extension/env.ts

@@ -5,6 +5,7 @@ import { thenMaybe } from '../core/results.ts';
 import type { AnyPadroneBuilder, CommandTypesBase, InterceptorValidateContext } from '../types/index.ts';
 import type { LoadEnvFilesOptions } from '../util/dotenv.ts';
 import { loadEnvFiles } from '../util/dotenv.ts';
+import type { WithAsync } from '../util/type-utils.ts';
 
 // ── Types ────────────────────────────────────────────────────────────────
 
@@ -53,13 +54,13 @@ function isSchema(value: unknown): value is StandardSchemaV1 {
  *
  * Env values have lower precedence than CLI args and stdin, but higher than config files.
  */
-export function padroneEnv(schema: StandardSchemaV1): <T extends CommandTypesBase>(builder: T) => T;
-export function padroneEnv(schema: StandardSchemaV1, options: PadroneEnvOptions): <T extends CommandTypesBase>(builder: T) => T;
-export function padroneEnv(options: PadroneEnvOptions): <T extends CommandTypesBase>(builder: T) => T;
+export function padroneEnv(schema: StandardSchemaV1): <T extends CommandTypesBase>(builder: T) => WithAsync<T>;
+export function padroneEnv(schema: StandardSchemaV1, options: PadroneEnvOptions): <T extends CommandTypesBase>(builder: T) => WithAsync<T>;
+export function padroneEnv(options: PadroneEnvOptions): <T extends CommandTypesBase>(builder: T) => WithAsync<T>;
 export function padroneEnv(
   schemaOrOptions: StandardSchemaV1 | PadroneEnvOptions,
   maybeOptions?: PadroneEnvOptions,
-): <T extends CommandTypesBase>(builder: T) => T {
+): <T extends CommandTypesBase>(builder: T) => WithAsync<T> {
   const schema = isSchema(schemaOrOptions) ? schemaOrOptions : undefined;
   const options = isSchema(schemaOrOptions) ? maybeOptions : schemaOrOptions;
   const hasFiles = options?.modes !== undefined;

package/src/extension/index.ts

@@ -1,3 +1,4 @@
+export type { WithAsync } from '../util/type-utils.ts';
 export type { PadroneAutoOutputOptions } from './auto-output.ts';
 export { padroneAutoOutput } from './auto-output.ts';
 export { padroneColor } from './color.ts';

package/src/extension/interactive.ts

@@ -37,7 +37,8 @@ const interactiveInterceptor = defineInterceptor({ id: 'padrone:interactive', na
     if (!willPrompt) return next();
 
     // Preprocess args to determine what's missing
-    const preprocessedArgs = buildCommandArgs(command, ctx.rawArgs, ctx.positionalArgs);
+    const { args: preprocessedArgs, issues: positionalIssues } = buildCommandArgs(command, ctx.rawArgs, ctx.positionalArgs);
+    if (positionalIssues) return { args: undefined, argsResult: { issues: positionalIssues } } as any;
 
     // Check for unknown args before prompting
     const unknowns = checkUnknownArgs(command, preprocessedArgs);

package/src/extension/logger.ts

@@ -209,7 +209,7 @@ function loggerInterceptor(rawConfig?: PadroneLoggerConfig) {
             timestamps: rawConfig?.timestamps ?? ctxCfg?.timestamps ?? false,
           };
           const logger = createLogger(ctx.runtime, resolved.level, resolved, ctx.context?.tracing);
-          return next({ context: { ...ctx.context, logger } });
+          return next({ context: { logger } });
         },
       };
     });

package/src/extension/progress.ts

@@ -201,7 +201,7 @@ function progressInterceptor(config: string | PadroneProgressConfig) {
           return next();
         },
 
-        execute(ctx, next) {
+        execute(_ctx, next) {
           // Transition from validation message to progress message
           if (indicator && msgs!.validation) indicator.update(msgs!.progress);
 
@@ -221,7 +221,7 @@ function progressInterceptor(config: string | PadroneProgressConfig) {
 
           let result: any;
           try {
-            result = next({ context: { ...(ctx.context as any), progress: effectiveIndicator } });
+            result = next({ context: { progress: effectiveIndicator } });
           } catch (err) {
             onError(err);
           }

package/src/extension/tracing.ts

@@ -109,7 +109,7 @@ function tracingInterceptor(config: ResolvedTracingConfig) {
           },
         };
 
-        return next({ context: { ...(ctx.context as any), tracing: padroneTracer } });
+        return next({ context: { tracing: padroneTracer } });
       },
 
       error(ctx, next) {

package/src/index.ts

@@ -38,6 +38,7 @@ export type {
   PadroneTracer,
   PadroneTracingConfig,
   VersionCommand,
+  WithAsync,
   WithCompletion,
   WithHelp,
   WithLogger,
@@ -79,7 +80,7 @@ export type { UpdateCheckConfig } from './feature/update-check.ts';
 export type { WrapConfig, WrapResult } from './feature/wrap.ts';
 export type { AnsiStyle, ColorConfig, ColorTheme } from './output/colorizer.ts';
 export { colorThemes } from './output/colorizer.ts';
-export type { HelpInfo } from './output/formatter.ts';
+export type { HelpDetail, HelpFormat, HelpInfo } from './output/formatter.ts';
 export type { PadroneOutputIndicator } from './output/output-indicator.ts';
 export type { KeyValueOptions, ListItem, ListOptions, TableOptions, TreeNode, TreeOptions } from './output/primitives.ts';
 export type { OutputContext, OutputFormat } from './output/styling.ts';
@@ -90,6 +91,8 @@ export type {
   AsyncPadroneSchema,
   CommandTypesBase,
   DefineCommand,
+  DefineCommandBuilder,
+  DefineCommandContext,
   ExtractInterceptorContext,
   ExtractInterceptorRequires,
   GetArgsMeta,
@@ -121,6 +124,7 @@ export type {
   PadroneProgram,
   PadroneProgramMeta,
   PadroneSchema,
+  RegisteredInterceptor,
 } from './types/index.ts';
 export type { AsyncStreamMeta } from './util/stream.ts';
 export { asyncStream } from './util/stream.ts';

package/src/output/formatter.ts

@@ -58,6 +58,8 @@ export type HelpArgumentInfo = {
   variadic?: boolean;
   /** Whether this arg is a boolean (shown as --[no-]arg) */
   negatable?: boolean;
+  /** Custom negative keyword(s) that set this arg to false (e.g. `['remote']` for `--remote`) */
+  negative?: string[];
   /** Config file key that maps to this arg */
   configKey?: string;
   /** Group name for organizing this option under a labeled section in help output */
@@ -316,7 +318,10 @@ function createGenericFormatter(styler: Styler, layout: LayoutConfig, showAllBui
       const remainingAliases = arg.aliases?.filter((a) => a !== primaryName);
 
       const flagsPlain = arg.flags?.length ? arg.flags.map((f) => `-${f}`).join(', ') : '';
-      const namesPlain = [`--${primaryName}`, ...(remainingAliases?.map((a) => `--${a}`) || [])].join(', ');
+      const negPlain = arg.negative?.length ? arg.negative.map((n) => `--${n}`).join(', ') : '';
+      const namesPlain = [`--${primaryName}`, ...(remainingAliases?.map((a) => `--${a}`) || []), ...(negPlain ? [negPlain] : [])].join(
+        ', ',
+      );
       const typePlain = arg.type && arg.type !== 'boolean' ? (arg.optional ? `[${arg.type}]` : `<${arg.type}>`) : '';
 
       const isDeprecated = !!arg.deprecated;

package/src/output/help.ts

@@ -128,9 +128,20 @@ function extractArgsInfo(schema: StandardJSONSchemaV1, meta?: PadroneArgsSchemaM
         const optMeta = argsMeta?.[key];
         const propType = prop.type as string;
 
-        // Booleans are negatable unless there's an explicit noArg property
-        // or this arg is itself a negation of another arg
-        const isNegatable = propType === 'boolean' && !hasExplicitNegation(key) && !isNegationOf(key);
+        // Resolve custom negative keywords from meta or schema
+        const rawNegative = optMeta?.negative ?? prop?.negative;
+        const hasCustomNegative = rawNegative !== undefined;
+        const negativeList = hasCustomNegative
+          ? typeof rawNegative === 'string'
+            ? rawNegative
+              ? [rawNegative]
+              : []
+            : Array.from(rawNegative as readonly string[]).filter(Boolean)
+          : undefined;
+
+        // Booleans are negatable unless there's an explicit noArg property,
+        // this arg is itself a negation of another arg, or custom negative keywords are set
+        const isNegatable = propType === 'boolean' && !hasCustomNegative && !hasExplicitNegation(key) && !isNegationOf(key);
 
         result.push({
           name: key,
@@ -144,6 +155,7 @@ function extractArgsInfo(schema: StandardJSONSchemaV1, meta?: PadroneArgsSchemaM
           examples: optMeta?.examples ?? prop?.examples,
           variadic: propType === 'array',
           negatable: isNegatable,
+          negative: negativeList?.length ? negativeList : undefined,
           group: optMeta?.group,
         });
       }

package/src/types/args-meta.ts

@@ -35,6 +35,16 @@ export 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[];

package/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';
@@ -340,21 +342,11 @@ export type PadroneBuilderMethods<
   >;
 
   /** 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<
+  command: {
+    <
+      TNameNested extends string,
+      TAliases extends string[] = [],
+      TBuilder extends CommandTypesBase = DefaultCommandBuilder<
         TProgramName,
         TNameNested,
         FullCommandName<TName, TParentName>,
@@ -362,28 +354,94 @@ export type PadroneBuilderMethods<
         TCommands,
         TContext & TContextProvided
       >,
-    ) => TBuilder,
-  ) => BuilderOrProgram<
-    TReturn,
-    TProgramName,
-    TName,
-    TParentName,
-    TArgs,
-    TRes,
-    TCommands extends []
-      ? [WithAliases<TBuilder['~types']['command'], TAliases>]
-      : AnyPadroneCommand[] extends TCommands
+    >(
+      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>]
-        : ReplaceOrAppendCommand<
-            TCommands,
-            TNameNested,
-            WithAliases<TBuilder['~types']['command'], ResolvedAliases<TCommands, TNameNested, TAliases>>
-          >,
-    TParentArgs,
-    TAsync,
-    TContext,
-    TContextProvided
-  >;
+        : AnyPadroneCommand[] extends TCommands
+          ? [WithAliases<TBuilder['~types']['command'], TAliases>]
+          : ReplaceOrAppendCommand<
+              TCommands,
+              TNameNested,
+              WithAliases<TBuilder['~types']['command'], ResolvedAliases<TCommands, TNameNested, TAliases>>
+            >,
+      TParentArgs,
+      TAsync,
+      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>(
+      name: TNameNested | readonly [TNameNested, ...TAliases],
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      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: {
@@ -694,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.
@@ -712,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;

package/src/types/index.ts

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

package/src/types/interceptor.ts

@@ -8,7 +8,7 @@ import type { AnyPadroneCommand, PadroneActionContext } from './command.ts';
 // ---------------------------------------------------------------------------
 
 /** Base context shared across all interceptor phases within a single execution. */
-export type InterceptorBaseContext<TContext = unknown> = {
+export 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). */
@@ -26,7 +26,7 @@ export type InterceptorBaseContext<TContext = unknown> = {
 };
 
 /** Context for the parse phase. */
-export type InterceptorParseContext<TContext = unknown> = InterceptorBaseContext<TContext>;
+export type InterceptorParseContext<TContext = object> = InterceptorBaseContext<TContext>;
 
 /** Result returned by the parse phase's `next()`. */
 export type InterceptorParseResult = {
@@ -36,7 +36,7 @@ export type InterceptorParseResult = {
 };
 
 /** Context for the validate phase. */
-export type InterceptorValidateContext<TContext = unknown> = InterceptorBaseContext<TContext> & {
+export 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. */
@@ -54,7 +54,7 @@ export type InterceptorValidateResult<TArgs = unknown> = {
 };
 
 /** Context for the execute phase. Includes validate context fields (rawArgs, positionalArgs). */
-export type InterceptorExecuteContext<TArgs = unknown, TContext = unknown> = InterceptorValidateContext<TContext> & {
+export 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;
 };
@@ -65,10 +65,10 @@ export type InterceptorExecuteResult<TResult = unknown> = {
 };
 
 /** Context for the start phase. Runs before parsing, wraps the entire pipeline. */
-export type InterceptorStartContext<TContext = unknown> = InterceptorBaseContext<TContext>;
+export type InterceptorStartContext<TContext = object> = InterceptorBaseContext<TContext>;
 
 /** Context for the error phase. Called when the pipeline throws. Includes pipeline state accumulated before the error. */
-export type InterceptorErrorContext<TContext = unknown> = InterceptorBaseContext<TContext> & {
+export type InterceptorErrorContext<TContext = object> = InterceptorBaseContext<TContext> & {
   /** The error that was thrown. */
   error: unknown;
   /** Raw named arguments (available if parse completed). */
@@ -88,7 +88,7 @@ export type InterceptorErrorResult<TResult = unknown> = {
 };
 
 /** Context for the shutdown phase. Always runs after the pipeline (success or failure). Includes pipeline state accumulated before completion. */
-export type InterceptorShutdownContext<TResult = unknown, TContext = unknown> = InterceptorBaseContext<TContext> & {
+export 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. */
@@ -156,7 +156,7 @@ export type InterceptorMeta = {
  * - `TArgs` — the validated arguments type (output of the args schema).
  * - `TResult` — the command's return type.
  */
-export type InterceptorPhases<TArgs = unknown, TResult = unknown, TContext = unknown> = {
+export 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.
@@ -188,7 +188,7 @@ export type InterceptorPhases<TArgs = unknown, TResult = unknown, TContext = unk
  * Factory function that creates phase handlers for an interceptor.
  * Called once per command execution — the closure provides typed, scoped cross-phase state across phases.
  */
-export type InterceptorFactory<TArgs = unknown, TResult = unknown, TContext = unknown> = () => InterceptorPhases<TArgs, TResult, TContext>;
+export 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.
@@ -198,7 +198,7 @@ export type InterceptorFactory<TArgs = unknown, TResult = unknown, TContext = un
  * Also accepted directly by `.intercept()` as the single-argument form.
  * Call `.provides<T>()` to brand it as a context-providing interceptor.
  */
-export type PadroneInterceptorFn<TArgs = unknown, TResult = unknown, TContext = unknown> = InterceptorFactory<TArgs, TResult, TContext> &
+export 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>;
@@ -217,7 +217,7 @@ export type PadroneInterceptorFn<TArgs = unknown, TResult = unknown, TContext =
  *
  * Create with `defineInterceptor(meta, factory)` or pass `(meta, factory)` directly to `.intercept()`.
  */
-export type PadroneInterceptor<TArgs = unknown, TResult = unknown, TContext = unknown> = PadroneInterceptorFn<TArgs, TResult, TContext>;
+export 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
@@ -227,7 +227,7 @@ export type PadroneInterceptor<TArgs = unknown, TResult = unknown, TContext = un
  * Created by calling `.provides<T>()` on a `PadroneInterceptorFn`.
  * Chain `.requires<T>()` to also declare context dependencies.
  */
-export type PadroneContextInterceptor<TProvides = unknown, TArgs = unknown, TResult = unknown, TContext = unknown> = Omit<
+export type PadroneContextInterceptor<TProvides = unknown, TArgs = unknown, TResult = unknown, TContext = object> = Omit<
   PadroneInterceptorFn<TArgs, TResult, TContext>,
   'requires'
 > &