@garygentry/feature-forge 0.1.0

package/dist/fsutil.d.ts

@@ -0,0 +1,56 @@
+import type { Result } from "./types.js";
+/**
+ * Resolve `segs` against `root` and assert the result lies WITHIN `root` (REQ-SEC-02). Returns the
+ * resolved absolute path on success, or a PATH_ESCAPE InstallerError if a `..` segment or a
+ * malformed agent id would escape the agent config root. MUST be called before ANY write/delete.
+ *
+ * Uses `path.relative` + the `..` prefix test (the robust boundary check — a bare string startsWith
+ * would false-pass `/root-evil`).
+ *
+ * @param root - the containment boundary (the agent config root, e.g. <home>/.claude)
+ * @param segs - path segments to join under root (destination, then a bundle-relative path)
+ * @returns ok(absolutePath) if inside; err(PATH_ESCAPE) otherwise.
+ */
+export declare function resolveWithin(root: string, ...segs: string[]): Result<string>;
+/**
+ * Recursively copy `src` → `dest` (copy mode). The CALLER is responsible for having
+ * containment-checked `dest` via resolveWithin first (REQ-SEC-02).
+ *
+ * @returns ok(undefined) on success; err(WRITE_DENIED) on EACCES/EPERM, naming `dest`.
+ */
+export declare function copyDir(src: string, dest: string): Promise<Result<void>>;
+/**
+ * Link the whole namespace dir `linkPath` → `target` (REQ-FLAG-03). On Windows, OR if the symlink
+ * syscall fails for any reason, FALL BACK to copyDir and report it via the `mode` so apply records
+ * the truthful mode.
+ *
+ * @returns ok({ mode }) where mode is "symlink" (link created) or "copy" (fallback fired);
+ *          err(WRITE_DENIED) if even the copy fallback fails.
+ */
+export declare function symlinkDir(target: string, linkPath: string): Promise<Result<{
+    mode: "symlink" | "copy";
+}>>;
+/**
+ * Remove `p` safely (REQ-SEC-03/REQ-SAFE-02). NEVER follows a symlink to delete its target — uses
+ * `lstat` (which does not dereference) to distinguish a symbolic link (unlink the link only), a real
+ * directory (recursive rm), and a real file (unlink). ENOENT → ok (idempotent removal).
+ *
+ * The CALLER must have containment-checked `p` via resolveWithin first (REQ-SEC-02).
+ *
+ * @returns ok(undefined) on success or already-absent; err(WRITE_DENIED) on EACCES/EPERM.
+ */
+export declare function removePath(p: string): Promise<Result<void>>;
+/**
+ * Prune now-empty directories from `startDir` UPWARD, stopping before `stopRoot` (exclusive). Used by
+ * `apply`'s copy-mode uninstall (§5.3) after the recorded files are removed. NEVER removes a
+ * non-empty dir nor `stopRoot` itself (REQ-SAFE-01). A non-existent `cur` is treated as
+ * already-removed and the ascent continues.
+ *
+ * @param startDir - the deepest dir to consider pruning (e.g. the namespace dir).
+ * @param stopRoot - the boundary; pruning never removes `stopRoot` itself nor anything outside it.
+ * @returns ok(undefined) when the upward prune completes (or halts on a non-empty dir);
+ *          err(PATH_ESCAPE) if `startDir` is not within `stopRoot`; err(WRITE_DENIED) on EACCES/EPERM.
+ */
+export declare function removeEmptyDirsWithin(startDir: string, stopRoot: string): Promise<Result<void>>;
+/** Platform check (REQ-FLAG-03, C-6). Centralized so resolveMode/symlinkDir share one decision. */
+export declare function isWindows(): boolean;

package/dist/fsutil.js

