@garygentry/feature-forge 0.1.0

package/dist/manifest.js

@@ -0,0 +1,222 @@
+/**
+ * The persisted install manifest (read/write/build) and the manifest-driven uninstall-exactness
+ * policy (spec 05). This module locates the hidden parent-sibling manifest, reads/validates and
+ * atomically writes it, builds an {@link InstallManifest} from an apply result, and owns the
+ * uninstall removal POLICY (`planUninstall`). The safe EXECUTION of that plan is `apply()` in
+ * spec 04 — there is no `applyUninstall` here.
+ *
+ * Zero runtime dependencies; only `node:` built-ins. Named exports only. Core functions return
+ * `Result<T, E>` and never throw for expected errors; `JSON.parse` is wrapped in `try/catch`.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { AGENT_TARGETS, MANIFEST_PREFIX, SCHEMA_VERSION, ok, err, } from "./types.js";
+import { destinationFor } from "./agent-targets.js";
+/**
+ * Assemble an {@link InstallManifest} from an apply result (REQ-SAFE-01/03). Pure — no I/O.
+ *
+ * Timestamp policy: `updatedAt` is always "now"; `installedAt` is `previous.installedAt` when
+ * reconciling an existing install, else "now". `featureForgeVersion` is always `null` today
+ * (OQ-A/IR-1; C-3 forbids synthesizing one).
+ */
+export function buildManifest(args) {
+    const now = (args.now ?? (() => new Date()))().toISOString();
+    const installedAt = args.previous?.installedAt ?? now;
+    const files = [...args.files]
+        .map((f) => ({ path: f.path, ...(f.sha256 !== undefined ? { sha256: f.sha256 } : {}) }))
+        .sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+    const skills = [...args.skills].sort();
+    return {
+        schemaVersion: SCHEMA_VERSION,
+        agent: args.agent,
+        scope: args.scope,
+        mode: args.mode,
+        destination: args.destination,
+        featureForgeVersion: null, // null today (OQ-A/IR-1); C-3 forbids synthesizing one.
+        sourceHash: args.sourceHash,
+        raufPin: args.raufPin,
+        installedAt,
+        updatedAt: now,
+        skills,
+        files,
+        ...(args.link !== undefined ? { link: args.link } : {}),
+    };
+}
+// ---------------------------------------------------------------------------
+// manifestPath
+// ---------------------------------------------------------------------------
+/**
+ * Absolute path of the hidden parent-sibling manifest for an agent + scope (D6/D8):
+ *   `<scopeRoot>/<configDirName>/<installSubdir>/.feature-forge.<scope>.json`
+ * e.g. `~/.claude/skills/.feature-forge.global.json`. Identical for copy and symlink mode.
+ */
+export function manifestPath(agent, scope, opts) {
+    const destination = destinationFor(AGENT_TARGETS[agent], scope, opts);
+    const installSubdirAbs = path.dirname(destination); // the skills/rules/extensions dir
+    return path.join(installSubdirAbs, `${MANIFEST_PREFIX}${scope}.json`);
+}
+// ---------------------------------------------------------------------------
+// readManifest / writeManifest
+// ---------------------------------------------------------------------------
+/**
+ * Read and validate the manifest at `p`. Absent (`ENOENT`) → `ok(null)`; present + valid →
+ * `ok(manifest)`; unreadable / invalid JSON / failed shape validation → `err(MANIFEST_CORRUPT)`.
+ */
+export function readManifest(p) {
+    let raw;
+    try {
+        raw = fs.readFileSync(p, "utf8");
+    }
+    catch (e) {
+        if (e.code === "ENOENT")
+            return ok(null);
+        return err({
+            code: "MANIFEST_CORRUPT",
+            message: `cannot read install manifest at ${p}: ${e.message}`,
+            path: p,
+            remedy: "check read permissions, or remove the file to force a fresh install",
+        });
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (e) {
+        return err({
+            code: "MANIFEST_CORRUPT",
+            message: `install manifest at ${p} is not valid JSON: ${e.message}`,
+            path: p,
+            remedy: "the manifest is corrupt; remove it and re-run install to regenerate it",
+        });
+    }
+    const v = validateManifest(parsed);
+    if (!v.ok) {
+        return err({
+            code: "MANIFEST_CORRUPT",
+            message: `install manifest at ${p} failed validation: ${v.reason}`,
+            path: p,
+            remedy: "the manifest is corrupt; remove it and re-run install to regenerate it",
+        });
+    }
+    return ok(v.value);
+}
+/**
+ * Atomically write the manifest to `p` (write `<p>.tmp` → `rename`). Creates the parent dir if
+ * missing. Returns `err(WRITE_DENIED)` on a permission failure, cleaning up the temp file.
+ */
+export function writeManifest(p, m) {
+    const tmp = `${p}.tmp`;
+    try {
+        fs.mkdirSync(path.dirname(p), { recursive: true });
+        fs.writeFileSync(tmp, `${JSON.stringify(m, null, 2)}\n`, "utf8");
+        fs.renameSync(tmp, p); // atomic on a single filesystem
+        return ok(undefined);
+    }
+    catch (e) {
+        // Best-effort cleanup of the temp file; ignore secondary failures.
+        try {
+            fs.rmSync(tmp, { force: true });
+        }
+        catch {
+            /* ignore */
+        }
+        const code = e.code;
+        if (code === "EACCES" || code === "EPERM") {
+            return err({
+                code: "WRITE_DENIED",
+                message: `no write permission for install manifest at ${p}`,
+                path: p,
+                remedy: `ensure you can write to ${path.dirname(p)} (do not use elevated privileges)`,
+            });
+        }
+        return err({
+            code: "UNEXPECTED",
+            message: `failed to write install manifest at ${p}: ${e.message}`,
+            path: p,
+        });
+    }
+}
+const AGENT_IDS_SET = new Set(["claude", "codex", "copilot", "cursor", "gemini"]);
+/** Structural validation of a parsed manifest (internal to manifest.ts). */
+function validateManifest(x) {
+    if (typeof x !== "object" || x === null)
+        return { ok: false, reason: "not an object" };
+    const o = x;
+    if (o.schemaVersion !== SCHEMA_VERSION) {
+        return { ok: false, reason: `unsupported schemaVersion ${String(o.schemaVersion)}` };
+    }
+    if (typeof o.agent !== "string" || !AGENT_IDS_SET.has(o.agent)) {
+        return { ok: false, reason: `invalid agent ${String(o.agent)}` };
+    }
+    if (o.scope !== "global" && o.scope !== "project") {
+        return { ok: false, reason: `invalid scope ${String(o.scope)}` };
+    }
+    if (o.mode !== "copy" && o.mode !== "symlink") {
+        return { ok: false, reason: `invalid mode ${String(o.mode)}` };
+    }
+    if (typeof o.destination !== "string" || o.destination.length === 0) {
+        return { ok: false, reason: "missing destination" };
+    }
+    if (!(o.featureForgeVersion === null || typeof o.featureForgeVersion === "string")) {
+        return { ok: false, reason: "invalid featureForgeVersion" };
+    }
+    if (typeof o.sourceHash !== "string")
+        return { ok: false, reason: "missing sourceHash" };
+    if (!(o.raufPin === null || typeof o.raufPin === "string")) {
+        return { ok: false, reason: "invalid raufPin" };
+    }
+    if (typeof o.installedAt !== "string" || typeof o.updatedAt !== "string") {
+        return { ok: false, reason: "missing timestamps" };
+    }
+    if (!Array.isArray(o.skills) || !o.skills.every((s) => typeof s === "string")) {
+        return { ok: false, reason: "invalid skills[]" };
+    }
+    if (!Array.isArray(o.files))
+        return { ok: false, reason: "invalid files[]" };
+    for (const f of o.files) {
+        if (typeof f !== "object" || f === null)
+            return { ok: false, reason: "invalid files[] entry" };
+        const ff = f;
+        if (typeof ff.path !== "string")
+            return { ok: false, reason: "files[].path not a string" };
+        if (ff.sha256 !== undefined && typeof ff.sha256 !== "string") {
+            return { ok: false, reason: "files[].sha256 not a string" };
+        }
+    }
+    if (o.link !== undefined) {
+        const l = o.link;
+        if (typeof l !== "object" || l === null || typeof l.target !== "string") {
+            return { ok: false, reason: "invalid link" };
+        }
+    }
+    // Cross-field: symlink ⇒ link present; copy ⇒ link absent (D8 invariant).
+    if (o.mode === "symlink" && o.link === undefined) {
+        return { ok: false, reason: "symlink mode manifest missing link.target" };
+    }
+    if (o.mode === "copy" && o.link !== undefined) {
+        return { ok: false, reason: "copy mode manifest must not carry link" };
+    }
+    return { ok: true, value: x };
+}
+// ---------------------------------------------------------------------------
+// planUninstall — the uninstall removal POLICY
+// ---------------------------------------------------------------------------
+/**
+ * Compute the uninstall plan from a manifest (REQ-OPS-03, REQ-SAFE-01/02). PURE — no I/O,
+ * manifest only. Returns an all-`"remove"` {@link PlannedAction}: copy mode one
+ * `{ relpath, action: "remove" }` per `manifest.files[].path` in recorded order; symlink mode the
+ * single `{ relpath: ".", action: "remove" }`. The safe EXECUTION is `apply()` in spec 04.
+ */
+export function planUninstall(manifest) {
+    const isSymlink = manifest.mode === "symlink" || manifest.link !== undefined;
+    const files = isSymlink
+        ? [{ relpath: ".", action: "remove" }]
+        : manifest.files.map((f) => ({ relpath: f.path, action: "remove" }));
+    return ok({
+        agent: manifest.agent,
+        scope: manifest.scope,
+        mode: manifest.mode,
+        destination: manifest.destination,
+        files,
+    });
+}

package/dist/plan.d.ts

@@ -0,0 +1,66 @@
+/**
+ * The pure planner (spec 04 §3-§6) — the dry-run = real-run engine.
+ *
+ * `plan.ts` performs ZERO filesystem writes and ZERO network calls. It MAY read destination bytes
+ * (via `sha256File`) and the prior manifest (already read by 05 and passed in via `PlanContext`).
+ * It diffs three facts per bundle-relative path — source hash (S), destination hash (D), and the
+ * manifest-recorded hash (M) — and emits a `PlannedAction`. The CLI hands the SAME object to
+ * `apply()` on a real run, so dry-run and real run can never drift. Zero runtime dependencies.
+ */
+import type { AgentId, FileActionKind, Mode, PlannedAction, Result, Scope, InstallManifest } from "./types.js";
+import { type LocatedSource } from "./source.js";
+/**
+ * Everything the pure planner needs to diff source ⇆ destination ⇆ manifest for ONE agent
+ * (spec 04 §4). Built by cli.ts (07); the planner reads these and writes nothing.
+ */
+export interface PlanContext {
+    /** The agent being planned. */
+    readonly agent: AgentId;
+    /** Active scope; copied onto the plan. */
+    readonly scope: Scope;
+    /** Resolved materialization mode. MUST already account for Windows (see `resolveMode`). */
+    readonly mode: Mode;
+    /** Absolute path of the `feature-forge/` namespace dir to be governed. */
+    readonly destination: string;
+    /** The located, integrity-checked source bundle (03), or `null` (absent/invalid bundle). */
+    readonly source: LocatedSource | null;
+    /** The prior manifest for this destination, or `null` if none exists (fresh install). */
+    readonly priorManifest: InstallManifest | null;
+    /** `--force`: overwrite `skip-modified` destinations instead of skipping. */
+    readonly force: boolean;
+    /** The pinned rauf coordinate to surface on the plan (06); the planner only echoes it. */
+    readonly raufPin?: string | null;
+}
+/**
+ * Classify one bundle-relative path (spec 04 §6 table). PURE: hashes are read, nothing is written.
+ *
+ * @param relpath      bundle-relative POSIX path (informational; not used in the decision)
+ * @param srcHash      sha256 of the source file (S)
+ * @param destHash     sha256 of the destination file, or undefined if absent (D)
+ * @param manifestHash sha256 recorded for this path in the prior manifest, or undefined (M)
+ * @param force        whether --force promotes skip-modified → overwrite
+ */
+export declare function classifyFile(relpath: string, srcHash: string, destHash: string | undefined, manifestHash: string | undefined, force: boolean): FileActionKind;
+/**
+ * PURE. Compute the install plan for one agent (spec 04 §4.1). Writes nothing. Returns
+ * err(SOURCE_MISSING/SOURCE_INVALID) when `ctx.source` is null.
+ */
+export declare function planInstall(ctx: PlanContext): Result<PlannedAction>;
+/**
+ * PURE. Compute the update/reconcile plan for one agent (spec 04 §4.2): identical to planInstall
+ * for create/overwrite/unchanged/skip-modified, PLUS manifest-scoped orphan removal — any path in
+ * `priorManifest.files` the current source no longer contains becomes `remove`. With no prior
+ * manifest, behaves exactly like planInstall (first install).
+ */
+export declare function planUpdate(ctx: PlanContext): Result<PlannedAction>;
+/**
+ * Convenience dispatcher used by cli.ts (07). Routes install/update to the typed planner;
+ * `uninstall` delegates to `planUninstall` (manifest-driven, from 05) — an absent prior manifest
+ * yields an empty-files plan (no-op).
+ */
+export declare function plan(subcommand: "install" | "update" | "uninstall", ctx: PlanContext): Result<PlannedAction>;
+/**
+ * Resolve the effective materialization mode (spec 04, REQ-FLAG-03, D8). `--symlink` requests
+ * symlink, but Windows ALWAYS copies. Pure; `windows` is injectable for tests.
+ */
+export declare function resolveMode(wantSymlink: boolean, windows?: boolean): Mode;

package/dist/plan.js

@@ -0,0 +1,166 @@
+/**
+ * The pure planner (spec 04 §3-§6) — the dry-run = real-run engine.
+ *
+ * `plan.ts` performs ZERO filesystem writes and ZERO network calls. It MAY read destination bytes
+ * (via `sha256File`) and the prior manifest (already read by 05 and passed in via `PlanContext`).
+ * It diffs three facts per bundle-relative path — source hash (S), destination hash (D), and the
+ * manifest-recorded hash (M) — and emits a `PlannedAction`. The CLI hands the SAME object to
+ * `apply()` on a real run, so dry-run and real run can never drift. Zero runtime dependencies.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { ok, err } from "./types.js";
+import { sha256File } from "./hash.js";
+import { planUninstall } from "./manifest.js";
+import { isWindows } from "./fsutil.js";
+/**
+ * Classify one bundle-relative path (spec 04 §6 table). PURE: hashes are read, nothing is written.
+ *
+ * @param relpath      bundle-relative POSIX path (informational; not used in the decision)
+ * @param srcHash      sha256 of the source file (S)
+ * @param destHash     sha256 of the destination file, or undefined if absent (D)
+ * @param manifestHash sha256 recorded for this path in the prior manifest, or undefined (M)
+ * @param force        whether --force promotes skip-modified → overwrite
+ */
+export function classifyFile(relpath, srcHash, destHash, manifestHash, force) {
+    void relpath;
+    if (destHash === undefined)
+        return "create"; // row 1
+    if (destHash === srcHash)
+        return "unchanged"; // row 3 (wins over rows 2/4)
+    // dest exists and differs from source:
+    const clean = manifestHash !== undefined && destHash === manifestHash;
+    if (clean)
+        return "overwrite"; // row 2 (REQ-IDEM-03: clean prior, source changed, no --force)
+    return force ? "overwrite" : "skip-modified"; // rows 4/5 (REQ-IDEM-02/REQ-FLAG-04)
+}
+/**
+ * PURE. Compute the install plan for one agent (spec 04 §4.1). Writes nothing. Returns
+ * err(SOURCE_MISSING/SOURCE_INVALID) when `ctx.source` is null.
+ */
+export function planInstall(ctx) {
+    return buildPlan(ctx, /* withOrphans */ false);
+}
+/**
+ * PURE. Compute the update/reconcile plan for one agent (spec 04 §4.2): identical to planInstall
+ * for create/overwrite/unchanged/skip-modified, PLUS manifest-scoped orphan removal — any path in
+ * `priorManifest.files` the current source no longer contains becomes `remove`. With no prior
+ * manifest, behaves exactly like planInstall (first install).
+ */
+export function planUpdate(ctx) {
+    return buildPlan(ctx, /* withOrphans */ true);
+}
+/**
+ * Convenience dispatcher used by cli.ts (07). Routes install/update to the typed planner;
+ * `uninstall` delegates to `planUninstall` (manifest-driven, from 05) — an absent prior manifest
+ * yields an empty-files plan (no-op).
+ */
+export function plan(subcommand, ctx) {
+    switch (subcommand) {
+        case "install":
+            return planInstall(ctx);
+        case "update":
+            return planUpdate(ctx);
+        case "uninstall":
+            return ctx.priorManifest === null
+                ? ok({
+                    agent: ctx.agent,
+                    scope: ctx.scope,
+                    mode: ctx.mode,
+                    destination: ctx.destination,
+                    files: [],
+                })
+                : planUninstall(ctx.priorManifest);
+    }
+}
+/**
+ * Resolve the effective materialization mode (spec 04, REQ-FLAG-03, D8). `--symlink` requests
+ * symlink, but Windows ALWAYS copies. Pure; `windows` is injectable for tests.
+ */
+export function resolveMode(wantSymlink, windows = isWindows()) {
+    return wantSymlink && !windows ? "symlink" : "copy";
+}
+// ---------------------------------------------------------------------------
+// Internal — plan assembly
+// ---------------------------------------------------------------------------
+/** Shared core of planInstall/planUpdate (the orphan pass differs). */
+function buildPlan(ctx, withOrphans) {
+    if (ctx.source === null) {
+        // A null source means 03 already failed to locate/validate the bundle (SOURCE_MISSING or
+        // SOURCE_INVALID). The CLI (07) surfaces 03's exact error; the planner only refuses to plan.
+        return err({
+            code: "SOURCE_MISSING",
+            agent: ctx.agent,
+            message: `no usable source bundle for agent "${ctx.agent}"`,
+            remedy: "run the adapters build to generate adapters/<agent>/, or pass --source <dir>",
+        });
+    }
+    const files = ctx.mode === "symlink"
+        ? planSymlink(ctx)
+        : planCopy(ctx, withOrphans);
+    const action = {
+        agent: ctx.agent,
+        scope: ctx.scope,
+        mode: ctx.mode,
+        files,
+        ...(ctx.raufPin !== undefined ? { raufPin: ctx.raufPin } : {}),
+    };
+    return ok(action);
+}
+/** Copy-mode per-file diff (spec 04 §6). `ctx.source` is non-null here. */
+function planCopy(ctx, withOrphans) {
+    const source = ctx.source;
+    const manifestByPath = new Map();
+    for (const f of ctx.priorManifest?.files ?? [])
+        manifestByPath.set(f.path, f);
+    const actions = [];
+    for (const sf of source.files) {
+        const destAbs = path.join(ctx.destination, sf.relpath);
+        const destHash = hashIfExists(destAbs);
+        const manifestHash = manifestByPath.get(sf.relpath)?.sha256;
+        const kind = classifyFile(sf.relpath, sf.sha256, destHash, manifestHash, ctx.force);
+        actions.push({ relpath: sf.relpath, action: kind });
+    }
+    if (withOrphans && ctx.priorManifest !== null) {
+        actions.push(...orphanRemovals(ctx.priorManifest.files, source.files));
+    }
+    return actions;
+}
+/**
+ * Symlink-mode plan shape (spec 04 §6): a single synthetic FileAction for the namespace dir.
+ * The prior-state decision is read from the manifest (no `readlink`), keeping the planner pure.
+ */
+function planSymlink(ctx) {
+    const source = ctx.source;
+    const prior = ctx.priorManifest;
+    const priorExists = prior !== null;
+    const priorIsLiveSymlinkToSameTarget = priorExists && prior.link?.target === source.root;
+    const action = priorIsLiveSymlinkToSameTarget
+        ? "unchanged"
+        : priorExists
+            ? ctx.force
+                ? "overwrite"
+                : "skip-modified"
+            : "create";
+    return [{ relpath: ".", action }];
+}
+/** Paths in the prior manifest that the current source no longer contains → `remove` (row 6). */
+function orphanRemovals(priorFiles, sourceFiles) {
+    const inSource = new Set(sourceFiles.map((f) => f.relpath));
+    return priorFiles
+        .filter((f) => !inSource.has(f.path))
+        .map((f) => ({ relpath: f.path, action: "remove" }));
+}
+/** sha256 of a destination file if it exists as a regular file, else undefined. PURE read. */
+function hashIfExists(absPath) {
+    let st;
+    try {
+        st = fs.lstatSync(absPath);
+    }
+    catch {
+        return undefined;
+    }
+    if (!st.isFile())
+        return undefined;
+    return sha256File(absPath);
+}

package/dist/rauf.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Rauf provisioning (spec 06): the single pinned rauf coordinate (`RAUF_PIN`), the
+ * install-time read-only resolvability preflight, the `--skip-rauf` short-circuit, and the
+ * fixed unavailable-pin failure mode.
+ *
+ * Scope: this module makes rauf the *provisioned default* loop runner by recording a pin and
+ * preflighting its resolvability — it never vendors a binary, never mutates global npm state,
+ * never invokes rauf, and performs NO filesystem write. The only side effect is the read-only
+ * `npm view` registry query in the default registry query (skipped when `opts.skip` or an
+ * injected query is used). Named exports only; zero runtime dependencies (only `node:`
+ * built-ins). No throw for expected errors — returns `Result<T, E>` from `00-core-definitions`.
+ */
+import { type Result } from "./types.js";
+/**
+ * The single pinned rauf coordinate the install provisions as the default loop runner
+ * (REQ-RAUF-03). One source of truth: re-exported by `src/index.ts` so importers and the
+ * downstream `forge-rauf-loop-default` read the same value, and recorded into each manifest
+ * as `InstallManifest.raufPin` (05-manifest-and-uninstall.md).
+ *
+ * Shape: `<name>@<version>` — UNSCOPED `rauf`. Advanced on each feature-forge release to a new
+ * known-compatible rauf (REQ-RAUF-03). The current rauf version is 0.6.0.
+ *
+ * Correctable config (OQ-C): the FINAL published coordinate is confirmed by `packaging-docs-ci`
+ * when rauf's publish path is stood up. Until then this resolves to a package that does not yet
+ * exist on npm (IR-2), so the preflight WILL fail — the known, designed failure mode, not a bug.
+ */
+export declare const RAUF_PIN = "rauf@0.6.0";
+/**
+ * An injectable, READ-ONLY registry query (D1). Given a coordinate `name@version`, returns the
+ * resolved version string on success, or an `InstallerError` if it is not resolvable.
+ *
+ * Injectable so tests mock the registry with NO real network: the default implementation
+ * (`defaultRegistryQuery`) shells `npm view <coordinate> version`; a test passes a stub
+ * returning `ok("0.6.0")` or `err({ code: "RAUF_UNRESOLVABLE", ... })`.
+ *
+ * Contract: the query MUST be read-only — it MUST NOT install, MUST NOT mutate global npm
+ * state, and MUST NOT execute rauf. `npm view` satisfies this (it only reads registry metadata).
+ *
+ * @param coordinate - the `name@version` to resolve, e.g. "rauf@0.6.0"
+ * @returns Result<string> — the resolved version on success; RAUF_UNRESOLVABLE on failure.
+ */
+export type RegistryQuery = (coordinate: string) => Result<string>;
+/** Options for the rauf preflight. */
+export interface PreflightRaufOpts {
+    /**
+     * When true (the `--skip-rauf` flag), skip the preflight entirely: perform NO network call
+     * and return `{ raufPin: null }`. For environments that knowingly defer rauf (e.g. CI
+     * dry-runs while rauf is unpublished — IR-2).
+     */
+    readonly skip?: boolean;
+    /**
+     * The registry query to use. Default: `defaultRegistryQuery` (`npm view rauf@<pin> version`
+     * via node:child_process). Tests inject a stub so no real network call is made.
+     */
+    readonly query?: RegistryQuery;
+}
+/**
+ * Resolvability preflight for the pinned default loop runner (D1; REQ-RAUF-01/02/03, OQ-1).
+ *
+ * Behavior:
+ *  - `opts.skip` (the `--skip-rauf` flag) ⇒ return `ok({ raufPin: null })` immediately, with NO
+ *    network call.
+ *  - otherwise ⇒ run a READ-ONLY registry resolvability check on `RAUF_PIN` (default query:
+ *    `npm view rauf@<pin> version`). No install, no global-npm mutation, no execution of rauf.
+ *      · resolvable  ⇒ return `ok({ raufPin: RAUF_PIN })` — the value the manifest records.
+ *      · unresolvable ⇒ return `err(<RAUF_UNRESOLVABLE>)` carrying the FIXED message (§6).
+ *
+ * NEVER throws for the expected unresolvable case — that is an `err(...)`. An unexpected spawn
+ * failure inside the default query is normalized to the same `RAUF_UNRESOLVABLE` error, so
+ * callers handle one code. Performs no filesystem write.
+ *
+ * @param opts - skip flag and/or an injected registry query (tests)
+ * @returns Result<{ raufPin: string | null }>:
+ *          ok + `raufPin: RAUF_PIN`  when resolvable,
+ *          ok + `raufPin: null`      when skipped,
+ *          err(RAUF_UNRESOLVABLE)    when the pin is not resolvable.
+ */
+export declare function preflightRauf(opts?: {
+    skip?: boolean;
+    query?: RegistryQuery;
+}): Result<{
+    raufPin: string | null;
+}>;

package/dist/rauf.js

@@ -0,0 +1,118 @@
+/**
+ * Rauf provisioning (spec 06): the single pinned rauf coordinate (`RAUF_PIN`), the
+ * install-time read-only resolvability preflight, the `--skip-rauf` short-circuit, and the
+ * fixed unavailable-pin failure mode.
+ *
+ * Scope: this module makes rauf the *provisioned default* loop runner by recording a pin and
+ * preflighting its resolvability — it never vendors a binary, never mutates global npm state,
+ * never invokes rauf, and performs NO filesystem write. The only side effect is the read-only
+ * `npm view` registry query in the default registry query (skipped when `opts.skip` or an
+ * injected query is used). Named exports only; zero runtime dependencies (only `node:`
+ * built-ins). No throw for expected errors — returns `Result<T, E>` from `00-core-definitions`.
+ */
+import { spawnSync } from "node:child_process";
+import { err, ok } from "./types.js";
+/**
+ * The single pinned rauf coordinate the install provisions as the default loop runner
+ * (REQ-RAUF-03). One source of truth: re-exported by `src/index.ts` so importers and the
+ * downstream `forge-rauf-loop-default` read the same value, and recorded into each manifest
+ * as `InstallManifest.raufPin` (05-manifest-and-uninstall.md).
+ *
+ * Shape: `<name>@<version>` — UNSCOPED `rauf`. Advanced on each feature-forge release to a new
+ * known-compatible rauf (REQ-RAUF-03). The current rauf version is 0.6.0.
+ *
+ * Correctable config (OQ-C): the FINAL published coordinate is confirmed by `packaging-docs-ci`
+ * when rauf's publish path is stood up. Until then this resolves to a package that does not yet
+ * exist on npm (IR-2), so the preflight WILL fail — the known, designed failure mode, not a bug.
+ */
+export const RAUF_PIN = "rauf@0.6.0";
+/**
+ * Resolvability preflight for the pinned default loop runner (D1; REQ-RAUF-01/02/03, OQ-1).
+ *
+ * Behavior:
+ *  - `opts.skip` (the `--skip-rauf` flag) ⇒ return `ok({ raufPin: null })` immediately, with NO
+ *    network call.
+ *  - otherwise ⇒ run a READ-ONLY registry resolvability check on `RAUF_PIN` (default query:
+ *    `npm view rauf@<pin> version`). No install, no global-npm mutation, no execution of rauf.
+ *      · resolvable  ⇒ return `ok({ raufPin: RAUF_PIN })` — the value the manifest records.
+ *      · unresolvable ⇒ return `err(<RAUF_UNRESOLVABLE>)` carrying the FIXED message (§6).
+ *
+ * NEVER throws for the expected unresolvable case — that is an `err(...)`. An unexpected spawn
+ * failure inside the default query is normalized to the same `RAUF_UNRESOLVABLE` error, so
+ * callers handle one code. Performs no filesystem write.
+ *
+ * @param opts - skip flag and/or an injected registry query (tests)
+ * @returns Result<{ raufPin: string | null }>:
+ *          ok + `raufPin: RAUF_PIN`  when resolvable,
+ *          ok + `raufPin: null`      when skipped,
+ *          err(RAUF_UNRESOLVABLE)    when the pin is not resolvable.
+ */
+export function preflightRauf(opts) {
+    // --skip-rauf: no network, record null.
+    if (opts?.skip) {
+        return ok({ raufPin: null });
+    }
+    const query = opts?.query ?? defaultRegistryQuery;
+    const resolved = query(RAUF_PIN);
+    if (resolved.ok) {
+        // Resolvable: record the pin. (We deliberately ignore the resolved version string — the
+        // recorded coordinate is RAUF_PIN itself, the single source of truth, REQ-RAUF-03.)
+        return ok({ raufPin: RAUF_PIN });
+    }
+    // Unresolvable: the designed failure mode (§6). Surface the FIXED, actionable error,
+    // regardless of any message the injected query returned.
+    return err(raufUnresolvableError());
+}
+/**
+ * Internal: the default read-only registry query. Runs `npm view <coordinate> version` via
+ * `node:child_process.spawnSync` — registry metadata read ONLY (no install, no global mutation,
+ * no rauf execution). Network is permitted at install (C-7).
+ *
+ * Resolution rule:
+ *  - exit code 0 AND non-empty stdout ⇒ ok(trimmed stdout) (the resolved version).
+ *  - anything else (non-zero exit, E404, a spawn error, npm absent) ⇒ err(RAUF_UNRESOLVABLE).
+ *
+ * NOT exported as public API — `preflightRauf`'s `query` option is the seam tests use.
+ */
+function defaultRegistryQuery(coordinate) {
+    let res;
+    try {
+        res = spawnSync("npm", ["view", coordinate, "version"], {
+            encoding: "utf8",
+            // No shell; argv form avoids injection. Timeout bounds a hung registry.
+            timeout: 30_000,
+            windowsHide: true,
+        });
+    }
+    catch {
+        // spawn itself threw (e.g. npm not found on some platforms) — treat as unresolvable.
+        return err(raufUnresolvableError());
+    }
+    if (res.error || res.status !== 0) {
+        return err(raufUnresolvableError());
+    }
+    const version = String(res.stdout ?? "").trim();
+    if (version.length === 0) {
+        return err(raufUnresolvableError());
+    }
+    return ok(version);
+}
+/**
+ * Internal: builds the structured RAUF_UNRESOLVABLE error with the FIXED message (§6,
+ * REQ-OBS-02). `<pin>` in the message is substituted with `RAUF_PIN`. Single constructor so the
+ * wording is identical everywhere the failure can arise (preflight + default query).
+ */
+function raufUnresolvableError() {
+    return {
+        code: "RAUF_UNRESOLVABLE",
+        message: "pinned default loop runner `" +
+            RAUF_PIN +
+            "` is not resolvable from the npm registry. Network is required at " +
+            "install; if rauf is not yet published this is the known cross-repo " +
+            "prerequisite (see packaging-docs-ci). Skills were still installed; " +
+            "the default loop will be unavailable until rauf publishes.",
+        remedy: "Ensure network access and that `" +
+            RAUF_PIN +
+            "` is published, or re-run with `--skip-rauf` to defer the default loop.",
+    };
+}