padrone 1.1.0 → 1.2.0

package/dist/index.d.mts

@@ -1,586 +1,160 @@
-import { StandardJSONSchemaV1, StandardSchemaV1 } from "@standard-schema/spec";
-import { Tool } from "ai";
+import { _ as PossibleCommands, a as PadroneActionContext, b as PadroneRuntime, c as PadroneCommandResult, d as PadroneProgram, f as PadroneSchema, g as PickCommandByName, h as UpdateCheckConfig, i as AsyncPadroneSchema, l as PadroneParseResult, m as WrapResult, n as AnyPadroneCommand, o as PadroneBuilder, p as WrapConfig, r as AnyPadroneProgram, s as PadroneCommand, t as AnyPadroneBuilder, u as PadronePlugin, v as InteractiveMode, x as REPL_SIGINT, y as InteractivePromptConfig } from "./types-qrtt0135.mjs";
+import { r as HelpInfo } from "./formatter-Dvx7jFXr.mjs";
 
-//#region src/formatter.d.ts
-type HelpFormat = 'text' | 'ansi' | 'console' | 'markdown' | 'html' | 'json';
-type HelpDetail = 'minimal' | 'standard' | 'full';
+//#region src/command-utils.d.ts
 /**
- * Information about a single positional argument.
- */
-type HelpArgumentInfo = {
-  name: string;
-  description?: string;
-  optional: boolean;
-  default?: unknown;
-  type?: string;
-};
-/**
- * Information about a single option/flag.
- */
-type HelpOptionInfo = {
-  name: string;
-  description?: string;
-  optional: boolean;
-  default?: unknown;
-  type?: string;
-  enum?: string[];
-  aliases?: string[];
-  deprecated?: boolean | string;
-  hidden?: boolean;
-  examples?: unknown[]; /** Environment variable(s) this option can be set from */
-  env?: string | string[]; /** Whether this option is an array type (shown as <type...>) */
-  variadic?: boolean; /** Whether this option is a boolean (shown as --[no-]option) */
-  negatable?: boolean; /** Config file key that maps to this option */
-  configKey?: string;
-};
-/**
- * Information about a subcommand (minimal info for listing).
- */
-type HelpSubcommandInfo = {
-  name: string;
-  title?: string;
-  description?: string;
-  aliases?: string[];
-  deprecated?: boolean | string;
-  hidden?: boolean;
-};
-/**
- * Comprehensive JSON structure for help information.
- * This is the single source of truth that all formatters use.
- */
-type HelpInfo = {
-  /** The full command name (e.g., "cli serve" or "<root>") */name: string; /** Short title for the command */
-  title?: string; /** Command description */
-  description?: string; /** Alternative names/aliases for this command */
-  aliases?: string[]; /** Whether the command is deprecated */
-  deprecated?: boolean | string; /** Whether the command is hidden */
-  hidden?: boolean; /** Usage string parts for flexible formatting */
-  usage: {
-    command: string;
-    hasSubcommands: boolean;
-    hasArguments: boolean;
-    hasOptions: boolean;
-  }; /** List of subcommands */
-  subcommands?: HelpSubcommandInfo[]; /** Positional arguments */
-  arguments?: HelpArgumentInfo[]; /** Options/flags (only visible ones, hidden filtered out) */
-  options?: HelpOptionInfo[]; /** Full help info for nested commands (used in 'full' detail mode) */
-  nestedCommands?: HelpInfo[];
-};
-//#endregion
-//#region src/help.d.ts
-type HelpOptions = {
-  format?: HelpFormat | 'auto';
-  detail?: HelpDetail;
-};
-//#endregion
-//#region src/options.d.ts
-interface PadroneOptionsMeta {
-  description?: string;
-  alias?: string[] | string;
-  deprecated?: boolean | string;
-  hidden?: boolean;
-  examples?: unknown[];
-}
-type PositionalArgs<TObj> = TObj extends Record<string, any> ? { [K in keyof TObj]: TObj[K] extends Array<any> ? `...${K & string}` : K & string }[keyof TObj] : string;
-/**
- * Meta configuration for options including positional arguments.
- * The `positional` array defines which options are positional arguments and their order.
- * Use '...name' prefix to indicate variadic (rest) arguments, matching JS/TS rest syntax.
+ * Brands a schema as async, signaling that its `validate()` may return a Promise.
+ * When an async-branded schema is passed to `.arguments()`, `.configFile()`, or `.env()`,
+ * the command's `parse()` and `cli()` will return Promises.
  *
  * @example
  * ```ts
- * .arguments(schema, {
- *   positional: ['source', '...files', 'dest'],  // '...files' is variadic
- * })
+ * const schema = asyncSchema(z.object({
+ *   name: z.string(),
+ * }).check(async (data) => {
+ *   // async validation logic
+ * }));
+ *
+ * const program = createPadrone('app')
+ *   .command('greet', (c) => c.arguments(schema).action((args) => args.name));
+ *
+ * // parse() now returns Promise<PadroneParseResult>
+ * const result = await program.parse('greet --name world');
  * ```
  */
