@garygentry/feature-forge 0.1.0

package/dist/agent-targets.d.ts

@@ -0,0 +1,70 @@
+/**
+ * The `agent-detection-map` exposed surface (spec 02): the static per-agent table plus the
+ * pure path derivations and the stat-based detection over it.
+ *
+ * One contract, two halves (REQ-DET-05):
+ *   - static  — `AGENT_TARGETS` (re-exported), `resolveRoots`, `destinationFor`
+ *   - behavioral — `detectAgent`, `detectAgents`, `formatZeroDetection`
+ *
+ * Every function is data-driven over `AGENT_TARGETS` / `AGENT_IDS`, so a new agent is exactly
+ * one table row (REQ-SCALE-01) with no edit here. Read-only and total: nothing writes, spawns
+ * an agent, or creates a directory. Zero runtime dependencies; only `node:` built-ins.
+ */
+import { type AgentId, type AgentTarget, type DetectionResult, type ResolveOpts, type Scope } from "./types.js";
+export { AGENT_TARGETS } from "./types.js";
+/**
+ * Resolve the two filesystem roots all destinations derive from, applying defaults. This is
+ * the single injection point for the home and working directories, so tests sandbox every
+ * path computation without touching the real `~` (spec 02 §4.2).
+ *
+ * - `home` (global scope root) defaults to `os.homedir()`.
+ * - `cwd`  (project scope root) defaults to `process.cwd()`.
+ *
+ * Both returned paths are absolute and `path.resolve`d. Pure: reads no files, spawns nothing.
+ */
+export declare function resolveRoots(opts?: ResolveOpts): {
+    home: string;
+    cwd: string;
+};
+/**
+ * Derive the absolute install destination for one agent under a given scope (REQ-DET-01,
+ * REQ-FLAG-02):
+ *
+ *     <scopeRoot>/<configDirName>/<installSubdir>/<FEATURE_FORGE_NS>/
+ *
+ * where `scopeRoot` is the home dir for `"global"` and the cwd for `"project"`. The path is
+ * derived, never stored, so a new agent is one `AGENT_TARGETS` row (REQ-SCALE-01). Pure.
+ *
+ * @example destinationFor(AGENT_TARGETS.claude, "global", { home: "/h" })
+ *   // → "/h/.claude/skills/feature-forge"
+ */
+export declare function destinationFor(target: AgentTarget, scope: Scope, opts?: ResolveOpts): string;
+/**
+ * Detect a single agent on the host (REQ-DET-02). Detection is decided solely by the presence
+ * of the agent's config dir under the active scope root (a `stat`, never an agent subprocess).
+ *
+ * Populates `configDirsProbed` (named in the zero-detection report, REQ-DET-04), `destination`
+ * (the resolved install dest for the active scope), and the advisory-only `cliOnPath` (never the
+ * detection signal). Total: any valid `AgentId` yields a `DetectionResult`; absence is
+ * `detected: false`, never an error.
+ */
+export declare function detectAgent(id: AgentId, opts?: ResolveOpts): DetectionResult;
+/** Options for {@link detectAgents}: {@link ResolveOpts} plus a single-agent scope (REQ-FLAG-01). */
+export interface DetectAgentsOpts extends ResolveOpts {
+    /** Restrict detection to this one agent (`--agent/-a`). Absent ⇒ all five (REQ-DET-03). */
+    readonly only?: AgentId;
+}
+/**
+ * Detect every supported agent in canonical `AGENT_IDS` order (REQ-DET-03). Pass `opts.only`
+ * to scope to a single agent (REQ-FLAG-01); the result is then a one-element array. The default
+ * project/global scope comes from `opts.scope`. Total — never throws; each agent is probed
+ * independently.
+ */
+export declare function detectAgents(opts?: DetectAgentsOpts): DetectionResult[];
+/**
+ * Build the clear, actionable message for the zero-agents-detected case (REQ-DET-04). Names
+ * every config dir probed (drawn from the supplied results' `configDirsProbed`) so the user sees
+ * exactly where the installer looked. Creates no directory and produces no opaque error.
+ * Pure: derives text from already-computed {@link DetectionResult}s.
+ */
+export declare function formatZeroDetection(results: DetectionResult[], scope: Scope): string;

