@garygentry/feature-forge 0.1.0

package/dist/report.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The run reporter (spec 07 §3.5/§3.6). Pure: turns a `RunReport` into a string;
+ * the caller (`cli.ts`) writes it. No I/O. Imports only types from `./types.js`.
+ *
+ * The `--json` form emits the same `RunReport` data — the machine surface the
+ * `agent-detection-map` consumers (OS-matrix dry-runs) read (REQ-DET-05).
+ */
+import { type FileActionKind, type InstallerError, type RunReport } from "./types.js";
+/** Options for rendering a run report. */
+export interface RenderOpts {
+    /** Emit machine-readable JSON instead of human text (REQ-DET-05, REQ-OBS-01). */
+    readonly json: boolean;
+}
+/**
+ * Render a RunReport to a string (REQ-OBS-01). Pure — no I/O; the caller writes it.
+ *
+ * Human form (default): a header line, then per agent a block, then a final
+ * `Summary: N ok, N failed (exit X)` line. JSON form: `JSON.stringify(report)`
+ * (the same RunReport data) so non-Node consumers can parse it (REQ-DET-05).
+ *
+ * @param report - the assembled run report.
+ * @param opts - { json } selecting the output form.
+ * @returns the rendered string (no trailing newline; the caller adds one).
+ */
+export declare function renderReport(report: RunReport, opts: RenderOpts): string;
+/** Map a FileActionKind to its human verb (REQ-OBS-01 vocabulary). */
+export declare function actionVerb(kind: FileActionKind): string;
+/**
+ * Compose a single actionable line from a structured error (REQ-OBS-02): always prefer
+ * the error's own `message`/`remedy`; supply a per-code default remedy when absent. Pure.
+ *
+ * @param e - the structured error.
+ * @returns "<message> — path: <path> — remedy: <remedy>" (agent is already in the header).
+ */
+export declare function formatError(e: InstallerError): string;

package/dist/report.js

