@davesheffer/hunch 0.17.0 → 0.17.2

package/README.md

@@ -160,14 +160,15 @@ per-machine fixups. → [docs](https://hunch-pi.vercel.app/docs#team)
 
 ## Private memory (public repo, private context)
 
-Open-source your code without open-sourcing your *reasoning*. Point `HUNCH_PRIVATE_DIR` at a
-separate **private repo** and Hunch unions that store into every query and guard **locally** —
-MCP and the pre-edit hook see your sensitive decisions/bugs/constraints — while your public
-`.hunch/` stays clean. It's **opt-in and default-off** (unset the var → fully inert), and
-**leak-safe by construction**: committed files and the CI PR comment render *public-only*, so a
-private record can't reach a public surface. Record sensitive items with `private: true`
-(`hunch_record_decision` / `hunch_record_correction`); `hunch doctor` shows whether the overlay
-is on. → [docs](https://hunch-pi.vercel.app/docs#private)
+Open-source your code without open-sourcing your *reasoning*. **`hunch private`** sets up a
+separate private store in one command — Hunch unions it into every query and guard **locally**
+(MCP and the pre-edit hook see your sensitive decisions/bugs/constraints) while your public
+`.hunch/` stays clean. It writes a gitignored `.hunch/local.json` so it's auto-detected — **no
+env var, no shell-profile edit** (and `HUNCH_PRIVATE_DIR` still overrides per-shell). **Opt-in,
+default-off** (no config → fully inert), and **leak-safe by construction**: committed files and
+the CI PR comment render *public-only*, so a private record can't reach a public surface. Record
+sensitive items with `private: true` (`hunch_record_decision` / `hunch_record_correction`);
+post-commit synthesis can route there too. → [docs](https://hunch-pi.vercel.app/docs#private)
 
 ## Continuous learning (CI)
 

package/dist/cli/index.js

@@ -13,14 +13,16 @@
  *   mcp       start the MCP server (Claude Code connects here)
  *   doctor    environment diagnostics
  */
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
 import { execFileSync, spawnSync } from "node:child_process";
-import { relative, resolve } from "node:path";
+import { join, relative, resolve, isAbsolute } from "node:path";
 import { Command } from "commander";
-import { hunchPaths, findRoot, toPosixTarget } from "../core/paths.js";
+import { hunchPaths, hunchPathsForDir, findRoot, toPosixTarget } from "../core/paths.js";
+import { writeFileAtomic } from "../core/io.js";
 import { looksLikeCorrection, CORRECTION_NUDGE } from "../core/correction.js";
 import { HUNCH_VERSION } from "../core/version.js";
 import { HunchStore } from "../store/hunchStore.js";
+import { JsonStore } from "../store/jsonStore.js";
 import { selectEmbedder } from "../store/embedder.js";
 import { indexRepo } from "../extractors/indexer.js";
 import { syncCommit, recordFailure, captureTestRun } from "../synthesis/synthesize.js";
@@ -64,6 +66,7 @@ program
     .option("--no-providers", "skip scaffolding non-Claude assistant configs (Cursor / VS Code / Codex / AGENTS.md)")
     .option("--no-agent-hooks", "skip installing the Claude Code agent hooks (.claude/settings.json)")
     .option("--firmness <level>", "agent-hook firmness: off | advisory | firm | strict")
+    .option("--private-sync", "post-commit synthesis writes captured decisions into the private overlay (HUNCH_PRIVATE_DIR), never the public repo")
     .action((opts) => {
     // Validate --firmness up front, before any side effects (indexing, git hooks,
     // .mcp.json) or opening the store — a bad value must not leave a half-init.
@@ -92,8 +95,8 @@ program
             console.log(`  ⚠ ${res.skipped} file(s) could not be parsed (skipped)`);
     }
     if (isGitRepo(root)) {
-        const h = installPostCommitHook(root, inv.shell);
-        console.log(`  ✓ post-commit hook ${h.action} (learning loop)`);
+        const h = installPostCommitHook(root, inv.shell, { private: opts.privateSync });
+        console.log(`  ✓ post-commit hook ${h.action} (learning loop)${opts.privateSync ? " — syncs to the private overlay" : ""}`);
         const m = installMergeDriver(root, inv.shell);
         console.log(`  ✓ team merge driver ${m.action}`);
         // Auto-install the pre-commit guard by default (advisory: flags invariants
@@ -223,12 +226,17 @@ program
     .option("--from-hook", "invoked by the git hook")
     .option("--quiet", "minimal output")
     .option("--force", "re-synthesize even if a decision already exists for the commit")
+    .option("--private", "write the synthesized decision into the private overlay (HUNCH_PRIVATE_DIR), not the public repo — for a repo whose memory is kept private")
     .action(async (sha, opts) => {
     const { store, root } = storeFor();
     if (!isGitRepo(root))
         return opts.quiet ? undefined : fail("sync needs a git repo");
+    if (opts.private && !store.hasPrivate) {
+        store.close();
+        return opts.quiet ? undefined : fail("--private needs HUNCH_PRIVATE_DIR set to a private store");
+    }
     store.json.ensureDirs();
-    const r = await syncCommit(store, root, sha ?? headSha(root), { force: opts.force });
+    const r = await syncCommit(store, root, sha ?? headSha(root), { force: opts.force, private: opts.private });
     if (r.status === "written") {
         store.reindex();
         // Don't rewrite CLAUDE.md from the hook — it would dirty the working tree
@@ -243,6 +251,54 @@ program
     }
     store.close();
 });
+// ---- private (one-command setup for the private memory overlay) ------------
+program
+    .command("private [dir]")
+    .description("Enable a PRIVATE memory overlay — sensitive decisions/bugs/constraints kept in a separate location, unioned into local queries, never committed here. Writes a gitignored .hunch/local.json so it's auto-detected (no env var needed).")
+    .option("--repo <url>", "clone a private git repo to use as the store (into ./.hunch-private)")
+    .option("--no-hook", "don't switch the post-commit hook to private sync")
+    .action((dir, opts) => {
+    const root = findRoot();
+    const paths = hunchPaths(root);
+    // 1) resolve the private store's hunch dir (holds decisions/, bugs/, …)
+    let hunchDir;
+    if (opts.repo) {
+        const dest = join(root, ".hunch-private");
+        if (!existsSync(dest)) {
+            const r = spawnSync("git", ["clone", opts.repo, dest], { stdio: "inherit" });
+            if (r.status !== 0)
+                return fail(`git clone failed for ${opts.repo}`);
+        }
+        hunchDir = join(dest, ".hunch");
+    }
+    else {
+        hunchDir = dir ? resolve(root, dir) : join(root, ".hunch-private", ".hunch");
+    }
+    // 2) create the layout (decisions/, manifest, …) so it's queryable immediately
+    new JsonStore(hunchPathsForDir(hunchDir)).ensureDirs();
+    // 3) record the path in a GITIGNORED local config — auto-detected, no env var, and
+    //    the MCP server picks it up too. Atomic write (con_902759b3dc) since it's under .hunch/.
+    mkdirSync(paths.hunch, { recursive: true }); // tolerate a repo where `hunch init` hasn't run yet
+    // Store a repo-relative POSIX path when the store lives INSIDE the repo (portable +
+    // OS-clean — survives a repo move, resolves the same on any OS); an absolute path for
+    // a store elsewhere on disk. Resolution (env || local.json) re-resolves against root.
+    const rel = relative(root, hunchDir);
+    const stored = rel && !rel.startsWith("..") && !isAbsolute(rel) ? toPosixTarget(rel) : hunchDir;
+    writeFileAtomic(join(paths.hunch, "local.json"), JSON.stringify({ privateDir: stored }, null, 2) + "\n");
+    ensureGitignore(root); // keeps .hunch/local.json + .hunch-private/ out of git
+    // 4) route post-commit synthesis to the overlay (local hook, never committed)
+    let hookNote = "";
+    if (opts.hook && isGitRepo(root)) {
+        const inv = resolveInvocation();
+        const h = installPostCommitHook(root, inv.shell, { private: true });
+        hookNote = `  ✓ post-commit hook ${h.action} — captured decisions route here\n`;
+    }
+    console.log(`✓ private overlay enabled → ${hunchDir}\n` +
+        `  ✓ recorded in .hunch/local.json (gitignored) — auto-detected, no env var or shell-profile edit\n` +
+        hookNote +
+        `  record sensitive items with private:true (hunch_record_decision / hunch_record_correction)\n` +
+        `  override per-shell with HUNCH_PRIVATE_DIR; CI / public PR comments stay public-only.`);
+});
 // ---- query ----------------------------------------------------------------
 program
     .command("query")
@@ -1043,10 +1099,9 @@ program
     }
     const c = store.reindex().counts;
     console.log(`hunch:      ${c.symbols} symbols, ${c.edges} edges, ${c.components} components, ${c.decisions} decisions, ${c.bugs} bugs, ${c.constraints} constraints`);
-    const privDir = process.env.HUNCH_PRIVATE_DIR?.trim();
-    console.log(privDir
-        ? `private:    on → ${resolve(privDir)} (local overlay — unioned into queries; never committed or posted publicly)`
-        : dim(`private:    off — set HUNCH_PRIVATE_DIR to overlay a separate private memory repo for sensitive records`));
+    console.log(store.privateDir
+        ? `private:    on → ${store.privateDir} (local overlay — unioned into queries; never committed or posted publicly)`
+        : dim(`private:    off — run \`hunch private\` to keep sensitive memory in a separate repo (or set HUNCH_PRIVATE_DIR)`));
     // Semantic search is opt-in and local. Report availability + coverage without
     // loading the model (selectEmbedder only probes; embeddingStats just counts rows).
     const emb = await selectEmbedder();

package/dist/integrations/gitignore.js

@@ -19,6 +19,9 @@ const ENTRIES = [
     ".hunch/*.sqlite-wal",
     ".hunch/*.sqlite-journal",
     ".hunch/**/*.tmp*",
+    // Per-machine private-overlay pointer written by `hunch private` (holds the local
+    // path to the private store) — never committed.
+    ".hunch/local.json",
     // A local PRIVATE overlay store (HUNCH_PRIVATE_DIR) for sensitive memory — never
     // committed. This is the conventional in-repo path; point the env elsewhere for a
     // fully separate private repo.

package/dist/integrations/hooks.js

@@ -9,17 +9,21 @@ import { join, isAbsolute } from "node:path";
 import { hooksDir } from "../extractors/git.js";
 const MARK = "# >>> hunch post-commit >>>";
 const ENDMARK = "# <<< hunch post-commit <<<";
-function block(invocation) {
+function block(invocation, opts = {}) {
+    // --private routes the auto-synthesized decision into the HUNCH_PRIVATE_DIR overlay
+    // instead of the public repo. The hook script is local (.git/hooks/), never committed,
+    // so a repo whose memory is kept private leaves no trace of this in the public tree.
+    const priv = opts.private ? " --private" : "";
     return [
         MARK,
         'if [ -z "$HUNCH_SYNC" ]; then',
         "  export HUNCH_SYNC=1",
-        `  ( ${invocation} sync --from-hook --quiet >/dev/null 2>&1 || true ) &`,
+        `  ( ${invocation} sync --from-hook --quiet${priv} >/dev/null 2>&1 || true ) &`,
         "fi",
         ENDMARK,
     ].join("\n");
 }
-export function installPostCommitHook(root, invocation) {
+export function installPostCommitHook(root, invocation, opts = {}) {
     const dir = hooksDir(root);
     // `git rev-parse --git-path hooks` returns a path relative to the repo in a
     // normal checkout, but an ABSOLUTE one inside a linked worktree (the shared
@@ -28,7 +32,7 @@ export function installPostCommitHook(root, invocation) {
     const abs = isAbsolute(dir) ? dir : join(root, dir);
     mkdirSync(abs, { recursive: true });
     const hookPath = join(abs, "post-commit");
-    const blk = block(invocation);
+    const blk = block(invocation, opts);
     if (!existsSync(hookPath)) {
         writeFileSync(hookPath, `#!/bin/sh\n${blk}\n`);
         chmodSync(hookPath, 0o755);

package/dist/store/hunchStore.js

@@ -10,7 +10,8 @@
  *   - bugLineage():     bugs matching a symptom/symbol + their lineage
  *   - fragility():      ranked fragility report with evidence
  */
-import { resolve } from "node:path";
+import { resolve, join } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
 import { toPosixTarget, hunchPathsForDir } from "../core/paths.js";
 import { ENTITY_KINDS } from "../core/types.js";
 import { openDb } from "./db.js";
@@ -27,6 +28,9 @@ export class HunchStore {
     /** Optional PRIVATE overlay (HUNCH_PRIVATE_DIR) — a second store in a repo the
      *  user controls. Unioned into reads via recs(); never written by public paths. */
     privateJson;
+    /** The resolved private-overlay hunch dir (from env or .hunch/local.json), or undefined
+     *  when no overlay is configured. Surfaced so `hunch doctor` reflects the true state. */
+    privateDir;
     /** When true, recs() ignores the private overlay (public-only). Set transiently by
      *  buildCheckReport({publicOnly}) so any PUBLICLY-POSTED report (the CI PR comment)
      *  can never render a private record — a publicly-posted output is a leak surface
@@ -36,9 +40,28 @@ export class HunchStore {
     constructor(paths) {
         this.paths = paths;
         this.json = new JsonStore(paths);
-        const priv = process.env.HUNCH_PRIVATE_DIR?.trim();
-        if (priv)
-            this.privateJson = new JsonStore(hunchPathsForDir(resolve(priv)));
+        // Private overlay location: env (override, for CI / portability) → else a gitignored
+        // local config (.hunch/local.json) so `hunch private` enables it with NO env var, and
+        // the MCP server / hook pick it up automatically. Relative paths resolve from root.
+        const priv = process.env.HUNCH_PRIVATE_DIR?.trim() || this.localPrivateDir();
+        if (priv) {
+            this.privateDir = resolve(this.paths.root, priv);
+            this.privateJson = new JsonStore(hunchPathsForDir(this.privateDir));
+        }
+    }
+    /** The private-overlay path from the gitignored `.hunch/local.json` (per-machine,
+     *  never committed). Tolerant: undefined on missing/invalid so reads never crash. */
+    localPrivateDir() {
+        try {
+            const f = join(this.paths.hunch, "local.json");
+            if (!existsSync(f))
+                return undefined;
+            const v = JSON.parse(readFileSync(f, "utf8"));
+            return typeof v.privateDir === "string" && v.privateDir.trim() ? v.privateDir.trim() : undefined;
+        }
+        catch {
+            return undefined;
+        }
     }
     /** Merged read: public ∪ private overlay (private wins on id collision). Every
      *  QUERY / REINDEX path uses this so MCP + the guards see private memory. Public-

package/dist/synthesis/synthesize.js

@@ -119,7 +119,12 @@ export async function syncCommit(store, root, sha, opts = {}) {
         },
         date: meta.date, // the commit date
     };
-    store.json.put("decisions", decision);
+    // Route to the PRIVATE overlay when asked (post-commit sync in a repo whose memory
+    // is kept private) — keeps auto-captured decisions out of the public repo entirely.
+    if (opts.private)
+        store.putPrivate("decisions", decision);
+    else
+        store.json.put("decisions", decision);
     return { status: "written", decision, provider: provider.name };
 }
 /** Capture a Bug from a test failure. Suspects are ranked churn×recency×fan-in. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davesheffer/hunch",
-  "version": "0.17.0",
+  "version": "0.17.2",
   "license": "Apache-2.0",
   "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.",