@@ -0,0 +1,175 @@
+/**
+ * Sandboxed filesystem primitives (spec 04 §7). Every filesystem mutation in `apply` routes through
+ * these — they are the single place REQ-SEC-01/02/03 are enforced. Cross-platform: node:fs/promises,
+ * node:path, node:os only (no shelling out). No throw for expected errors — all return `Result`.
+ */
+import * as fsp from "node:fs/promises";
+import * as path from "node:path";
+import * as os from "node:os";
+import { ok, err } from "./types.js";
+/**
+ * Resolve `segs` against `root` and assert the result lies WITHIN `root` (REQ-SEC-02). Returns the
+ * resolved absolute path on success, or a PATH_ESCAPE InstallerError if a `..` segment or a
+ * malformed agent id would escape the agent config root. MUST be called before ANY write/delete.
+ *
+ * Uses `path.relative` + the `..` prefix test (the robust boundary check — a bare string startsWith
+ * would false-pass `/root-evil`).
+ *
+ * @param root - the containment boundary (the agent config root, e.g. <home>/.claude)
+ * @param segs - path segments to join under root (destination, then a bundle-relative path)
+ * @returns ok(absolutePath) if inside; err(PATH_ESCAPE) otherwise.
+ */
+export function resolveWithin(root, ...segs) {
+    const base = path.resolve(root);
+    const target = path.resolve(base, ...segs);
+    const rel = path.relative(base, target);
+    const inside = rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+    if (!inside) {
+        return err({
+            code: "PATH_ESCAPE",
+            message: `refusing to write outside the agent config root: resolved "${target}" escapes "${base}"`,
+            path: target,
+            remedy: "this indicates a malformed agent id or path segment; report it as a bug",
+        });
+    }
+    return ok(target);
+}
+/**
+ * Recursively copy `src` → `dest` (copy mode). The CALLER is responsible for having
+ * containment-checked `dest` via resolveWithin first (REQ-SEC-02).
+ *
+ * @returns ok(undefined) on success; err(WRITE_DENIED) on EACCES/EPERM, naming `dest`.
+ */
+export async function copyDir(src, dest) {
+    try {
+        await fsp.mkdir(path.dirname(dest), { recursive: true });
+        await fsp.cp(src, dest, { recursive: true, force: true, dereference: false });
+        return ok(undefined);
+    }
+    catch (e) {
+        return err(toWriteError(e, dest));
+    }
+}
+/**
+ * Link the whole namespace dir `linkPath` → `target` (REQ-FLAG-03). On Windows, OR if the symlink
+ * syscall fails for any reason, FALL BACK to copyDir and report it via the `mode` so apply records
+ * the truthful mode.
+ *
+ * @returns ok({ mode }) where mode is "symlink" (link created) or "copy" (fallback fired);
+ *          err(WRITE_DENIED) if even the copy fallback fails.
+ */
+export async function symlinkDir(target, linkPath) {
+    if (isWindows()) {
+        const copied = await copyDir(target, linkPath);
+        return copied.ok ? ok({ mode: "copy" }) : err(copied.error);
+    }
+    try {
+        await fsp.mkdir(path.dirname(linkPath), { recursive: true });
+        await fsp.symlink(target, linkPath, "dir");
+        return ok({ mode: "symlink" });
+    }
+    catch {
+        const copied = await copyDir(target, linkPath);
+        return copied.ok ? ok({ mode: "copy" }) : err(copied.error);
+    }
+}
+/**
+ * Remove `p` safely (REQ-SEC-03/REQ-SAFE-02). NEVER follows a symlink to delete its target — uses
+ * `lstat` (which does not dereference) to distinguish a symbolic link (unlink the link only), a real
+ * directory (recursive rm), and a real file (unlink). ENOENT → ok (idempotent removal).
+ *
+ * The CALLER must have containment-checked `p` via resolveWithin first (REQ-SEC-02).
+ *
+ * @returns ok(undefined) on success or already-absent; err(WRITE_DENIED) on EACCES/EPERM.
+ */
+export async function removePath(p) {
+    let st;
+    try {
+        st = await fsp.lstat(p); // lstat: does NOT dereference the link
+    }
+    catch (e) {
+        if (e.code === "ENOENT")
+            return ok(undefined);
+        return err(toWriteError(e, p));
+    }
+    try {
+        if (st.isSymbolicLink()) {
+            await fsp.unlink(p); // remove the LINK only — never the target (REQ-SAFE-02)
+        }
+        else if (st.isDirectory()) {
+            await fsp.rm(p, { recursive: true, force: true });
+        }
+        else {
+            await fsp.unlink(p);
+        }
+        return ok(undefined);
+    }
+    catch (e) {
+        return err(toWriteError(e, p));
+    }
+}
+/**
+ * Prune now-empty directories from `startDir` UPWARD, stopping before `stopRoot` (exclusive). Used by
+ * `apply`'s copy-mode uninstall (§5.3) after the recorded files are removed. NEVER removes a
+ * non-empty dir nor `stopRoot` itself (REQ-SAFE-01). A non-existent `cur` is treated as
+ * already-removed and the ascent continues.
+ *
+ * @param startDir - the deepest dir to consider pruning (e.g. the namespace dir).
+ * @param stopRoot - the boundary; pruning never removes `stopRoot` itself nor anything outside it.
+ * @returns ok(undefined) when the upward prune completes (or halts on a non-empty dir);
+ *          err(PATH_ESCAPE) if `startDir` is not within `stopRoot`; err(WRITE_DENIED) on EACCES/EPERM.
+ */
+export async function removeEmptyDirsWithin(startDir, stopRoot) {
+    const contained = resolveWithin(stopRoot, startDir);
+    if (!contained.ok)
+        return contained;
+    const stop = path.resolve(stopRoot);
+    let cur = contained.value;
+    while (cur !== stop && cur.startsWith(stop)) {
+        let entries;
+        try {
+            entries = await fsp.readdir(cur);
+        }
+        catch (e) {
+            if (e.code === "ENOENT") {
+                cur = path.dirname(cur);
+                continue;
+            }
+            return err(toWriteError(e, cur));
+        }
+        if (entries.length > 0)
+            break; // non-empty ⇒ MUST NOT remove (REQ-SAFE-01) — halt
+        try {
+            await fsp.rmdir(cur); // remove this now-empty dir only
+        }
+        catch (e) {
+            return err(toWriteError(e, cur));
+        }
+        cur = path.dirname(cur); // ascend
+    }
+    return ok(undefined);
+}
+/** Platform check (REQ-FLAG-03, C-6). Centralized so resolveMode/symlinkDir share one decision. */
+export function isWindows() {
+    return os.platform() === "win32";
+}
+/**
+ * Map a caught fs exception to an actionable InstallerError (REQ-OBS-02). EACCES/EPERM → WRITE_DENIED;
+ * anything else → UNEXPECTED carrying the message. Internal helper (not exported as public surface).
+ */
+function toWriteError(e, p) {
+    const code = e?.code;
+    if (code === "EACCES" || code === "EPERM") {
+        return {
+            code: "WRITE_DENIED",
+            message: `no write permission to ${p}`,
+            path: p,
+            remedy: "check directory permissions, or choose a different scope (--global vs project)",
+        };
+    }
+    return {
+        code: "UNEXPECTED",
+        message: `filesystem error at ${p}: ${e?.message ?? String(e)}`,
+        path: p,
+    };
+}

