import { A as Out, I as ResolutionProvenance, Jn as schemaBrand, Ln as HelpThemeFactory, Rn as ActivityEvent, U as Verbosity, b as CommandSchema, o as PromptEngine, y as CommandMeta } from "./index-BziI2aKc.mjs";
import { Colors } from "ansispeck";
//#region src/core/cli/builtins.d.ts
/** A built-in flag a consumer can take over. */
type BuiltinName = 'help' | 'json' | 'quiet';
/** Whether the root keeps a built-in or releases it to commands. */
type BuiltinMode = 'on' | 'off';
/**
 * Built-in flag settings accepted by {@linkcode CLIBuilder.builtins} and the
 * `builtins` field of {@link CLIDefinition}.
 *
 * `version` and `completions` are absent by design: `.version()` and
 * `.completions()` are opt-in, so a CLI declines those two by not calling them.
 */
interface BuiltinsConfig {
  /**
   * Root `--help`/`-h`, command-level `--help`/`-h`, and the bare `help` token.
   * @defaultValue `'on'`
   */
  readonly help?: BuiltinMode;
  /**
   * Root `--json`.
   * @defaultValue `'on'`
   */
  readonly json?: BuiltinMode;
  /**
   * Root `--quiet`/`-q`.
   * @defaultValue `'on'`
   */
  readonly quiet?: BuiltinMode;
}
/**
 * Normalized built-in flag state stored on {@link CLISchema}.
 *
 * Sealed by {@link createCLISchema}; every key is present after normalization.
 */
interface Builtins {
  /** Type-only seal produced by {@link createCLISchema}. */
  readonly [schemaBrand]: 'builtins';
  /** Whether the root owns `--help`/`-h` and the bare `help` token. */
  readonly help: BuiltinMode;
  /** Whether the root owns `--json`. */
  readonly json: BuiltinMode;
  /** Whether the root owns `--quiet`/`-q`. */
  readonly quiet: BuiltinMode;
}
//#endregion
//#region src/core/errors/index.d.ts
/**
 * Structured error types for DreamCLI.
 *
 * Base {@linkcode CLIError} carries stable code, exit code, suggestion, and structured
 * details. {@linkcode ParseError} and {@linkcode ValidationError} derive from it with
 * category-appropriate defaults.
 *
 * @module dreamcli/core/errors
 */
/** Codes emitted during argv parsing. */
type ParseErrorCode = 'UNKNOWN_FLAG' | 'UNKNOWN_COMMAND' | 'MISSING_VALUE' | 'INVALID_VALUE' | 'INVALID_SCHEMA' | 'DUPLICATE_FLAG' | 'UNEXPECTED_POSITIONAL';
/** Codes emitted during post-parse validation / resolution. */
type ValidationErrorCode = 'REQUIRED_FLAG' | 'REQUIRED_ARG' | 'MISSING_STDIN' | 'INVALID_ENUM' | 'TYPE_MISMATCH' | 'CONSTRAINT_VIOLATED';
/** Any framework error code (extensible via `string & {}`). */
type ErrorCode = ParseErrorCode | ValidationErrorCode | (string & {});
/** Options accepted by the `CLIError` constructor. */
interface CLIErrorOptions {
  /** Stable machine-readable identifier (e.g. `"UNKNOWN_FLAG"`). */
  readonly code: ErrorCode;
  /**
   * Process exit code.
   * @defaultValue `1`
   */
  readonly exitCode?: number;
  /** One-liner actionable hint shown to the user. */
  readonly suggest?: string;
  /** Arbitrary structured payload (serialised in `--json` mode). */
  readonly details?: Readonly<Record<string, unknown>>;
  /** Original error, if this wraps another. */
  readonly cause?: unknown;
}
/**
 * Base structured error for DreamCLI.
 *
 * Every error surfaced by the framework extends this class, ensuring a
 * consistent shape for rendering (TTY pretty-print, `--json`, test assertions).
 */