-interface PadroneMeta<TObj = Record<string, any>> {
-  /**
-   * Array of option names that should be treated as positional arguments.
-   * Order in array determines position. Use '...name' prefix for variadic args.
-   * @example ['source', '...files', 'dest'] - 'files' captures multiple values
-   */
-  positional?: PositionalArgs<TObj>[];
-  /**
-   * Per-option metadata.
-   */
-  options?: { [K in keyof TObj]?: PadroneOptionsMeta };
-}
-//#endregion
-//#region src/type-utils.d.ts
-type SafeString = string & {};
-type IsUnknown<T> = unknown extends T ? true : false;
-type IsAny<T> = any extends T ? true : false;
-type IsNever<T> = [T] extends [never] ? true : false;
-type IsGeneric<T> = IsAny<T> extends true ? true : IsUnknown<T> extends true ? true : IsNever<T> extends true ? true : false;
-type SplitString<TName extends string, TSplitBy extends string = ' '> = TName extends `${infer FirstPart}${TSplitBy}${infer RestParts}` ? [FirstPart, ...SplitString<RestParts, TSplitBy>] : [TName];
-type JoinString<TParts extends string[], TJoinBy extends string = ' '> = TParts extends [infer FirstPart extends string, ...infer RestParts extends string[]] ? RestParts extends [] ? FirstPart : `${FirstPart}${TJoinBy}${JoinString<RestParts, TJoinBy>}` : TParts extends [] ? '' : TParts[number];
-type SplitLastSpace<S extends string> = SplitString<S> extends [...infer Init extends string[], infer Last extends string] ? Init extends [] ? [S, never] : [JoinString<Init>, Last] : [S, never];
-type AnyPartExtends<U, T> = [U] extends [never] ? false : U extends any ? (U extends T ? true : never) : never extends true ? true : false;
-type FullCommandName<TName extends string, TParentName extends string = ''> = TParentName extends '' ? TName : `${TParentName} ${TName}`;
-/**
- * Generate full alias paths by combining parent path with each alias.
- */
-type FullAliasPaths<TAliases extends string[], TParentName extends string = ''> = TAliases extends [infer First extends string, ...infer Rest extends string[]] ? FullCommandName<First, TParentName> | FullAliasPaths<Rest, TParentName> : never;
-/**
- * Get all paths for a command including its primary path and all alias paths.
- */
-type GetCommandPathsAndAliases<TCommand extends AnyPadroneCommand> = TCommand['~types']['path'] extends infer Path extends string ? TCommand['~types']['aliases'] extends infer Aliases extends string[] ? TCommand['~types']['parentName'] extends infer ParentName extends string ? Path | FullAliasPaths<Aliases, ParentName> : Path : Path : never;
-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 : TCommands extends [infer FirstCommand, ...infer RestCommands] ? (RestCommands extends AnyPadroneCommand[] ? FlattenCommands<RestCommands> : never) | (FirstCommand extends AnyPadroneCommand ? FlattenCommands<FirstCommand['~types']['commands']> | FirstCommand : never) : IsAny<TCommands[number]> extends true ? never : TCommands[number];
-/**
- * Get all command paths including alias paths for all commands.
- */
-type GetCommandPathsOrAliases<TCommands extends AnyPadroneCommand[]> = GetCommandPathsAndAliases<FlattenCommands<TCommands>>;
-/**
- * Find all the commands that are prefixed with a command name or alias.
- * This is needed to avoid matching other commands when followed by a space and another word.
- * For example, let's say `level1` and `level1 level2` are commands.
- * Then `level1 ${string}` would also match `level1 level2`,
- * and it would cause `level1 level2` to not show up in the autocomplete.
- * By excluding those cases, we can ensure autocomplete works correctly.
- */
-type PrefixedCommands<TCommands extends AnyPadroneCommand[]> = GetCommandPathsOrAliases<TCommands> extends infer CommandNames ? CommandNames extends string ? AnyPartExtends<GetCommandPathsOrAliases<TCommands>, `${CommandNames} ${string}`> extends true ? never : `${CommandNames} ${string}` : never : never;
-/**
- * The possible commands are the commands that can be parsed by the program.
- * This includes the string that are exact matches to a command name or alias, and strings that are prefixed with a command name or alias.
- */
-type PossibleCommands<TCommands extends AnyPadroneCommand[], TWithPrefixed extends boolean = false, TWithObjects extends boolean = false, TWithFallback extends boolean = true> = GetCommandPathsOrAliases<TCommands> | (TWithPrefixed extends true ? PrefixedCommands<TCommands> : never) | (TWithObjects extends true ? FlattenCommands<TCommands> : never) | (TWithFallback extends true ? SafeString : never);
-type CommandIsUnknownable<TCommand> = IsGeneric<TCommand> extends true ? true : string extends TCommand ? true : SafeString extends TCommand ? true : false;
-/**
- * Match a string to a command by the possible commands.
- * This is done by recursively splitting the string by the last space, and then checking if the prefix is a valid command name or alias.
- * This is needed to avoid matching the top-level command when there are nested commands.
- */
-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/wrap.d.ts
-/**
- * Configuration options for wrapping an external CLI tool.
- */
-type WrapConfig<TCommandOpts extends PadroneSchema = PadroneSchema, TWrapOpts extends PadroneSchema = TCommandOpts> = {
-  /**
-   * The command to execute (e.g., 'git', 'docker', 'npm').
-   */
-  command: string;
-  /**
-   * Optional fixed arguments that always precede the options (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 options to external CLI arguments.
-   * The schema's input type should match the command options, and its output type defines
-   * the arguments expected by the external command.
-   * If not provided, command options are passed through as-is.
-   */
-  schema?: TWrapOpts | ((commandOptions: TCommandOpts) => TWrapOpts);
+declare function asyncSchema<T extends PadroneSchema>(schema: T): T & {
+  '~async': true;
 };
 /**
- * Result from executing a wrapped CLI tool.
+ * Builds a completer function for the REPL from the command tree.
+ * Completes command names, subcommand names, option names (--foo), and aliases (-f).
+ * Also includes dot-prefixed built-in REPL commands (.exit, .clear, .scope, .help, .history).
  */
-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/types.d.ts
-type UnknownRecord = Record<string, unknown>;
-type EmptyRecord = Record<string, never>;
-type DefaultOpts = UnknownRecord | void;
-/**
- * A schema that supports both validation (StandardSchemaV1) and JSON schema generation (StandardJSONSchemaV1).
- * This is the type required for command arguments and options in Padrone.
- */
-type PadroneSchema<Input = unknown, Output = Input> = StandardSchemaV1<Input, Output> & StandardJSONSchemaV1<Input, Output>;
-/**
- * Helper type to set aliases on a command type.
- * Uses intersection to override just the aliases while preserving all other type information.
- */
-type WithAliases<TCommand extends AnyPadroneCommand, TAliases extends string[]> = Omit<TCommand, 'aliases' | '~types'> & {
-  aliases?: TAliases;
-  '~types': Omit<TCommand['~types'], 'aliases'> & {
-    aliases: TAliases;
-  };
-};
-type PadroneCommand<TName extends string = string, TParentName extends string = '', TOpts extends PadroneSchema = PadroneSchema<DefaultOpts>, TRes = void, TCommands extends [...AnyPadroneCommand[]] = [], TAliases extends string[] = string[], TConfig extends PadroneSchema<unknown, StandardSchemaV1.InferInput<TOpts>> = PadroneSchema<void>, TEnv extends PadroneSchema<unknown, StandardSchemaV1.InferInput<TOpts>> = PadroneSchema<void>> = {
-  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;
-  needsApproval?: boolean | ((options: TOpts) => Promise<boolean> | boolean);
-  options?: TOpts;
-  config?: TConfig;
-  envSchema?: TEnv;
-  meta?: GetMeta<TOpts>;
-  handler?: (options: StandardSchemaV1.InferOutput<TOpts>) => TRes; /** List of possible config file names to search for. */
-  configFiles?: string[];
-  parent?: AnyPadroneCommand;
-  commands?: TCommands; /** @deprecated Internal use only */
-  '~types': {
-    name: TName;
-    parentName: TParentName;
-    path: FullCommandName<TName, TParentName>;
-    aliases: TAliases;
-    optionsInput: StandardSchemaV1.InferInput<TOpts>;
-    optionsOutput: StandardSchemaV1.InferOutput<TOpts>;
-    result: TRes;
-    commands: TCommands;
-  };
-};
-type AnyPadroneCommand = PadroneCommand<string, any, any, any, [...AnyPadroneCommand[]], string[]>;
-/**
- * Base type for extracting command information from builder or program.
- * Both PadroneBuilder and PadroneProgram share this structure.
- */
-type CommandTypesBase = {
-  '~types': {
-    command: AnyPadroneCommand;
-  };
-};
-/**
- * Configuration options for a command.
- */
-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;
-};
-/**
- * Conditional type that returns either PadroneBuilder or PadroneProgram based on TReturn.
- * Used to avoid repetition in PadroneBuilderMethods return types.
- */
-type BuilderOrProgram<TReturn extends 'builder' | 'program', TProgramName extends string, TName extends string, TParentName extends string, TOpts extends PadroneSchema, TRes, TCommands extends [...AnyPadroneCommand[]], TParentOpts extends PadroneSchema, TConfig extends PadroneSchema<unknown, StandardSchemaV1.InferInput<TOpts>>, TEnv extends PadroneSchema<unknown, StandardSchemaV1.InferInput<TOpts>>> = TReturn extends 'builder' ? PadroneBuilder<TProgramName, TName, TParentName, TOpts, TRes, TCommands, TParentOpts, TConfig, TEnv> : PadroneProgram<TProgramName, TName, TParentName, TOpts, TRes, TCommands, TParentOpts, TConfig, TEnv>;
-/**
- * Base builder methods shared between PadroneBuilder and PadroneProgram.
- * These methods are used for defining command structure (options, config, env, action, subcommands).
- */
-type PadroneBuilderMethods<TProgramName extends string, TName extends string, TParentName extends string, TOpts extends PadroneSchema, TRes, TCommands extends [...AnyPadroneCommand[]], TParentOpts extends PadroneSchema, TConfig extends PadroneSchema<unknown, StandardSchemaV1.InferInput<TOpts>>, TEnv extends PadroneSchema<unknown, StandardSchemaV1.InferInput<TOpts>>, /** The return type for builder methods - either PadroneBuilder or PadroneProgram */TReturn extends 'builder' | 'program'> = {
-  /**
-   * Configures command properties like title, description, version, deprecated, and hidden.
-   * @example
-   * ```ts
-   * .configure({
-   *   title: 'Build Project',
-   *   description: 'Compiles the project',
-   *   deprecated: 'Use "compile" instead',
-   * })
-   * ```
-   */
-  configure: (config: PadroneCommandConfig) => BuilderOrProgram<TReturn, TProgramName, TName, TParentName, TOpts, TRes, TCommands, TParentOpts, TConfig, TEnv>;
-  /**
-   * Defines the options schema for the command, including positional arguments.
-   * Can accept either a schema directly or a function that takes parent options as a base and returns a schema.
-   * Use the `positional` array in meta to specify which options are positional args.
-   * Use '...name' prefix for variadic (rest) arguments, matching JS/TS rest syntax.
-   *
-   * @example
-   * ```ts
-   * // Direct schema
-   * .arguments(z.object({
-   *   source: z.string(),
-   *   files: z.string().array(),
-   *   dest: z.string(),
-   *   recursive: z.boolean().default(false),
-   * }), {
-   *   positional: ['source', '...files', 'dest'],
-   * })
-   * ```
-   *
-   * @example
-   * ```ts
-   * // Function-based schema extending parent options
-   * .arguments((parentOpts) => {
-   *   return z.object({
-   *     ...parentOpts.shape,
-   *     verbose: z.boolean().default(false),
-   *   });
-   * })
-   * ```
-   */
-  arguments: <TNewOpts extends PadroneSchema = PadroneSchema<void>>(options?: TNewOpts | ((parentOptions: TParentOpts) => TNewOpts), meta?: GetMeta<TNewOpts>) => BuilderOrProgram<TReturn, TProgramName, TName, TParentName, TNewOpts, TRes, TCommands, TParentOpts, TConfig, TEnv>;
-  /**
-   * Configures config file path(s) and schema for parsing config files.
-   * @example
-   * ```ts
-   * .configFile('config.json', z.object({ port: z.number() }))
-   * ```
-   */
-  configFile: <TNewConfig extends PadroneSchema<unknown, StandardSchemaV1.InferInput<TOpts>> = TOpts>(file: string | string[] | undefined, schema?: TNewConfig | ((optionsSchema: TOpts) => TNewConfig)) => BuilderOrProgram<TReturn, TProgramName, TName, TParentName, TOpts, TRes, TCommands, TParentOpts, TNewConfig, TEnv>;
-  /**
-   * Configures environment variable schema for parsing env vars into options.
-   * The schema should transform environment variables (typically SCREAMING_SNAKE_CASE)
-   * into the option names used by the command.
-   * @example
-   * ```ts
-   * .env(z.object({ MY_APP_PORT: z.coerce.number() }).transform(e => ({ port: e.MY_APP_PORT })))
-   * ```
-   */
-  env: <TNewEnv extends PadroneSchema<unknown, StandardSchemaV1.InferInput<TOpts>> = TOpts>(schema: TNewEnv | ((optionsSchema: TOpts) => TNewEnv)) => BuilderOrProgram<TReturn, TProgramName, TName, TParentName, TOpts, TRes, TCommands, TParentOpts, TConfig, TNewEnv>;
-  /**
-   * Defines the handler function to be executed when the command is run.
-   */
-  action: <TNewRes>(handler?: (options: StandardSchemaV1.InferOutput<TOpts>) => TNewRes) => BuilderOrProgram<TReturn, TProgramName, TName, TParentName, TOpts, TNewRes, TCommands, TParentOpts, TConfig, TEnv>;
-  /**
-   * Wraps an external CLI tool with optional schema transformation.
-   * The config can include a schema that transforms command options to external CLI arguments.
-   *
-   * @example
-   * ```ts
-   * // No transformation - pass options as-is
-   * .arguments(z.object({
-   *   message: z.string(),
-   * }))
-   * .wrap({
-   *   command: 'echo',
-   * })
-   * ```
-   *
-   * @example
-   * ```ts
-   * // With transformation schema
-   * .arguments(z.object({
-   *   message: z.string(),
-   *   all: z.boolean().optional(),
-   * }), {
-   *   positional: ['message'],
-   * })
-   * .wrap({
-   *   command: 'git',
-   *   args: ['commit'],
-   *   positional: ['m'],
-   *   schema: z.object({
-   *     message: z.string(),
-   *     all: z.boolean().optional(),
-   *   }).transform(opts => ({
-   *     m: opts.message,
-   *     a: opts.all,
-   *   })),
-   * })
-   * ```
-   *
-   * @example
-   * ```ts
-   * // Using function-based schema for type inference
-   * .arguments(z.object({
-   *   image: z.string(),
-   *   detach: z.boolean().optional(),
-   * }))
-   * .wrap({
-   *   command: 'docker',
-   *   args: ['run'],
-   *   positional: ['image'],
-   *   schema: (cmdOpts) => cmdOpts.transform(opts => ({
-   *     d: opts.detach,
-   *     image: opts.image,
-   *   })),
-   * })
-   * ```
-   */
-  wrap: <TWrapOpts extends PadroneSchema = TOpts>(config: WrapConfig<TOpts, TWrapOpts>) => BuilderOrProgram<TReturn, TProgramName, TName, TParentName, TOpts, Promise<WrapResult>, TCommands, TParentOpts, TConfig, TEnv>;
-  /**
-   * Creates a nested command within the current command with the given name and builder function.
-   * The name can be a single string or a tuple of [name, ...aliases] where additional strings are aliases.
-   * @example
-   * ```ts
-   * // Single name
-   * .command('list', (c) => c.action(() => 'list'))
-   *
-   * // Name with aliases
-   * .command(['list', 'ls', 'l'], (c) => c.action(() => 'list'))
-   * ```
-   */
-  command: <TNameNested extends string, TAliases extends string[] = [], TBuilder extends CommandTypesBase = PadroneBuilder<TProgramName, TNameNested, FullCommandName<TName, TParentName>, any, void, [], TOpts, any, any>>(name: TNameNested | readonly [TNameNested, ...TAliases], builderFn?: (builder: PadroneBuilder<TProgramName, TNameNested, FullCommandName<TName, TParentName>, PadroneSchema<void>, void, [], TOpts, PadroneSchema<void>, PadroneSchema<void>>) => TBuilder) => BuilderOrProgram<TReturn, TProgramName, TName, TParentName, TOpts, TRes, TCommands extends [] ? [WithAliases<TBuilder['~types']['command'], TAliases>] : AnyPadroneCommand[] extends TCommands ? [WithAliases<TBuilder['~types']['command'], TAliases>] : [...TCommands, WithAliases<TBuilder['~types']['command'], TAliases>], TParentOpts, TConfig, TEnv>; /** @deprecated Internal use only */
-  '~types': {
-    programName: TProgramName;
-    name: TName;
-    parentName: TParentName;
-    path: FullCommandName<TName, TParentName>;
-    aliases: [];
-    options: TOpts;
-    result: TRes;
-    commands: TCommands;
-    command: PadroneCommand<TName, TParentName, TOpts, TRes, TCommands, []>;
-  };
-};
-type PadroneBuilder<TProgramName extends string = '', TName extends string = string, TParentName extends string = '', TOpts extends PadroneSchema = PadroneSchema<DefaultOpts>, TRes = void, TCommands extends [...AnyPadroneCommand[]] = [], TParentOpts extends PadroneSchema = PadroneSchema<void>, TConfig extends PadroneSchema<unknown, StandardSchemaV1.InferInput<TOpts>> = PadroneSchema<void>, TEnv extends PadroneSchema<unknown, StandardSchemaV1.InferInput<TOpts>> = PadroneSchema<void>> = PadroneBuilderMethods<TProgramName, TName, TParentName, TOpts, TRes, TCommands, TParentOpts, TConfig, TEnv, 'builder'>;
-type PadroneProgram<TProgramName extends string = '', TName extends string = string, TParentName extends string = '', TOpts extends PadroneSchema = PadroneSchema<DefaultOpts>, TRes = void, TCommands extends [...AnyPadroneCommand[]] = [], TParentOpts extends PadroneSchema = PadroneSchema<void>, TConfig extends PadroneSchema<unknown, StandardSchemaV1.InferInput<TOpts>> = PadroneSchema<void>, TEnv extends PadroneSchema<unknown, StandardSchemaV1.InferInput<TOpts>> = PadroneSchema<void>> = PadroneBuilderMethods<TProgramName, TName, TParentName, TOpts, TRes, TCommands, TParentOpts, TConfig, TEnv, 'program'> & {
-  /**
-   * Runs a command programmatically by name with provided options (including positional args).
-   */
-  run: <const TCommand extends PossibleCommands<[PadroneCommand<'', '', TOpts, TRes, TCommands>], true, true>>(name: TCommand | SafeString, options: NoInfer<GetOptions<'in', PickCommandByName<[PadroneCommand<'', '', TOpts, TRes, TCommands>], TCommand>>>) => PadroneCommandResult<PickCommandByName<[PadroneCommand<'', '', TOpts, TRes, TCommands>], TCommand>>;
-  /**
-   * Runs the program as a CLI application, parsing `process.argv` or provided input.
-   */
-  cli: <const TCommand extends PossibleCommands<[PadroneCommand<'', '', TOpts, TRes, TCommands>], true, true>>(input?: TCommand | SafeString, options?: PadroneParseOptions) => PadroneCommandResult<PickCommandByPossibleCommands<[PadroneCommand<'', '', TOpts, TRes, TCommands>], TCommand>>;
-  /**
-   * Parses CLI input (or the provided input string) into command, args, and options without executing anything.
-   */
-  parse: <const TCommand extends PossibleCommands<[PadroneCommand<'', '', TOpts, TRes, TCommands>], true, false>>(input?: TCommand | SafeString, options?: PadroneParseOptions) => PadroneParseResult<PickCommandByPossibleCommands<[PadroneCommand<'', '', TOpts, TRes, TCommands>], TCommand>>;
-  /**
-   * Converts command and options back into a CLI string.
-   */
-  stringify: <const TCommand extends PossibleCommands<[PadroneCommand<'', '', TOpts, TRes, TCommands>], false, true>>(command?: TCommand | SafeString, options?: GetOptions<'out', PickCommandByPossibleCommands<[PadroneCommand<'', '', TOpts, TRes, TCommands>], TCommand>>) => string;
-  /**
-   * Finds a command by name, returning `undefined` if not found.
-   */
-  find: <const TFind extends PossibleCommands<[PadroneCommand<'', '', TOpts, TRes, TCommands>], false, true>>(command: TFind | SafeString) => PickCommandByPossibleCommands<[PadroneCommand<'', '', TOpts, TRes, TCommands>], TFind> | undefined;
-  /**
-   * Generates a type-safe API for invoking commands programmatically.
-   */
-  api: () => PadroneAPI<PadroneCommand<'', '', TOpts, TRes, TCommands>>;
-  /**
-   * Starts an interactive prompt to run commands.
-   */
-  /**
-   * Starts a REPL (Read-Eval-Print Loop) for running commands interactively.
-   */
-  /**
-   * Returns a tool definition that can be passed to AI SDK.
-   */
-  tool: () => Tool<{
-    command: string;
-  }>;
-  /**
-   * Returns the help information for the program or a specific command.
-   */
-  help: <const TCommand extends PossibleCommands<[PadroneCommand<'', '', TOpts, TRes, TCommands>], false, true>>(command?: TCommand, options?: HelpOptions) => string;
-  /**
-   * Generates and returns a shell completion script.
-   * If shell is not specified, automatically detects the current shell and provides instructions.
-   * @param shell - The shell type (bash, zsh, fish, powershell). If not provided, auto-detects.
-   * @returns The shell completion script as a string.
-   * @example
-   * ```ts
-   * // Get bash completion script
-   * const bashScript = program.completion('bash');
-   *
-   * // Auto-detect shell and get completion script with instructions
-   * const script = program.completion();
-   * ```
-   */
-  completion: (shell?: 'bash' | 'zsh' | 'fish' | 'powershell') => string;
-};
-type AnyPadroneProgram = PadroneProgram<string, string, string, any, any, [...AnyPadroneCommand[]]>;
-type PadroneCommandResult<TCommand extends AnyPadroneCommand = AnyPadroneCommand> = PadroneParseResult<TCommand> & {
-  result: GetResults<TCommand>;
-};
-/**
- * Options for parsing CLI input.
- */
-type PadroneParseOptions = {
-  /**
-   * Raw environment variables to use for env schema validation.
-   * If not provided, process.env will be used.
-   */
-  env?: Record<string, string | undefined>;
-  /**
-   * Pre-parsed environment data to use directly (bypasses env schema validation).
-   * Keys should match option names.
-   */
-  envData?: Record<string, unknown>;
-  /**
-   * Config file data to use for config binding.
-   * This should be the parsed content of a config file (JSON, YAML, etc.).
-   */
-  configData?: Record<string, unknown>;
-};
-type PadroneParseResult<TCommand extends AnyPadroneCommand = AnyPadroneCommand> = {
-  command: TCommand;
-  options?: GetOptions<'out', TCommand>;
-  optionsResult?: StandardSchemaV1.Result<GetOptions<'out', TCommand>>;
-};
-type PadroneAPI<TCommand extends AnyPadroneCommand> = PadroneAPICommand<TCommand> & { [K in TCommand['~types']['commands'][number] as K['name']]: PadroneAPI<K> };
-type PadroneAPICommand<TCommand extends AnyPadroneCommand> = (options: GetOptions<'in', TCommand>) => GetResults<TCommand>;
-type NormalizeOptions<TOptions> = IsGeneric<TOptions> extends true ? void | EmptyRecord : TOptions;
-type GetOptions<TDir extends 'in' | 'out', TCommand extends AnyPadroneCommand> = TDir extends 'in' ? NormalizeOptions<TCommand['~types']['optionsInput']> : NormalizeOptions<TCommand['~types']['optionsOutput']>;
-type GetResults<TCommand extends AnyPadroneCommand> = ReturnType<NonNullable<TCommand['handler']>>;
-type GetMeta<TOpts extends PadroneSchema> = PadroneMeta<NonNullable<StandardSchemaV1.InferInput<TOpts>>>;
+declare function buildReplCompleter(rootCommand: AnyPadroneCommand, builtins: {
+  inScope?: boolean;
+}): (line: string) => [string[], string];
 //#endregion
 //#region src/create.d.ts
 declare function createPadrone<TProgramName extends string>(name: TProgramName): PadroneProgram<TProgramName, '', ''>;
 //#endregion
