padrone 1.4.0 → 1.6.0

package/src/types/command.ts

@@ -0,0 +1,157 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+import type { PadroneRuntime, ResolvedPadroneRuntime } from '../core/runtime.ts';
+import type { FullCommandName } from '../util/type-utils.ts';
+import type { PadroneArgsSchemaMeta } from './args-meta.ts';
+import type { AnyPadroneProgram } from './builder.ts';
+import type { RegisteredInterceptor } from './interceptor.ts';
+import type { PadroneSchema } from './schema.ts';
+
+type UnknownRecord = Record<string, unknown>;
+type DefaultArgs = UnknownRecord | void;
+
+/**
+ * Read-only metadata about a Padrone program.
+ * Returned by `program.info` to expose program-level properties without leaking internal command internals.
+ */
+export type PadroneProgramMeta<TName extends string = string> = {
+  /** The program name (CLI binary name). */
+  name: TName;
+  /** Display title shown in help output. */
+  title?: string;
+  /** Program description. */
+  description?: string;
+  /** Program version string. */
+  version?: string;
+  /** Usage examples shown in help output. */
+  examples?: string[];
+  /** Whether the program is deprecated. */
+  deprecated?: boolean | string;
+  /** Names of registered subcommands. */
+  commands: string[];
+};
+
+/**
+ * Context object passed as the second argument to command action handlers.
+ * Contains the resolved runtime, the executing command, and the program instance.
+ */
+export type PadroneActionContext<TContext = unknown> = {
+  /** The resolved runtime for this command (I/O, env, config, etc.). */
+  runtime: ResolvedPadroneRuntime;
+  /** The command being executed. */
+  command: AnyPadroneCommand;
+  /** The root program instance. */
+  program: AnyPadroneProgram;
+  /**
+   * Cancellation signal that fires when the process receives SIGINT, SIGTERM, or SIGHUP.
+   * Use with `fetch()`, child processes, or any API that accepts `AbortSignal`.
+   * Check `signal.aborted` to test if cancellation was requested.
+   * The `signal.reason` is a `PadroneSignal` string ('SIGINT', 'SIGTERM', or 'SIGHUP').
+   */
+  signal: AbortSignal;
+  /** User-defined context object. Set via `.context()` on the builder and provided at `cli()`/`eval()` time. */
+  context: TContext;
+  /** Which API entry point triggered this execution. */
+  caller: 'cli' | 'eval' | 'run' | 'repl' | 'serve' | 'mcp' | 'tool';
+};
+
+/**
+ * Configuration for a command.
+ */
+export type PadroneCommandConfig = {
+  /** A short title for the command, displayed in help. */
+  title?: string;
+  /** A longer description of what the command does. */
+  description?: string;
+  /** The version of the command. */
+  version?: string;
+  /** Whether the command is deprecated, or a message explaining the deprecation. */
+  deprecated?: boolean | string;
+  /** Whether the command should be hidden from help output. */
+  hidden?: boolean;
+  /** Group name for organizing this command under a labeled section in help output. */
+  group?: string;
+  /** Usage examples shown in help output. Each entry is a command-line invocation string. */
+  examples?: string[];
+  /**
+   * Whether this command performs a mutation (create, update, delete).
+   * - In `serve()`: mutation commands accept POST only; non-mutation commands accept GET and POST.
+   * - In `mcp()`: sets `annotations.destructiveHint` on the tool definition.
+   * - In `tool()`: defaults `needsApproval` to `true` when not explicitly set.
+   */
+  mutation?: boolean;
+};
+
+export type PadroneCommand<
+  TName extends string = string,
+  TParentName extends string = '',
+  TArgs extends PadroneSchema = PadroneSchema<DefaultArgs>,
+  TRes = void,
+  TCommands extends [...AnyPadroneCommand[]] = [],
+  TAliases extends string[] = string[],
+  TAsync extends boolean = false,
+  TContext = unknown,
+  TContextProvided = unknown,
+> = {
+  name: TName;
+  path: FullCommandName<TName, TParentName>;
+  title?: string;
+  description?: string;
+  version?: string;
+  /** Alternative names that can be used to invoke this command. Derived from the names passed to command(). */
+  aliases?: TAliases;
+  deprecated?: boolean | string;
+  hidden?: boolean;
+  /** Group name for organizing this command under a labeled section in help output. */
+  group?: string;
+  /** Whether this command performs a mutation (create, update, delete). Affects HTTP method in serve (POST-only) and MCP tool annotations (destructiveHint). */
+  mutation?: boolean;
+  needsApproval?: boolean | ((args: TArgs) => Promise<boolean> | boolean);
+  /** Usage examples shown in help output. Each entry is a command-line invocation string. */
+  examples?: string[];
+  argsSchema?: TArgs;
+  meta?: GetArgsMeta<TArgs>;
+  action?: (args: StandardSchemaV1.InferOutput<TArgs>, ctx: PadroneActionContext<TContext & TContextProvided>) => TRes;
+  /** Runtime flag indicating this command uses async validation. Set by `.async()` or `asyncSchema()`. */
+  isAsync?: boolean;
+  /** Runtime configuration for I/O abstraction. */
+  runtime?: PadroneRuntime;
+
+  /** Transform function that maps parent context to this command's context. Set by `.context(transform)`. */
+  contextTransform?: (ctx: unknown) => unknown;
+
+  /** Interceptors registered on this command. Collected from the parent chain at execution time. */
+  interceptors?: RegisteredInterceptor[];
+
+  parent?: AnyPadroneCommand;
+  commands?: TCommands;
+
+  /** @deprecated Internal use only */
+  '~types': {
+    name: TName;
+    parentName: TParentName;
+    path: FullCommandName<TName, TParentName>;
+    aliases: TAliases;
+    argsSchema: TArgs;
+    argsInput: StandardSchemaV1.InferInput<TArgs>;
+    argsOutput: StandardSchemaV1.InferOutput<TArgs>;
+    result: TRes;
+    commands: TCommands;
+    async: TAsync;
+    context: TContext;
+    contextProvided: TContextProvided;
+  };
+};
+
+export type AnyPadroneCommand = PadroneCommand<string, any, any, any, [...AnyPadroneCommand[]], string[], any, any, any>;
+
+/**
+ * Base type for extracting command information from builder or program.
+ * Both PadroneBuilder and PadroneProgram share this structure.
+ */
+export type CommandTypesBase = {
+  '~types': {
+    command: AnyPadroneCommand;
+  };
+};
+
+export type GetArgsMeta<TArgs extends PadroneSchema> = PadroneArgsSchemaMeta<NonNullable<StandardSchemaV1.InferInput<TArgs>>>;