declare class CLIError extends Error {
  /** Error class name, always `'CLIError'` for the base class. @override */
  readonly name: string;
  /** Stable machine-readable identifier. */
  readonly code: ErrorCode;
  /** Process exit code (defaults to `1`). */
  readonly exitCode: number;
  /** One-liner actionable hint. */
  readonly suggest: string | undefined;
  /** Structured payload for machine output. */
  readonly details: Readonly<Record<string, unknown>> | undefined;
  /** Create a structured CLI error from a human message and machine-readable options. */
  constructor(message: string, options: CLIErrorOptions);
  /**
   * Serialise to a plain object suitable for JSON output.
   *
   * `details` is projected onto JSON-representable values: bigints become
   * decimal digits and entries JSON cannot carry are omitted. The error
   * object itself keeps the runtime values.
   *
   * @sealed
   */
  toJSON(): CLIErrorJSON;
}
/** Shape returned by {@linkcode CLIError}.toJSON(). */
interface CLIErrorJSON {
  /** Error class name (e.g. `'CLIError'`, `'ParseError'`). */
  readonly name: string;
  /** Stable machine-readable identifier for programmatic matching. */
  readonly code: ErrorCode;
  /** Human-readable description of what went wrong. */
  readonly message: string;
  /** Process exit code associated with this error. */
  readonly exitCode: number;
  /** Actionable hint shown to the user, when available. */
  readonly suggest?: string;
  /** Structured payload for machine consumers, when available. */
  readonly details?: Readonly<Record<string, unknown>>;
}
/** Options for {@linkcode ParseError}. Code is narrowed to parse-specific codes. */
interface ParseErrorOptions extends Omit<CLIErrorOptions, 'code' | 'exitCode'> {
  /** Parse-category error code (e.g. `'UNKNOWN_FLAG'`, `'MISSING_VALUE'`). */
  readonly code: ParseErrorCode;
  /**
   * Process exit code for parse failures.
   * @defaultValue `2`
   */
  readonly exitCode?: number;
}
/**
 * Error thrown when argv tokenization / parsing fails.
 *
 * Exit code defaults to `2` (standard for CLI usage errors).
 */
declare class ParseError extends CLIError {
  /** Always `'ParseError'`. @override */
  readonly name: "ParseError";
  /** Narrowed to parse-category codes. */
  readonly code: ParseErrorCode;
  /** Create a parse error with exit code defaulting to `2`. */
  constructor(message: string, options: ParseErrorOptions);
}
/** Options for {@linkcode ValidationError}. Code is narrowed to validation-specific codes. */
interface ValidationErrorOptions extends Omit<CLIErrorOptions, 'code' | 'exitCode'> {
  /** Validation-category error code (e.g. `'REQUIRED_FLAG'`, `'INVALID_ENUM'`). */
  readonly code: ValidationErrorCode;
  /**
   * Process exit code for validation failures.
   * @defaultValue `2`
   */
  readonly exitCode?: number;
}
/**
 * Error thrown when resolved values fail validation constraints.
 *
 * Exit code defaults to `2` (standard for CLI usage errors).
 */
declare class ValidationError extends CLIError {
  /** Always `'ValidationError'`. @override */
  readonly name: "ValidationError";
  /** Narrowed to validation-category codes. */
  readonly code: ValidationErrorCode;
  /** Create a validation error with exit code defaulting to `2`. */
  constructor(message: string, options: ValidationErrorOptions);
}
/** Narrows an unknown value to `CLIError`. */
declare function isCLIError(value: unknown): value is CLIError;
/** Narrows an unknown value to `ParseError`. */
declare function isParseError(value: unknown): value is ParseError;
/** Narrows an unknown value to `ValidationError`. */
declare function isValidationError(value: unknown): value is ValidationError;
//#endregion
//#region src/core/parse/index.d.ts
/**
 * Token discriminated union.
 *
 * The tokenizer produces these from raw argv strings. The parser then
 * interprets them against a command schema.
 */
type Token = {
  readonly kind: 'long-flag';
  readonly name: string;
  readonly value: string | undefined;
} | {
  readonly kind: 'short-flags';
  readonly chars: string;
} | {
  readonly kind: 'positional';
  readonly value: string;
} | {
  readonly kind: 'separator';
};
/**
 * Tokenize raw argv into structured tokens.
 *
 * Low-level utility: most apps should use {@link parse}, `cli().run()`, or
 * `runCommand()` instead of tokenizing manually. Reach for `tokenize()` when
 * building custom tooling such as debuggers, inspectors, or parser tests.
 *
 * Rules:
 * - `--`        → separator (everything after is positional)
 * - `--flag`    → long flag, no inline value
 * - `--flag=v`  → long flag with inline value
 * - `-abc`      → short flags (expanded individually by parser)
 * - `-`         → positional (convention: stdin placeholder)
 * - everything else → positional
 *
 * @param argv - Raw argument strings to tokenize
 * @returns Ordered token array ready for {@link parse}
 *
 * @example
 * ```ts
 * tokenize(['deploy', '--force', '--region=eu', '-v']);
 * ```
 */
