@garygentry/feature-forge 0.2.2 → 0.2.4

package/dist/apply.js

@@ -91,8 +91,9 @@ async function applyCopyInstall(planned, ctx) {
     if (!placementResult.ok)
         return fail(ctx, planned, placementResult.error);
     // No-op short-circuit (REQ-IDEM-01): every action — primary AND placement — unchanged ⇒ zero
-    // writes, manifest untouched.
-    if (allUnchanged(planned)) {
+    // writes, manifest untouched — UNLESS manifest metadata (raufPin) drifted, which must persist
+    // even with no file change (F1) so report / on-disk manifest / a later `list` agree.
+    if (allUnchanged(planned) && !manifestNeedsRewrite(ctx)) {
         return success(ctx, planned);
     }
     const manifest = buildManifest({
@@ -113,6 +114,18 @@ async function applyCopyInstall(planned, ctx) {
         return fail(ctx, planned, wrote.error);
     return success(ctx, planned);
 }
+/**
+ * True when manifest metadata diverges from the prior manifest, so the manifest must be rewritten
+ * even when every file action is "unchanged" (F1). Today the only such field is `raufPin`; a null
+ * prior manifest also counts (there is nothing recorded yet). `updatedAt` is deliberately NOT a
+ * trigger — it is a consequence of writing, so keying on it would defeat the idempotency short-circuit.
+ */
+function manifestNeedsRewrite(ctx) {
+    const prior = ctx.priorManifest;
+    if (prior === null)
+        return true;
+    return prior.raufPin !== ctx.raufPin;
+}
 /** True iff every planned action — primary files and all placement files — is "unchanged". */
 function allUnchanged(planned) {
     return (planned.files.every((f) => f.action === "unchanged") &&
@@ -164,8 +177,8 @@ async function applySymlinkInstall(planned, ctx) {
     const primary = planned.files;
     const primaryUntouched = primary.every((f) => f.action === "unchanged") ||
         primary.every((f) => f.action === "skip-modified");
-    // Nothing changed anywhere ⇒ zero writes, manifest untouched.
-    if (allUnchanged(planned)) {
+    // Nothing changed anywhere ⇒ zero writes, manifest untouched — unless raufPin drifted (F1).
+    if (allUnchanged(planned) && !manifestNeedsRewrite(ctx)) {
         return success(ctx, planned);
     }
     // The recorded mode/link reflect the primary namespace dir: only (re)link when it actually changed
@@ -285,12 +298,25 @@ async function applyMirror(pl, ctx, source, prior) {
             case "skip-modified": {
                 // Carry the prior record forward; if none exists (e.g. a v1→v2 manifest migration where the
                 // file is already on disk), reconstruct it by hashing the destination so the inventory stays
-                // faithful rather than silently dropping an unrecorded-but-present file.
+                // faithful rather than silently dropping an unrecorded-but-present file. Guard the hash: a
+                // TOCTOU vanish (file removed after planning) must yield an err Result, never throw ENOENT
+                // out of apply (REQ-OBS-03 — a throw would abort every sibling agent at the CLI boundary).
                 const p = priorByPath.get(fa.relpath);
-                if (p !== undefined)
+                if (p !== undefined) {
                     inventory.push(p);
-                else
-                    inventory.push({ path: fa.relpath, sha256: sha256File(destAbs) });
+                }
+                else {
+                    try {
+                        inventory.push({ path: fa.relpath, sha256: sha256File(destAbs) });
+                    }
+                    catch {
+                        return err({
+                            code: "UNEXPECTED",
+                            agent: ctx.agent,
+                            message: `mirror file "${fa.relpath}" vanished before it could be recorded (${destAbs})`,
+                        });
+                    }
+                }
                 break;
             }
         }

package/dist/cli.js

@@ -23,7 +23,8 @@ import { plan, resolveMode } from "./plan.js"; // 04
 import { apply } from "./apply.js"; // 04
 import { manifestPath, readManifest, planUninstall } from "./manifest.js"; // 05
 import { preflightRauf, RAUF_PIN } from "./rauf.js"; // 06
-import { sha256File } from "./hash.js"; // 03 (list destination-drift hashing)
+import { sha256File, sha256String } from "./hash.js"; // 03 (list destination-drift hashing)
+import { extractManagedRegion } from "./placements.js"; // A4b managed-block drift
 import { renderReport } from "./report.js"; // 09
 /** Canonical subcommand table (REQ-DIST-03, §1.2). */
 export const SUBCOMMANDS = [
@@ -424,12 +425,18 @@ function listOneAgent(agent, detection, flags, scope, env) {
 /**
  * Return `"true"` if any manifest-recorded file's on-disk bytes differ from its recorded sha256
  * (a locally-modified destination, REQ-SAFE-03), `"false"` if every recorded file matches, or
- * `"n/a(symlink)"` for a symlink-mode install (no per-file sha256 to compare). A missing recorded
- * file also counts as drift. Pure read of the manifest's per-file sha256 against a fresh local
- * hash — no network, no source bundle needed (REQ-PERF-01). Hash errors are swallowed as drift
+ * `"n/a(symlink)"` for a symlink-mode primary install (no per-file sha256 to compare). A missing
+ * recorded file also counts as drift. Pure read of the manifest's per-file sha256 against a fresh
+ * local hash — no network, no source bundle needed (REQ-PERF-01). Hash errors are swallowed as drift
  * (an unreadable recorded file is itself a deviation from the clean install).
+ *
+ * Secondary placements (A4b) are checked in EVERY mode — they are always copy-written with a recorded
+ * hash even when the primary namespace is a symlink, so ignoring them (the prior behavior) left codex
+ * `.toml` mirrors and copilot managed blocks unwatched for drift.
  */
 function detectDestinationDrift(manifest) {
+    if (detectPlacementDrift(manifest))
+        return "true";
     if (manifest.mode === "symlink")
         return "n/a(symlink)";
     for (const f of manifest.files) {
@@ -445,6 +452,35 @@ function detectDestinationDrift(manifest) {
     }
     return "false";
 }
+/**
+ * True iff any secondary placement diverges from its recorded hash. A "mirror" file drifts when its
+ * on-disk bytes differ from the recorded sha256 (destination is a DIR, paths relative to it). A
+ * "managed-block" drifts when the sentinel region extracted from the (user-owned) target FILE no
+ * longer hashes to the recorded region hash — or the region is gone entirely. Read errors count as
+ * drift, matching the primary check.
+ */
+function detectPlacementDrift(manifest) {
+    for (const p of manifest.placements ?? []) {
+        for (const f of p.files) {
+            if (f.sha256 === undefined)
+                continue;
+            try {
+                if (p.kind === "managed-block") {
+                    const region = extractManagedRegion(readFileSync(p.destination, "utf8"));
+                    if (region === null || sha256String(region) !== f.sha256)
+                        return true;
+                }
+                else if (sha256File(path.join(p.destination, f.path)) !== f.sha256) {
+                    return true;
+                }
+            }
+            catch {
+                return true; // unreadable/absent recorded placement ⇒ drift
+            }
+        }
+    }
+    return false;
+}
 // ---------------------------------------------------------------------------
 // 7. helpText and --version (§3.4)
 // ---------------------------------------------------------------------------

package/dist/fsutil.d.ts

@@ -1,16 +1,4 @@
 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

package/dist/fsutil.js

@@ -19,6 +19,12 @@ import { ok, err } from "./types.js";
  * @param segs - path segments to join under root (destination, then a bundle-relative path)
  * @returns ok(absolutePath) if inside; err(PATH_ESCAPE) otherwise.
  */
+/** True iff `child` is strictly within `parent` (path.relative + `..`-prefix test, never a bare
+ *  `startsWith`). Shares the boundary logic of {@link resolveWithin} for a plain boolean check. */
+function isWithin(parent, child) {
+    const rel = path.relative(parent, child);
+    return rel !== "" && !rel.startsWith("..") && !path.isAbsolute(rel);
+}
 export function resolveWithin(root, ...segs) {
     const base = path.resolve(root);
     const target = path.resolve(base, ...segs);
@@ -125,7 +131,10 @@ export async function removeEmptyDirsWithin(startDir, stopRoot) {
         return contained;
     const stop = path.resolve(stopRoot);
     let cur = contained.value;
-    while (cur !== stop && cur.startsWith(stop)) {
+    // Robust boundary test (path.relative + `..` prefix), not a bare `cur.startsWith(stop)` — the
+    // exact anti-pattern this module warns against at the top: `startsWith` false-passes a sibling
+    // like `<stop>-evil`. Safe here by the ancestor invariant today, but don't rely on it.
+    while (cur !== stop && isWithin(stop, cur)) {
         let entries;
         try {
             entries = await fsp.readdir(cur);

package/dist/manifest.d.ts

@@ -28,7 +28,7 @@ export interface BuildManifestArgs {
     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. "@garygentry/rauf@0.10.1"); `null` when `--skip-rauf` (spec 06). */
+    /** Recorded pinned rauf coordinate (e.g. "@garygentry/rauf@0.12.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?: {

package/dist/plan.js

@@ -220,8 +220,16 @@ 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
+    const manifestSaysLive = priorExists && prior.link?.target === source.root;
+    // The manifest can claim a live symlink that no longer exists on disk (deleted, or clobbered by a
+    // regular file/dir). Copy mode self-heals via per-file hashing; symlink mode had no on-disk check
+    // and would classify a broken link "unchanged" forever. lstat the link and force a relink when the
+    // manifest says live but the link is absent/not-a-symlink (F2) — never "skip-modified", which apply
+    // treats as untouched and would leave the install broken.
+    if (manifestSaysLive && !isLiveSymlink(ctx.destination)) {
+        return [{ relpath: ".", action: "create" }];
+    }
+    const action = manifestSaysLive
         ? "unchanged"
         : priorExists
             ? ctx.force
@@ -230,6 +238,18 @@ function planSymlink(ctx) {
             : "create";
     return [{ relpath: ".", action }];
 }
+/**
+ * True iff `absPath` exists and is currently a symbolic link. `lstat`, not `readlink` — we only need
+ * the node type to decide whether a manifest-recorded symlink is still live (F2). Absent ⇒ false.
+ */
+function isLiveSymlink(absPath) {
+    try {
+        return fs.lstatSync(absPath).isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+}
 /** 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));

package/dist/rauf.d.ts

@@ -19,13 +19,13 @@ import { type Result } from "./types.js";
  *
  * Shape: `<name>@<version>` — the SCOPED package `@garygentry/rauf` (the unscoped `rauf` name is
  * blocked by npm's similarity filter). Advanced on each feature-forge release to a new
- * known-compatible rauf (REQ-RAUF-03). The current rauf version is 0.10.1.
+ * known-compatible rauf (REQ-RAUF-03). The current rauf version is 0.12.0.
  *
- * rauf is now PUBLISHED (rauf#28): `@garygentry/rauf@0.10.1` resolves from the npm registry, so the
+ * rauf is now PUBLISHED (rauf#28): `@garygentry/rauf@0.12.0` resolves from the npm registry, so the
  * preflight below passes by default. (Historically this pin pointed at an unpublished package and
  * the preflight was a designed-to-fail check — see the `--skip-rauf` escape hatch.)
  */
-export declare const RAUF_PIN = "@garygentry/rauf@0.10.1";
+export declare const RAUF_PIN = "@garygentry/rauf@0.12.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.
@@ -37,7 +37,7 @@ export declare const RAUF_PIN = "@garygentry/rauf@0.10.1";
  * 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. "@garygentry/rauf@0.10.1"
+ * @param coordinate - the `name@version` to resolve, e.g. "@garygentry/rauf@0.12.0"
  * @returns Result<string> — the resolved version on success; RAUF_UNRESOLVABLE on failure.
  */
 export type RegistryQuery = (coordinate: string) => Result<string>;

package/dist/rauf.js

@@ -20,13 +20,13 @@ import { err, ok } from "./types.js";
  *
  * Shape: `<name>@<version>` — the SCOPED package `@garygentry/rauf` (the unscoped `rauf` name is
  * blocked by npm's similarity filter). Advanced on each feature-forge release to a new
- * known-compatible rauf (REQ-RAUF-03). The current rauf version is 0.10.1.
+ * known-compatible rauf (REQ-RAUF-03). The current rauf version is 0.12.0.
  *
- * rauf is now PUBLISHED (rauf#28): `@garygentry/rauf@0.10.1` resolves from the npm registry, so the
+ * rauf is now PUBLISHED (rauf#28): `@garygentry/rauf@0.12.0` resolves from the npm registry, so the
  * preflight below passes by default. (Historically this pin pointed at an unpublished package and
  * the preflight was a designed-to-fail check — see the `--skip-rauf` escape hatch.)
  */
-export const RAUF_PIN = "@garygentry/rauf@0.10.1";
+export const RAUF_PIN = "@garygentry/rauf@0.12.0";
 /**
  * Resolvability preflight for the pinned default loop runner (D1; REQ-RAUF-01/02/03, OQ-1).
  *

package/dist/report.js

@@ -126,6 +126,6 @@ const DEFAULT_REMEDY = {
     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",
+    RAUF_UNRESOLVABLE: "could not resolve the rauf loop runner (a network/registry hiccup or an unmet version pin) — skills were still installed; retry, or install rauf manually",
     MANIFEST_CORRUPT: "remove the corrupt .feature-forge.<scope>.json and re-run install",
 };

package/dist/types.d.ts

@@ -216,7 +216,7 @@ export interface InstallManifest {
     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. "@garygentry/rauf@0.10.1"; `null` if `--skip-rauf` (spec 06). */
+    /** Pinned rauf coordinate recorded at install, e.g. "@garygentry/rauf@0.12.0"; `null` if `--skip-rauf` (spec 06). */
     readonly raufPin: string | null;
     /** ISO-8601 timestamps. */
     readonly installedAt: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@garygentry/feature-forge",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "Cross-agent installer for the feature-forge skill suite — installs the canonical forge pipeline into Claude, Codex, Copilot, Cursor, or Gemini.",
   "license": "MIT",
   "type": "module",