package/dist/agent-targets.js

@@ -0,0 +1,111 @@
+/**
+ * The `agent-detection-map` exposed surface (spec 02): the static per-agent table plus the
+ * pure path derivations and the stat-based detection over it.
+ *
+ * One contract, two halves (REQ-DET-05):
+ *   - static  — `AGENT_TARGETS` (re-exported), `resolveRoots`, `destinationFor`
+ *   - behavioral — `detectAgent`, `detectAgents`, `formatZeroDetection`
+ *
+ * Every function is data-driven over `AGENT_TARGETS` / `AGENT_IDS`, so a new agent is exactly
+ * one table row (REQ-SCALE-01) with no edit here. Read-only and total: nothing writes, spawns
+ * an agent, or creates a directory. Zero runtime dependencies; only `node:` built-ins.
+ */
+import * as os from "node:os";
+import * as path from "node:path";
+import { AGENT_IDS, AGENT_TARGETS, FEATURE_FORGE_NS, } from "./types.js";
+import { probeConfigDir, cliOnPath } from "./detect.js";
+// Re-export the static table so importers reach the data and the behavior from one surface
+// (REQ-DET-01, REQ-DET-05).
+export { AGENT_TARGETS } from "./types.js";
+/**
+ * Resolve the two filesystem roots all destinations derive from, applying defaults. This is
+ * the single injection point for the home and working directories, so tests sandbox every
+ * path computation without touching the real `~` (spec 02 §4.2).
+ *
+ * - `home` (global scope root) defaults to `os.homedir()`.
+ * - `cwd`  (project scope root) defaults to `process.cwd()`.
+ *
+ * Both returned paths are absolute and `path.resolve`d. Pure: reads no files, spawns nothing.
+ */
+export function resolveRoots(opts) {
+    return {
+        home: path.resolve(opts?.home ?? os.homedir()),
+        cwd: path.resolve(opts?.cwd ?? process.cwd()),
+    };
+}
+/**
+ * Internal: select the root directory for a scope (REQ-FLAG-02).
+ * `"global"` → the resolved home dir; `"project"` → the resolved cwd.
+ */
+function scopeRootFor(scope, roots) {
+    return scope === "global" ? roots.home : roots.cwd;
+}
+/**
+ * Derive the absolute install destination for one agent under a given scope (REQ-DET-01,
+ * REQ-FLAG-02):
+ *
+ *     <scopeRoot>/<configDirName>/<installSubdir>/<FEATURE_FORGE_NS>/
+ *
+ * where `scopeRoot` is the home dir for `"global"` and the cwd for `"project"`. The path is
+ * derived, never stored, so a new agent is one `AGENT_TARGETS` row (REQ-SCALE-01). Pure.
+ *
+ * @example destinationFor(AGENT_TARGETS.claude, "global", { home: "/h" })
+ *   // → "/h/.claude/skills/feature-forge"
+ */
+export function destinationFor(target, scope, opts) {
+    const roots = resolveRoots(opts);
+    const root = scopeRootFor(scope, roots);
+    return path.resolve(root, target.configDirName, target.installSubdir, FEATURE_FORGE_NS);
+}
+/**
+ * Detect a single agent on the host (REQ-DET-02). Detection is decided solely by the presence
+ * of the agent's config dir under the active scope root (a `stat`, never an agent subprocess).
+ *
+ * Populates `configDirsProbed` (named in the zero-detection report, REQ-DET-04), `destination`
+ * (the resolved install dest for the active scope), and the advisory-only `cliOnPath` (never the
+ * detection signal). Total: any valid `AgentId` yields a `DetectionResult`; absence is
+ * `detected: false`, never an error.
+ */
+export function detectAgent(id, opts) {
+    const target = AGENT_TARGETS[id];
+    const scope = opts?.scope ?? "project";
+    const roots = resolveRoots(opts);
+    const root = scopeRootFor(scope, roots);
+    // Primary signal (REQ-DET-02): presence of the config dir under the active scope root.
+    const configDir = path.resolve(root, target.configDirName);
+    const detected = probeConfigDir(configDir);
+    return {
+        agent: id,
+        detected,
+        configDirsProbed: [configDir],
+        destination: destinationFor(target, scope, opts),
+        cliOnPath: cliOnPath(id), // advisory only; never gates `detected`
+    };
+}
+/**
+ * Detect every supported agent in canonical `AGENT_IDS` order (REQ-DET-03). Pass `opts.only`
+ * to scope to a single agent (REQ-FLAG-01); the result is then a one-element array. The default
+ * project/global scope comes from `opts.scope`. Total — never throws; each agent is probed
+ * independently.
+ */
+export function detectAgents(opts) {
+    const ids = opts?.only ? [opts.only] : AGENT_IDS;
+    return ids.map((id) => detectAgent(id, opts));
+}
+/**
+ * Build the clear, actionable message for the zero-agents-detected case (REQ-DET-04). Names
+ * every config dir probed (drawn from the supplied results' `configDirsProbed`) so the user sees
+ * exactly where the installer looked. Creates no directory and produces no opaque error.
+ * Pure: derives text from already-computed {@link DetectionResult}s.
+ */
+export function formatZeroDetection(results, scope) {
+    const probed = results.flatMap((r) => r.configDirsProbed);
+    const lines = [
+        `No supported coding agents detected (scope: ${scope}).`,
+        `Probed config directories (none present):`,
+        ...probed.map((p) => `  - ${p}`),
+        `No directories were created. Install an agent (or pass --global/project scope, or`,
+        `--source for tests) and re-run.`,
+    ];
+    return lines.join("\n");
+}