package/src/types/index.ts

@@ -0,0 +1,59 @@
+export type { PadroneArgsSchemaMeta, PadroneFieldMeta, SingleChar, StdinConfig } from './args-meta.ts';
+export type {
+  AnyPadroneBuilder,
+  AnyPadroneProgram,
+  PadroneBuilder,
+  PadroneBuilderMethods,
+  PadroneExtension,
+  PadroneProgram,
+} from './builder.ts';
+export type {
+  AnyPadroneCommand,
+  CommandTypesBase,
+  GetArgsMeta,
+  PadroneActionContext,
+  PadroneCommand,
+  PadroneCommandConfig,
+  PadroneProgramMeta,
+} from './command.ts';
+export type {
+  ExtractInterceptorContext,
+  ExtractInterceptorRequires,
+  InterceptorBaseContext,
+  InterceptorDefBuilder,
+  InterceptorErrorContext,
+  InterceptorErrorResult,
+  InterceptorExecuteContext,
+  InterceptorExecuteResult,
+  InterceptorFactory,
+  InterceptorMeta,
+  InterceptorNextOverrides,
+  InterceptorParseContext,
+  InterceptorParseResult,
+  InterceptorPhases,
+  InterceptorShutdownContext,
+  InterceptorStartContext,
+  InterceptorValidateContext,
+  InterceptorValidateResult,
+  PadroneContextInterceptor,
+  PadroneInterceptor,
+  PadroneInterceptorFn,
+  RegisteredInterceptor,
+  ResolvedInterceptor,
+} from './interceptor.ts';
+export type {
+  PadroneCliPreferences,
+  PadroneEvalPreferences,
+  PadroneReplPreferences,
+  PadroneReplSpacing,
+} from './preferences.ts';
+export type {
+  GetArguments,
+  GetResults,
+  MaybePromiseCommandResult,
+  PadroneAPI,
+  PadroneCommandResult,
+  PadroneDrainResult,
+  PadroneParseResult,
+} from './result.ts';
+export type { AsyncPadroneSchema, PadroneSchema } from './schema.ts';