declare function tokenize(argv: readonly string[]): readonly Token[];
/**
 * Whether `token` appears in argv before the `--` end-of-options separator.
 *
 * Everything at or after the first `--` is a literal positional, so root-level
 * flag interception (`--help` / `--version` / `--json`) must use this instead of
 * a naive `Array.includes()` — otherwise a post-separator literal (`-- --json`)
 * is wrongly treated as the flag.
 *
 * @param argv - Raw argument strings.
 * @param token - Exact flag token to look for (e.g. `--version`).
 * @returns `true` if `token` occurs before any `--` separator.
 */
declare function includesBeforeSeparator(argv: readonly string[], token: string): boolean;
/**
 * Remove every occurrence of `token` that appears before the `--` end-of-options
 * separator, leaving post-separator literals untouched.
 *
 * The strip counterpart to {@linkcode includesBeforeSeparator}: root-level flags
 * (`--json`) are stripped before dispatch/parse so the command schema never sees
 * them, but a literal after `--` (`-- --json`) must reach the command unchanged.
 *
 * @param argv - Raw argument strings.
 * @param token - Exact flag token to strip (e.g. `--json`).
 * @returns A new argv with pre-separator occurrences of `token` removed, or the
 *   original reference when `token` does not occur before the separator.
 */
declare function stripBeforeSeparator(argv: readonly string[], token: string): readonly string[];
/**
 * Raw parsed values before resolution (defaults, env, config, etc.).
 *
 * Flag values are `unknown` because type coercion happens here but the
 * generic type info lives in the schema builders, not at runtime.
 */
interface ParseResult {
  /** Flag values keyed by canonical flag name. */
  readonly flags: Readonly<Record<string, unknown>>;
  /** Positional arg values keyed by arg name. */
  readonly args: Readonly<Record<string, unknown>>;
}
/** Options accepted by {@link parse} and {@link buildFlagLookup}. */
interface ParseOptions {
  /**
   * Accept the kebab↔camel counterpart spelling of each flag name/alias
   * (`--doThis` for a flag named `do-this`, and vice versa). Automatically
   * disabled per spelling pair when a command explicitly defines both.
   *
   * @defaultValue `true`
   */
  readonly caseParity?: boolean;
}
/**
 * Parse tokenized argv against a command schema.
 *
 * Low-level API: most apps should let `cli()` or `runCommand()` handle parsing
 * automatically. Call `parse()` directly when you need raw parsed values before
 * env/config/default resolution or when writing custom tooling around schemas.
 *
 * @param schema - The command schema to parse against
 * @param argv   - Raw argv strings (NOT including the command name itself)
 * @param options - Parser behavior toggles (see {@link ParseOptions})
 * @returns Parsed flag and arg values
 * @throws ParseError for unknown flags, missing values, type mismatches
 *
 * @example
 * ```ts
 * const parsed = parse(deploy.schema, ['production', '--force']);
 * // => { args: { target: 'production' }, flags: { force: true } }
 * ```
 */
declare function parse(schema: CommandSchema, argv: readonly string[], options?: ParseOptions): ParseResult;
//#endregion
//#region src/core/resolve/contracts.d.ts
/**
 * External state the resolver may consult after parsing.
 *
 * The resolver never reaches into `process`, files, or terminal APIs directly;
 * callers inject those facts through this contract.
 */