@@ -0,0 +1,110 @@
+/**
+ * The run reporter (spec 07 §3.5/§3.6). Pure: turns a `RunReport` into a string;
+ * the caller (`cli.ts`) writes it. No I/O. Imports only types from `./types.js`.
+ *
+ * The `--json` form emits the same `RunReport` data — the machine surface the
+ * `agent-detection-map` consumers (OS-matrix dry-runs) read (REQ-DET-05).
+ */
+/**
+ * Render a RunReport to a string (REQ-OBS-01). Pure — no I/O; the caller writes it.
+ *
+ * Human form (default): a header line, then per agent a block, then a final
+ * `Summary: N ok, N failed (exit X)` line. JSON form: `JSON.stringify(report)`
+ * (the same RunReport data) so non-Node consumers can parse it (REQ-DET-05).
+ *
+ * @param report - the assembled run report.
+ * @param opts - { json } selecting the output form.
+ * @returns the rendered string (no trailing newline; the caller adds one).
+ */
+export function renderReport(report, opts) {
+    if (opts.json) {
+        return JSON.stringify(report);
+    }
+    return renderHuman(report);
+}
+/** Human-readable rendering (REQ-OBS-01/02). */
+function renderHuman(report) {
+    const out = [];
+    const dr = report.dryRun ? " — dry-run" : "";
+    out.push(`${report.subcommand} (${report.scope}, ${report.mode})${dr}`);
+    for (const a of report.agents) {
+        out.push(...renderAgent(report.subcommand, a));
+    }
+    // Run-level rauf preflight failure (spec 07 §3.2): skills still installed, but surface it.
+    if (report.raufError) {
+        out.push(`rauf: FAILED — ${report.raufError.code}`);
+        out.push(`  ${formatError(report.raufError)}`);
+    }
+    const okCount = report.agents.filter((a) => a.ok).length;
+    const failCount = report.agents.length - okCount;
+    out.push(`Summary: ${okCount} ok, ${failCount} failed (exit ${report.exitCode})`);
+    return out.join("\n");
+}
+/** One agent's block: status line, per-file actions, and (if failed) the actionable error. */
+function renderAgent(subcommand, a) {
+    const lines = [];
+    if (subcommand === "list") {
+        // Decode the synthetic status rows (§3.3) into one human line.
+        const status = a.actions.map((f) => f.relpath).join("  ");
+        lines.push(`${a.agent}: ${a.detected ? "detected" : "not detected"}  ${status}`);
+        return lines;
+    }
+    if (!a.ok && a.error) {
+        lines.push(`${a.agent}: FAILED — ${a.error.code}`);
+        lines.push(`  ${formatError(a.error)}`); // actionable: agent + path + remedy (REQ-OBS-02)
+        return lines;
+    }
+    lines.push(`${a.agent}: ok`);
+    for (const f of a.actions) {
+        lines.push(`  ${actionVerb(f.action)} ${f.relpath}`);
+    }
+    if (a.raufPin)
+        lines.push(`  rauf default runner pinned: ${a.raufPin}`);
+    return lines;
+}
+/** Map a FileActionKind to its human verb (REQ-OBS-01 vocabulary). */
+export function actionVerb(kind) {
+    switch (kind) {
+        case "create":
+            return "create   ";
+        case "overwrite":
+            return "overwrite";
+        case "skip-modified":
+            return "skip     "; // (locally modified — see error/remedy)
+        case "unchanged":
+            return "unchanged";
+        case "remove":
+            return "remove   ";
+    }
+}
+/**
+ * Compose a single actionable line from a structured error (REQ-OBS-02): always prefer
+ * the error's own `message`/`remedy`; supply a per-code default remedy when absent. Pure.
+ *
+ * @param e - the structured error.
+ * @returns "<message> — path: <path> — remedy: <remedy>" (agent is already in the header).
+ */
+export function formatError(e) {
+    const parts = [e.message];
+    if (e.path)
+        parts.push(`path: ${e.path}`);
+    const remedy = e.remedy ?? DEFAULT_REMEDY[e.code];
+    if (remedy)
+        parts.push(`remedy: ${remedy}`);
+    return parts.join(" — ");
+}
+/**
+ * Per-code default remedy when the error did not carry one (REQ-OBS-02). Intentionally
+ * `Partial` over `ErrorCode`: `UNEXPECTED` is surfaced via the `cli.ts` boundary message
+ * (spec 07 §3.1/§4), not `formatError`, so it has no entry here.
+ */
+const DEFAULT_REMEDY = {
+    USAGE: "run 'feature-forge --help' for usage",
+    SOURCE_MISSING: "run the adapters build to generate adapters/<agent>/",
+    SOURCE_INVALID: "regenerate the bundle (run the adapters build)",
+    LOCALLY_MODIFIED: "re-run with --force to overwrite local changes",
+    WRITE_DENIED: "check write permission to the path, or choose --global vs project scope",
+    PATH_ESCAPE: "report this — a destination resolved outside the agent config dir",
+    RAUF_UNRESOLVABLE: "the default loop will be unavailable until rauf publishes (see packaging-docs-ci); skills were still installed",
+    MANIFEST_CORRUPT: "remove the corrupt .feature-forge.<scope>.json and re-run install",
+};

