import { Verbosity } from "../output/contracts.mjs";
import "../output/index.mjs";
import { PromptEngine } from "../prompt/index.mjs";
import { CLIPlugin } from "./plugin.mjs";
import { CLIError } from "../errors/index.mjs";
import { HelpThemeFactory } from "../help/theme.mjs";
import "../help/index.mjs";
import { CommandSchema, ErasedCommand } from "../schema/command.mjs";
import { ParseOptions } from "../parse/index.mjs";
import { RuntimeAdapter } from "../../runtime/adapter.mjs";
import { PackageJsonData } from "../config/package-json.mjs";
import { HelpLinks } from "./help-links.mjs";
import { CompletionOptions } from "../completion/shells/shared.mjs";
import { Shell } from "../completion/index.mjs";
import { FormatLoader } from "../config/index.mjs";
//#region src/core/cli/runtime-preflight.d.ts
/** Config discovery settings extracted from CLISchema for preflight use. @internal */
interface RuntimeConfigSettings {
  /** Application name used to locate config files (e.g. `~/.config/<appName>/`). */
  readonly appName: string;
  /** Optional format loaders (JSON/YAML/TOML); `undefined` uses built-in JSON. */
  readonly loaders: readonly FormatLoader[] | undefined;
}
/**
 * Manifest discovery settings extracted from CLISchema for preflight use.
 *
 * Mirrors the public `ResolvedManifestSettings` shape (consumed structurally),
 * named with the `Runtime` prefix to match its {@link RuntimeConfigSettings}
 * sibling and avoid colliding with the exported public type.
 * @internal
 */
interface RuntimeManifestSettings {
  /** Whether to infer the CLI binary name from `bin` keys or `name`. */
  readonly inferName: boolean;
  /** Strip a leading `@scope/` from the inferred `name` fallback. */
  readonly stripScope: boolean;
  /** Explicit anchor (resolved path) for discovery; `undefined` falls back to `adapter.cwd`. */
  readonly from: string | undefined;
  /** Candidate manifest filenames in priority order. */
  readonly files: readonly string[];
  /** Pre-loaded data; when set, discovery is skipped entirely. */
  readonly data: PackageJsonData | undefined;
}
/**
 * Structural subset of CLISchema used by runtime preflight.
 *
 * Decouples adapter-driven sourcing (config, package.json, stdin) from the
 * full CLIBuilder surface so preflight can be tested independently.
 * @internal
 */
interface RuntimePreflightSchemaLike {
  /** CLI program name; may be overridden by package.json discovery or inheritance. */
  readonly name: string;
  /** Whether this CLI inherits its name from a parent (nested CLI embedding). */
  readonly inheritName: boolean;
  /** Declared version; `undefined` means version will be inferred from package.json if available. */
  readonly version: string | undefined;
  /** Declared description; `undefined` allows package.json inference. */
  readonly description: string | undefined;
  /** Registered top-level commands for dispatch planning during stdin detection. */
  readonly commands: readonly ErasedCommand[];
  /** Fallback command when no subcommand token matches. */
  readonly defaultCommand: ErasedCommand | undefined;
  /** Whether the default command is also exposed as a named top-level route. */
  readonly defaultCommandRouted: boolean;
  /** Config file discovery settings; `undefined` disables config loading. */
  readonly configSettings: RuntimeConfigSettings | undefined;
  /** Package.json discovery settings; `undefined` disables package.json inference. */
  readonly packageJsonSettings: RuntimeManifestSettings | undefined;
  /** Root-help header link targets; `undefined` fields may be derived from package.json. */
  readonly helpLinks: HelpLinks | undefined;
  /** Whether `.completions()` registered the built-in completions command/flag. */
  readonly hasBuiltInCompletions: boolean;
  /** Eager `--completions <shell>` flag config; `undefined` disables interception. */
  readonly completionsFlag: {
    readonly shells: readonly Shell[];
    readonly options: CompletionOptions | undefined;
  } | undefined;
  /** Consumer-configured root-help defaults. */
  readonly helpConfig: {
    readonly inlineDefault?: boolean;
    readonly showDefaultInCommands?: boolean;
    readonly footer?: boolean;
    readonly width?: number;
    readonly hyperlinks?: boolean;
    readonly theme?: HelpThemeFactory;
  } | undefined;
  /** Flag-parsing behavior settings (e.g. case parity). */
  readonly flagSettings: ParseOptions | undefined;
  /** Plugins forwarded into the execution pipeline. */
  readonly plugins: readonly CLIPlugin[];
}
/**
 * Caller-supplied overrides for runtime preflight.
 *
 * When provided, these bypass adapter auto-detection (useful for testing
 * and the `CLIRunOptions` public surface).
 * @internal
 */