-//#region src/type-helpers.d.ts
+//#region src/errors.d.ts
 /**
- * Extracts the input type of the options schema from a command.
- * @example
- * ```ts
- * type Options = InferOptionsInput<typeof myCommand>;
- * ```
+ * Structured error hierarchy for Padrone CLI framework.
+ *
+ * All Padrone errors extend `PadroneError`, which carries an exit code,
+ * optional suggestions, and context about which command/phase produced the error.
+ * This allows callers to distinguish user errors (bad input) from bugs (unexpected throws)
+ * and to present formatted, actionable error messages.
  */
-type InferOptionsInput<T extends AnyPadroneCommand> = T['~types']['optionsInput'];
+type PadroneErrorOptions = {
+  /** Process exit code. Defaults to 1. */exitCode?: number; /** Actionable suggestions shown to the user (e.g. "Use --env production"). */
+  suggestions?: string[]; /** The command path that produced the error (e.g. "deploy staging"). */
+  command?: string; /** The phase where the error occurred. */
+  phase?: 'parse' | 'validate' | 'execute' | 'config'; /** Original cause for error chaining. */
+  cause?: unknown;
+};
 /**
- * Extracts the output type of the options schema from a command.
+ * Base error class for all Padrone errors.
+ * Carries structured metadata for user-friendly formatting and programmatic handling.
+ *
  * @example
  * ```ts
- * type Options = InferOptionsOutput<typeof myCommand>;
+ * throw new PadroneError('Something went wrong', {
+ *   exitCode: 1,
+ *   suggestions: ['Try --help for usage information'],
+ * });
  * ```
  */
