@davesheffer/hunch 1.39.0 → 1.39.2

package/dist/integrations/gitignore.js

@@ -7,11 +7,15 @@
  * index is ignored.
  *
  * Idempotent + merge-safe (con_8460b6770f): appends a single marked block and
- * never rewrites the user's existing entries; re-running is a no-op.
+ * never rewrites the user's existing entries. Once the block exists, re-running
+ * brings ONLY the content between its markers up to the current entry list (so a
+ * block written by an older release gains entries added later) and is otherwise
+ * byte-identical; everything outside the markers is left untouched.
  */
 import { readFileSync, existsSync, lstatSync, realpathSync } from "node:fs";
 import { isAbsolute, join, relative, resolve, sep } from "node:path";
 import { writeFileAtomic } from "../core/io.js";
+import { gitTrackedPaths, gitUntrackCached, isGitRepoRoot } from "../extractors/git.js";
 const MARK = "# >>> hunch (derived runtime index — regenerable from .hunch/*.json) >>>";
 const END = "# <<< hunch <<<";
 const ENTRIES = [
@@ -45,11 +49,16 @@ const ENTRIES = [
 // re-touch the block above, and so the two concerns read clearly in the file.
 const MEM_MARK = "# >>> hunch private-only (engineering memory kept in a private overlay; not published here) >>>";
 const MEM_END = "# <<< hunch private-only <<<";
+// Every ENTITY_KINDS directory (src/core/types.ts) must be listed here — guarded by
+// test/gitignore.test.ts — plus the non-entity Constitution/ledger directories.
 const MEM_ENTRIES = [
     ".hunch/decisions/",
     ".hunch/bugs/",
     ".hunch/constraints/",
     ".hunch/components/",
+    ".hunch/resources/",
+    ".hunch/conventions/",
+    ".hunch/workspaces/",
     ".hunch/evidence/",
     ".hunch/corpora/",
     ".hunch/policies/",
@@ -107,33 +116,71 @@ export function assertSafeTopLevelConfigFile(root, name) {
     }
     return path;
 }
-/** Idempotent + merge-safe append of one marked block (con_8460b6770f): never
- *  rewrites the user's existing entries, and re-running is a no-op once the block
- *  (or an equivalent hand-written set of the same patterns) is present. */
-function appendBlock(root, mark, entries, end) {
+const cleanLine = (line) => line.replace(/\r$/, "").trim();
+/** Locate a managed block as whole lines: the marker line and the FIRST end-marker
+ *  line after it. `null` when either is missing — a hand-damaged block is never
+ *  guessed at (con_8460b6770f). Indices are into `text.split("\n")`, whose items
+ *  keep a trailing `\r` in a CRLF file. */
+function findBlock(lines, mark, end) {
+    const start = lines.findIndex((l) => cleanLine(l) === mark);
+    if (start < 0)
+        return null;
+    const stop = lines.findIndex((l, i) => i > start && cleanLine(l) === end);
+    if (stop < 0)
+        return null;
+    return { start, end: stop, inner: lines.slice(start + 1, stop).map(cleanLine).filter(Boolean) };
+}
+/** Rewrite ONLY the lines between an existing block's markers to the current entry
+ *  list, keeping the file's line-ending style and every byte outside the markers.
+ *  No write (byte-identical) when the block is already current. */
+function upgradeBlock(root, path, cur, mark, entries, end) {
+    const lines = cur.split("\n");
+    const span = findBlock(lines, mark, end);
+    if (!span)
+        return { path, action: "unchanged", added: [] };
+    const cr = lines[span.start].endsWith("\r") ? "\r" : "";
+    const endCr = lines[span.end].endsWith("\r") ? "\r" : "";
+    const replacement = [mark + cr, ...entries.map((e) => e + cr), end + endCr];
+    const next = [...lines.slice(0, span.start), ...replacement, ...lines.slice(span.end + 1)].join("\n");
+    if (next === cur)
+        return { path, action: "unchanged", added: [] };
+    const had = new Set(span.inner);
+    assertSafeTopLevelConfigFile(root, ".gitignore");
+    writeFileAtomic(path, next);
+    return { path, action: "updated", added: entries.filter((e) => !had.has(e)) };
+}
+/** Idempotent + merge-safe write of one marked block (con_8460b6770f): never
+ *  rewrites the user's entries outside the markers. A present block is upgraded in
+ *  place to the current entry list; an absent one is appended unless the user's own
+ *  lines already cover every entry. Re-running on a current file is a no-op. */
+function appendBlock(root, mark, entries, end, upgrade = true) {
     const path = assertSafeTopLevelConfigFile(root, ".gitignore");
-    const block = [mark, ...entries, end].join("\n");
     if (!existsSync(path)) {
         assertSafeTopLevelConfigFile(root, ".gitignore");
-        writeFileAtomic(path, block + "\n");
-        return { path, action: "created" };
+        writeFileAtomic(path, [mark, ...entries, end].join("\n") + "\n");
+        return { path, action: "created", added: [...entries] };
     }
     const cur = readFileSync(path, "utf8");
-    if (cur.includes(mark))
-        return { path, action: "unchanged" }; // already managed
+    if (cur.includes(mark)) { // already managed
+        return upgrade ? upgradeBlock(root, path, cur, mark, entries, end) : { path, action: "unchanged", added: [] };
+    }
     // Already covered by the user's OWN entries (e.g. a hand-written, commented
     // section listing the same patterns)? Don't append a redundant managed block —
     // that would leave two copies of every ignore. Keep the .gitignore clean.
-    const lines = new Set(cur.split("\n").map((l) => l.trim()));
+    const lines = new Set(cur.split("\n").map(cleanLine));
     if (entries.every((e) => lines.has(e)))
-        return { path, action: "unchanged" };
-    const sep = cur.endsWith("\n") || cur.length === 0 ? "" : "\n";
+        return { path, action: "unchanged", added: [] };
+    const eol = cur.includes("\r\n") ? "\r\n" : "\n";
+    const gap = cur.endsWith("\n") || cur.length === 0 ? "" : eol;
     assertSafeTopLevelConfigFile(root, ".gitignore");
-    writeFileAtomic(path, `${cur}${sep}${block}\n`);
-    return { path, action: "appended" };
+    writeFileAtomic(path, `${cur}${gap}${[mark, ...entries, end].join(eol)}${eol}`);
+    return { path, action: "appended", added: [...entries] };
 }
-export function ensureGitignore(root) {
-    return appendBlock(root, MARK, ENTRIES, END);
+/** `upgradeExisting: false` only adds a missing block and never rewrites a present
+ *  one — for `hunch index`, which also runs in CI and release gates where rewriting
+ *  a tracked .gitignore would dirty the checkout. Setup and repair commands upgrade. */
+export function ensureGitignore(root, opts = {}) {
+    return appendBlock(root, MARK, ENTRIES, END, opts.upgradeExisting ?? true);
 }
 /** Ignore the engineering-memory tree so a private-migrated repo stays code-only.
  *  The kind subdirs the user's records live in (decisions/, bugs/, …) move to the
@@ -144,4 +191,43 @@ export function ignoreHunchMemory(root) {
 }
 /** The .hunch memory subdirs un-published by a private migration (git pathspecs). */
 export const HUNCH_MEMORY_DIRS = MEM_ENTRIES.map((e) => e.replace(/\/$/, ""));
+/** Bring every EXISTING managed block up to the current entry lists without adding
+ *  a block the repository never had (a repair path, not setup). A private-only
+ *  block means the repository already declared its memory tree unpublished, so
+ *  memory directories that a later release added to that block are also removed
+ *  from the git index — never from disk — as `private --migrate` does for the whole
+ *  list. */
+export function upgradeManagedGitignore(root) {
+    const result = { base: null, memory: null, untracked: [] };
+    const path = assertSafeTopLevelConfigFile(root, ".gitignore");
+    if (!existsSync(path))
+        return result;
+    if (readFileSync(path, "utf8").includes(MARK))
+        result.base = ensureGitignore(root);
+    if (readFileSync(path, "utf8").includes(MEM_MARK)) {
+        result.memory = ignoreHunchMemory(root);
+        const dirs = result.memory.added.map((e) => e.replace(/\/$/, ""));
+        if (dirs.length && isGitRepoRoot(root)) {
+            result.untracked = gitTrackedPaths(root, dirs);
+            if (result.untracked.length)
+                gitUntrackCached(root, dirs);
+        }
+    }
+    return result;
+}
+/** Output lines describing what an upgrade changed; empty when nothing did. */
+export function describeGitignoreUpgrade(upgrade) {
+    const out = [];
+    if (upgrade.base?.action === "updated") {
+        out.push(`.gitignore: Hunch runtime block updated (added ${upgrade.base.added.join(", ") || "nothing; block normalized"})`);
+    }
+    if (upgrade.memory?.action === "updated") {
+        out.push(`.gitignore: private-only memory block updated (added ${upgrade.memory.added.join(", ") || "nothing; block normalized"})`);
+    }
+    if (upgrade.untracked.length) {
+        const shown = upgrade.untracked.slice(0, 5).join(", ") + (upgrade.untracked.length > 5 ? ", ..." : "");
+        out.push(`removed ${upgrade.untracked.length} newly ignored memory file(s) from the git index, kept on disk (commit the removal): ${shown}`);
+    }
+    return out;
+}
 //# sourceMappingURL=gitignore.js.map

package/dist/integrations/hooks.d.ts

@@ -1,7 +1,36 @@
+/** Which hook manager (if any) owns the hook file git would run.
+ *  - `none`: a plain local hooks dir Hunch may write into.
+ *  - `pre-commit`: the pre-commit framework's generated hook (ends in `exec`).
+ *  - `husky`: husky v9 (`core.hooksPath=.husky/_`, stubs source `h`, which exits).
+ *  - `husky-legacy`: husky ≤8 (`core.hooksPath=.husky`, a tracked directory).
+ *  - `tracked-hooks-path`: any other `core.hooksPath` inside the work tree that git tracks.
+ *  - `exec-exit`: no known manager, but the existing hook ends in exec/exit before our block. */
+export type HookManagerKind = "none" | "pre-commit" | "husky" | "husky-legacy" | "tracked-hooks-path" | "exec-exit";
 export interface HookInstall {
+    /** The hook file written; for a non-writing result, the file the user should edit. */
     path: string;
-    action: "created" | "appended" | "updated" | "unchanged";
+    /** created/appended/updated/unchanged: the block is (now) in a file git reaches.
+     *  managed-elsewhere: a hook manager owns the hook — nothing was written.
+     *  unreachable: the existing hook ends in exec/exit before our block — nothing was written. */
+    action: "created" | "appended" | "updated" | "unchanged" | "managed-elsewhere" | "unreachable";
+    manager?: HookManagerKind;
+    /** Why nothing was written (non-writing actions only). */
+    reason?: string;
+    /** What to add to `path` by hand (non-writing actions only). */
+    snippet?: string;
 }
+/** Portable invocation for text that lands in a TRACKED file (a husky script, a
+ *  committed hooks dir, .pre-commit-config.yaml): the same exact-version npx
+ *  package reference the committed MCP/provider configs use — never this
+ *  machine's absolute node/CLI path. */
+export declare const PORTABLE_HOOK_INVOCATION: string;
+/** The line that ends the script unconditionally before anything appended after
+ *  it could run, or null. Deliberately conservative (a heuristic, not a shell
+ *  parser): an `exec`/`exit` statement outside any if/case/loop/function block,
+ *  or a trailing top-level `if … else … fi` whose every branch ends in
+ *  `exec`/`exit` — the shape of the pre-commit framework's generated hook. */
+export declare function terminalExitLine(content: string): string | null;
+type BlockState = "installed" | "unreachable" | "missing";
 export declare function installPostCommitHook(root: string, invocation: string, opts?: {
     private?: boolean;
     commit?: boolean;
@@ -29,15 +58,40 @@ export declare function installPreCommitHook(root: string, invocation: string, s
  *  gets the other appended rather than clobbered. */
 export declare function installPostMergeHook(root: string, invocation: string): HookInstall;
 export declare function installPostCheckoutHook(root: string, invocation: string): HookInstall;
-/** Read-only diagnostic (used by `hunch doctor`): which of the three managed
- *  hooks are currently present. Never writes anything — a hook counts as
- *  installed if its managed marker is present, regardless of whether the
- *  invocation inside it happens to be stale. postMerge requires BOTH halves
- *  (grounding-refresh and repair-provenance) present — a repo carrying only
- *  one is a partial install, same as `installPostMergeHook` self-healing it. */
+export type HookState = BlockState;
+export interface HookReportEntry {
+    state: HookState;
+    manager: HookManagerKind;
+    /** The file where the block lives (or should live). */
+    path: string;
+    /** Why an `unreachable` block never runs. */
+    reason?: string;
+}
+export interface HookReport {
+    postCommit: HookReportEntry;
+    preCommit: HookReportEntry;
+    postMerge: HookReportEntry;
+    postCheckout: HookReportEntry;
+}
+/** Read-only diagnostic (used by `hunch doctor`): each managed hook's state —
+ *  `installed` (present where git will run it), `unreachable` (present, but
+ *  after an exec/exit or in a manager-owned file git never reaches), or
+ *  `missing`. postMerge requires BOTH halves (grounding-refresh and
+ *  repair-provenance) — a repo carrying only one is a partial install, same as
+ *  `installPostMergeHook` self-healing it. Never writes anything. */
+export declare function hookReport(root: string): HookReport;
+/** Boolean view of `hookReport`: a hook counts as installed only when its
+ *  managed block is present where git will actually run it, regardless of
+ *  whether the invocation inside it happens to be stale. An unreachable block
+ *  (issue #311) is NOT installed. */
 export declare function hookStatus(root: string): {
     postCommit: boolean;
     preCommit: boolean;
     postMerge: boolean;
     postCheckout: boolean;
 };
+/** CLI lines for one install result: the usual ✓ line when the block is in a
+ *  file git runs, otherwise a warning with the reason and the snippet to add to
+ *  the manager's own file. */
+export declare function formatHookInstall(root: string, label: string, h: HookInstall, detail?: string): string[];
+export {};