@aiviatic/kindling 0.1.0

package/dist/engine/index.d.ts

@@ -0,0 +1,546 @@
+import { d as Pins, b as ErrorCode, e as StepId, a as EngineEmitter, C as Config, K as KindlingEvent, E as EngineCommands } from '../emitter-oidLJDmn.js';
+export { c as EventListener, I as InspectResult, L as Level, N as NON_FATAL_STEPS, P as Phase, S as Status } from '../emitter-oidLJDmn.js';
+import { E as ExecResult } from '../exec-JnCZZPZU.js';
+export { e as exec } from '../exec-JnCZZPZU.js';
+
+declare const pins: Readonly<Pins>;
+
+declare const stepMessages: Record<StepId, string>;
+declare const errorMessages: Record<ErrorCode, string>;
+/**
+ * Structured recovery guidance for the in-UI error screen (Story 3.6). The UI RENDERS this; it
+ * never composes its own copy. Each entry names the cause and a concrete next step; some carry a
+ * one-line fix command (shown with a copy button) or route to a non-destructive choice.
+ *  - `recovery: 'retry'`  → show a Retry button (re-run the failed step).
+ *  - `recovery: 'choose-folder'` → no destructive default; let the user pick another folder (FR-9).
+ */
+interface RecoveryGuidance {
+    /** Short reassuring framing headline. */
+    title: string;
+    /** The cause + the concrete next step, plain language. */
+    detail: string;
+    /** Optional one-line command the user runs, then retries (e.g. the Windows policy fix). */
+    fixCommand?: string;
+    recovery: 'retry' | 'choose-folder';
+}
+declare const recoveryGuidance: Record<ErrorCode, RecoveryGuidance>;
+
+type ScaffoldOutcome = 'created' | 'resumed' | 'skipped' | 'blocked';
+interface ScaffoldOptions {
+    projectDir: string;
+    projectName: string;
+    emitter: EngineEmitter;
+    /** Absolute path to the provisioned git (Epic 2); defaults to PATH lookup. */
+    git?: string;
+    /** Injectable clock for deterministic tests. */
+    now?: () => string;
+}
+declare function scaffold(opts: ScaffoldOptions): Promise<ScaffoldOutcome>;
+
+type InstallAction = 'install' | 'update';
+/**
+ * Compose the `bmad-method install` argv. `action` (2.7) selects a fresh install vs a re-run:
+ * on a project that already has a BMad install, pass `--action update` so the re-run updates in
+ * place rather than erroring/duplicating; a fresh project omits it (defaults to install).
+ */
+declare function composeInstallArgs(config: Config, action?: InstallAction): string[];
+
+interface LaunchRuntime {
+    /** Absolute path to the provisioned node binary, or null to use `node`/`npx` on PATH
+     *  (a reused system Node, or nvm sourced same-shell). See ProvisionResult.nodeExe. */
+    nodeExe: string | null;
+    /** Pinned Kindling version (pins.kindling). */
+    kindlingVersion: string;
+}
+interface LaunchCommand {
+    cmd: string;
+    args: string[];
+}
+/** Path to npx's CLI script beside a provisioned node binary (the npm bundled with the dist). */
+declare function npxCliPath(nodeExe: string): string;
+/**
+ * Compose the command to launch Kindling once Node is provisioned (Story 2.6). The clean-runtime
+ * rule (AR6): never depend on a freshly-mutated PATH —
+ *  - `nodeExe === null` → Node is already on PATH (nvm sourced same-shell, or a reused system
+ *    Node) → plain `npx -y @aiviatic/kindling@<pin>`.
+ *  - `nodeExe` set (Windows portable, absolute) → invoke npx's CLI through that exact node binary,
+ *    so the launch works without the portable Node ever being on PATH.
+ * Pure — the bootstrap (or a future Windows launcher) spawns the returned command.
+ */
+declare function composeLaunchCommand({ nodeExe, kindlingVersion }: LaunchRuntime): LaunchCommand;
+
+declare function defaultBmadInstalled(projectDir: string): Promise<boolean>;
+/**
+ * Result of an install attempt.
+ *
+ * Failure contract: a **non-zero exit** resolves with `{ ok: false }` (the caller must check
+ * `.ok`); a **spawn error** (e.g. npx not found) emits `Failed` then *throws*. Either way a
+ * terminal `Failed` event is emitted exactly once. (Note: `scaffold()` throws on a non-zero
+ * exit — the orchestrator story must reconcile these two error models; see deferred-work.md.)
+ *
+ * Version target (Story 7.1 / FR27): `config.bmadTarget` selects the npx package tag. `'pinned'`
+ * (default) is byte-for-byte the historical behavior — `bmad-method@<pins.bmad>` with
+ * `--action install` (fresh) vs `--action update` (existing `_bmad`, Story 2.7). `'latest'` is the
+ * explicit opt-in update variant — `bmad-method@latest` with `--action update` FORCED regardless of
+ * the `_bmad`-present detection. `bmadVersion` in the result is the resolved TAG (`<pins.bmad>` or
+ * the literal `'latest'`); the concrete version `@latest` resolves to is picked up by the
+ * self-check's manifest read (FR26), not here.
+ */
+interface BmadInstallResult {
+    ok: boolean;
+    bmadVersion: string;
+}
+interface BmadInstallOptions {
+    config: Config;
+    emitter: EngineEmitter;
+    /** Injectable subprocess runner (tests pass a fake; never runs a real install). */
+    exec?: (cmd: string, args: string[]) => Promise<ExecResult>;
+    /**
+     * Command used to invoke npx. Default 'npx' (macOS/Linux dev). On Windows this must be
+     * the provisioned `node` + npm-cli.js (Epic 2) since `npx.cmd` can't spawn with shell:false
+     * — see deferred-work.md.
+     */
+    npxCommand?: string;
+    /**
+     * Idempotent re-run (2.7): is BMad already installed in this project? When true, the install
+     * runs with `--action update` (update in place) instead of a fresh install. Default detects a
+     * `_bmad` dir under config.projectDir; injectable for tests.
+     */
+    bmadAlreadyInstalled?: (projectDir: string) => Promise<boolean>;
+    now?: () => string;
+}
+declare function runBmadInstall(opts: BmadInstallOptions): Promise<BmadInstallResult>;
+
+/**
+ * Explicit id → npm package table. The scope guard: only these two picked-tool ids are eligible
+ * for an agent-CLI install; every other `--tools` id (vscode, cursor, …) is ignored and stays
+ * skill-files-only. Kept explicit and in one place so the mapping — and the DELIBERATE unpinned
+ * (latest) package spelling — is one edit to change / verify against the registry.
+ *
+ * `[DECISION]` Unpinned (latest): everywhere else Kindling pins, but the agent CLIs are the
+ * deliberate exception — they self-update, and pinning would strand cohort users on a stale
+ * binary. So the pkg strings carry NO `@version`; `exec(npm, ['install','-g', pkg])` installs
+ * latest.
+ */
+declare const AGENT_CLI_TABLE: Record<string, {
+    pkg: string;
+    bin: string;
+    name: string;
+}>;
+/** A resolved, eligible agent-CLI descriptor (the id folded into its table row). */
+interface AgentCliDescriptor {
+    id: string;
+    pkg: string;
+    bin: string;
+    name: string;
+}
+/**
+ * SSOT accessor: map the requested `installCli` ids to their eligible descriptors, applying the
+ * same scope guard + de-dupe as `installAgentCli`. The single source both the install step AND the
+ * self-check (Story 6.2) read, so the id→{pkg,bin,name} mapping is never hard-coded twice. A
+ * non-eligible id (vscode, cursor, …) is dropped; an empty/absent list yields `[]`.
+ */
+declare function eligibleAgentClis(installCli: string[] | undefined): AgentCliDescriptor[];
+/**
+ * Outcome of the install-agent-cli step. `ok` reflects only that the step RAN TO COMPLETION —
+ * it is INDEPENDENT of individual install failures (which land in `failed`). This is the step's
+ * defining property versus every other engine step: it is NON-FATAL, so the engine reaches the
+ * self-check / Welcome even if a CLI failed to install (AC-3). The failed ids are surfaced solely
+ * as `Failed` events (keyed by ErrorCode.AgentCliInstallFailed) for the error surface / Story 6.2.
+ */
+interface AgentCliResult {
+    ok: boolean;
+    installed: string[];
+    skipped: string[];
+    failed: string[];
+}
+interface AgentCliOptions {
+    config: Config;
+    emitter: EngineEmitter;
+    /** Injectable subprocess runner (tests pass a fake; NEVER runs a real npm install). */
+    exec?: (cmd: string, args: string[]) => Promise<ExecResult>;
+    /**
+     * Command used to invoke npm. Default 'npm' (macOS/Linux dev). On Windows this must be the
+     * provisioned `node` + npm-cli.js (Epic 2) since `npm.cmd` can't spawn with shell:false — the
+     * same absolute-node strategy `launch.ts` uses via `npxCliPath` (the npm equivalent is
+     * `<dir>/node_modules/npm/bin/npm-cli.js`). Not over-plumbed in 6.1: like bmad-install's
+     * `npxCommand`, the seam defaults to 'npm' and the rehearsal / Story 6.2 plugs the abs path in.
+     */
+    npmCommand?: string;
+    /**
+     * Resolve an agent CLI's bin name to a spawnable form before the idempotent-skip probe. Default:
+     * identity. On Windows a global `npm install -g` writes a `claude.cmd`/`.ps1` shim (not a bare
+     * `claude` executable), and `exec` uses `shell:false` — so a bare bin can't be spawned there and
+     * `probeVersion` would wrongly report "absent" and reinstall on every run. This seam is the probe
+     * equivalent of `npmCommand`: the Epic-2 Windows wiring / dress rehearsal plugs the resolved shim
+     * path in here. Not over-plumbed in 6.1 (defaults to identity, exactly as `npmCommand` defaults
+     * to 'npm'). See deferred-work.md → agent-CLI Windows resolution.
+     */
+    resolveBin?: (bin: string) => string;
+    now?: () => string;
+}
+/**
+ * Optionally installs the picked agent's CLI (Claude Code / Codex) globally at latest, AFTER the
+ * BMad install and BEFORE the self-check. Mirrors `bmad-install.ts` (injectable `exec`/`now`, an
+ * `npmCommand` seam) but with the opposite failure contract:
+ *
+ *   - **Idempotent skip** (AC-2): probe `<bin> --version` first; if present, emit `Skipped` and do
+ *     not re-install. The install is machine-global (`npm -g`), so a second run / other project
+ *     simply skips — which is what makes repeated runs and multiple projects safe.
+ *   - **Scope guard** (AC-4): only ids in AGENT_CLI_TABLE install; others are ignored.
+ *   - **NON-fatal failure** (AC-3): a non-zero exit OR a caught spawn error emits ONE `Failed`
+ *     event (with the manual-install fallback) and CONTINUES to the next CLI — it NEVER throws.
+ *     A CLI-install failure must not invalidate the successful BMad install.
+ *
+ * Returns `{ ok: true, ... }` whenever the step ran to completion, regardless of individual
+ * failures — the engine step returns `true` unconditionally off the back of this.
+ */
+declare function installAgentCli(opts: AgentCliOptions): Promise<AgentCliResult>;
+
+declare const SCHEMA_VERSION = 3;
+/** Node runtime floor (BMad's hard requirement). */
+declare const NODE_FLOOR_MAJOR = 20;
+/**
+ * Presence of one requested agent CLI in the final self-check (FR24). Self-describing — it carries
+ * `name`/`bin`/`pkg` so the browser Validation Page and both Welcome renderers render copy WITHOUT
+ * re-importing the engine's `AGENT_CLI_TABLE`. `pkg` lets the "install-it-yourself" notice (AC-8)
+ * show the exact `npm install -g <pkg>` command for an absent CLI. NON-blocking: this never feeds
+ * `success` (AC-6). Empty list when no CLI was requested (present for schema stability).
+ */
+interface CliPresence {
+    id: string;
+    name: string;
+    bin: string;
+    pkg: string;
+    present: boolean;
+}
+interface ValidationSummary {
+    schemaVersion: number;
+    kindlingVersion: string;
+    os: string;
+    arch: string;
+    osVersion: string;
+    node: {
+        present: boolean;
+        version: string | null;
+        satisfiesFloor: boolean;
+    };
+    git: {
+        present: boolean;
+        version: string | null;
+    };
+    /**
+     * `pinnedVersion` = the REQUESTED cohort pin (`pins.bmad`); `installed` = the `_bmad` dir is
+     * present; `installedVersion` (FR26) = the ACTUAL version read from the manifest — `null` when
+     * the manifest is absent/unreadable/unparseable (honest "couldn't read disk reality", never a
+     * false pin). The Validation Page (Story 7.1) compares `installedVersion` against the expected pin.
+     */
+    bmad: {
+        pinnedVersion: string;
+        installed: boolean;
+        installedVersion: string | null;
+    };
+    scaffold: {
+        created: boolean;
+    };
+    /** Requested agent CLIs + their presence (FR24). NON-blocking — never part of `success`. */
+    cli: CliPresence[];
+    success: boolean;
+    generatedAt: string;
+}
+interface ValidationFacts {
+    kindlingVersion: string;
+    os: string;
+    arch: string;
+    osVersion: string;
+    node: {
+        present: boolean;
+        version: string | null;
+        satisfiesFloor: boolean;
+    };
+    git: {
+        present: boolean;
+        version: string | null;
+    };
+    bmad: {
+        pinnedVersion: string;
+        installed: boolean;
+        installedVersion: string | null;
+    };
+    scaffold: {
+        created: boolean;
+    };
+    cli: CliPresence[];
+    generatedAt: string;
+}
+declare function buildValidationSummary(facts: ValidationFacts): ValidationSummary;
+/**
+ * The requested CLIs that ARE present after the run — drives the FR25 login guidance ("run `claude`
+ * and log in"). Pure + shared so the React Welcome and the static welcome.html render identical copy
+ * from one source. Tolerant of a missing/legacy `cli` field or a malformed element (returns []/skips).
+ */
+declare function cliLoginGuidance(summary: Pick<ValidationSummary, 'cli'>): CliPresence[];
+/**
+ * The requested CLIs that are ABSENT after the run — drives the calm, non-blocking "didn't finish
+ * installing — here's the one line to install it, then log in" notice (AC-8). Order-robust: derived
+ * from the summary's actual presence, not the transient step row. Skips malformed elements.
+ */
+declare function cliMissing(summary: Pick<ValidationSummary, 'cli'>): CliPresence[];
+/**
+ * The honest BMad version chip (Story 7.2 / FR26). Pure + shared so the React Welcome and the static
+ * welcome.html render identical copy from ONE source. When the summary carries an `installedVersion`
+ * (7.1's manifest read) that is a non-empty string DIFFERING from the pinned fallback, the run was an
+ * update-to-latest, so the pinned "a stable, tested version" chip would be a false statement; show
+ * the real installed version + "updated to latest". Otherwise (absent/null/equal, the default run,
+ * unchanged) fall back to the pinned chip. Never blank, never a crash. Node-free (browser-safe).
+ */
+declare function bmadVersionLabel(summary: {
+    bmad?: {
+        installedVersion?: string | null;
+    };
+} | null | undefined, pinnedFallback: string): {
+    version: string;
+    note: string;
+};
+/**
+ * Parse a major version from version strings: `v24.16.0`, `24.16.0`, `v20.0`, `v20`,
+ * `git version 2.43.0.windows.1`, `v24.0.0-nightly…`. Null if no leading integer is found.
+ */
+declare function parseMajor(version: string | null): number | null;
+
+interface SelfCheckOptions {
+    /** Outcomes threaded from prior steps (Stories 1.4 / 1.5). */
+    scaffoldCreated: boolean;
+    bmadInstalled: boolean;
+    /** Project directory — where the BMad manifest lives (`<projectDir>/_bmad/_config/manifest.yaml`). */
+    projectDir: string;
+    emitter: EngineEmitter;
+    /** Provisioned binaries (Epic 2); default PATH lookup. */
+    node?: string;
+    git?: string;
+    /**
+     * The requested eligible agent CLIs (Story 6.2), threaded from the engine's install-agent-cli
+     * step. Each is probed for presence and reported in the summary's non-blocking `cli` field.
+     * Absent/empty ⇒ `cli: []`.
+     */
+    agentClis?: AgentCliDescriptor[];
+    exec?: (cmd: string, args: string[]) => Promise<ExecResult>;
+    now?: () => string;
+    /**
+     * Resolve a CLI bin to a spawnable form before the presence probe — the probe equivalent of
+     * agent-cli.ts's `resolveBin` seam. Default: identity. On Windows the installed CLI is a
+     * `claude.cmd` shim and `exec` is `shell:false`, so a bare-bin probe would wrongly report
+     * "absent"; the Epic-2 Windows wiring / dress rehearsal plugs the resolved shim path in here.
+     */
+    resolveBin?: (bin: string) => string;
+    /**
+     * Read the ACTUAL installed BMad version from the project manifest (FR26). Injectable so unit
+     * tests never touch a real fs/manifest (mirrors the `bmadAlreadyInstalled`/`exec` seams).
+     * Default: the node-side `readInstalledBmadVersion` helper. Returns `null` on any read/parse
+     * failure — reported as `bmad.installedVersion: null`, never a false pin.
+     */
+    readInstalledBmadVersion?: (projectDir: string) => Promise<string | null>;
+    /** Platform facts (injectable for tests); default the running process. */
+    platform?: {
+        os: string;
+        arch: string;
+        osVersion: string;
+    };
+}
+declare function runSelfCheck(opts: SelfCheckOptions): Promise<ValidationSummary>;
+
+/**
+ * Read the ACTUAL installed BMad version from a project's manifest (FR26).
+ *
+ * Reads `<projectDir>/_bmad/_config/manifest.yaml` and returns `installation.version` as a string,
+ * or `null` on ANY of: file absent, YAML parse error, a non-object document, or a
+ * missing/non-string `installation.version`. NEVER throws — it mirrors the tolerance of
+ * `probeVersion`/`defaultBmadInstalled`: a "couldn't read disk reality" degrades to `null`
+ * (honest not-ready on the Validation Page), never a crash or a false pin.
+ *
+ * Node-side only (uses `node:fs/promises` + `js-yaml`). The PURE summary module
+ * (`validation-summary.ts`) must not import this — the browser imports that module.
+ */
+declare function readInstalledBmadVersion(projectDir: string): Promise<string | null>;
+
+interface ToolState {
+    present: boolean;
+    version: string | null;
+}
+interface NodeState extends ToolState {
+    satisfiesFloor: boolean;
+}
+interface DependencyState {
+    node: NodeState;
+    git: ToolState;
+}
+interface DetectOptions {
+    exec?: (cmd: string, args: string[]) => Promise<ExecResult>;
+    node?: string;
+    git?: string;
+    emitter?: EngineEmitter;
+    now?: () => string;
+}
+declare function detectDependencies(opts?: DetectOptions): Promise<DependencyState>;
+
+interface ProvisionGitUnixOptions {
+    platform: NodeJS.Platform;
+    emitter: EngineEmitter;
+    /** From 2.1 detection: Git is already present → reuse it (Skipped). */
+    alreadyOk?: boolean;
+    /** macOS: trigger the Xcode Command Line Tools install (opens the system dialog). */
+    triggerXcodeInstall?: () => Promise<void>;
+    /** macOS: true once `xcode-select -p` resolves (CLT — hence Git — installed). */
+    checkXcode?: () => Promise<boolean>;
+    /** Linux: install Git via the distro package manager (apt primary). */
+    installLinuxGit?: () => Promise<void>;
+    /** Poll cadence + cap for the Xcode wait (injected so tests don't actually wait). */
+    sleep?: (ms: number) => Promise<void>;
+    pollIntervalMs?: number;
+    maxPolls?: number;
+    exec?: (cmd: string, args: string[]) => Promise<ExecResult>;
+    now?: () => string;
+}
+interface ProvisionGitResult {
+    ok: boolean;
+}
+/**
+ * Provision Git on macOS (via the Xcode Command Line Tools) or Linux (via apt). macOS triggers
+ * the CLT install early and POLLS `xcode-select -p`, emitting a Working event on every tick so the
+ * un-silenceable Apple dialog never looks frozen (AC1/AC2). Git already present → Skipped (AC).
+ *
+ * The real `xcode-select`/apt run is validated at the dress rehearsal; here the shell effects +
+ * the clock are injected and the orchestration/poll/events/skip/fail paths are unit-tested.
+ */
+declare function provisionGitUnix(opts: ProvisionGitUnixOptions): Promise<ProvisionGitResult>;
+
+declare function defaultLogDir(): string;
+interface FailureLogEntry {
+    step: StepId;
+    error: string;
+    events: readonly KindlingEvent[];
+}
+interface WriteLogOptions {
+    dir?: string;
+    now?: () => string;
+}
+/**
+ * Writes a local, human-readable failure report and returns its path. Local-only (no network).
+ * Deliberately does NOT include the config object, environment variables, or any credentials
+ * (NFR7) — just the failed step, the error message, and the event log.
+ */
+declare function writeFailureLog(entry: FailureLogEntry, opts?: WriteLogOptions): Promise<string>;
+
+interface EngineDeps {
+    detect: (opts: DetectOptions) => Promise<DependencyState>;
+    provisionGit: (opts: ProvisionGitUnixOptions) => Promise<ProvisionGitResult>;
+    scaffold: (opts: ScaffoldOptions) => Promise<ScaffoldOutcome>;
+    runBmadInstall: (opts: BmadInstallOptions) => Promise<BmadInstallResult>;
+    installAgentCli: (opts: AgentCliOptions) => Promise<AgentCliResult>;
+    runSelfCheck: (opts: SelfCheckOptions) => Promise<ValidationSummary>;
+    writeFailureLog: (entry: FailureLogEntry) => Promise<string>;
+    /** Host platform — selects the Git provisioning step id (xcode-clt on macOS, else git). */
+    platform: NodeJS.Platform;
+}
+interface EngineRunResult {
+    ok: boolean;
+    failedStep: StepId | null;
+    summary: ValidationSummary | null;
+    logPath: string | null;
+}
+/**
+ * Orchestrates the full step sequence — provision Node (verify) → provision Git/Xcode →
+ * scaffold → install → install-agent-cli (optional, non-fatal) → self-check — tracking which
+ * steps completed so retry() can resume without re-running done steps. On a step failure it
+ * writes the on-disk failure report (the
+ * step itself already emitted its Failed event) and stops. The bootstrap provisions Node before
+ * launch; Git/Xcode is provisioned here so the browser shows the never-frozen progress.
+ */
+declare class Engine implements EngineCommands<EngineRunResult> {
+    private readonly emitter;
+    private readonly config;
+    private readonly deps;
+    private readonly completed;
+    private cancelled;
+    private running;
+    private scaffoldCreated;
+    private bmadInstalled;
+    private lastSummary;
+    private readonly steps;
+    constructor(config: Config, emitter: EngineEmitter, deps?: Partial<EngineDeps>);
+    start(config?: Config): Promise<EngineRunResult>;
+    retry(step: StepId): Promise<EngineRunResult>;
+    cancel(): void;
+    private emit;
+    private runFrom;
+    private fail;
+}
+
+type NodeArch = 'x64' | 'arm64';
+/** Official Node Windows .zip URL for a pinned version. Pure. */
+declare function nodeDistUrl(version: string, arch?: NodeArch): string;
+/** Absolute path to node.exe inside the extracted distribution. Pure. */
+declare function nodeExePath(baseDir: string, version: string, arch?: NodeArch): string;
+interface ProvisionNodeWindowsOptions {
+    /** Pinned Node version (pins.node). */
+    version: string;
+    /** Install root, e.g. %LOCALAPPDATA%\kindling\node. */
+    baseDir: string;
+    arch?: NodeArch;
+    emitter: EngineEmitter;
+    /** From 2.1 detection: a Node ≥ floor is already present → skip the download. */
+    alreadyOk?: boolean;
+    /** Injectable so tests run without network/Windows. Defaults below are spike-validation-pending. */
+    download?: (url: string, dest: string) => Promise<void>;
+    extract?: (zip: string, destDir: string) => Promise<void>;
+    exec?: (cmd: string, args: string[]) => Promise<ExecResult>;
+    now?: () => string;
+}
+interface ProvisionResult {
+    ok: boolean;
+    /**
+     * Absolute path to the provisioned node binary for the launch step (2.6) to invoke directly
+     * (the clean-runtime rule — never rely on a mutated PATH). `null` means an existing system
+     * Node was reused → the launch resolves `node` from PATH instead.
+     */
+    nodeExe: string | null;
+}
+declare function provisionNodeWindows(opts: ProvisionNodeWindowsOptions): Promise<ProvisionResult>;
+
+declare const NVM_VERSION = "v0.40.3";
+/** Absolute path to the nvm-installed node binary for a version. Pure. */
+declare function nvmNodePath(nvmDir: string, version: string): string;
+interface ProvisionNodeUnixOptions {
+    /** Pinned Node version (pins.node). */
+    version: string;
+    /** nvm install dir (default ~/.nvm). */
+    nvmDir: string;
+    emitter: EngineEmitter;
+    /** From 2.1 detection: a system Node ≥ floor is already present. Honored only OFF macOS — on
+     *  macOS we always install the exact pin via nvm so the workshop is reproducible (AC2 reuse is
+     *  Linux-only; AC3 resolved-version-equals-pins.node). */
+    alreadyOk?: boolean;
+    /** Host platform — gates the reuse rule above. */
+    platform?: NodeJS.Platform;
+    /** Injectable side effects so tests run without network/a real shell. Defaults below are
+     *  shell-based and UNVALIDATED until the dress rehearsal (macOS + Linux). */
+    installNvm?: (nvmDir: string) => Promise<void>;
+    nvmInstallNode?: (nvmDir: string, version: string) => Promise<void>;
+    /** Idempotent re-run check (2.7): is the PINNED node already installed AND runnable? Default
+     *  runs the resolved binary with --version. Verifying it RUNS (not just that a dir exists)
+     *  means a partial/dirty prior install is repaired (re-installed), not skipped-into-broken. */
+    nodeInstalled?: (nvmDir: string, version: string) => Promise<boolean>;
+    exec?: (cmd: string, args: string[]) => Promise<ExecResult>;
+    now?: () => string;
+}
+/**
+ * Provision the pinned Node on macOS/Linux via nvm, returning the ABSOLUTE node path so the
+ * launch step (2.6) never depends on a mutated PATH (the clean-runtime rule). A system Node ≥
+ * floor is reused (Skipped, AC2). Emits provision.node events; Failed + rethrow on error.
+ *
+ * The real nvm install + same-shell source is validated at the dress rehearsal; here the shell
+ * effects are injectable and the orchestration/events/skip/fail paths are unit-tested.
+ */
+declare function provisionNodeUnix(opts: ProvisionNodeUnixOptions): Promise<ProvisionResult>;
+
+export { AGENT_CLI_TABLE, type AgentCliDescriptor, type AgentCliOptions, type AgentCliResult, type BmadInstallOptions, type BmadInstallResult, type CliPresence, Config, type DependencyState, Engine, EngineCommands, type EngineDeps, EngineEmitter, type EngineRunResult, ErrorCode, ExecResult, type FailureLogEntry, KindlingEvent, type LaunchCommand, type LaunchRuntime, NODE_FLOOR_MAJOR, NVM_VERSION, type NodeArch, type NodeState, Pins, type ProvisionGitResult, type ProvisionGitUnixOptions, type ProvisionNodeUnixOptions, type ProvisionNodeWindowsOptions, type ProvisionResult, SCHEMA_VERSION, type ScaffoldOptions, type ScaffoldOutcome, type SelfCheckOptions, StepId, type ToolState, type ValidationFacts, type ValidationSummary, bmadVersionLabel, buildValidationSummary, cliLoginGuidance, cliMissing, composeInstallArgs, composeLaunchCommand, defaultBmadInstalled, defaultLogDir, detectDependencies, eligibleAgentClis, errorMessages, installAgentCli, nodeDistUrl, nodeExePath, npxCliPath, nvmNodePath, parseMajor, pins, provisionGitUnix, provisionNodeUnix, provisionNodeWindows, readInstalledBmadVersion, recoveryGuidance, runBmadInstall, runSelfCheck, scaffold, stepMessages, writeFailureLog };