-type InferOptionsOutput<T extends AnyPadroneCommand> = T['~types']['optionsOutput'];
+declare class PadroneError extends Error {
+  readonly exitCode: number;
+  readonly suggestions: string[];
+  readonly command?: string;
+  readonly phase?: 'parse' | 'validate' | 'execute' | 'config';
+  constructor(message: string, options?: PadroneErrorOptions);
+  /**
+   * Returns a serializable representation of the error,
+   * suitable for non-terminal runtimes (web UIs, APIs, etc.).
+   */
+  toJSON(): {
+    name: string;
+    message: string;
+    exitCode: number;
+    suggestions: string[];
+    command?: string;
+    phase?: string;
+  };
+}
 /**
- * Extracts the input type of the config schema from a command.
- * @example
- * ```ts
- * type Config = InferConfigInput<typeof myCommand>;
- * ```
+ * Thrown when command routing fails — unknown command, unexpected arguments, etc.
+ */
+declare class RoutingError extends PadroneError {
+  constructor(message: string, options?: PadroneErrorOptions);
+}
+/**
+ * Thrown when argument or schema validation fails.
+ * Carries the structured issues from the schema validator.
+ */
+declare class ValidationError extends PadroneError {
+  readonly issues: readonly {
+    path?: PropertyKey[];
+    message: string;
+  }[];
+  constructor(message: string, issues: readonly {
+    path?: PropertyKey[];
+    message: string;
+  }[], options?: PadroneErrorOptions);
+  toJSON(): {
+    issues: {
+      path: string[] | undefined;
+      message: string;
+    }[];
+    name: string;
+    message: string;
+    exitCode: number;
+    suggestions: string[];
+    command?: string;
+    phase?: string;
+  };
+}
+/**
+ * Thrown when config file loading or validation fails.
  */