interface ResolveOptions {
  /** Pre-read stdin content, or `null` when stdin was not piped. */
  readonly stdinData?: string | null;
  /** Environment variable snapshot injected by the caller. */
  readonly env?: Readonly<Record<string, string | undefined>>;
  /** Parsed config file contents keyed by dotted path segments. */
  readonly config?: Readonly<Record<string, unknown>>;
  /** Interactive prompt engine; absent in non-TTY / CI contexts. */
  readonly prompter?: PromptEngine;
  /**
   * Filesystem probe for `flag.path()` and `arg.path()` checks: what exists
   * at the path, or `null` when nothing does. When absent, path checks are
   * skipped.
   */
  readonly stat?: (path: string) => Promise<'file' | 'directory' | null>;
  /**
   * Recursive directory creation for `flag.path()` and `arg.path()` `create`
   * checks. When absent, missing paths are not created and existence rules
   * apply as-is.
   */
  readonly mkdir?: (path: string) => Promise<void>;
}
/** Structured deprecation notice emitted for explicitly sourced values. */
interface DeprecationWarning {
  /** Whether this deprecation targets a flag or a positional arg. */
  readonly kind: 'flag' | 'arg';
  /** Name of the deprecated flag or arg. */
  readonly name: string;
  /** Custom deprecation message, or `true` for the generic warning. */
  readonly message: string | true;
}
/**
 * Which stage produced each resolved value of one command.
 *
 * The erased form of {@link InputSources}: same records, keyed by plain strings
 * because `resolve()` takes a `CommandSchema` rather than typed builders.
 */
interface ResolutionProvenanceRecord {
  /** Provenance of every declared flag, keyed by flag name. */
  readonly flags: Readonly<Record<string, ResolutionProvenance>>;
  /** Provenance of every declared arg, keyed by arg name. */
  readonly args: Readonly<Record<string, ResolutionProvenance>>;
}
/** Fully resolved command input handed to the executor layer. */
interface ResolveResult {
  /** Fully resolved flag values keyed by flag name. */
  readonly flags: Readonly<Record<string, unknown>>;
  /** Fully resolved positional arg values keyed by arg name. */
  readonly args: Readonly<Record<string, unknown>>;
  /** Deprecation notices collected during resolution (may be empty). */
  readonly deprecations: readonly DeprecationWarning[];
  /**
   * Which stage produced each value. Present only for inputs that resolved a
   * value, so an unset optional input has no entry.
   */
  readonly provenance: ResolutionProvenanceRecord;
}
//#endregion
//#region src/core/resolve/index.d.ts
/**
 * Resolve parsed values against a command schema.
 *
 * Low-level API: most applications should rely on `cli().run()`, `.execute()`,
 * or `runCommand()`, which already call {@linkcode resolve} at the right time.
 * Reach for this function when testing precedence rules directly or building
 * custom execution flows around {@linkcode CommandSchema}.
 *
 * Resolution order:
 * 1. CLI parsed value (from {@linkcode ParseResult})
 * 2. Stdin (from {@linkcode ResolveOptions.stdinData}, if the input declares `stdin`)
 * 3. Env variable (from {@linkcode ResolveOptions.env}, if the input declares `envVar`)
 * 4. Config value (from {@linkcode ResolveOptions.config}, if the input declares `configPath`)
 * 5. Prompt (from {@linkcode ResolveOptions.prompter}, if the input declares `prompt`)
 * 6. Default value (from schema)
 *
 * After resolution, validates that all required flags and args have
 * a value. Collects **all** validation errors before throwing, so the
 * user sees every missing field at once.
 *
 * @param schema - The command schema defining flags and args
 * @param parsed - Raw parsed values from the parser
 * @param options - External state for the resolution chain
 * @returns Fully resolved flag and arg values
 * @throws {@linkcode ValidationError} if any required flag or arg is missing,
 *   or if an env/config value fails coercion
 *
 * @example
 * ```ts
 * const parsed = parse(deploy.schema, ['production']);
 * const resolved = await resolve(deploy.schema, parsed, {
 *   env: { DEPLOY_REGION: 'eu' },
 * });
 * ```
 */
