@davesheffer/hunch 0.9.0 → 0.10.1

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Dave Sheffer
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Dave Sheffer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -124,6 +124,7 @@ they all consult the same memory:
 | Cursor | `.cursor/mcp.json` | `.cursor/rules/hunch.mdc` (always-applied) |
 | VS Code (Copilot) | `.vscode/mcp.json` | `.github/copilot-instructions.md` |
 | Codex CLI | `.codex/config.toml` | `AGENTS.md` |
+| Windsurf | `.windsurf/mcp_config.json` | `.windsurf/rules/hunch.md` (always-on) |
 | Anything else | — | `AGENTS.md` (cross-tool standard) |
 
 Each writer **merges** into existing files (other MCP servers and your own prose are
@@ -133,7 +134,7 @@ preserved) and is idempotent. Opt out with `hunch init --no-providers`.
 
 | Command | What |
 |---|---|
-| `hunch init` | scaffold `.hunch/`, index, install hook + merge driver, auto-install the advisory pre-commit guard, install the **Claude Code agent hooks**, and wire up **every assistant** (Claude Code, Cursor, VS Code/Copilot, Codex, AGENTS.md). Flags: `--no-enforce`, `--enforce-strict`, `--no-providers`, `--no-agent-hooks`, `--firmness <level>` |
+| `hunch init` | scaffold `.hunch/`, index, install hook + merge driver, auto-install the advisory pre-commit guard, install the **Claude Code agent hooks**, and wire up **every assistant** (Claude Code, Cursor, VS Code/Copilot, Codex, Windsurf, AGENTS.md). Flags: `--no-enforce`, `--enforce-strict`, `--no-providers`, `--no-agent-hooks`, `--firmness <level>` |
 | `hunch index` | parse repo → symbols / edges / components (deterministic, no LLM) |
 | `hunch backfill --since 90d` | replay git history → seed decisions |
 | `hunch sync [sha]` | turn a commit into a Decision (run automatically by the hook) |

package/dist/extractors/parse.js

@@ -26,19 +26,19 @@ const BUILTIN_METHODS = new Set([
     "log", "error", "warn", "info", "debug",
 ]);
 /** Tree-sitter query capturing every construct we care about in one pass. */