-type InferConfigInput<T extends AnyPadroneCommand> = T['config'] extends PadroneSchema<infer I, any> ? I : never;
+declare class ConfigError extends PadroneError {
+  constructor(message: string, options?: PadroneErrorOptions);
+}
 /**
- * Extracts the output type of the config schema from a command.
- * This is the type after transformation, which should match the options shape.
+ * Thrown from user action handlers to surface structured errors with exit codes and suggestions.
+ * This is the primary error class users should throw from their command actions.
+ *
  * @example
  * ```ts
- * type ConfigOutput = InferConfigOutput<typeof myCommand>;
+ * throw new ActionError('Missing environment', {
+ *   exitCode: 1,
+ *   suggestions: ['Use --env production or --env staging'],
+ * });
  * ```
  */
-type InferConfigOutput<T extends AnyPadroneCommand> = T['config'] extends PadroneSchema<any, infer O> ? O : never;
+declare class ActionError extends PadroneError {
+  constructor(message: string, options?: PadroneErrorOptions);
+}
+//#endregion
+//#region src/type-helpers.d.ts
 /**
- * Extracts the input type of the env schema from a command.
- * This represents the raw environment variables shape (e.g., { PORT: string }).
+ * Extracts the input type of the arguments schema from a command.
  * @example
  * ```ts
- * type EnvInput = InferEnvInput<typeof myCommand>;
+ * type Args = InferArgsInput<typeof myCommand>;
  * ```
  */