package/dist/hash.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Content hashing for the cross-agent installer (spec 03 §3.3-§3.6, OQ-4).
+ *
+ * Drift detection is decided by SHA-256 *content* hashing, NEVER mtime. The tree digest is a
+ * function of the set of `{ relativePosixPath, fileContentHash }` pairs only, so two
+ * materializations of the same bundle at different paths/times hash identically. Zero runtime
+ * dependencies — only `node:` built-ins.
+ */
+/**
+ * SHA-256 of a single file's bytes, hex-encoded (OQ-4 — content hash, never mtime).
+ *
+ * @param filePath - Absolute path to a regular file.
+ * @returns 64-char lowercase hex digest of the file's bytes.
+ * @throws Propagates the underlying node:fs error (ENOENT/EACCES) — an *unexpected* IO failure
+ *         for an already-located, integrity-checked bundle, caught at the operation boundary.
+ */
+export declare function sha256File(filePath: string): string;
+/**
+ * Deterministic SHA-256 over a directory tree's file set (OQ-4). The digest is a function of the
+ * set of `{ relativePosixPath, fileContentHash }` pairs ONLY — never of mtime, inode, or
+ * traversal order.
+ *
+ * Canonical form: walk regular files, compute POSIX-relative paths, sort byte-wise, then fold a
+ * single hash over `update(rel); update("\0"); update(contentHash); update("\n")` per file.
+ *
+ * @param dir - Absolute path to the directory whose tree to hash.
+ * @returns 64-char lowercase hex digest, invariant under relocation and traversal order.
+ */
+export declare function sha256Tree(dir: string): string;
+/**
+ * Compute the `sourceHash` stored in InstallManifest (spec 00 §3, spec 03 §3.4). It is exactly
+ * `sha256Tree(bundlePath)` — the sorted-path canonical digest over the bundle's file set, so two
+ * materializations of the same bundle produce the SAME hash (REQ-IDEM-01 basis).
+ *
+ * @param bundlePath - Absolute path to a *located, integrity-checked* bundle dir.
+ * @returns 64-char lowercase hex digest — store verbatim in `InstallManifest.sourceHash`.
+ */
+export declare function computeSourceHash(bundlePath: string): string;
+/**
+ * The bundle's per-file inventory: every regular file under `bundlePath`, each as its
+ * bundle-relative POSIX path plus the content `sha256`. Sorted by relative POSIX path — the SAME
+ * sorted walk `sha256Tree` folds over, so the inventory and `sourceHash` always agree.
+ *
+ * @param bundlePath - Absolute path to a located, integrity-checked bundle dir.
+ * @returns Array of `{ relpath, sha256 }`, sorted by `relpath` (POSIX `/` separators).
+ */
+export declare function listBundleFiles(bundlePath: string): Array<{
+    relpath: string;
+    sha256: string;
+}>;