package/dist/apply.d.ts

@@ -0,0 +1,49 @@
+/**
+ * The apply engine (spec 04 §5) — the executor that turns a pure `PlannedAction` into filesystem
+ * mutations, then records the install manifest. `apply` NEVER throws for expected errors: a failure
+ * (write denied, path escape, manifest unwritable) returns `AgentReport{ ok:false, error }` so the
+ * CLI loop (07) can record one agent's failure and proceed with the others (REQ-OBS-03).
+ *
+ * Every mutation routes through the sandboxed `fsutil` primitives (each preceded by a
+ * `resolveWithin` containment check, REQ-SEC-01/02/03). There is NO gemini-specific branch — the
+ * bundle's `gemini-extension.json` is just another file in `source.files` (D9). There is no
+ * `applyUninstall`: an all-`"remove"` plan from `planUninstall` (05) is executed here (§5.3).
+ *
+ * Zero runtime dependencies; only `node:` built-ins.
+ */
+import type { AgentReport, InstallManifest, Mode, PlannedAction, Result, Scope, AgentId } from "./types.js";
+import type { LocatedSource } from "./source.js";
+/**
+ * Apply-time context for ONE agent (spec 04 §5). `agentRoot` is the containment boundary every
+ * write is checked against (REQ-SEC-02): the resolved `<scopeRoot>/<configDirName>` (from 02).
+ * `destination` is the namespace dir; `manifestPath` the parent-sibling hidden file (05).
+ */
+export interface ApplyContext {
+    readonly agent: AgentId;
+    readonly scope: Scope;
+    readonly mode: Mode;
+    /** Containment boundary for REQ-SEC-02: the agent's config root (e.g. `<home>/.claude`). */
+    readonly agentRoot: string;
+    /** The `feature-forge/` namespace dir (manifest.destination). */
+    readonly destination: string;
+    /** Hidden parent-sibling manifest path, from 05 `manifestPath`. */
+    readonly manifestPath: string;
+    /** Located source bundle (copy bytes / symlink target). `null` only for uninstall. */
+    readonly source: LocatedSource | null;
+    /** Pinned rauf coordinate to record in the manifest (06); `null` under `--skip-rauf`. */
+    readonly raufPin: string | null;
+    /** ISO-8601 "now" (injectable for deterministic tests). */
+    readonly now: string;
+    /** Prior manifest (for preserving `installedAt` across updates, and carrying inventory). */
+    readonly priorManifest: InstallManifest | null;
+    /**
+     * Injectable per-file write seam (tests force a deterministic WRITE_DENIED). Default:
+     * mkdir parent + `fs.copyFile`. Returns `Result` and never throws for expected errors.
+     */
+    readonly writeFileSeam?: (srcAbs: string, destAbs: string) => Promise<Result<void>>;
+}
+/**
+ * Execute one agent's `PlannedAction` against the filesystem, then write/delete the manifest.
+ * Returns an `AgentReport` instead of throwing (REQ-OBS-03). See spec 04 §5.
+ */
+export declare function apply(planned: PlannedAction, ctx: ApplyContext): Promise<AgentReport>;