-type InferEnvInput<T extends AnyPadroneCommand> = T['envSchema'] extends PadroneSchema<infer I, any> ? I : never;
+type InferArgsInput<T extends AnyPadroneCommand> = T['~types']['argsInput'];
 /**
- * Extracts the output type of the env schema from a command.
- * This is the type after transformation, which should match the options shape.
+ * Extracts the output type of the arguments schema from a command.
  * @example
  * ```ts
- * type EnvOutput = InferEnvOutput<typeof myCommand>;
+ * type Args = InferArgsOutput<typeof myCommand>;
  * ```
  */
-type InferEnvOutput<T extends AnyPadroneCommand> = T['envSchema'] extends PadroneSchema<any, infer O> ? O : never;
+type InferArgsOutput<T extends AnyPadroneCommand> = T['~types']['argsOutput'];
 /**
  * Gets a command type by its path from a program or command tree.
  * Supports both full paths (e.g., "config set") and alias paths.
@@ -598,5 +172,5 @@ type InferEnvOutput<T extends AnyPadroneCommand> = T['envSchema'] extends Padron
  */
 type InferCommand<T extends AnyPadroneCommand | AnyPadroneProgram, TPath extends PossibleCommands<T extends AnyPadroneCommand ? [T] : T['~types']['commands'], true, true>> = T extends AnyPadroneProgram ? PickCommandByName<[PadroneCommand<'', '', any, any, T['~types']['commands']>], TPath> : T extends AnyPadroneCommand ? PickCommandByName<[T], TPath> : never;
 //#endregion