declare function resolve(schema: CommandSchema, parsed: ParseResult, options?: ResolveOptions): Promise<ResolveResult>;
//#endregion
//#region src/core/cli/plugin.d.ts
/** Shared hook payload for a concrete command execution. */
interface PluginCommandContext {
  /** Runtime command schema being executed. */
  readonly command: CommandSchema;
  /** CLI metadata for this execution. */
  readonly meta: CommandMeta;
  /** Output channel for this execution. */
  readonly out: Out;
}
/** Payload for `beforeParse`. */
interface BeforeParseParams extends PluginCommandContext {
  /** Raw argv that will be parsed for the leaf command. */
  readonly argv: readonly string[];
}
/** Payload for hooks that observe resolved inputs. */
interface ResolvedCommandParams extends PluginCommandContext {
  /** Fully resolved flag values. */
  readonly flags: Readonly<Record<string, unknown>>;
  /** Fully resolved argument values. */
  readonly args: Readonly<Record<string, unknown>>;
  /** Structured deprecation warnings collected during resolution. */
  readonly deprecations: readonly DeprecationWarning[];
}
/**
 * Individual lifecycle hooks that a plugin may implement.
 *
 * Hook order for a successful command run is:
 * `beforeParse` → `afterResolve` → `beforeAction` → middleware/action → `afterAction`.
 *
 * Hooks are awaited serially and run in plugin registration order at each
 * stage. Throwing from any hook aborts the command just like throwing from
 * middleware or the action handler. `afterAction` runs only after the
 * middleware chain and action complete successfully.
 */
interface CLIPluginHooks {
  /** Called immediately before leaf-command argv is parsed. */
  readonly beforeParse?: (params: BeforeParseParams) => void | Promise<void>;
  /** Called after parse + resolve, before middleware or action execution. */
  readonly afterResolve?: (params: ResolvedCommandParams) => void | Promise<void>;
  /** Called immediately before the middleware chain and action handler run. */
  readonly beforeAction?: (params: ResolvedCommandParams) => void | Promise<void>;
  /** Called after the middleware chain and action handler complete successfully. */
  readonly afterAction?: (params: ResolvedCommandParams) => void | Promise<void>;
}
/**
 * Immutable plugin definition registered via `CLIBuilder.plugin()`.
 *
 * Use {@link plugin} to construct values of this shape instead of manually
 * assembling the object.
 */
interface CLIPlugin {
  /** Optional label for diagnostics and debugging. */
  readonly name: string | undefined;
  /** Lifecycle hooks implemented by the plugin. */
  readonly hooks: CLIPluginHooks;
}
/**
 * Create a CLI plugin from lifecycle hooks.
 *
 * @param hooks - Lifecycle hooks to register.
 * @param name - Optional plugin name for diagnostics.
 *
 * @example
 * ```ts
 * import { cli, command, plugin } from '@kjanat/dreamcli';
 *
 * const deploy = command('deploy').action(({ out }) => {
 *   out.log('deploying');
 * });
 *
 * const trace = plugin(
 *   {
 *     beforeParse: ({ argv, out }) => {
 *       out.info(`argv: ${argv.join(' ')}`);
 *     },
 *     afterResolve: ({ flags, args }) => {
 *       console.log({ flags, args });
 *     },
 *   },
 *   'trace',
 * );
 *
 * cli('mycli').plugin(trace).command(deploy).run();
 * ```
 *
 * @returns A frozen {@link CLIPlugin} definition.
 */
