#!/usr/bin/env node
/**
 * CLI entry & dispatch (spec 07). The installer's process entry point and orchestration
 * layer: it parses `process.argv` via `node:util.parseArgs`, resolves the target agent set,
 * runs the per-agent plan/apply (or list) pipeline catching per-agent failures, renders the
 * `RunReport`, and returns the process exit code.
 *
 * Zero runtime deps (`node:` built-ins only). Core functions return `Result`/`RunReport` and
 * never throw for expected errors; `main` is the single boundary that maps to exit codes and
 * touches `process`. `runCli` is the env-injectable testable core (the hermetic seam item 011
 * relies on). Named exports only.
 */
import { type CliFlags, type ExitCode, type InstallerError, type Result, type RunReport, type Subcommand } from "./types.js";
import { type RegistryQuery } from "./rauf.js";
/** A flag's declarative spec — drives both parseArgs config and helpText (REQ-DIST-03). */
interface FlagSpec {
    /** Long name without leading dashes, e.g. "agent". */
    readonly name: string;
    /** Single-char alias without dash, e.g. "a"; omitted if none. */
    readonly short?: string;
    /** parseArgs type. */
    readonly type: "boolean" | "string";
    /** One-line help description. */
    readonly help: string;
    /** Hidden from --help (e.g. --source for tests). */
    readonly hidden?: boolean;
    /** Placeholder shown in help for string flags, e.g. "<id>". */
    readonly arg?: string;
}
/** A subcommand's declarative spec. */
interface SubcommandSpec {
    readonly canonical: Subcommand;
    /** Accepted aliases that resolve to `canonical` (e.g. ["add"]). */
    readonly aliases: readonly string[];
    readonly help: string;
}
/** Canonical subcommand table (REQ-DIST-03, §1.2). */
export declare const SUBCOMMANDS: readonly SubcommandSpec[];
/** Canonical flag table (REQ-FLAG-01..05, §1.3). */
export declare const FLAGS: readonly FlagSpec[];
/** Parsed CLI invocation: a resolved subcommand plus normalized flags. */
export interface ParsedCli {
    readonly subcommand: Subcommand;
    readonly flags: CliFlags;
}
/**
 * Parse and validate `argv` (already sliced past `node` + script — `process.argv.slice(2)`)
 * via `node:util.parseArgs` (zero-dep). Resolves aliases, rejects unknown
 * subcommand/flag/agent (and a parseArgs throw) as a `USAGE` error. Pure: no I/O, no exit.
 */
export declare function parseCliArgs(argv: string[]): Result<ParsedCli>;
/**
 * Map a structured `InstallerError` to a process exit code (tech-spec §7).
 * "USAGE" → EXIT.USAGE (2); everything else → EXIT.FAILURE (1).
 */
export declare function mapErrorToExit(error: InstallerError): ExitCode;
/**
 * Injected environment for a programmatic CLI run (the hermetic-test seam, 08 §3.4). Every
 * field is optional; an omitted field falls back to the real default `main` uses.
 */
export interface CliEnv {
    /** Stand-in for `~` — threaded into detection/destination/manifest resolution as ResolveOpts.home. */
    readonly home?: string;
    /** Stand-in for `process.cwd()` — threaded into resolution as ResolveOpts.cwd. */
    readonly cwd?: string;
    /** Mock rauf registry query (06) for the preflight; default = the real `npm view` query. */
    readonly registry?: RegistryQuery;
    /** Forced platform for the copy/symlink mode decision (REQ-FLAG-03); default = process.platform. */
    readonly platform?: NodeJS.Platform;
}
/**
 * Run the full CLI pipeline programmatically and return the assembled `RunReport` WITHOUT
 * touching `process` (no argv read, no stdout/stderr write, no exit). This is the testable
 * core (08 §3.4): it threads env.home/cwd into detection/manifest calls, env.registry into the
 * rauf preflight, and env.platform into the copy/symlink mode decision.
 */
export declare function runCli(argv: string[], env?: CliEnv): Promise<RunReport>;
/**
 * Parse → help/version precedence → run pipeline (catching per-agent errors via runCli) →
 * render → exit code. The only place that writes to stdout/stderr and decides the exit code.
 * Never reads stdin (REQ-DIST-02).
 *
 * @param argv - the post-`node` argument list (`process.argv.slice(2)` in production).
 * @param env  - the injectable CLI env (the hermetic-test seam, §3.1a); default `{}` = real
 *               defaults. Tests inject a throwing seam (e.g. a registry that throws) here to
 *               exercise the UNEXPECTED boundary catch deterministically without a network call.
 */
export declare function main(argv: string[], env?: CliEnv): Promise<ExitCode>;
/**
 * Build the full `--help` text from the single CLI_SPEC (SUBCOMMANDS + FLAGS, §1.5) so the
 * listed surface can never drift from what parseArgs accepts (REQ-DIST-03). Hidden flags
 * (--source) are omitted. Pure: returns a string, no I/O.
 */
export declare function helpText(): string;
export {};