-export { type AnyPadroneCommand, type AnyPadroneProgram, type HelpArgumentInfo, type HelpFormat, type HelpInfo, type HelpOptionInfo, type HelpOptions, type HelpSubcommandInfo, type InferCommand, type InferConfigInput, type InferConfigOutput, type InferEnvInput, type InferEnvOutput, type InferOptionsInput, type InferOptionsOutput, type PadroneBuilder, type PadroneCommand, type PadroneCommandConfig, type PadroneCommandResult, type PadroneOptionsMeta, type PadroneParseOptions, type PadroneParseResult, type PadroneProgram, type PadroneSchema, type WrapConfig, type WrapResult, createPadrone };
+export { ActionError, type AnyPadroneBuilder, type AnyPadroneCommand, type AnyPadroneProgram, type AsyncPadroneSchema, ConfigError, type HelpInfo, type InferArgsInput, type InferArgsOutput, type InferCommand, type InteractiveMode, type InteractivePromptConfig, type PadroneActionContext, type PadroneBuilder, type PadroneCommand, type PadroneCommandResult, PadroneError, type PadroneErrorOptions, type PadroneParseResult, type PadronePlugin, type PadroneProgram, type PadroneRuntime, type PadroneSchema, REPL_SIGINT, RoutingError, type UpdateCheckConfig, ValidationError, type WrapConfig, type WrapResult, asyncSchema, buildReplCompleter, createPadrone };
 //# sourceMappingURL=index.d.mts.map