declare function plugin(hooks: CLIPluginHooks, name?: string): CLIPlugin;
//#endregion
//#region src/core/help/index.d.ts
/** Options for customising help output. */
interface HelpOptions {
  /** Maximum line width (columns). Defaults to 80. */
  readonly width?: number;
  /** Binary/program name shown in the usage line. Defaults to command name. */
  readonly binName?: string;
  /** Program version passed to function-form examples as `meta.version`. */
  readonly version?: string;
  /**
   * Order of flags in the `Flags:` table.
   *
   * - `'alphabetical'` — short-aliased flags first, then alphabetical by name.
   * - `'declaration'` — the order `.flag()` was called.
   *
   * Ignored when {@link HelpOptions.sortFlags} is set.
   *
   * @defaultValue `'alphabetical'`
   */
  readonly flagOrder?: 'alphabetical' | 'declaration';
  /**
   * Custom comparator over flag long names for the `Flags:` table. When set,
   * it wins over {@link HelpOptions.flagOrder}.
   *
   * @defaultValue `undefined` (use `flagOrder`)
   */
  readonly sortFlags?: (a: string, b: string) => number;
  /**
   * Emit OSC 8 hyperlinks where link metadata is available (currently the
   * root-help header name/version configured via `CLIBuilder.links()`).
   * Defaults to `false`; `CLIBuilder.execute()`/`.run()` enable it
   * automatically when stdout is a TTY.
   */
  readonly hyperlinks?: boolean;
  /**
   * Render the default command's arguments and flags inline in root help.
   *
   * Only affects root-level help. When `false`, root help lists commands and
   * defers default-command details to `<bin> --help`-style hints.
   *
   * @defaultValue `true`
   */
  readonly inlineDefault?: boolean;
  /**
   * List the default command in the root `Commands:` table.
   *
   * By default the default command is treated as the root surface and omitted
   * from the command list (its args/flags render inline instead).
   *
   * @defaultValue `false`
   */
  readonly showDefaultInCommands?: boolean;
  /**
   * Show the `Run '<bin> <command> --help' for more information.` footer.
   *
   * Defaults to showing the hint only when visible subcommands exist; set
   * explicitly to force it on or off.
   */
  readonly footer?: boolean;
  /** @internal Whether this usage line is being rendered as merged root/default help. */
  readonly isDefaultHelp?: boolean;
  /**
   * Gated ANSI palette used to style help output. Identity formatters mean
   * plain text. `CLIBuilder.execute()`/`.run()` thread the output channel's
   * `out.color` here automatically, so styling follows the same policy as
   * handler output (TTY + color support, no `--json`, `NO_COLOR` honored).
   *
   * @defaultValue `undefined` (plain text)
   */
  readonly colors?: Colors;
  /**
   * Theme overrides merged over the built-in help theme. Receives the gated
   * palette; never invoked when color is off, so overrides cannot leak
   * escapes into piped output.
   *
   * @defaultValue `undefined` (built-in theme)
   */
  readonly theme?: HelpThemeFactory;
  /**
   * Theme overrides used only by function-form flag and argument descriptions.
   * Merged over the resolved global theme, one role at a time.
   *
   * @defaultValue `undefined` (use the global theme)
   */
  readonly descriptionTheme?: HelpThemeFactory;
}
/**
 * Generate help text from a command schema.
 *
 * Low-level formatter: most applications reach this through `--help`,
 * `help <command>`, or root help rendering in `CLIBuilder`. Call
 * `formatHelp()` directly when embedding DreamCLI help text into custom UIs,
 * tests, or generated docs.
 *
 * Sections rendered (in order):
 * 1. **Usage** line — `program <command> [flags] <args>`
 * 2. **Description** — the command's `.description()` text
 * 3. **Commands** — subcommands table (if any, skips hidden)
 * 4. **Arguments** — positional args table (if any)
 * 5. **Flags** — flags table with type hints and defaults
 * 6. **Examples** — usage examples (if any)
 *
 * @param schema - The command schema to render help for.
 * @param options - Formatting options (width, binary name).
 * @returns The formatted help string.
 *
 * @example
 * ```ts
 * const text = formatHelp(deploy.schema, { binName: 'mycli' });
 * ```
 */
declare function formatHelp(schema: CommandSchema, options?: HelpOptions): string;
//#endregion
//#region src/core/prompt/test-prompter.d.ts
/**
 * Sentinel value representing a cancelled/aborted prompt in the test
 * prompter's answer queue.
 *
 * Uses `Symbol.for()` for cross-bundle safety — the same symbol is
 * returned regardless of which copy of the module is loaded.
 *
 * @example
 * ```ts
 * const prompter = createTestPrompter([
 *   'us',           // first prompt answered 'us'
 *   PROMPT_CANCEL,  // second prompt cancelled
 * ]);
 * ```
 */
declare const PROMPT_CANCEL: unique symbol;
/**
 * A queued answer consumed by {@link createTestPrompter}.
 *
 * The test prompter returns these values exactly as provided; it does not
 * coerce them. The one exception mirrors the terminal prompter: a string answer
 * to an `input` prompt is run through the prompt's `validate` function, and a
 * failing answer is rejected as a cancellation (see {@link createTestPrompter}).
 * The normal resolution pipeline performs any later type coercion, so tests can
 * supply values in the same shapes real prompts would yield:
 *
 * - `string` for `input` and `select`
 * - `boolean` for `confirm`
 * - `string[]` for `multiselect`
 * - `PROMPT_CANCEL` to simulate user cancellation
 *
 * Because the type is intentionally `unknown`, tests may also inject malformed
 * answers to exercise downstream validation and error reporting.
 */