package/src/types/interceptor.ts

@@ -0,0 +1,296 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+import type { ResolvedPadroneRuntime } from '../core/runtime.ts';
+import type { AnyPadroneProgram } from './builder.ts';
+import type { AnyPadroneCommand, PadroneActionContext } from './command.ts';
+
+// ---------------------------------------------------------------------------
+// Interceptor system
+// ---------------------------------------------------------------------------
+
+/** Base context shared across all interceptor phases within a single execution. */
+export type InterceptorBaseContext<TContext = unknown> = {
+  /** 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. */
+  context: TContext;
+  /** The resolved runtime for this execution. Interceptors can override this before calling `next()`. */
+  runtime: ResolvedPadroneRuntime;
+  /** The program instance. Available for extensions that need program-level methods. */
+  program: AnyPadroneProgram;
+  /** The invocation method that triggered this execution (e.g. 'cli', 'eval', 'run'). */
+  caller: PadroneActionContext['caller'];
+};
+
+/** Context for the parse phase. */
+export type InterceptorParseContext<TContext = unknown> = InterceptorBaseContext<TContext>;
+
+/** Result returned by the parse phase's `next()`. */
+export type InterceptorParseResult = {
+  command: AnyPadroneCommand;
+  rawArgs: Record<string, unknown>;
+  positionalArgs: string[];
+};
+
+/** Context for the validate phase. */
+export type InterceptorValidateContext<TContext = unknown> = 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. */
+  evalInteractive?: boolean;
+};
+
+/** Result returned by the validate phase's `next()`. */
+export type InterceptorValidateResult<TArgs = unknown> = {
+  args: TArgs;
+  argsResult: StandardSchemaV1.Result<TArgs>;
+};
+
+/** Context for the execute phase. Includes validate context fields (rawArgs, positionalArgs). */
+export type InterceptorExecuteContext<TArgs = unknown, TContext = unknown> = 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()`. */
+export type InterceptorExecuteResult<TResult = unknown> = {
+  result: TResult;
+};
+
+/** Context for the start phase. Runs before parsing, wraps the entire pipeline. */
+export type InterceptorStartContext<TContext = unknown> = 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> & {
+  /** 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). */
+  args?: unknown;
+};
+
+/** Result returned by the error phase's `next()`. */
+export type InterceptorErrorResult<TResult = unknown> = {
+  /** The error (possibly transformed). Set to `undefined` to suppress the error. */
+  error?: unknown;
+  /** A replacement result when suppressing the error. */
+  result?: TResult;
+};
+
+/** 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> & {
+  /** 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). */
+  positionalArgs?: string[];
+  /** Validated arguments (available if validate completed). */
+  args?: unknown;
+};
+
+/** Overrides passable to `next()`. Provides autocomplete for common fields; accepts any phase-specific fields. */
+export type InterceptorNextOverrides = Partial<InterceptorBaseContext> & Record<string, unknown>;
+
+/**
+ * A phase handler function for the interceptor middleware chain.
+ *
+ * - `TCtx` — the context object available to the handler.
+ * - `TNextResult` — the typed result returned by `next()`, giving the handler type-safe access to downstream output.
+ * - `TReturn` — the type the handler itself returns. Defaults to `TNextResult` but can be wider,
+ *   allowing interceptors to transform or replace the result (e.g., error-recovery interceptors returning a different type).
+ */
+type InterceptorPhaseHandler<TCtx, TNextResult, TReturn = TNextResult> = (
+  ctx: TCtx,
+  next: (overrides?: InterceptorNextOverrides) => TNextResult | Promise<TNextResult>,
+) => TReturn | Promise<TReturn>;
+
+// ---------------------------------------------------------------------------
+// Interceptor meta, phases, and factory
+// ---------------------------------------------------------------------------
+
+/** Static metadata for an interceptor. Always available at registration time without calling the factory. */
+export type InterceptorMeta = {
+  /** Display name for this interceptor. Used for identification in logs and debugging. */
+  name: string;
+  /**
+   * Optional unique identifier for deduplication. When multiple interceptors share the same `id`,
+   * only the last one registered is kept. Useful for allowing downstream code to override
+   * an interceptor without accumulating duplicates.
+   */
+  id?: string;
+  /**
+   * Ordering hint. Lower values run as outer layers (earlier before `next()`, later after).
+   * Interceptors with the same order preserve registration order. Defaults to `0`.
+   */
+  order?: number;
+  /**
+   * When `true`, the interceptor is skipped during execution. Combined with `id`-based deduplication,
+   * this lets downstream code disable an interceptor by re-registering it with `disabled: true`.
+   */
+  disabled?: boolean;
+  /**
+   * When `false`, the interceptor applies only to the command it was registered on
+   * and is not inherited by subcommands. Defaults to `true`.
+   */
+  inherit?: boolean;
+};
+
+/**
+ * Phase handler definitions returned by an interceptor factory.
+ * The factory's closure provides typed, scoped cross-phase state.
+ *
+ * Type parameters:
+ * - `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> = {
+  /**
+   * 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. */
+  validate?: InterceptorPhaseHandler<InterceptorValidateContext<TContext>, InterceptorValidateResult<TArgs>, InterceptorValidateResult>;
+  /** Intercepts handler execution. */
+  execute?: InterceptorPhaseHandler<
+    InterceptorExecuteContext<TArgs, TContext>,
+    InterceptorExecuteResult<TResult>,
+    InterceptorExecuteResult
+  >;
+  /**
+   * Called when the pipeline throws an error. `next()` passes to the next error handler
+   * (innermost returns `{ error }` unchanged). Return `{ result }` without `error` to suppress.
+   */
+  error?: InterceptorPhaseHandler<InterceptorErrorContext<TContext>, InterceptorErrorResult<TResult>, InterceptorErrorResult>;
+  /**
+   * Always runs after the pipeline completes (success or failure). `next()` calls the next shutdown handler.
+   * Use for cleanup: closing connections, flushing logs, etc.
+   */
+  shutdown?: InterceptorPhaseHandler<InterceptorShutdownContext<TResult, TContext>, void>;
+};
+
+/**
+ * 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>;
+
+/**
+ * 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
+ * importable value that packages can export.
+ *
+ * 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> &
+  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.
+     * `.intercept()` will produce a compile error if the required context is not satisfied.
+     * Use optional properties for soft requirements: `.requires<{ db: DB; logger?: Logger }>()`.
+     * No-op at runtime; purely a type-level cast.
+     */
+    requires: <TRequires>() => PadroneInterceptorFn<TArgs, TResult, TContext> & InterceptorRequiresBrand<TRequires>;
+  };
+
+/**
+ * A Padrone interceptor in its single-value distributable form.
+ * Alias for `PadroneInterceptorFn` — this is the primary public type.
+ *
+ * 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>;
+
+/**
+ * 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
+ * intersected with `TProvides`.
+ *
+ * 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<
+  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>;
+  };
+
+/**
+ * Phantom brand for context requirements. Uses a contravariant function type so that
+ * `.intercept()` overloads can check `TAvailableContext extends TRequires` via assignability.
+ */
+type InterceptorRequiresBrand<TRequires> = { '~contextRequires': (ctx: TRequires) => void };
+
+/** Extracts the provided context type from a context-providing interceptor, or `unknown` if not branded. */
+export type ExtractInterceptorContext<T> = T extends { '~context': infer C } ? C : unknown;
+
+/** Extracts the required context type from an interceptor, or `unknown` if no requirements. */
+export type ExtractInterceptorRequires<T> = T extends { '~contextRequires': (ctx: infer R) => void } ? R : unknown;
+
+/**
+ * Checks whether an interceptor's context requirements are satisfied by the available context.
+ * Returns `true` if the interceptor has no requirements or if the available context extends the requirements.
+ */
+export type InterceptorRequiresCheck<TInterceptor, TAvailableContext> = TInterceptor extends {
+  '~contextRequires': (ctx: infer TReq) => void;
+}
+  ? TAvailableContext extends TReq
+    ? true
+    : false
+  : true;
+
+/** Error brand returned by `.intercept()` when the interceptor's required context is not satisfied. */
+export type InterceptorRequiresError = {
+  readonly '~error': 'Required context not satisfied. Ensure required interceptors are registered before this one.';
+};
+
+/**
+ * Builder returned by `defineInterceptor(meta)` (single-arg form).
+ * Call `.requires<T>()` to declare (and type) the context dependency, then `.factory()` to provide the phase handlers.
+ */
+export type InterceptorDefBuilder<TContext = unknown, TBrand = unknown> = {
+  /** Declare the context type this interceptor requires. Sets `TContext` for phase handler typing. */
+  requires: <TRequires>() => InterceptorDefBuilder<TRequires, InterceptorRequiresBrand<TRequires>>;
+  /** Provide the interceptor factory. Phase handlers receive the typed `TContext` from `.requires()`. */
+  factory: <TArgs = unknown, TResult = unknown>(
+    factory: InterceptorFactory<TArgs, TResult, TContext>,
+  ) => PadroneInterceptorFn<TArgs, TResult, TContext> & TBrand;
+};
+
+/**
+ * Internal stored form on command objects. Separates static metadata from the factory
+ * so that deduplication and sorting can happen without calling the factory.
+ */
+export type RegisteredInterceptor = {
+  meta: InterceptorMeta;
+  factory: InterceptorFactory<any, any, any>;
+};
+
+/**
+ * Resolved interceptor: metadata merged with phase handlers after the factory has been called.
+ * Used internally by the runtime chain runner.
+ */
+export type ResolvedInterceptor = InterceptorMeta & InterceptorPhases<any, any, any>;

