@davesheffer/hunch 1.8.3 → 1.9.2

package/dist/core/io.js

@@ -1,15 +1,18 @@
 /** Durable file writes for the Hunch. */
-import { writeFileSync, renameSync, rmSync } from "node:fs";
+import { linkSync, writeFileSync, renameSync, rmSync } from "node:fs";
 let counter = 0;
+const renameRetryDelaysMs = [10, 20, 40, 80];
+const renameRetryWaiter = new Int32Array(new SharedArrayBuffer(Int32Array.BYTES_PER_ELEMENT));
 /**
  * Write `data` to `file` via a temp file + rename, so an interrupted write can't
  * leave the target truncated (the symbols/edges index is the worst to half-write).
  *
  * Windows caveat: renameSync can't REPLACE a file another process holds open (even
  * for read) — it throws EPERM/EBUSY/EACCES, exactly when the MCP server is reading
- * while a CLI writes. Atomicity is crash-safety insurance, not worth FAILING a write
- * the old in-place writeFileSync would have completed — so we fall back to a direct
- * write there. The temp file is always cleaned up; a failed write never leaks it.
+ * while a CLI writes. Retry that atomic replacement with bounded backoff. If the
+ * contention persists, fail with the old target untouched; never trade availability
+ * for a direct write that an interruption could truncate. Failed writes clean up the
+ * temporary file.
  */
 export function writeFileAtomic(file, data) {
     const tmp = `${file}.tmp${process.pid}.${counter++}`;
@@ -21,16 +24,48 @@ export function writeFileAtomic(file, data) {
         throw e;
     }
     try {
-        renameSync(tmp, file);
+        renameWithContentionRetry(tmp, file);
     }
     catch (e) {
         safeRm(tmp);
-        const code = e.code;
-        if (code === "EPERM" || code === "EBUSY" || code === "EACCES") {
-            writeFileSync(file, data); // non-atomic fallback (matches pre-hardening behavior)
+        throw e;
+    }
+}
+function renameWithContentionRetry(from, to) {
+    for (let attempt = 0;; attempt++) {
+        try {
+            renameSync(from, to);
             return;
         }
-        throw e;
+        catch (error) {
+            const delayMs = renameRetryDelaysMs[attempt];
+            if (delayMs === undefined || !isRenameContention(error))
+                throw error;
+            Atomics.wait(renameRetryWaiter, 0, 0, delayMs);
+        }
+    }
+}
+function isRenameContention(error) {
+    const code = error.code;
+    return code === "EPERM" || code === "EBUSY" || code === "EACCES";
+}
+/** Atomically create a complete file only when no target exists. A same-dir
+ * hard link publishes the fully written temp inode with create-if-absent
+ * semantics, so concurrent lifecycle writers can never be overwritten. */
+export function writeFileAtomicIfAbsent(file, data) {
+    const tmp = `${file}.tmp${process.pid}.${counter++}`;
+    try {
+        writeFileSync(tmp, data);
+        linkSync(tmp, file);
+        return true;
+    }
+    catch (error) {
+        if (error.code === "EEXIST")
+            return false;
+        throw error;
+    }
+    finally {
+        safeRm(tmp);
     }
 }
 function safeRm(p) {

package/dist/core/overlaySafety.js

@@ -0,0 +1,178 @@
+import { existsSync, lstatSync, readdirSync, realpathSync } from "node:fs";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import { ENTITY_KINDS } from "./types.js";
+function pathIsWithin(path, parent) {
+    const rel = relative(parent, path);
+    return rel === "" || (rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel));
+}
+/** Validate the materialized overlay without following links. Git's metadata is
+ * deliberately skipped, but its own directory must still be contained under the
+ * canonical overlay root. Every remotely controlled entry must be an ordinary
+ * file or real directory whose canonical path stays inside that root. */
+export function safeOverlayTree(root) {
+    try {
+        const lexicalRoot = resolve(root);
+        const rootStat = lstatSync(lexicalRoot);
+        if (rootStat.isSymbolicLink() || !rootStat.isDirectory())
+            return false;
+        const canonicalRoot = realpathSync(lexicalRoot);
+        const walk = (dir, topLevel = false) => {
+            const dirStat = lstatSync(dir);
+            if (dirStat.isSymbolicLink() || !dirStat.isDirectory())
+                return false;
+            if (!pathIsWithin(realpathSync(dir), canonicalRoot))
+                return false;
+            for (const name of readdirSync(dir)) {
+                const entry = join(dir, name);
+                const stat = lstatSync(entry);
+                if (stat.isSymbolicLink())
+                    return false;
+                if (!pathIsWithin(realpathSync(entry), canonicalRoot))
+                    return false;
+                if (topLevel && (name === ".gitignore" || name === ".gitattributes")
+                    && (!stat.isFile() || stat.nlink !== 1))
+                    return false;
+                if (topLevel && name === ".hunch" && !stat.isDirectory())
+                    return false;
+                if (topLevel && name === ".git") {
+                    if (!stat.isDirectory())
+                        return false;
+                    continue;
+                }
+                if (stat.isDirectory()) {
+                    if (!walk(entry))
+                        return false;
+                }
+                else if (!stat.isFile()) {
+                    return false;
+                }
+            }
+            return true;
+        };
+        if (!walk(lexicalRoot, true))
+            return false;
+        const hunchDir = join(lexicalRoot, ".hunch");
+        if (existsSync(hunchDir)) {
+            for (const kind of ENTITY_KINDS) {
+                const kindDir = join(hunchDir, kind);
+                if (existsSync(kindDir) && !lstatSync(kindDir).isDirectory())
+                    return false;
+            }
+            for (const name of ["manifest.json", "config.json"]) {
+                const file = join(hunchDir, name);
+                if (existsSync(file) && !lstatSync(file).isFile())
+                    return false;
+            }
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Validate `git ls-tree -r -t -z <exact-oid>` output before checkout. A Git
+ * remote can encode symlinks (120000) and gitlinks (160000); accepting only
+ * ordinary blobs and trees makes the fetched object graph safe to materialize.
+ * The explicit Hunch topology rules keep canonical record directories and
+ * capability/config paths from changing shape on a later pull. */
+export function safeOverlayGitTreeListing(listing) {
+    const entries = new Map();
+    for (const row of listing.split("\0")) {
+        if (!row)
+            continue;
+        const tab = row.indexOf("\t");
+        if (tab <= 0)
+            return false;
+        const header = row.slice(0, tab).match(/^([0-7]{6}) (blob|tree|commit) ([0-9a-f]+)$/);
+        if (!header)
+            return false;
+        const path = row.slice(tab + 1);
+        const segments = path.split("/");
+        if (!path || path.startsWith("/") || path.includes("\\")
+            || segments.some((segment) => !segment || segment === "." || segment === ".."
+                || segment.toLowerCase() === ".git" || segment === ".hunch-commit.lock")) {
+            return false;
+        }
+        // These are clone-local/derived runtime artifacts, never graph source of
+        // truth. Accepting a tracked pointer can disclose or redirect a machine's
+        // private store; tracked SQLite/temp/cache artifacts poison the clean-tree
+        // and additive-publication contracts on every later request.
+        if (path === ".hunch/local.json"
+            || path === ".hunch-cache" || path.startsWith(".hunch-cache/")
+            || /^\.hunch\/[^/]+\.sqlite[^/]*$/i.test(path)
+            || (path.startsWith(".hunch/") && segments.slice(1).some((segment) => segment.includes(".tmp")))) {
+            return false;
+        }
+        const mode = header[1];
+        const type = header[2];
+        const ordinaryTree = mode === "040000" && type === "tree";
+        const ordinaryBlob = (mode === "100644" || mode === "100755") && type === "blob";
+        if (!ordinaryTree && !ordinaryBlob)
+            return false;
+        if (entries.has(path))
+            return false;
+        entries.set(path, type);
+    }
+    const isTree = (path) => !entries.has(path) || entries.get(path) === "tree";
+    const isBlob = (path) => !entries.has(path) || entries.get(path) === "blob";
+    if (!isTree(".hunch"))
+        return false;
+    for (const kind of ENTITY_KINDS)
+        if (!isTree(`.hunch/${kind}`))
+            return false;
+    for (const path of [".gitattributes", ".gitignore", ".hunch/manifest.json", ".hunch/config.json"]) {
+        if (!isBlob(path))
+            return false;
+    }
+    return true;
+}
+/** A dedicated Hunch overlay needs exactly one attribute capability: selecting
+ * the locally installed `merge=hunch` JSON merge driver, plus Hunch's exact
+ * `.hunch/manifest.json merge=text` override (the manifest has no record id and
+ * must use Git's built-in text merge). Reject every other token/pattern pair,
+ * including byte-transforming built-ins such as `ident` and
+ * `working-tree-encoding`, rather than maintaining a command-key blacklist.
+ * Blank lines and comments remain harmless. */
+export function hunchAttributesAreSafe(content) {
+    for (const line of content.split(/\r?\n/)) {
+        const candidate = line.trimStart();
+        if (!candidate || candidate.startsWith("#"))
+            continue;
+        const fields = candidate.split(/\s+/);
+        if (fields.length < 2)
+            return false;
+        const attributes = fields.slice(1);
+        if (attributes.every((attribute) => attribute === "merge=hunch"))
+            continue;
+        if (fields[0] === ".hunch/manifest.json"
+            && attributes.every((attribute) => attribute === "merge=text"))
+            continue;
+        return false;
+    }
+    return true;
+}
+/** Validate every committed .gitattributes blob in an already-safe ls-tree
+ * listing. Blob loading is injected so clone and later-pull seams share one
+ * parser without either trusting worktree bytes before materialization. */
+export function hunchTreeAttributesAreSafe(listing, readBlob) {
+    if (!safeOverlayGitTreeListing(listing))
+        return false;
+    for (const row of listing.split("\0")) {
+        if (!row)
+            continue;
+        const tab = row.indexOf("\t");
+        if (tab < 1)
+            return false;
+        const header = row.slice(0, tab).match(/^100(?:644|755) blob ([0-9a-f]{40,64})$/i);
+        const path = row.slice(tab + 1);
+        if (path !== ".gitattributes" && !path.endsWith("/.gitattributes"))
+            continue;
+        if (!header)
+            return false;
+        const content = readBlob(header[1]);
+        if (content === null || !hunchAttributesAreSafe(content))
+            return false;
+    }
+    return true;
+}
+//# sourceMappingURL=overlaySafety.js.map

package/dist/core/paths.js

@@ -1,6 +1,6 @@
 /** Filesystem layout for the Hunch (DESIGN.md §6 folder structure). */
 import { join } from "node:path";
-import { existsSync, statSync } from "node:fs";
+import { existsSync, realpathSync, statSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 export const HUNCH_DIR = ".hunch";
 /** Canonicalize a free-form path/target to repo-relative POSIX form. Hunch stores
@@ -27,7 +27,18 @@ export function hunchPaths(root) {
  *  PRIVATE overlay store (HUNCH_PRIVATE_DIR), which lives in a separate repo the
  *  user controls rather than under the current repo's `.hunch/`. */
 export function hunchPathsForDir(hunchDir) {
-    const hunch = resolve(hunchDir);
+    const lexical = resolve(hunchDir);
+    // An explicitly configured PRIVATE overlay may intentionally be a
+    // final-component symlink to a distinct physical repository. Resolve that
+    // user-selected root before handing it to JsonStore; public hunchPaths()
+    // deliberately does not do this, so a committed public `.hunch` symlink and
+    // every kind/record symlink remain fail-closed.
+    let hunch = lexical;
+    try {
+        if (statSync(lexical).isDirectory())
+            hunch = realpathSync(lexical);
+    }
+    catch { /* missing overlay root is created at the lexical location */ }
     return {
         root: dirname(hunch),
         hunch,

package/dist/core/safeRepoFile.js

@@ -0,0 +1,74 @@
+import { closeSync, constants, fstatSync, lstatSync, openSync, readSync, realpathSync, } from "node:fs";
+import { isAbsolute, relative, resolve, sep } from "node:path";
+/** Automatic repository scans are a convenience boundary, not a license to
+ * materialize arbitrarily large tracked blobs in memory. Eight MiB is well
+ * above ordinary source-file sizes while keeping one malicious/generated file
+ * from becoming an unbounded descriptor read. */
+export const MAX_REPO_SOURCE_FILE_BYTES = 8 * 1024 * 1024;
+/** Build a no-follow reader for automatic repository scanners. A Git-tracked
+ * symlink still appears in `git ls-files`; following it can copy host data into
+ * generated memory or reports. This reader accepts only one unchanged regular
+ * file beneath the canonical repository root and reads through the descriptor
+ * whose identity was checked. */
+export function createRepoFileBufferReader(root, options = {}) {
+    const lexicalRoot = resolve(root);
+    const canonicalRoot = realpathSync(lexicalRoot);
+    const maxBytes = options.maxBytes ?? MAX_REPO_SOURCE_FILE_BYTES;
+    if (!Number.isSafeInteger(maxBytes) || maxBytes < 0) {
+        throw new RangeError("maxBytes must be a non-negative safe integer");
+    }
+    return (file) => {
+        let descriptor;
+        try {
+            const target = isAbsolute(file) ? resolve(file) : resolve(lexicalRoot, file);
+            const lexicalRelative = relative(lexicalRoot, target);
+            if (!lexicalRelative || lexicalRelative === ".." || lexicalRelative.startsWith(`..${sep}`) || isAbsolute(lexicalRelative))
+                return null;
+            const before = lstatSync(target);
+            if (!before.isFile() || before.isSymbolicLink())
+                return null;
+            const canonicalTarget = realpathSync(target);
+            const canonicalRelative = relative(canonicalRoot, canonicalTarget);
+            if (!canonicalRelative || canonicalRelative === ".." || canonicalRelative.startsWith(`..${sep}`) || isAbsolute(canonicalRelative)
+                || canonicalTarget !== resolve(canonicalRoot, lexicalRelative)) {
+                return null;
+            }
+            descriptor = openSync(target, constants.O_RDONLY | constants.O_NOFOLLOW);
+            const opened = fstatSync(descriptor);
+            const after = lstatSync(target);
+            if (!opened.isFile() || !after.isFile() || after.isSymbolicLink()
+                || opened.size > maxBytes
+                || opened.dev !== before.dev || opened.ino !== before.ino
+                || after.dev !== opened.dev || after.ino !== opened.ino
+                || realpathSync(target) !== canonicalTarget) {
+                return null;
+            }
+            // Read exactly the size that passed fstat. readFileSync(fd) reads to EOF,
+            // so an in-place grow after the check could otherwise defeat the ceiling.
+            const bytes = Buffer.allocUnsafe(opened.size);
+            let offset = 0;
+            while (offset < bytes.length) {
+                const read = readSync(descriptor, bytes, offset, bytes.length - offset, offset);
+                if (read === 0)
+                    break;
+                offset += read;
+            }
+            return bytes.subarray(0, offset);
+        }
+        catch {
+            return null;
+        }
+        finally {
+            if (descriptor !== undefined)
+                closeSync(descriptor);
+        }
+    };
+}
+/** Text facade for parsers and legacy callers. Security-sensitive identities
+ * should hash the raw bytes returned by createRepoFileBufferReader first, since
+ * distinct invalid UTF-8 sequences can decode to the same replacement text. */
+export function createRepoFileReader(root, options = {}) {
+    const read = createRepoFileBufferReader(root, options);
+    return (file) => read(file)?.toString("utf8") ?? null;
+}
+//# sourceMappingURL=safeRepoFile.js.map

package/dist/extractors/comments.js

@@ -7,10 +7,11 @@
  * <!--, ;) so a matching STRING literal in code isn't mistaken for intent. (Line-based,
  * so a tagged line that is itself a string literal can still false-positive — advisory.)
  */
-import { readFileSync, readdirSync } from "node:fs";
+import { readdirSync } from "node:fs";
 import { join } from "node:path";
 import { trackedFiles } from "./git.js";
 import { toPosixTarget } from "../core/paths.js";
+import { createRepoFileReader } from "../core/safeRepoFile.js";
 const EXTS = [
     ".ts", ".tsx", ".mts", ".cts", ".js", ".jsx", ".mjs", ".cjs",
     ".py", ".go", ".rb", ".java", ".rs", ".php", ".cs", ".kt", ".swift", ".scala",
@@ -42,7 +43,7 @@ function sourceFiles(root) {
                 if (!SKIP.has(e.name))
                     walk(join(dir, e.name), r, depth + 1);
             }
-            else if (EXTS.some((x) => e.name.endsWith(x))) {
+            else if (e.isFile() && EXTS.some((x) => e.name.endsWith(x))) {
                 out.push(r);
             }
         }
@@ -52,14 +53,11 @@ function sourceFiles(root) {
 }
 export function extractInlineIntent(root) {
     const out = [];
+    const readSourceFile = createRepoFileReader(root);
     for (const rel of sourceFiles(root)) {
-        let content;
-        try {
-            content = readFileSync(join(root, rel), "utf8");
-        }
-        catch {
+        const content = readSourceFile(rel);
+        if (content === null)
             continue;
-        }
         if (!content.includes("hunch-"))
             continue; // cheap skip before the per-line scan
         const file = toPosixTarget(rel);