package/dist/apply.js

@@ -0,0 +1,246 @@
+/**
+ * The apply engine (spec 04 §5) — the executor that turns a pure `PlannedAction` into filesystem
+ * mutations, then records the install manifest. `apply` NEVER throws for expected errors: a failure
+ * (write denied, path escape, manifest unwritable) returns `AgentReport{ ok:false, error }` so the
+ * CLI loop (07) can record one agent's failure and proceed with the others (REQ-OBS-03).
+ *
+ * Every mutation routes through the sandboxed `fsutil` primitives (each preceded by a
+ * `resolveWithin` containment check, REQ-SEC-01/02/03). There is NO gemini-specific branch — the
+ * bundle's `gemini-extension.json` is just another file in `source.files` (D9). There is no
+ * `applyUninstall`: an all-`"remove"` plan from `planUninstall` (05) is executed here (§5.3).
+ *
+ * Zero runtime dependencies; only `node:` built-ins.
+ */
+import * as fsp from "node:fs/promises";
+import * as path from "node:path";
+import { ok, err } from "./types.js";
+import { sha256File } from "./hash.js";
+import { resolveWithin, symlinkDir, removePath, removeEmptyDirsWithin, } from "./fsutil.js";
+import { buildManifest, writeManifest } from "./manifest.js";
+/**
+ * Execute one agent's `PlannedAction` against the filesystem, then write/delete the manifest.
+ * Returns an `AgentReport` instead of throwing (REQ-OBS-03). See spec 04 §5.
+ */
+export async function apply(planned, ctx) {
+    // Empty-files plan (e.g. uninstall with no prior manifest) is a no-op — touch nothing.
+    if (planned.files.length === 0)
+        return success(ctx, planned);
+    const isUninstall = planned.files.every((f) => f.action === "remove");
+    if (ctx.mode === "symlink") {
+        return isUninstall
+            ? applySymlinkUninstall(planned, ctx)
+            : applySymlinkInstall(planned, ctx);
+    }
+    return isUninstall
+        ? applyCopyUninstall(planned, ctx)
+        : applyCopyInstall(planned, ctx);
+}
+// ---------------------------------------------------------------------------
+// Copy mode
+// ---------------------------------------------------------------------------
+/** §5.1 copy flow: per-file copy/remove, then write the manifest (unless every action unchanged). */
+async function applyCopyInstall(planned, ctx) {
+    const source = ctx.source;
+    if (source === null) {
+        return fail(ctx, planned, {
+            code: "UNEXPECTED",
+            agent: ctx.agent,
+            message: `apply(copy) for "${ctx.agent}" requires a located source bundle but got null`,
+        });
+    }
+    const priorByPath = new Map();
+    for (const f of ctx.priorManifest?.files ?? [])
+        priorByPath.set(f.path, f);
+    const writeFile = ctx.writeFileSeam ?? defaultCopyFile;
+    const inventory = [];
+    for (const fa of planned.files) {
+        const resolved = resolveWithin(ctx.agentRoot, ctx.destination, fa.relpath);
+        if (!resolved.ok)
+            return fail(ctx, planned, resolved.error);
+        const destAbs = resolved.value;
+        switch (fa.action) {
+            case "create":
+            case "overwrite": {
+                const srcAbs = path.join(source.root, fa.relpath);
+                const wrote = await writeFile(srcAbs, destAbs);
+                if (!wrote.ok)
+                    return fail(ctx, planned, wrote.error);
+                inventory.push({ path: fa.relpath, sha256: sha256File(destAbs) });
+                break;
+            }
+            case "remove": {
+                const removed = await removePath(destAbs);
+                if (!removed.ok)
+                    return fail(ctx, planned, removed.error);
+                break;
+            }
+            case "unchanged":
+            case "skip-modified": {
+                // No write. Carry the prior inventory entry forward so the rewritten manifest is faithful.
+                const prior = priorByPath.get(fa.relpath);
+                if (prior !== undefined)
+                    inventory.push(prior);
+                break;
+            }
+        }
+    }
+    // No-op short-circuit (REQ-IDEM-01): every action unchanged ⇒ zero writes, manifest untouched.
+    if (planned.files.every((f) => f.action === "unchanged")) {
+        return success(ctx, planned);
+    }
+    const manifest = buildManifest({
+        agent: ctx.agent,
+        scope: ctx.scope,
+        mode: "copy",
+        destination: ctx.destination,
+        files: inventory,
+        skills: source.skills,
+        sourceHash: source.sourceHash,
+        raufPin: ctx.raufPin,
+        previous: ctx.priorManifest,
+        now: () => new Date(ctx.now),
+    });
+    const wrote = writeManifest(ctx.manifestPath, manifest);
+    if (!wrote.ok)
+        return fail(ctx, planned, wrote.error);
+    return success(ctx, planned);
+}
+/** §5.3 copy-mode uninstall: remove recorded files, prune empty dirs, delete the manifest LAST. */
+async function applyCopyUninstall(planned, ctx) {
+    for (const fa of planned.files) {
+        const resolved = resolveWithin(ctx.agentRoot, ctx.destination, fa.relpath);
+        if (!resolved.ok)
+            return fail(ctx, planned, resolved.error);
+        const removed = await removePath(resolved.value);
+        if (!removed.ok)
+            return fail(ctx, planned, removed.error);
+    }
+    const pruned = await removeEmptyDirsWithin(ctx.destination, ctx.agentRoot);
+    if (!pruned.ok)
+        return fail(ctx, planned, pruned.error);
+    const deleted = await deleteManifest(ctx);
+    if (!deleted.ok)
+        return fail(ctx, planned, deleted.error);
+    return success(ctx, planned);
+}
+// ---------------------------------------------------------------------------
+// Symlink mode
+// ---------------------------------------------------------------------------
+/** §5.2 symlink flow: remove any prior, link the whole namespace dir → source bundle root. */
+async function applySymlinkInstall(planned, ctx) {
+    const source = ctx.source;
+    if (source === null) {
+        return fail(ctx, planned, {
+            code: "UNEXPECTED",
+            agent: ctx.agent,
+            message: `apply(symlink) for "${ctx.agent}" requires a located source bundle but got null`,
+        });
+    }
+    const resolved = resolveWithin(ctx.agentRoot, ctx.destination);
+    if (!resolved.ok)
+        return fail(ctx, planned, resolved.error);
+    const linkPath = resolved.value;
+    // Unchanged (live link already points at the same target) ⇒ zero writes, manifest untouched.
+    if (planned.files.every((f) => f.action === "unchanged")) {
+        return success(ctx, planned);
+    }
+    // skip-modified (prior exists, no --force) ⇒ leave it; report, write nothing.
+    if (planned.files.every((f) => f.action === "skip-modified")) {
+        return success(ctx, planned);
+    }
+    const removed = await removePath(linkPath);
+    if (!removed.ok)
+        return fail(ctx, planned, removed.error);
+    const linked = await symlinkDir(source.root, linkPath);
+    if (!linked.ok)
+        return fail(ctx, planned, linked.error);
+    const effectiveMode = linked.value.mode;
+    // files[] lists the bundle-relative paths with sha256 OMITTED (no per-file copy exists, 00 §3).
+    const files = source.files.map((f) => ({ path: f.relpath }));
+    const manifest = buildManifest({
+        agent: ctx.agent,
+        scope: ctx.scope,
+        mode: effectiveMode,
+        destination: ctx.destination,
+        files,
+        skills: source.skills,
+        sourceHash: source.sourceHash,
+        raufPin: ctx.raufPin,
+        // Truthful record: a copy fallback must NOT carry link (copy-mode manifest invariant, 05).
+        ...(effectiveMode === "symlink" ? { link: { target: source.root } } : {}),
+        previous: ctx.priorManifest,
+        now: () => new Date(ctx.now),
+    });
+    const wrote = writeManifest(ctx.manifestPath, manifest);
+    if (!wrote.ok)
+        return fail(ctx, planned, wrote.error);
+    return success(ctx, planned);
+}
+/** §5.3 symlink-mode uninstall: `lstat`+`unlink` the link only (never recurse), delete manifest. */
+async function applySymlinkUninstall(planned, ctx) {
+    const resolved = resolveWithin(ctx.agentRoot, ctx.destination);
+    if (!resolved.ok)
+        return fail(ctx, planned, resolved.error);
+    const removed = await removePath(resolved.value);
+    if (!removed.ok)
+        return fail(ctx, planned, removed.error);
+    const deleted = await deleteManifest(ctx);
+    if (!deleted.ok)
+        return fail(ctx, planned, deleted.error);
+    return success(ctx, planned);
+}
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+/** Default per-file write seam: ensure the parent dir, then copy the source bytes. */
+async function defaultCopyFile(srcAbs, destAbs) {
+    try {
+        await fsp.mkdir(path.dirname(destAbs), { recursive: true });
+        await fsp.copyFile(srcAbs, destAbs);
+        return ok(undefined);
+    }
+    catch (e) {
+        const code = e?.code;
+        if (code === "EACCES" || code === "EPERM") {
+            return err({
+                code: "WRITE_DENIED",
+                message: `no write permission to ${destAbs}`,
+                path: destAbs,
+                remedy: "check directory permissions, or choose a different scope (--global vs project)",
+            });
+        }
+        return err({
+            code: "UNEXPECTED",
+            message: `filesystem error at ${destAbs}: ${e?.message ?? String(e)}`,
+            path: destAbs,
+        });
+    }
+}
+/** Delete the manifest file (containment-checked), idempotent (ENOENT → ok). */
+async function deleteManifest(ctx) {
+    const resolved = resolveWithin(ctx.agentRoot, ctx.manifestPath);
+    if (!resolved.ok)
+        return resolved;
+    return removePath(resolved.value);
+}
+/** Build a successful AgentReport for `ctx`/`planned`. */
+function success(ctx, planned) {
+    return {
+        agent: ctx.agent,
+        detected: true,
+        ok: true,
+        actions: planned.files,
+        raufPin: ctx.raufPin,
+    };
+}
+/** Build a failed AgentReport carrying `error` (never throws — REQ-OBS-03). */
+function fail(ctx, planned, error) {
+    return {
+        agent: ctx.agent,
+        detected: true,
+        ok: false,
+        actions: planned.files,
+        error,
+        raufPin: ctx.raufPin,
+    };
+}

package/dist/cli.d.ts

@@ -0,0 +1,94 @@
+/**
+ * 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 {};