type TestAnswer = unknown;
/**
 * Options for `createTestPrompter`.
 */
interface TestPrompterOptions {
  /**
   * Behavior when all answers have been consumed.
   *
   * - `'throw'` (default) — throws an error, making the test fail
   *   loudly if more prompts fire than expected.
   * - `'cancel'` — returns `{ answered: false }`, simulating the
   *   user cancelling all subsequent prompts.
   */
  readonly onExhausted?: 'throw' | 'cancel';
}
/**
 * Create a prompt engine that returns pre-configured answers.
 *
 * Each call to `promptOne` consumes the next answer from the queue.
 * Pass `PROMPT_CANCEL` as an answer to simulate the user cancelling
 * that prompt.
 *
 * For `input` prompts that declare a `validate` function, a string answer is
 * validated just as the terminal prompter does. An answer that fails validation
 * is rejected as a cancellation (`{ answered: false }`) — mirroring the terminal
 * prompter exhausting its retries — so prompt validation is integration-testable
 * via {@linkcode runCommand} rather than silently accepted as the resolved value.
 *
 * @param answers - Ordered queue of answers. Use `PROMPT_CANCEL` for
 *   cancellation.
 * @param options - Controls behavior when the queue is exhausted.
 * @returns A {@linkcode PromptEngine} suitable for testing.
 *
 * @example
 * ```ts
 * const prompter = createTestPrompter(['eu', true, PROMPT_CANCEL]);
 *
 * // First promptOne → { answered: true, value: 'eu' }
 * // Second promptOne → { answered: true, value: true }
 * // Third promptOne → { answered: false }
 * ```
 */
declare function createTestPrompter(answers: readonly TestAnswer[], options?: TestPrompterOptions): PromptEngine;
//#endregion
//#region src/core/schema/run.d.ts
/**
 * Options accepted by `runCommand()` and internal command execution paths.
 *
 * Every field is optional — sensible defaults are applied. This is the
 * primary process-free execution seam: inject env, config, prompt I/O, and
 * dispatch-layer metadata without touching process state.
 */