-const QUERY_SRC = `
-  (function_declaration name: (identifier) @fn.name) @fn.def
-  (generator_function_declaration name: (identifier) @fn.name) @fn.def
-  (method_definition name: (property_identifier) @method.name) @method.def
-  (class_declaration name: (type_identifier) @class.name) @class.def
-  (interface_declaration name: (type_identifier) @iface.name) @iface.def
-  (type_alias_declaration name: (type_identifier) @type.name) @type.def
-  (variable_declarator
-     name: (identifier) @arrow.name
-     value: [(arrow_function) (function_expression)]) @arrow.def
-  (import_statement source: (string) @import.src)
-  (call_expression function: (identifier) @call.id)
-  (call_expression function: (member_expression property: (property_identifier) @call.member))
+const QUERY_SRC = `
+  (function_declaration name: (identifier) @fn.name) @fn.def
+  (generator_function_declaration name: (identifier) @fn.name) @fn.def
+  (method_definition name: (property_identifier) @method.name) @method.def
+  (class_declaration name: (type_identifier) @class.name) @class.def
+  (interface_declaration name: (type_identifier) @iface.name) @iface.def
+  (type_alias_declaration name: (type_identifier) @type.name) @type.def
+  (variable_declarator
+     name: (identifier) @arrow.name
+     value: [(arrow_function) (function_expression)]) @arrow.def
+  (import_statement source: (string) @import.src)
+  (call_expression function: (identifier) @call.id)
+  (call_expression function: (member_expression property: (property_identifier) @call.member))
 `;
 const cache = new Map();
 function bundleFor(lang, key) {

package/dist/integrations/providers.js

@@ -11,6 +11,7 @@
  *   Cursor      | .cursor/mcp.json        | mcpServers     | .cursor/rules/hunch.mdc
  *   VS Code     | .vscode/mcp.json        | servers (+type)| .github/copilot-instructions.md
  *   Codex CLI   | .codex/config.toml      | [mcp_servers.*]| AGENTS.md
+ *   Windsurf    | .windsurf/mcp_config.json| mcpServers    | .windsurf/rules/hunch.md
  *   (any other) | —                       | —              | AGENTS.md (cross-tool standard)
  *
  * Every writer MERGES into existing files (preserving other servers / user prose)
@@ -206,6 +207,25 @@ export function writeCursorRule(root, store) {
     writeFileSync(file, body);
     return file;
 }
+/** Windsurf (Cascade): .windsurf/mcp_config.json — same `mcpServers` shape as
+ *  Cursor. Repo-local (committed, shared via git) to match Hunch's other configs,
+ *  rather than the global ~/.codeium/windsurf path. Merges; refuses to clobber. */
+export function writeWindsurfMcp(root, inv) {
+    const file = join(root, ".windsurf", "mcp_config.json");
+    const json = readJsonObj(file);
+    json.mcpServers = json.mcpServers ?? {};
+    json.mcpServers.hunch = { command: inv.command, args: [...inv.args, "mcp"] };
+    return writeJson(file, json);
+}
+/** Windsurf project rule (.windsurf/rules/hunch.md). `trigger: always_on` keeps the
+ *  Hunch grounding in Cascade's context for every request. Fully managed (overwritten). */
+export function writeWindsurfRule(root, store) {
+    const file = join(root, ".windsurf", "rules", "hunch.md");
+    const body = `---\ntrigger: always_on\ndescription: Hunch engineering memory — consult the hunch_* MCP tools before editing\n---\n\n${renderHunchSection(store)}\n`;
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, body);
+    return file;
+}
 /** Scaffold MCP config + grounding for all supported assistants. Returns a
  *  per-assistant summary for `hunch init` to print. Each assistant is isolated:
  *  a writer that refuses to clobber a malformed file degrades to a warning rather
@@ -215,6 +235,7 @@ export function scaffoldProviders(root, inv, store) {
         ["Cursor", () => [writeCursorMcp(root, inv), writeCursorRule(root, store)]],
         ["VS Code (Copilot)", () => [writeVscodeMcp(root, inv), writeCopilotInstructions(root, store)]],
         ["Codex CLI", () => [writeCodexConfig(root, inv)]],
+        ["Windsurf", () => [writeWindsurfMcp(root, inv), writeWindsurfRule(root, store)]],
         ["Any (AGENTS.md)", () => [writeAgentsMd(root, store)]],
     ];
     return tasks.map(([assistant, run]) => {

package/dist/store/hunchStore.js

@@ -30,6 +30,11 @@ export class HunchStore {
         const tx = db.transaction(() => {
             db.exec(RESET_SQL);
             const j = (s) => s; // readability marker for JSON-encoded columns
+            // Prepare the FTS insert ONCE (after RESET created the table), not per row.
+            const insFts = db.prepare(`INSERT INTO search (ref, kind, title, body) VALUES (?,?,?,?)`);
+            const fts = (ref, kind, title, body) => {
+                insFts.run(ref, kind, title, body ?? "");
+            };
             const comps = this.json.loadAll("components");
             const insComp = db.prepare(`INSERT INTO components VALUES (@id,@kind,@name,@responsibility,@paths,@status,@owners,@fragility,@ps,@pc,@pe,@created_at,@updated_at)`);
             for (const c of comps) {
@@ -39,7 +44,7 @@ export class HunchStore {
                     fragility: c.fragility, ps: c.provenance.source, pc: c.provenance.confidence,
                     pe: JSON.stringify(c.provenance.evidence), created_at: c.created_at, updated_at: c.updated_at,
                 });
-                this.fts(db, c.id, "components", c.name, `${c.responsibility} ${c.paths.join(" ")}`);
+                fts(c.id, "components", c.name, `${c.responsibility} ${c.paths.join(" ")}`);
             }
             counts.components = comps.length;
             const edges = this.json.loadAll("edges");
@@ -56,7 +61,7 @@ export class HunchStore {
                     calls: JSON.stringify(s.calls), called_by: JSON.stringify(s.called_by),
                     loc: s.metrics.loc, churn: s.metrics.churn_90d, bug: s.metrics.bug_count,
                     fanin: s.metrics.fan_in, fanout: s.metrics.fan_out, last: s.last_changed });
-                this.fts(db, s.id, "symbols", `${s.name} (${s.kind})`, s.file);
+                fts(s.id, "symbols", `${s.name} (${s.kind})`, s.file);
             }
             counts.symbols = syms.length;
             const decs = this.json.loadAll("decisions");
@@ -67,7 +72,7 @@ export class HunchStore {
                     rc: JSON.stringify(d.related_components), rf: JSON.stringify(d.related_files),
                     sup: d.supersedes, cbb: d.caused_by_bug, commit: d.commit,
                     ps: d.provenance.source, pc: d.provenance.confidence, pe: JSON.stringify(d.provenance.evidence), date: d.date });
-                this.fts(db, d.id, "decisions", d.title, `${d.context} ${d.decision} ${d.consequences.join(" ")}`);
+                fts(d.id, "decisions", d.title, `${d.context} ${d.decision} ${d.consequences.join(" ")}`);
             }
             counts.decisions = decs.length;
             const bugs = this.json.loadAll("bugs");
@@ -76,7 +81,7 @@ export class HunchStore {
                 insBug.run({ id: b.id, title: b.title, symptom: b.symptom, rc: b.root_cause, sev: b.severity, status: b.status,
                     af: JSON.stringify(b.affected_files), as: JSON.stringify(b.affected_symbols), lin: JSON.stringify(b.lineage),
                     ps: b.provenance.source, pc: b.provenance.confidence, pe: JSON.stringify(b.provenance.evidence) });
-                this.fts(db, b.id, "bugs", b.title, `${b.symptom} ${b.root_cause}`);
+                fts(b.id, "bugs", b.title, `${b.symptom} ${b.root_cause}`);
             }
             counts.bugs = bugs.length;
             const cons = this.json.loadAll("constraints");
@@ -85,7 +90,7 @@ export class HunchStore {
                 insCon.run({ id: c.id, type: c.type, statement: c.statement, scope: JSON.stringify(c.scope),
                     sev: c.severity, enf: c.enforcement, rat: c.rationale, sd: c.source_decision, viol: JSON.stringify(c.violations),
                     ps: c.provenance.source, pc: c.provenance.confidence, pe: JSON.stringify(c.provenance.evidence) });
-                this.fts(db, c.id, "constraints", c.statement, `${c.rationale} ${c.scope.join(" ")}`);
+                fts(c.id, "constraints", c.statement, `${c.rationale} ${c.scope.join(" ")}`);
             }
             counts.constraints = cons.length;
             void j;
@@ -97,9 +102,6 @@ export class HunchStore {
         this.pruneStaleEmbeddings();
         return { counts };
     }
-    fts(db, ref, kind, title, body) {
-        db.prepare(`INSERT INTO search (ref, kind, title, body) VALUES (?,?,?,?)`).run(ref, kind, title, body ?? "");
-    }
     // ---- read path ----------------------------------------------------------
     /** FTS5 ranked search (hunch_query). Falls back to LIKE if the query has no
      *  FTS-tokenizable terms. */
@@ -305,7 +307,7 @@ export class HunchStore {
      *  `id`, via a recursive CTE over the edges graph (hunch_get_dependents). We
      *  walk edges BACKWARD (edges.to = current) following call/dep/import/contains. */
     getDependents(id, maxDepth = 6) {
-        const rows = this.db.prepare(
+        return this.db.prepare(
         /* sql */ `
       WITH RECURSIVE up(node, depth) AS (
         SELECT ?, 0
@@ -314,13 +316,16 @@ export class HunchStore {
         FROM edges e JOIN up ON e."to" = up.node
         WHERE e.type IN ('calls','depends_on','imports','contains') AND up.depth < ?
       )
-      SELECT DISTINCT up.node AS id, MIN(up.depth) AS depth FROM up
+      SELECT up.node AS id, MIN(up.depth) AS depth,
+             COALESCE(s.name || ' @ ' || s.file, c.name, up.node) AS via
+      FROM up
+      LEFT JOIN symbols s ON s.id = up.node
+      LEFT JOIN components c ON c.id = up.node
       WHERE up.node <> ? GROUP BY up.node ORDER BY depth, id`).all(id, maxDepth, id);
-        return rows.map((r) => ({ id: r.id, depth: r.depth, via: this.labelFor(r.id) }));
     }
     /** Symbols/components this id depends ON (forward walk) — used for refactor blast radius. */
     getDependencies(id, maxDepth = 6) {
-        const rows = this.db.prepare(
+        return this.db.prepare(
         /* sql */ `
       WITH RECURSIVE down(node, depth) AS (
         SELECT ?, 0
@@ -329,40 +334,34 @@ export class HunchStore {
         FROM edges e JOIN down ON e."from" = down.node
         WHERE e.type IN ('calls','depends_on','imports','contains') AND down.depth < ?
       )
-      SELECT DISTINCT down.node AS id, MIN(down.depth) AS depth FROM down
+      SELECT down.node AS id, MIN(down.depth) AS depth,
+             COALESCE(s.name || ' @ ' || s.file, c.name, down.node) AS via
+      FROM down
+      LEFT JOIN symbols s ON s.id = down.node
+      LEFT JOIN components c ON c.id = down.node
       WHERE down.node <> ? GROUP BY down.node ORDER BY depth, id`).all(id, maxDepth, id);
-        return rows.map((r) => ({ id: r.id, depth: r.depth, via: this.labelFor(r.id) }));
-    }
-    labelFor(id) {
-        if (id.startsWith("sym_")) {
-            const r = this.db.prepare(`SELECT name, file FROM symbols WHERE id=?`).get(id);
-            return r ? `${r.name} @ ${r.file}` : id;
-        }
-        if (id.startsWith("cmp_")) {
-            const r = this.db.prepare(`SELECT name FROM components WHERE id=?`).get(id);
-            return r ? r.name : id;
-        }
-        return id;
     }
     /** Files whose symbols (in)directly DEPEND ON a symbol defined in `file` — the
      *  blast radius of editing `file`, collapsed to file granularity (nearest depth
      *  wins per file). Powers `hunch check` near-violation detection and `--blast`. */
     blastRadiusFiles(file, maxDepth = 4) {
-        const syms = this.db.prepare(`SELECT id FROM symbols WHERE file = ?`).all(file);
-        const out = new Map();
-        for (const s of syms) {
-            for (const dep of this.getDependents(s.id, maxDepth)) {
-                if (!dep.id.startsWith("sym_"))
-                    continue;
-                const r = this.db.prepare(`SELECT name, file FROM symbols WHERE id=?`).get(dep.id);
-                if (!r || r.file === file)
-                    continue; // ignore self-file dependents
-                const prev = out.get(r.file);
-                if (!prev || dep.depth < prev.depth)
-                    out.set(r.file, { file: r.file, via: r.name, depth: dep.depth });
-            }
-        }
-        return [...out.values()].sort((a, b) => a.depth - b.depth || a.file.localeCompare(b.file));
+        // ONE backward CTE seeded by every symbol in `file`, joined to symbols for the
+        // dependent file/name. GROUP BY file + MIN(depth): SQLite's single-min rule makes
+        // the bare `via` take the name from the nearest-depth row. The inner JOIN drops
+        // non-symbol nodes; `s.file <> ?` drops self-file dependents.
+        return this.db.prepare(
+        /* sql */ `
+      WITH RECURSIVE up(node, depth) AS (
+        SELECT id, 0 FROM symbols WHERE file = ?
+        UNION
+        SELECT e."from", up.depth + 1
+        FROM edges e JOIN up ON e."to" = up.node
+        WHERE e.type IN ('calls','depends_on','imports','contains') AND up.depth < ?
+      )
+      SELECT s.file AS file, s.name AS via, MIN(up.depth) AS depth
+      FROM up JOIN symbols s ON s.id = up.node
+      WHERE up.depth > 0 AND s.file <> ?
+      GROUP BY s.file ORDER BY depth, file`).all(file, maxDepth, file);
     }
     /** Constraints whose scope glob matches a path/glob (hunch_check_constraints).
      *  By default only ACTIVE invariants are returned — a retired constraint is no

package/dist/store/jsonStore.js

@@ -3,7 +3,7 @@
  * in PRs, diffable, mergeable). This layer never touches SQLite — it is the
  * authoritative read/write surface; SQLite is rebuilt from it.
  */
-import { mkdirSync, readdirSync, readFileSync, existsSync, rmSync } from "node:fs";
+import { mkdirSync, readdirSync, readFileSync, existsSync, rmSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { ENTITY_KINDS, SCHEMAS } from "../core/types.js";
 import { migrateRaw, readManifest, writeManifest, SCHEMA_VERSION } from "../core/migrate.js";
@@ -17,9 +17,27 @@ const encode = (v) => JSON.stringify(v, null, 2) + "\n";
 export class JsonStore {
     paths;
     _warnedForward = false;
+    /** Memoized validated records per kind. loadAll() is on every read-path method
+     *  (why/checkConstraints/fragility/assembleContext…), each of which previously
+     *  re-read the directory and re-ran Zod over every record. Cache keyed by the
+     *  kind dir's mtime: every write goes through writeFileAtomic (temp + rename) or
+     *  rmSync, both of which bump the dir mtime — so an OUT-OF-BAND write by another
+     *  process self-invalidates on the next read. In-process writes also invalidate
+     *  explicitly (exact, independent of mtime granularity). */
+    cache = new Map();
     constructor(paths) {
         this.paths = paths;
     }
+    /** Drop memoized loadAll results. Writes through this store invalidate the
+     *  affected kind automatically; call this for OUT-OF-BAND changes to .hunch/
+     *  JSON (e.g. the long-lived MCP server reacting to a file-watch, or after an
+     *  external `hunch migrate`). */
+    clearCache() {
+        this.cache.clear();
+    }
+    invalidate(kind) {
+        this.cache.delete(kind);
+    }
     /** Create .hunch/<kind>/ directories. Stamp the manifest at the CURRENT version
      *  only when scaffolding a FRESH .hunch/ (so `hunch index`/`sync` on a brand-new
      *  repo records the version too, not just `init`). A pre-existing .hunch/ without
@@ -56,9 +74,22 @@ export class JsonStore {
             return join(this.paths.dir(kind), single);
         return join(this.paths.dir(kind), `${id}.json`);
     }
-    /** Load every record of a kind, validated against its schema. Invalid records
-     *  are skipped with a warning rather than crashing the whole load. */
+    /** Load every record of a kind, validated against its schema. Memoized — the
+     *  returned array is shared and MUST be treated read-only (every caller already
+     *  derives via filter/map/sort, which copy). Invalidated on write. */
     loadAll(kind) {
+        const dir = this.paths.dir(kind);
+        const mtimeMs = existsSync(dir) ? statSync(dir).mtimeMs : 0;
+        const hit = this.cache.get(kind);
+        if (hit && hit.mtimeMs === mtimeMs)
+            return hit.data;
+        const data = this.readAllFromDisk(kind);
+        this.cache.set(kind, { mtimeMs, data });
+        return data;
+    }
+    /** Uncached disk read + validate. Invalid records are skipped with a warning
+     *  rather than crashing the whole load. */
+    readAllFromDisk(kind) {
         const dir = this.paths.dir(kind);
         if (!existsSync(dir))
             return [];
@@ -126,12 +157,14 @@ export class JsonStore {
         else {
             writeFileAtomic(this.fileFor(kind, validated.id), encode(validated));
         }
+        this.invalidate(kind);
         return validated;
     }
     /** Bulk replace all records of a kind (used by the extractor for symbols/edges). */
     replaceAll(kind, records) {
         const schema = SCHEMAS[kind];
         const validated = records.map((r) => schema.parse(r));
+        this.invalidate(kind);
         mkdirSync(this.paths.dir(kind), { recursive: true });
         const single = SINGLE_FILE[kind];
         if (single) {
@@ -186,12 +219,14 @@ export class JsonStore {
             if (next.length === arr.length)
                 return false;
             writeFileAtomic(f, encode(next));
+            this.invalidate(kind);
             return true;
         }
         const f = this.fileFor(kind, id);
         if (!existsSync(f))
             return false;
         rmSync(f);
+        this.invalidate(kind);
         return true;
     }
     /** Persist a schema migration: rewrite every LOADABLE record in its current shape.
@@ -201,6 +236,7 @@ export class JsonStore {
     persistMigration() {
         let migrated = 0;
         let skipped = 0;
+        this.cache.clear(); // every record is rewritten; drop all memoized loads
         const version = this.schemaVersion(); // read once; we're migrating FROM this
         for (const kind of ENTITY_KINDS) {
             const dir = this.paths.dir(kind);

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@davesheffer/hunch",
-  "version": "0.9.0",
+  "version": "0.10.1",
   "license": "MIT",
   "author": "Dave Sheffer <dave.sheffer1@gmail.com>",
   "description": "Hunch — an Engineering Memory OS: a persistent, git-native reasoning graph over a codebase, exposed to Claude Code via MCP.",
-  "homepage": "https://hunch.sh",
+  "homepage": "https://hunch-pi.vercel.app",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/davesheffer/hunch.git"