/**
 * Node runtime-version enforcement gate (SSoT).
 *
 * Single source of truth for "is the running Node new enough to run CLEO".
 * The minimum is read from this package's own shipped `engines.node` at
 * runtime — NOT a hardcoded constant — so bumping the floor is a one-line
 * `package.json` edit and the gate evolves with it. A CI lint
 * (`scripts/lint-node-engine-ssot.mjs`) keeps every workspace package's
 * `engines.node` equal to root's, so the value the gate reads is authoritative.
 *
 * Lives in `@cleocode/paths` — the zero-dep leaf (only `env-paths`) that is
 * importable BEFORE any `@cleocode/core` import. The CLI guard must run here,
 * not at `node:sqlite` load, so an under-floor Node fails with an actionable
 * message instead of a cryptic `ERR_UNKNOWN_BUILTIN_MODULE` / divergent-SQLite
 * behavior. (Importing this package does NOT eagerly load `node:sqlite` — that
 * is lazy via `createRequire`; see `cleo-paths.ts`.)
 *
 * Why a full-semver floor and not a major-only check: 24.13.1 satisfies
 * `major >= 24` yet is below 24.16.0, where the bundled SQLite WAL-reset
 * corruption fix (SQLite 3.53.0) landed. The major-only guards
 * (`cli/index.ts`, `dependencies.ts:checkNode`) waved it through, then the
 * persistence layer diverged from CI. This gate compares full semver.
 *
 * @packageDocumentation
 * @task T11281
 * @task T11242
 */
/**
 * Last-resort floor used only when this package's `engines.node` cannot be
 * read (e.g. a corrupted install). Kept equal to root `engines.node` by the
 * `lint-node-engine-ssot` CI gate so it can never silently lie.
 */
export declare const FALLBACK_MIN_NODE = "24.16.0";
/** A parsed `major.minor.patch` triple. */
export interface Semver {
    major: number;
    minor: number;
    patch: number;
}
/**
 * Parse the first `x.y.z` triple out of a version fragment such as
 * `24.16.0`, `v24.16.0`, or a range like `>=24.16.0 <27`.
 *
 * @param raw - The version or range string.
 * @returns The parsed {@link Semver}, or `null` when no triple is present.
 */
export declare function parseSemver(raw: string): Semver | null;
/**
 * Read the minimum Node version from this package's shipped `engines.node`
 * (the SSoT). Falls back to {@link FALLBACK_MIN_NODE} when the manifest is
 * unreadable or declares no parseable version.
 *
 * @returns A normalized `major.minor.patch` string.
 *
 * @public
 */
export declare function getRequiredNodeVersion(): string;
/** A version manager (or platform installer) CLEO can suggest for upgrading. */
export type NodeManager = 'fnm' | 'nvm' | 'n' | 'volta' | 'asdf' | 'brew' | 'winget' | 'choco' | 'nodesource';
/** A concrete, copy-pasteable upgrade instruction. */
export interface UpgradeHint {
    manager: NodeManager;
    command: string;
    note?: string;
}
/** Result of evaluating the running Node against the required floor. */
export interface NodeVersionVerdict {
    compliant: boolean;
    current: string;
    required: string;
    platform: NodeJS.Platform;
    arch: string;
    /** Ordered best-first; empty when compliant. */
    hints: UpgradeHint[];
}
/**
 * Evaluate the running Node against the required floor. Pure and
 * side-effect-free (no `process.exit`, no I/O beyond the SSoT manifest read) —
 * safe to call from `doctor`/`health` and unit tests.
 *
 * @param currentRaw - The Node version to evaluate. Defaults to
 *   `process.versions.node`.
 * @returns The {@link NodeVersionVerdict}.
 *
 * @public
 */
export declare function evaluateNodeVersion(currentRaw?: string): NodeVersionVerdict;
/** Options controlling {@link enforceNodeVersion}. */
export interface EnforceOptions {
    /**
     * `enforce` (default): print guidance + exit 1.
     * `warn`: print guidance + continue.
     * `auto`: best-effort install, then exit 1 ("open a new shell + re-run").
     * Default resolves to `auto` when `CLEO_NODE_AUTO_UPGRADE=1`, else `enforce`.
     */
    mode?: 'enforce' | 'warn' | 'auto';
    /** stderr writer (injectable for tests). */
    write?: (s: string) => void;
    /** process exit (injectable for tests). */
    exit?: (code: number) => never;
    /**
     * Node version to evaluate. Defaults to `process.versions.node`. Injectable
     * so tests assert a fixed verdict deterministically on any runtime (otherwise
     * the same assertion flips between a below-floor dev box and a compliant CI).
     */
    current?: string;
}
/**
 * The runtime gate. A microsecond no-op when Node is compliant; otherwise
 * prints an exact, OS-/manager-aware upgrade instruction and (by default)
 * exits non-zero.
 *
 * Auto mode (opt-in via `CLEO_NODE_AUTO_UPGRADE=1`) runs the install command,
 * then STILL exits non-zero: version managers switch Node via shell shims, so
 * a child process cannot hot-swap the interpreter already executing — the user
 * must open a new shell and re-run. Silent toolchain mutation is deliberately
 * never the default.
 *
 * @param opts - {@link EnforceOptions}.
 * @returns The {@link NodeVersionVerdict} (for the compliant no-op path, and
 *   for tests that stub `exit`).
 *
 * @public
 */
export declare function enforceNodeVersion(opts?: EnforceOptions): NodeVersionVerdict;
//# sourceMappingURL=node-version-gate.d.ts.map