interface RuntimePreflightOptions {
  /** Environment variables override; bypasses adapter env when set. */
  readonly env?: Readonly<Record<string, string | undefined>>;
  /** Pre-loaded config object; skips config file discovery when set. */
  readonly config?: Readonly<Record<string, unknown>>;
  /** Pre-read stdin data; `null` means stdin was explicitly empty. */
  readonly stdinData?: string | null;
  /** Custom prompt engine; bypasses terminal prompter auto-creation. */
  readonly prompter?: PromptEngine;
  /** Output verbosity level override. */
  readonly verbosity?: Verbosity;
  /** Force JSON output mode regardless of `--json` flag presence. */
  readonly jsonMode?: boolean;
  /** TTY detection override; bypasses adapter TTY check. */
  readonly isTTY?: boolean;
  /** Filesystem probe override for `flag.path()` checks; bypasses the adapter probe. */
  readonly stat?: (path: string) => Promise<'file' | 'directory' | null>;
  /** Directory creation override for `flag.path()` `create` checks; bypasses the adapter. */
  readonly mkdir?: (path: string) => Promise<void>;
}
/**
 * Fully resolved runtime inputs ready for the execution pipeline.
 *
 * All adapter vs. caller-override decisions are settled by the time this
 * is constructed; the executor treats these as final truth.
 * @internal
 */
interface RuntimeExecutionInputs {
  /** Resolved environment variables (from adapter or caller override). */
  readonly env: Readonly<Record<string, string | undefined>>;
  /** Whether stdout is a TTY (controls color, spinners, interactive prompts). */
  readonly isTTY: boolean;
  /** Whether structured JSON output mode is active. */
  readonly jsonMode: boolean;
  /** Output verbosity level. */
  readonly verbosity: Verbosity;
  /** Pre-read stdin data if the invocation declared stdin-mode args. */
  readonly stdinData?: string | null;
  /** Prompt engine for interactive flag resolution; absent in non-TTY. */
  readonly prompter?: PromptEngine;
  /** Loaded config data for the config resolution step. */
  readonly config?: Readonly<Record<string, unknown>>;
  /** Filesystem probe (from the adapter) for `flag.path()` checks. */
  readonly stat?: (path: string) => Promise<'file' | 'directory' | null>;
  /** Directory creation (from the adapter) for `flag.path()` `create` checks. */
  readonly mkdir?: (path: string) => Promise<void>;
}
/** Preflight succeeded — all runtime inputs are resolved and ready for execution. @internal */
interface ReadyRuntimePreflight {
  /** Discriminant — preflight completed without errors. */
  readonly kind: 'ready';
  /** Schema after package.json discovery and name inheritance applied. */
  readonly schema: RuntimePreflightSchemaLike;
  /** Argv with valid runtime `--config` tokens stripped out. */
  readonly filteredArgv: readonly string[];
  /** Fully resolved runtime inputs for the execution pipeline. */
  readonly inputs: RuntimeExecutionInputs;
}
/** Preflight failed during config file discovery/loading. @internal */
interface RuntimeConfigErrorPreflight {
  /** Discriminant — config loading produced a structured error. */
  readonly kind: 'config-error';
  /** The config discovery/parse error to render. */
  readonly error: CLIError;
  /** Whether JSON output was requested (needed to choose error rendering). */
  readonly jsonMode: boolean;
}
/** Discriminated union of preflight outcomes — either ready or config-error. @internal */
type RuntimePreflightResult = ReadyRuntimePreflight | RuntimeConfigErrorPreflight;
/** Options bag for {@linkcode prepareRuntimePreflight}. @internal */
interface PrepareRuntimePreflightOptions {
  /** CLI schema subset driving preflight decisions. */
  readonly schema: RuntimePreflightSchemaLike;
  /** Runtime adapter providing argv, env, stdin, and filesystem access. */
  readonly adapter: RuntimeAdapter;
  /** Caller-supplied overrides; `undefined` means auto-detect everything. */
  readonly options: RuntimePreflightOptions | undefined;
  /** Name inherited from a parent CLI (nested embedding); `undefined` for standalone. */
  readonly inheritedName: string | undefined;
}
/** Extract and strip valid runtime `--config` forms from argv, returning path + filtered tokens. @internal */
declare function extractConfigFlag(argv: readonly string[]): {
  readonly configPath: string | undefined;
  readonly filteredArgv: readonly string[];
};
/** Check whether a single command's args declare stdin-mode and argv leaves them unresolved. @internal */
declare function commandInvocationNeedsStdin(schema: CommandSchema, argv: readonly string[], flagSettings?: ParseOptions): boolean;
/** Plan the invocation and check whether the matched command needs stdin data. @internal */
declare function invocationNeedsStdin(schema: RuntimePreflightSchemaLike, argv: readonly string[]): boolean;
/**
 * Run all adapter-driven sourcing work before command execution.
 *
 * Discovers config files, reads package.json metadata, detects stdin needs,
 * wires up the prompt engine, and resolves output policy overrides into a
 * single {@linkcode RuntimePreflightResult}.
 * @internal
 */
declare function prepareRuntimePreflight(options: PrepareRuntimePreflightOptions): Promise<RuntimePreflightResult>;
//#endregion
export { type PrepareRuntimePreflightOptions, type ReadyRuntimePreflight, type RuntimeExecutionInputs, type RuntimePreflightOptions, type RuntimePreflightResult, type RuntimePreflightSchemaLike, commandInvocationNeedsStdin, extractConfigFlag, invocationNeedsStdin, prepareRuntimePreflight };