import { OutputPolicy } from "../output/contracts.mjs";
import { CLIPlugin } from "./plugin.mjs";
import { CLIError } from "../errors/index.mjs";
import { HelpOptions } from "../help/index.mjs";
import { CommandMeta, CommandSchema, ErasedCommand } from "../schema/command.mjs";
import { ParseOptions } from "../parse/index.mjs";
import { CompletionOptions } from "../completion/shells/shared.mjs";
import { Shell } from "../completion/index.mjs";
//#region src/core/cli/planner.d.ts
/**
 * Structural subset of CLISchema used by the planner.
 *
 * Decouples invocation planning from the full CLIBuilder surface so the
 * planner can be tested and reasoned about without constructing a real CLI.
 * @internal
 */
interface PlannerSchemaLike {
  /** CLI program name used in help text and error messages. */
  readonly name: string;
  /** Declared version string; `undefined` disables `--version` interception. */
  readonly version: string | undefined;
  /** Registered top-level commands available for dispatch. */
  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;
  /**
   * Eager `--completions <shell>` flag configuration, when `.completions()`
   * was registered with `{ as: 'flag' }`. `undefined` disables interception.
   */
  readonly completionsFlag: {
    readonly shells: readonly Shell[];
    readonly options: CompletionOptions | undefined;
  } | undefined;
  /** Flag-parsing behavior settings (case parity) applied to flag lookups. */
  readonly flagSettings?: ParseOptions | undefined;
  /** Plugins forwarded into every matched execution plan. */
  readonly plugins: readonly CLIPlugin[];
}
/** Root-level help interception outcome. */
interface RootHelpOutcome {
  /** Discriminant — argv matched `--help` / `-h` before any command. */
  readonly kind: 'root-help';
  /** Help options to render root-level usage. */
  readonly help: HelpOptions;
}
/** Root-level version interception outcome. */
interface RootVersionOutcome {
  /** Discriminant — argv matched `--version` / `-V` and schema declares a version. */
  readonly kind: 'root-version';
  /** Resolved version string to render. */
  readonly version: string;
}
/** Root-level `--completions [shell]` interception outcome. */
interface RootCompletionsOutcome {
  /** Discriminant — argv matched the eager `--completions [shell]` flag. */
  readonly kind: 'root-completions';
  /**
   * Resolved, validated target shell, or `undefined` when the flag was given
   * without a value and the shell should be auto-detected from the environment.
   */
  readonly shell: Shell | undefined;
  /** Generator options captured at build time. */
  readonly options: CompletionOptions | undefined;
}
/** CLI-level dispatch failure before command execution starts. */
interface DispatchErrorOutcome {
  /** Discriminant — dispatch could not resolve a command from argv. */
  readonly kind: 'dispatch-error';
  /** Structured error with suggestion text for the caller to render. */
  readonly error: CLIError;
}
/** Successful planner handoff to the shared command execution path. */
interface PlannerMatchOutcome {
  /** Discriminant — dispatch found a matching command for argv. */
  readonly kind: 'match';
  /** Fully resolved execution plan ready for the executor pipeline. */
  readonly plan: CommandExecutionPlan;
}
/**
 * Stable planner result union for the re-foundation workstream.
 *
 * `CLIBuilder.execute()` still renders and executes these outcomes, but
 * planning itself is intentionally bounded to this union.
 */
type DispatchOutcome = RootHelpOutcome | RootVersionOutcome | RootCompletionsOutcome | DispatchErrorOutcome | PlannerMatchOutcome;
/**
 * Concrete execution handoff produced by a successful planner match.
 *
 * `mergedSchema` is the exact command schema the executor sees after
 * propagated ancestor flags are collected and child definitions shadow them.
 */
interface CommandExecutionPlan {
  /** Type-erased command instance that owns the handler. */
  readonly command: ErasedCommand;
  /** Command schema with propagated ancestor flags merged in. */
  readonly mergedSchema: CommandSchema;
  /** Remaining argv tokens after command dispatch consumed the command path. */
  readonly argv: readonly string[];
  /** CLI-level metadata (program name, bin, version) for the handler context. */
  readonly meta: CommandMeta;
  /** Plugins to run through the execution lifecycle. */
  readonly plugins: readonly CLIPlugin[];
  /** Output policy (json mode, TTY, verbosity) governing handler rendering. */
  readonly output: OutputPolicy;
  /** Help options for rendering per-command help; `undefined` when unavailable. */
  readonly help: HelpOptions | undefined;
}
interface BuildCommandExecutionPlanOptions {
  readonly command: ErasedCommand;
  readonly commandPath: readonly CommandSchema[];
  readonly argv: readonly string[];
  readonly meta: CommandMeta;
  readonly plugins: readonly CLIPlugin[];
  readonly output: OutputPolicy;
  readonly help: HelpOptions | undefined;
}
/**
 * Dispatch resolved a group command that requires a subcommand selection.
 *
 * The caller should render subcommand-level help for the matched group.
 * @internal
 */
interface NeedsSubcommandOutcome {
  /** Discriminant — group command matched but no leaf subcommand was selected. */
  readonly kind: 'needs-subcommand';
  /** The group command that was matched. */
  readonly command: ErasedCommand;
  /** Full ancestor path from root to this group, used for propagated flag collection. */
  readonly commandPath: readonly CommandSchema[];
  /** Help options scoped to the group command's bin path. */
  readonly help: HelpOptions;
}
/** Full planner result including the `needs-subcommand` variant used by CLIBuilder. @internal */
type InvocationPlan = DispatchOutcome | NeedsSubcommandOutcome;
/** Options bag for {@linkcode planInvocation}. @internal */
interface PlanInvocationOptions {
  /** CLI schema subset driving dispatch decisions. */
  readonly schema: PlannerSchemaLike;
  /** Raw argv tokens (typically `adapter.argv.slice(2)`). */
  readonly argv: readonly string[];
  /** Root-level help configuration for rendering. */
  readonly help: HelpOptions;
  /** Output policy propagated into matched execution plans. */
  readonly output: OutputPolicy;
}
/** Build a name+alias lookup map for top-level commands. @internal */
declare function buildRootCommandMap(commands: readonly ErasedCommand[]): ReadonlyMap<string, ErasedCommand>;
/**
 * Merge propagated ancestor flags into the matched command schema.
 *
 * Child flag definitions win when names collide, matching current CLI
 * dispatch semantics and the future planner contract.
 */
declare function mergeCommandSchema(command: ErasedCommand, commandPath: readonly CommandSchema[]): CommandSchema;
/** Build the planner handoff for a matched command invocation. */
declare function buildCommandExecutionPlan(options: BuildCommandExecutionPlanOptions): CommandExecutionPlan;
/**
 * Decide what to do with an argv invocation before any command executes.
 *
 * Handles root interception (`--help`, `--version`, `--completions <shell>`,
 * bare `help` token), dispatches into the command tree, falls back to the
 * default command, and produces structured errors for unknown commands/flags.
 * @internal
 */
declare function planInvocation(options: PlanInvocationOptions): InvocationPlan;
//#endregion
export { type CommandExecutionPlan, type DispatchErrorOutcome, type DispatchOutcome, type InvocationPlan, type NeedsSubcommandOutcome, type OutputPolicy, type PlanInvocationOptions, type PlannerMatchOutcome, type PlannerSchemaLike, type RootCompletionsOutcome, type RootHelpOutcome, type RootVersionOutcome, buildCommandExecutionPlan, buildRootCommandMap, mergeCommandSchema, planInvocation };