package/dist/source.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Source bundle location and integrity checking (spec 03, REQ-OPS-06, D7).
+ *
+ * Resolves the read-only adapter bundle for an agent from one of three locations (explicit
+ * `--source`, the packaged copy, or the in-repo `../adapters/`), runs the minimal integrity
+ * check, and fingerprints it (sourceHash + skills + files). Fallible operations return
+ * `Result<T, E>` and never throw for expected errors. Zero runtime dependencies.
+ */
+import { type AgentId, type Result } from "./types.js";
+/** Options for bundle resolution. */
+export interface LocateBundleOpts {
+    /**
+     * Hidden test hook (`--source <dir>`, D7). When set, the bundle is resolved as
+     * `<source>/<agent>` and the packaged / in-repo locations are NOT consulted.
+     */
+    source?: string;
+}
+/**
+ * Aggregate of a located, integrity-checked, fingerprinted bundle (spec 03 §3.7).
+ */
+export interface LocatedSource {
+    /** Absolute path to the agent bundle root (e.g. `.../adapters/claude`). */
+    readonly root: string;
+    /** sha256 over the bundle's sorted-path file set — the drift anchor (`manifest.sourceHash`). */
+    readonly sourceHash: string;
+    /** Installed skill ids (the bundle's `skills/*` dir names) for `manifest.skills`. */
+    readonly skills: readonly string[];
+    /** Per-file inventory (`{ relpath, sha256 }`, sorted by POSIX relpath) — the planner's input. */
+    readonly files: ReadonlyArray<{
+        readonly relpath: string;
+        readonly sha256: string;
+    }>;
+}
+/**
+ * Locate the read-only adapter bundle directory for `agent` (D7, REQ-OPS-06).
+ *
+ * Resolution order (first existing directory wins): `opts.source/<agent>`, then
+ * `<installerPkgRoot>/adapters/<agent>`, then `<repoRoot>/adapters/<agent>` (both derived from
+ * `import.meta.url`, cwd-independent).
+ *
+ * @returns ok(absolutePath) when a candidate dir exists; err(SOURCE_MISSING) naming the expected
+ *          path + remedy otherwise.
+ */
+export declare function locateBundle(agent: AgentId, opts?: LocateBundleOpts): Result<string>;
+/**
+ * Minimal integrity check for a located bundle (REQ-OPS-06). Valid iff the `BUNDLE_REQUIRED_PATHS`
+ * are present: `skills/` is a non-empty dir, `scripts/forge-root.sh` exists, and (gemini)
+ * `gemini-extension.json` exists. Does NOT require `.claude-plugin/plugin.json` or
+ * `epic-manifest.py` (IR-1 / OQ-A).
+ *
+ * @returns ok(undefined) when every required path is present; err(SOURCE_INVALID) naming the
+ *          first missing/invalid required path otherwise.
+ */
+export declare function checkIntegrity(bundlePath: string, agent: AgentId): Result<void>;
+/**
+ * List the skill ids a bundle contains: the directory names directly under
+ * `<bundlePath>/skills/` (REQ-SCALE-02). Enumerates DIRECTORY NAMES ONLY and never opens a skill
+ * file. Returned sorted (byte-wise).
+ */
+export declare function listBundleSkills(bundlePath: string): string[];
+/**
+ * Locate, integrity-check, and fingerprint one agent's bundle in a single call (spec 03 §3.7).
+ *
+ * @returns ok(LocatedSource) when the bundle exists and passes the integrity check; otherwise the
+ *          exact err(SOURCE_MISSING) / err(SOURCE_INVALID) from locateBundle/checkIntegrity.
+ */
+export declare function locateSource(agent: AgentId, opts?: {
+    source?: string;
+}): Result<LocatedSource>;

package/dist/source.js