interface RunOptions {
  /**
   * Environment variables for flag and arg resolution.
   *
   * Inputs with `.env('VAR')` configured resolve from this record when CLI
   * and stdin produce nothing
   * (CLI → stdin → env → config → prompt → default).
   */
  readonly env?: Readonly<Record<string, string | undefined>>;
  /**
   * Configuration object for flag and arg resolution.
   *
   * Inputs with `.config('path')` configured resolve from this record when
   * CLI, stdin, and env produce nothing
   * (CLI → stdin → env → config → prompt → default).
   * Config is plain JSON, so file loading is the caller's responsibility.
   */
  readonly config?: Readonly<Record<string, unknown>>;
  /**
   * Full stdin contents for flags and args configured with `.stdin()`.
   *
   * Lets tests inject piped input without a runtime adapter.
   */
  readonly stdinData?: string | null;
  /**
   * Prompt engine for interactive flag and arg resolution.
   *
   * When provided, inputs with `.prompt()` configured that have no value
   * after CLI, stdin, env, and config resolution are prompted interactively.
   *
   * When absent (and `answers` is also absent), prompting is skipped
   * and resolution falls through to default/required.
   *
   * Takes precedence over `answers` when both are provided.
   */
  readonly prompter?: PromptEngine;
  /**
   * Pre-configured prompt answers for testing convenience.
   *
   * When provided, a test prompter is created from these answers via
   * `createTestPrompter(answers)`. Each entry is consumed in order —
   * use `PROMPT_CANCEL` to simulate cancellation.
   *
   * Ignored when an explicit `prompter` is provided.
   */
  readonly answers?: readonly TestAnswer[];
  /**
   * Filesystem probe for `flag.path()` and `arg.path()` checks: reports what
   * exists at a path (`'file'`, `'directory'`, or `null` for nothing).
   *
   * `CLIBuilder.run()` supplies the runtime adapter's probe automatically.
   * When absent (process-free `.execute()` / `runCommand()` without an
   * override), path checks are skipped.
   */
  readonly stat?: (path: string) => Promise<'file' | 'directory' | null>;
  /**
   * Recursive directory creation for `flag.path()` and `arg.path()` `create`
   * checks.
   *
   * `CLIBuilder.run()` supplies the runtime adapter's implementation
   * automatically. When absent, missing paths are not created.
   */
  readonly mkdir?: (path: string) => Promise<void>;
  /**
   * Verbosity level for the output channel.
   * @defaultValue `'normal'`
   */
  readonly verbosity?: Verbosity;
  /**
   * Enable JSON output mode.
   *
   * When `true`, `log` and `info` messages are redirected to stderr
   * so that stdout is reserved exclusively for structured {@linkcode Out.json | json()} output.
   * Framework-rendered errors are emitted as structured JSON to stdout.
   *
   * @defaultValue `false`
   */
  readonly jsonMode?: boolean;
  /**
   * Whether stdout is connected to a TTY.
   *
   * Handlers can check {@linkcode Out.isTTY | out.isTTY} to decide whether to emit decorative
   * output (spinners, progress bars, ANSI codes). Defaults to `false`
   * (safe default for tests — non-TTY until proven otherwise).
   *
   * @defaultValue `false`
   */
  readonly isTTY?: boolean;
  /**
   * Help formatting options (width, binName).
   * Used when `--help` is detected.
   */
  readonly help?: HelpOptions;
  /**
   * Flag-parsing behavior settings.
   *
   * `caseParity` accepts the kebab↔camel counterpart spelling of each flag
   * name/alias (`--doThis` for `do-this`, and vice versa). The CLI layer
   * threads `cli(name, { flags })` settings here automatically.
   *
   * @defaultValue `{ caseParity: true }`
   */
  readonly flags?: ParseOptions;
}
/**
 * Structured result from {@linkcode runCommand}.
 *
 * Contains the exit code, captured stdout/stderr output, recorded
 * {@linkcode ActivityEvent | activity events}, and an `error` field.
 * `error` is `undefined` when execution completed without throwing, even if
 * the handler requested a non-zero status via {@linkcode Out.setExitCode}.
 *
 * @example
 * ```ts
 * const result = await runCommand(greetCmd, ['World']);
 *
 * expect(result.exitCode).toBe(0);
 * expect(result.stdout).toContain('Hello, World!');
 * expect(result.error).toBeUndefined();
 * ```
 */
interface RunResult {
  /** Process exit code. 0 = success. */
  readonly exitCode: number;
  /** Captured stdout lines (from `out.log` and `out.info`). */
  readonly stdout: readonly string[];
  /** Captured stderr lines (from `out.warn` and `out.error`). */
  readonly stderr: readonly string[];
  /**
   * Captured spinner and progress lifecycle events.
   *
   * Recorded separately from stdout/stderr — handlers that call
   * {@linkcode Out.spinner | out.spinner()} or {@linkcode Out.progress | out.progress()} produce events here, enabling
   * targeted assertions on activity lifecycle without parsing text.
   */
  readonly activity: readonly ActivityEvent[];
  /**
   * The error that caused a failure, or `undefined` when execution completed.
   * A non-zero `exitCode` can still have no error when a handler calls
   * {@linkcode Out.setExitCode}. {@linkcode CLIError} instances are preserved;
   * unknown errors are wrapped.
   */
  readonly error: CLIError | undefined;
}
//#endregion
export { ErrorCode as A, BuiltinMode as B, includesBeforeSeparator as C, CLIError as D, tokenize as E, ValidationErrorCode as F, Builtins as H, ValidationErrorOptions as I, isCLIError as L, ParseErrorCode as M, ParseErrorOptions as N, CLIErrorJSON as O, ValidationError as P, isParseError as R, Token as S, stripBeforeSeparator as T, BuiltinsConfig as U, BuiltinName as V, ResolutionProvenanceRecord as _, TestPrompterOptions as a, ParseOptions as b, formatHelp as c, CLIPluginHooks as d, PluginCommandContext as f, DeprecationWarning as g, resolve as h, TestAnswer as i, ParseError as j, CLIErrorOptions as k, BeforeParseParams as l, plugin as m, RunResult as n, createTestPrompter as o, ResolvedCommandParams as p, PROMPT_CANCEL as r, HelpOptions as s, RunOptions as t, CLIPlugin as u, ResolveOptions as v, parse as w, ParseResult as x, ResolveResult as y, isValidationError as z };