package/src/types/preferences.ts

@@ -0,0 +1,83 @@
+import type { PadroneRuntime } from '../core/runtime.ts';
+import type { PadroneActionContext } from './command.ts';
+
+/**
+ * Options for `repl()` to customize the REPL session.
+ */
+/** A single spacing value: blank line (`true`), separator string, or an array of these for multiple lines. */
+export type PadroneReplSpacing = boolean | string | (boolean | string)[];
+
+export type PadroneReplPreferences<TScope extends string = string> = {
+  /** The prompt string displayed before each input, or a function returning it. Defaults to `"<programName>> "`. */
+  prompt?: string | (() => string);
+  /**
+   * A greeting message displayed when the REPL starts.
+   * When not provided, defaults to `"Welcome to <name> v<version>"` (or just `"Welcome to <name>"` if no version).
+   * Set to `false` to suppress the default greeting entirely.
+   */
+  greeting?: string | false;
+  /**
+   * A hint message displayed below the greeting in dimmed text.
+   * When not provided, defaults to `'Type ".help" for more information, ".exit" to quit.'`.
+   * Set to `false` to suppress the hint.
+   */
+  hint?: string | false;
+  /** Initial history entries (most recent last). Arrow keys navigate history in the terminal. */
+  history?: string[];
+  /** Set to `false` to disable tab completion. Defaults to `true`. */
+  completion?: boolean;
+  /**
+   * Add spacing/separators around each command's output.
+   * A spacing value can be:
+   * - `true` — blank line
+   * - A string — separator line (single char like `'─'` repeats to terminal width, multi-char prints as-is)
+   * - An array of the above — multiple lines in order (e.g. `[true, '─']` for blank line then separator)
+   *
+   * Shorthand applies to both before and after. Use `{ before?, after? }` for independent control.
+   */
+  spacing?: PadroneReplSpacing | { before?: PadroneReplSpacing; after?: PadroneReplSpacing };
+  /** Prefix each line of command output/error with this string (e.g. `'│ '`, `'  '`, `'▎ '`). */
+  outputPrefix?: string;
+  /**
+   * Start the REPL scoped to a command subtree. The scope path is a space-separated command path
+   * (e.g. `'db'` or `'db migrate'`). Commands are resolved relative to the scoped command.
+   * Users can change scope at runtime with `.scope <subcommand>` and `.scope ..`/`..`.
+   */
+  scope?: TScope;
+};
+
+/**
+ * Options that can be passed to `eval()` to control execution behavior.
+ */
+export type PadroneEvalPreferences = {
+  /**
+   * Controls interactive prompting for this execution.
+   * Overrides the runtime's `interactive` setting, but is itself overridden by `--interactive` / `-i` flags.
+   *
+   * - `undefined`: inherit from runtime (default).
+   * - `true`: force prompting for all configured interactive fields, even if values are already provided.
+   * - `false`: suppress all interactive prompts.
+   */
+  interactive?: boolean;
+
+  /**
+   * Override the runtime for this execution.
+   * Partial — only the provided fields replace the command's resolved runtime.
+   * Useful for capturing output, injecting test doubles, or running in non-terminal contexts (e.g. AI tool calls).
+   */
+  runtime?: PadroneRuntime;
+
+  /**
+   * User-defined context object passed to command action handlers via `ctx.context`.
+   * The context flows through the command tree and can be transformed by subcommands via `.context(transform)`.
+   */
+  context?: unknown;
+
+  /** @internal Which API entry point triggered this execution. */
+  caller?: PadroneActionContext['caller'];
+};
+
+/**
+ * Options that can be passed to `cli()` to control execution behavior.
+ */
+export type PadroneCliPreferences = PadroneEvalPreferences;