@@ -0,0 +1,164 @@
+/**
+ * Source bundle location and integrity checking (spec 03, REQ-OPS-06, D7).
+ *
+ * Resolves the read-only adapter bundle for an agent from one of three locations (explicit
+ * `--source`, the packaged copy, or the in-repo `../adapters/`), runs the minimal integrity
+ * check, and fingerprints it (sourceHash + skills + files). Fallible operations return
+ * `Result<T, E>` and never throw for expected errors. Zero runtime dependencies.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { ok, err, BUNDLE_REQUIRED_PATHS, } from "./types.js";
+import { computeSourceHash, listBundleFiles } from "./hash.js";
+/**
+ * Locate the read-only adapter bundle directory for `agent` (D7, REQ-OPS-06).
+ *
+ * Resolution order (first existing directory wins): `opts.source/<agent>`, then
+ * `<installerPkgRoot>/adapters/<agent>`, then `<repoRoot>/adapters/<agent>` (both derived from
+ * `import.meta.url`, cwd-independent).
+ *
+ * @returns ok(absolutePath) when a candidate dir exists; err(SOURCE_MISSING) naming the expected
+ *          path + remedy otherwise.
+ */
+export function locateBundle(agent, opts = {}) {
+    for (const candidate of bundleCandidates(agent, opts)) {
+        if (isDirectory(candidate))
+            return ok(candidate);
+    }
+    const expected = primaryExpectedPath(agent, opts);
+    return err({
+        code: "SOURCE_MISSING",
+        agent,
+        path: expected,
+        message: `no source bundle for agent "${agent}" — expected an adapters directory at ${expected}. ` +
+            `The bundle is generated by the adapters build; run it (or pass --source <dir>) before installing.`,
+        remedy: "run the adapters build to generate adapters/<agent>/, or pass --source <dir>",
+    });
+}
+/**
+ * Minimal integrity check for a located bundle (REQ-OPS-06). Valid iff the `BUNDLE_REQUIRED_PATHS`
+ * are present: `skills/` is a non-empty dir, `scripts/forge-root.sh` exists, and (gemini)
+ * `gemini-extension.json` exists. Does NOT require `.claude-plugin/plugin.json` or
+ * `epic-manifest.py` (IR-1 / OQ-A).
+ *
+ * @returns ok(undefined) when every required path is present; err(SOURCE_INVALID) naming the
+ *          first missing/invalid required path otherwise.
+ */
+export function checkIntegrity(bundlePath, agent) {
+    const skillsDir = path.join(bundlePath, "skills");
+    if (!isDirectory(skillsDir) || !hasEntries(skillsDir)) {
+        return invalid(agent, skillsDir, "skills/ is missing or empty");
+    }
+    const required = requiredPathsFor(agent).filter((rel) => rel !== "skills");
+    for (const rel of required) {
+        const abs = path.join(bundlePath, rel);
+        if (!fs.existsSync(abs)) {
+            return invalid(agent, abs, `required path "${rel}" is missing`);
+        }
+    }
+    return ok(undefined);
+}
+/**
+ * List the skill ids a bundle contains: the directory names directly under
+ * `<bundlePath>/skills/` (REQ-SCALE-02). Enumerates DIRECTORY NAMES ONLY and never opens a skill
+ * file. Returned sorted (byte-wise).
+ */
+export function listBundleSkills(bundlePath) {
+    const skillsDir = path.join(bundlePath, "skills");
+    let entries;
+    try {
+        entries = fs.readdirSync(skillsDir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    return entries
+        .filter((e) => e.isDirectory())
+        .map((e) => e.name)
+        .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+}
+/**
+ * Locate, integrity-check, and fingerprint one agent's bundle in a single call (spec 03 §3.7).
+ *
+ * @returns ok(LocatedSource) when the bundle exists and passes the integrity check; otherwise the
+ *          exact err(SOURCE_MISSING) / err(SOURCE_INVALID) from locateBundle/checkIntegrity.
+ */
+export function locateSource(agent, opts) {
+    const located = locateBundle(agent, opts);
+    if (!located.ok)
+        return located; // SOURCE_MISSING
+    const integrity = checkIntegrity(located.value, agent);
+    if (!integrity.ok)
+        return integrity; // SOURCE_INVALID
+    return ok({
+        root: located.value,
+        sourceHash: computeSourceHash(located.value),
+        skills: listBundleSkills(located.value),
+        files: listBundleFiles(located.value),
+    });
+}
+// ---------------------------------------------------------------------------
+// Internal helpers (module-private — spec 03 §4.1, §4.2)
+// ---------------------------------------------------------------------------
+/** dist/source.js at runtime → its dir is <installerPkgRoot>/dist. */
+function moduleDir() {
+    return path.dirname(fileURLToPath(import.meta.url));
+}
+/** <installerPkgRoot> = parent of dist/. */
+function installerPkgRoot() {
+    return path.resolve(moduleDir(), "..");
+}
+/** <repoRoot> = parent of installer/. */
+function repoRoot() {
+    return path.resolve(installerPkgRoot(), "..");
+}
+/** The ordered candidate bundle dirs for an agent (spec 03 §3.1 table). */
+function bundleCandidates(agent, opts) {
+    // Explicit --source is exclusive: the packaged / in-repo locations are NOT consulted (spec §3.1).
+    if (opts.source)
+        return [path.resolve(opts.source, agent)];
+    const candidates = [];
+    candidates.push(path.join(installerPkgRoot(), "adapters", agent)); // packaged copy (D7)
+    candidates.push(path.join(repoRoot(), "adapters", agent)); // in-repo dev (C-3)
+    return candidates;
+}
+/** The most actionable expected path to name in a SOURCE_MISSING error (REQ-OBS-02). */
+function primaryExpectedPath(agent, opts) {
+    return opts.source
+        ? path.resolve(opts.source, agent)
+        : path.join(repoRoot(), "adapters", agent);
+}
+/** common + per-agent required paths (from BUNDLE_REQUIRED_PATHS, 00 §6). */
+function requiredPathsFor(agent) {
+    const perAgent = BUNDLE_REQUIRED_PATHS.perAgent[agent] ?? [];
+    return [...BUNDLE_REQUIRED_PATHS.common, ...perAgent];
+}
+/** Construct the SOURCE_INVALID error naming the offending path (REQ-OBS-02). */
+function invalid(agent, badPath, why) {
+    return err({
+        code: "SOURCE_INVALID",
+        agent,
+        path: badPath,
+        message: `source bundle for agent "${agent}" is invalid: ${why} (at ${badPath}).`,
+        remedy: "re-run the adapters build to regenerate a complete bundle",
+    });
+}
+/** True iff `p` exists and is a directory. */
+function isDirectory(p) {
+    try {
+        return fs.statSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/** True iff directory `p` has at least one entry (used for the non-empty `skills/` check). */
+function hasEntries(p) {
+    try {
+        return fs.readdirSync(p).length > 0;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,264 @@
+/**
+ * Shared type system, error hierarchy, and constants for the cross-agent installer.
+ *
+ * This module is the foundation: every other module imports the types, constants, and
+ * `Result` defined here and does not redefine them (spec 00-core-definitions). Named
+ * exports only; `node:` built-ins only where applicable; zero runtime dependencies.
+ */
+/**
+ * The five coding agents this installer targets (REQ-DET-01). Order is the canonical
+ * iteration order used by detection, planning, and reporting so output is deterministic.
+ */
+export declare const AGENT_IDS: readonly ["claude", "codex", "copilot", "cursor", "gemini"];
+/** A supported coding-agent identifier. */
+export type AgentId = (typeof AGENT_IDS)[number];
+/**
+ * Install scope (REQ-FLAG-02). `"project"` (default) installs into the current project's
+ * agent dir (e.g. `./.claude/skills/feature-forge/`); `"global"` installs into the
+ * user-level dir (e.g. `~/.claude/skills/feature-forge/`).
+ */
+export type Scope = "project" | "global";
+/**
+ * Materialization mode (REQ-FLAG-03). `"copy"` is the default and the only mode on Windows;
+ * `"symlink"` links the whole namespace dir to the source bundle (opt-in via `--symlink`).
+ */
+export type Mode = "copy" | "symlink";
+/** The four invocable subcommands (aliases resolved before this type, spec 07). */
+export type Subcommand = "install" | "update" | "uninstall" | "list";
+/** Process exit codes (REQ-OBS-01/03, spec 07). */
+export declare const EXIT: {
+    readonly SUCCESS: 0;
+    readonly FAILURE: 1;
+    readonly USAGE: 2;
+};
+export type ExitCode = (typeof EXIT)[keyof typeof EXIT];
+/** Manifest schema version; bumped only on a breaking manifest-shape change. */
+export declare const SCHEMA_VERSION: 1;
+/** The single namespace directory name written inside each agent's install location [D5]. */
+export declare const FEATURE_FORGE_NS: "feature-forge";
+/** Filename prefix for the hidden parent-sibling manifest, completed by the scope (§3, spec 05). */
+export declare const MANIFEST_PREFIX: ".feature-forge.";
+/**
+ * One row of the static per-agent detection map (REQ-DET-01, REQ-DET-05). Adding a new
+ * agent is exactly adding one entry to `AGENT_TARGETS` — no logic change (REQ-SCALE-01).
+ *
+ * The on-disk destination for an agent under a given scope is derived, not stored:
+ *   <scopeRoot>/<configDirName>/<installSubdir>/<FEATURE_FORGE_NS>/
+ * where scopeRoot is the resolved home (global) or cwd (project).
+ */
+export interface AgentTarget {
+    /** Stable agent identifier. */
+    readonly id: AgentId;
+    /**
+     * Basename of the agent's config directory, probed for detection (REQ-DET-02),
+     * e.g. ".claude", ".codex", ".cursor". Detection is `stat` on this dir, never a subprocess.
+     */
+    readonly configDirName: string;
+    /**
+     * Sub-path under the config dir that holds the namespaced install dir, e.g.
+     * "skills" (claude/codex/copilot), "rules" (cursor), "extensions" (gemini).
+     */
+    readonly installSubdir: string;
+    /**
+     * Informational: the skill-file form this agent's bundle uses — "SKILL.md" (claude),
+     * "<name>.md" (codex/copilot/gemini), "<name>.mdc" (cursor). The installer copies the
+     * bundle verbatim (REQ-SCALE-02) and does not parse skill files, so this is documentation.
+     */
+    readonly skillFileForm: string;
+    /**
+     * Confidence in this row's paths. "confirmed" = source-verified (claude). "best-known"
+     * = the TQ-1 paths (codex/copilot/cursor/gemini) to re-verify against each agent's current
+     * docs at implementation (REQ-SCALE-01 — isolated, localized correction).
+     */
+    readonly confidence: "confirmed" | "best-known";
+}
+/** Options for path resolution, injectable so tests never touch the real `~` (spec 02, spec 08). */
+export interface ResolveOpts {
+    /** Home dir for global scope. Default: `os.homedir()`. */
+    readonly home?: string;
+    /** Working dir for project scope. Default: `process.cwd()`. */
+    readonly cwd?: string;
+    /** Active scope. Default: `"project"`. */
+    readonly scope?: Scope;
+}
+/**
+ * One agent's detection outcome (REQ-DET-02/04). Returned by `detectAgent`/`detectAgents`
+ * (spec 02) and the data half of the `agent-detection-map` surface (REQ-DET-05).
+ */
+export interface DetectionResult {
+    readonly agent: AgentId;
+    /** True iff the agent's config dir is present (primary signal, REQ-DET-02). */
+    readonly detected: boolean;
+    /** Every config dir probed — named verbatim in the zero-detection report (REQ-DET-04). */
+    readonly configDirsProbed: string[];
+    /** Secondary, advisory only: whether the agent's CLI is on PATH (never the detection signal). */
+    readonly cliOnPath?: boolean;
+    /** Resolved absolute install destination for the active scope (the `feature-forge/` namespace dir). */
+    readonly destination: string;
+}
+/** One file recorded in the manifest inventory (REQ-SAFE-01). */
+export interface ManifestFile {
+    /** Path relative to the manifest's `destination`. */
+    readonly path: string;
+    /** SHA-256 of the written bytes. Omitted for symlink mode (no per-file copy exists). */
+    readonly sha256?: string;
+}
+/**
+ * The persisted per-install manifest (REQ-SAFE-01/03), written as the hidden parent-sibling
+ * `<installSubdir>/.feature-forge.<scope>.json` (spec 05). It is the sole record `list`/`update`/
+ * `uninstall` use to tell installer-written content from user content and to detect drift.
+ */
+export interface InstallManifest {
+    readonly schemaVersion: typeof SCHEMA_VERSION;
+    readonly agent: AgentId;
+    readonly scope: Scope;
+    readonly mode: Mode;
+    /** Absolute path of the `feature-forge/` namespace dir this manifest governs. */
+    readonly destination: string;
+    /**
+     * Bundle version coordinate. **`null` today** — the consumed `adapters/` bundles carry no
+     * version (no plugin.json / version header; gemini's `gemini-extension.json` version is a
+     * `0.0.0` placeholder). Recording a real value is deferred to the generator under OQ-A/IR-1;
+     * C-3 forbids the installer reading outside `adapters/` to synthesize one.
+     */
+    readonly featureForgeVersion: string | null;
+    /** SHA-256 over the source bundle's canonical (sorted-path) file set — drift anchor (OQ-4, spec 03). */
+    readonly sourceHash: string;
+    /** Pinned rauf coordinate recorded at install, e.g. "rauf@0.6.0"; `null` if `--skip-rauf` (spec 06). */
+    readonly raufPin: string | null;
+    /** ISO-8601 timestamps. */
+    readonly installedAt: string;
+    readonly updatedAt: string;
+    /** Installed skill ids (the bundle's `skills/*` dir names). */
+    readonly skills: string[];
+    /** Per-file inventory (copy mode); `sha256` omitted in symlink mode. */
+    readonly files: ManifestFile[];
+    /** Symlink mode only: the source bundle the namespace dir links to (REQ-SAFE-02). */
+    readonly link?: {
+        readonly target: string;
+    };
+}
+/**
+ * The per-file action the planner assigns by diffing source ⇆ destination ⇆ manifest (spec 04).
+ * - "create": destination file absent → will be written.
+ * - "overwrite": clean prior file whose source bytes changed → will be refreshed.
+ * - "skip-modified": destination locally modified (≠ recorded hash AND ≠ what we'd write)
+ *   → left untouched and reported, unless `--force` (REQ-IDEM-02, REQ-FLAG-04).
+ * - "unchanged": destination matches source → no write (REQ-IDEM-01).
+ * - "remove": manifest records it but canon no longer has it → removed by `update` (REQ-OPS-02).
+ */
+export type FileActionKind = "create" | "overwrite" | "skip-modified" | "unchanged" | "remove";
+/** A single planned file action (REQ-OPS-05). */
+export interface FileAction {
+    /** Path relative to the agent's install destination. */
+    readonly relpath: string;
+    readonly action: FileActionKind;
+}
+/**
+ * One agent's complete plan (REQ-OPS-05). `--dry-run` prints exactly this; a real run hands
+ * the *same* `PlannedAction` to `apply` (spec 04), guaranteeing "dry-run = real run".
+ */
+export interface PlannedAction {
+    readonly agent: AgentId;
+    readonly scope: Scope;
+    readonly mode: Mode;
+    readonly files: FileAction[];
+    /** Surfaced in the plan/report for visibility (spec 06); not a file action. */
+    readonly raufPin?: string | null;
+}
+/** One agent's outcome in a run summary (REQ-OBS-01/03). */
+export interface AgentReport {
+    readonly agent: AgentId;
+    readonly detected: boolean;
+    /** False iff this agent's operation failed (others still proceed — REQ-OBS-03). */
+    readonly ok: boolean;
+    /** The actions performed (or planned, under `--dry-run`). */
+    readonly actions: FileAction[];
+    /** Present iff `ok` is false. */
+    readonly error?: InstallerError;
+    readonly raufPin?: string | null;
+}
+/** The whole-run summary, rendered human-readable or as `--json` (REQ-OBS-01, REQ-DET-05). */
+export interface RunReport {
+    readonly subcommand: Subcommand;
+    readonly scope: Scope;
+    readonly mode: Mode;
+    readonly dryRun: boolean;
+    readonly agents: AgentReport[];
+    /** EXIT.SUCCESS unless any agent failed (FAILURE) or args were invalid (USAGE). */
+    readonly exitCode: ExitCode;
+    /**
+     * Run-level rauf preflight failure (spec 07 §3.2): set when the install/update rauf
+     * resolvability check failed. Skills still install (each `AgentReport.ok` stays true) but the
+     * run `exitCode` is FAILURE and the renderer surfaces this message. Absent on success.
+     *
+     * This is the sanctioned run-level field spec 07 §3.2 permits in lieu of the `attachRaufError`
+     * hook (see cli.ts run-report assembly). It is part of the `--json` machine surface
+     * (REQ-DET-05): consumers reading `renderReport(report, { json: true })` see it verbatim.
+     */
+    readonly raufError?: InstallerError;
+}
+/**
+ * The static detection map (REQ-DET-01, REQ-SCALE-01). Keyed by AgentId; iteration order
+ * follows `AGENT_IDS`. Paths for non-claude agents are "best-known" (TQ-1) — re-verify each
+ * against the agent's current config-dir/skills-dir convention at implementation (OQ-B).
+ *
+ * Verified ground truth: every bundle has `skills/` (11 skills), `references/`,
+ * `scripts/forge-root.sh`, `agents/`; gemini adds a root `gemini-extension.json`,
+ * codex adds `agents/openai.yaml`, cursor uses `.mdc` files.
+ */
+export declare const AGENT_TARGETS: Readonly<Record<AgentId, AgentTarget>>;
+/**
+ * Minimal integrity check (REQ-OPS-06, spec 03): a located bundle is valid iff `skills/` is a
+ * non-empty dir, `scripts/forge-root.sh` exists, and — for gemini only — `gemini-extension.json`
+ * exists at the bundle root. Defined here as data so the check is a localized table read.
+ */
+export declare const BUNDLE_REQUIRED_PATHS: {
+    /** Required of every agent bundle. */
+    readonly common: readonly ["skills", "scripts/forge-root.sh"];
+    /** Additional per-agent requirements. */
+    readonly perAgent: Partial<Record<AgentId, readonly string[]>>;
+};
+/**
+ * Stable error codes. Each maps to an actionable message form (REQ-OBS-02) and, at the CLI
+ * boundary, an exit code (spec 07): USAGE → EXIT.USAGE (2); everything else → EXIT.FAILURE (1).
+ */
+export type ErrorCode = "USAGE" | "SOURCE_MISSING" | "SOURCE_INVALID" | "LOCALLY_MODIFIED" | "WRITE_DENIED" | "PATH_ESCAPE" | "RAUF_UNRESOLVABLE" | "MANIFEST_CORRUPT" | "UNEXPECTED";
+/**
+ * A structured, actionable installer error (REQ-OBS-02). `message` must name the agent, the
+ * path, and the remedy where applicable; `remedy` optionally carries the suggested fix verbatim.
+ */
+export interface InstallerError {
+    readonly code: ErrorCode;
+    readonly message: string;
+    readonly agent?: AgentId;
+    readonly path?: string;
+    readonly remedy?: string;
+}
+/** Result<T,E> — success carries a value; failure carries a structured error. */
+export type Result<T, E = InstallerError> = {
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly ok: false;
+    readonly error: E;
+};
+/** Success constructor. */
+export declare const ok: <T>(value: T) => Result<T, never>;
+/** Failure constructor. */
+export declare const err: <E>(error: E) => Result<never, E>;
+/**
+ * Parsed, normalized CLI flags (REQ-FLAG-01..05, REQ-DIST-02). Produced by `cli.ts` from
+ * `node:util.parseArgs` (spec 07). `agent` undefined ⇒ all detected agents (REQ-DET-03).
+ */
+export interface CliFlags {
+    readonly agent?: AgentId;
+    readonly global: boolean;
+    readonly symlink: boolean;
+    readonly force: boolean;
+    readonly dryRun: boolean;
+    readonly yes: boolean;
+    readonly json: boolean;
+    readonly skipRauf: boolean;
+    readonly source?: string;
+}