package/dist/hash.js

@@ -0,0 +1,107 @@
+/**
+ * Content hashing for the cross-agent installer (spec 03 §3.3-§3.6, OQ-4).
+ *
+ * Drift detection is decided by SHA-256 *content* hashing, NEVER mtime. The tree digest is a
+ * function of the set of `{ relativePosixPath, fileContentHash }` pairs only, so two
+ * materializations of the same bundle at different paths/times hash identically. Zero runtime
+ * dependencies — only `node:` built-ins.
+ */
+import { createHash } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+/**
+ * SHA-256 of a single file's bytes, hex-encoded (OQ-4 — content hash, never mtime).
+ *
+ * @param filePath - Absolute path to a regular file.
+ * @returns 64-char lowercase hex digest of the file's bytes.
+ * @throws Propagates the underlying node:fs error (ENOENT/EACCES) — an *unexpected* IO failure
+ *         for an already-located, integrity-checked bundle, caught at the operation boundary.
+ */
+export function sha256File(filePath) {
+    const buf = fs.readFileSync(filePath);
+    return createHash("sha256").update(buf).digest("hex");
+}
+/**
+ * Deterministic SHA-256 over a directory tree's file set (OQ-4). The digest is a function of the
+ * set of `{ relativePosixPath, fileContentHash }` pairs ONLY — never of mtime, inode, or
+ * traversal order.
+ *
+ * Canonical form: walk regular files, compute POSIX-relative paths, sort byte-wise, then fold a
+ * single hash over `update(rel); update("\0"); update(contentHash); update("\n")` per file.
+ *
+ * @param dir - Absolute path to the directory whose tree to hash.
+ * @returns 64-char lowercase hex digest, invariant under relocation and traversal order.
+ */
+export function sha256Tree(dir) {
+    const files = walkFiles(dir);
+    const entries = files
+        .map((abs) => ({
+        rel: toPosix(path.relative(dir, abs)),
+        contentHash: sha256File(abs),
+    }))
+        .sort((a, b) => (a.rel < b.rel ? -1 : a.rel > b.rel ? 1 : 0));
+    const h = createHash("sha256");
+    for (const e of entries) {
+        h.update(e.rel);
+        h.update("\0");
+        h.update(e.contentHash);
+        h.update("\n");
+    }
+    return h.digest("hex");
+}
+/**
+ * Compute the `sourceHash` stored in InstallManifest (spec 00 §3, spec 03 §3.4). It is exactly
+ * `sha256Tree(bundlePath)` — the sorted-path canonical digest over the bundle's file set, so two
+ * materializations of the same bundle produce the SAME hash (REQ-IDEM-01 basis).
+ *
+ * @param bundlePath - Absolute path to a *located, integrity-checked* bundle dir.
+ * @returns 64-char lowercase hex digest — store verbatim in `InstallManifest.sourceHash`.
+ */
+export function computeSourceHash(bundlePath) {
+    return sha256Tree(bundlePath);
+}
+/**
+ * The bundle's per-file inventory: every regular file under `bundlePath`, each as its
+ * bundle-relative POSIX path plus the content `sha256`. Sorted by relative POSIX path — the SAME
+ * sorted walk `sha256Tree` folds over, so the inventory and `sourceHash` always agree.
+ *
+ * @param bundlePath - Absolute path to a located, integrity-checked bundle dir.
+ * @returns Array of `{ relpath, sha256 }`, sorted by `relpath` (POSIX `/` separators).
+ */
+export function listBundleFiles(bundlePath) {
+    const files = walkFiles(bundlePath);
+    return files
+        .map((abs) => ({
+        relpath: toPosix(path.relative(bundlePath, abs)),
+        sha256: sha256File(abs),
+    }))
+        .sort((a, b) => (a.relpath < b.relpath ? -1 : a.relpath > b.relpath ? 1 : 0));
+}
+// ---------------------------------------------------------------------------
+// Internal helpers (module-private — spec 03 §4.2)
+// ---------------------------------------------------------------------------
+/**
+ * Recursively collect every REGULAR FILE under `dir` (absolute paths). Directories contribute only
+ * via their files; symlink entries are NOT followed and NOT included. Order is unspecified —
+ * callers sort by relative path so traversal order never affects the digest.
+ */
+function walkFiles(dir) {
+    const out = [];
+    const stack = [dir];
+    while (stack.length > 0) {
+        const cur = stack.pop();
+        for (const ent of fs.readdirSync(cur, { withFileTypes: true })) {
+            const abs = path.join(cur, ent.name);
+            if (ent.isDirectory())
+                stack.push(abs);
+            else if (ent.isFile())
+                out.push(abs);
+            // symlinks / sockets / fifos: ignored (not expected in a copied bundle)
+        }
+    }
+    return out;
+}
+/** Normalize an OS-relative path to POSIX separators so hashes match across Windows and POSIX. */
+function toPosix(rel) {
+    return rel.split(path.sep).join("/");
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Library barrel (spec 01 §4): the public surface of the cross-agent installer as a Node
+ * library. Re-exports the agent-detection-map surface, the rauf pin, and the shared spec-00
+ * types. Named exports only; no runtime logic of its own.
+ */
+export { AGENT_TARGETS, resolveRoots, destinationFor, detectAgent, detectAgents, formatZeroDetection, } from "./agent-targets.js";
+export { RAUF_PIN } from "./rauf.js";
+export type { AgentId, AgentTarget, DetectionResult, ResolveOpts, Scope, Mode, InstallManifest, PlannedAction, RunReport, } from "./types.js";

package/dist/index.js

@@ -0,0 +1,9 @@
+/**
+ * Library barrel (spec 01 §4): the public surface of the cross-agent installer as a Node
+ * library. Re-exports the agent-detection-map surface, the rauf pin, and the shared spec-00
+ * types. Named exports only; no runtime logic of its own.
+ */
+// The agent-detection-map surface (spec 02).
+export { AGENT_TARGETS, resolveRoots, destinationFor, detectAgent, detectAgents, formatZeroDetection, } from "./agent-targets.js";
+// The pinned default loop-runner coordinate (spec 06).
+export { RAUF_PIN } from "./rauf.js";

package/dist/manifest.d.ts

@@ -0,0 +1,72 @@
+/**
+ * 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 { type AgentId, type InstallManifest, type ManifestFile, type Mode, type PlannedAction, type ResolveOpts, type Result, type Scope } from "./types.js";
+/**
+ * Inputs to {@link buildManifest}. The caller (apply.ts, spec 04) assembles this from the resolved
+ * detection target, the chosen scope/mode, and the apply result's per-file inventory.
+ */
+export interface BuildManifestArgs {
+    readonly agent: AgentId;
+    readonly scope: Scope;
+    readonly mode: Mode;
+    /** Absolute path of the `feature-forge/` namespace dir this manifest governs. */
+    readonly destination: string;
+    /**
+     * Per-file inventory of what was written, paths relative to `destination`. In `"symlink"` mode
+     * this is `[]` (no per-file copy exists). In `"copy"` mode each entry carries its `sha256`.
+     */
+    readonly files: readonly ManifestFile[];
+    /** Installed skill ids (the bundle's `skills/*` dir names). */
+    readonly skills: readonly string[];
+    /** SHA-256 over the source bundle's canonical (sorted-path) file set — drift anchor (spec 03). */
+    readonly sourceHash: string;
+    /** Recorded pinned rauf coordinate (e.g. "rauf@0.6.0"); `null` when `--skip-rauf` (spec 06). */
+    readonly raufPin: string | null;
+    /** Symlink mode only: the source bundle the namespace dir links to (REQ-SAFE-02). */
+    readonly link?: {
+        readonly target: string;
+    };
+    /** Prior manifest, if any. When present, its `installedAt` is preserved (this is an update). */
+    readonly previous?: InstallManifest | null;
+    /** Injectable clock for deterministic tests. Default: `() => new Date()`. */
+    readonly now?: () => Date;
+}
+/**
+ * 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 declare function buildManifest(args: BuildManifestArgs): InstallManifest;
+/**
+ * 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 declare function manifestPath(agent: AgentId, scope: Scope, opts?: Omit<ResolveOpts, "scope">): string;
+/**
+ * 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 declare function readManifest(p: string): Result<InstallManifest | null>;
+/**
+ * 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 declare function writeManifest(p: string, m: InstallManifest): Result<void>;
+/**
+ * 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 declare function planUninstall(manifest: InstallManifest): Result<PlannedAction>;