package/src/types/result.ts

@@ -0,0 +1,71 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+import type { PadroneSignal } from '../core/runtime.ts';
+import type { Drained, IsGeneric, MaybePromise } from '../util/type-utils.ts';
+import type { AnyPadroneCommand } from './command.ts';
+
+type EmptyRecord = Record<string, never>;
+
+type NormalizeArguments<TArgs> = IsGeneric<TArgs> extends true ? void | EmptyRecord : TArgs;
+export type GetArguments<TDir extends 'in' | 'out', TCommand extends AnyPadroneCommand> = TDir extends 'in'
+  ? NormalizeArguments<TCommand['~types']['argsInput']>
+  : NormalizeArguments<TCommand['~types']['argsOutput']>;
+
+export type GetResults<TCommand extends AnyPadroneCommand> = ReturnType<NonNullable<TCommand['action']>>;
+
+/**
+ * Result of `drain()` — a discriminated union that never throws.
+ * On success, `value` holds the fully resolved/collected result; on failure, `error` holds the error.
+ */
+export type PadroneDrainResult<TResult> = { value: Drained<TResult>; error?: never } | { error: unknown; value?: never };
+
+/**
+ * Result returned by `eval()`, `cli()`, and `run()`. Never thrown — errors are captured in the `error` field.
+ * Discriminated union: check `error` to distinguish success from failure.
+ *
+ * On success: `command`, `args`, `argsResult`, `result` are populated; `error` is absent.
+ * On failure: `error` is populated; `command` may be present if routing succeeded.
+ */
+export type PadroneCommandResult<TCommand extends AnyPadroneCommand = AnyPadroneCommand> =
+  | (PadroneParseResult<TCommand> & {
+      result: GetResults<TCommand>;
+      error?: never;
+      /** The signal that caused cancellation, if any. */
+      signal?: PadroneSignal;
+      /** Suggested exit code (e.g. 130 for SIGINT). Present when a signal caused termination. */
+      exitCode?: number;
+      /** Flattens the result: awaits Promises, collects iterables, catches errors. Never throws. */
+      drain: () => Promise<PadroneDrainResult<GetResults<TCommand>>>;
+    })
+  | {
+      command?: TCommand;
+      args?: GetArguments<'out', TCommand>;
+      argsResult?: StandardSchemaV1.Result<GetArguments<'out', TCommand>>;
+      error: unknown;
+      result?: never;
+      /** The signal that caused cancellation, if any. */
+      signal?: PadroneSignal;
+      /** Suggested exit code (e.g. 130 for SIGINT). Present when a signal caused termination. */
+      exitCode?: number;
+      /** Returns `{ error }` since there is no result to drain. */
+      drain: () => Promise<PadroneDrainResult<GetResults<TCommand>>>;
+    };
+
+/**
+ * Like `MaybePromise<PadroneCommandResult<TCommand>, TAsync>` but ensures `drain()` is available
+ * at the outer level in all cases — both sync (Thenable) and async (Promise).
+ */
+export type MaybePromiseCommandResult<TCommand extends AnyPadroneCommand, TAsync> = MaybePromise<PadroneCommandResult<TCommand>, TAsync> & {
+  drain: () => Promise<PadroneDrainResult<GetResults<TCommand>>>;
+};
+
+export type PadroneParseResult<TCommand extends AnyPadroneCommand = AnyPadroneCommand> = {
+  command: TCommand;
+  args?: GetArguments<'out', TCommand>;
+  argsResult?: StandardSchemaV1.Result<GetArguments<'out', TCommand>>;
+};
+
+export type PadroneAPI<TCommand extends AnyPadroneCommand> = PadroneAPICommand<TCommand> & {
+  [K in TCommand['~types']['commands'][number] as K['name']]: PadroneAPI<K>;
+};
+
+type PadroneAPICommand<TCommand extends AnyPadroneCommand> = (args: GetArguments<'in', TCommand>) => GetResults<TCommand>;