engramx 2.1.0 → 3.0.1

package/dist/{core-TSXA5XZH.js → core-77F2BVYV.js}

@@ -11,8 +11,8 @@ import {
   path,
   query,
   stats
-} from "./chunk-ZVWRIVWQ.js";
-import "./chunk-PEH54LYC.js";
+} from "./chunk-B4UOE64J.js";
+import "./chunk-645NBY6L.js";
 export {
   benchmark,
   computeKeywordIDF,

package/dist/{cursor-mdc-VEOFFDVO.js → cursor-mdc-EEO7PYZ3.js}

@@ -33,7 +33,7 @@ function buildSection(heading, bullets) {
   return [`## ${heading}`, "", ...bullets, ""].join("\n");
 }
 async function generateCursorMdc(projectPath) {
-  const { getStore } = await import("./core-TSXA5XZH.js");
+  const { getStore } = await import("./core-77F2BVYV.js");
   const store = await getStore(projectPath);
   try {
     const allNodes = store.getAllNodes();

package/dist/{exporter-AWXS34AS.js → exporter-ZYJ4WM2F.js}

@@ -12,7 +12,7 @@ function buildSection(heading, nodes) {
   return [`## ${heading}`, "", ...bullets, ""].join("\n");
 }
 async function exportCcs(projectRoot) {
-  const { getStore } = await import("./core-TSXA5XZH.js");
+  const { getStore } = await import("./core-77F2BVYV.js");
   const store = await getStore(projectRoot);
   try {
     const allNodes = store.getAllNodes();

package/dist/{importer-3Q5M6QBL.js → importer-4UWQDH4W.js}

@@ -25,7 +25,7 @@ async function importCcs(projectRoot) {
   if (!existsSync(filePath)) {
     return { nodesCreated: 0, sectionsFound: 0 };
   }
-  const { getStore } = await import("./core-TSXA5XZH.js");
+  const { getStore } = await import("./core-77F2BVYV.js");
   const store = await getStore(projectRoot);
   try {
     const raw = readFileSync(filePath, "utf-8");

package/dist/index.js

@@ -4,7 +4,7 @@ import {
   generateSummary,
   install,
   uninstall
-} from "./chunk-4XA6ENNL.js";
+} from "./chunk-VLTWBTQ7.js";
 import {
   GraphStore,
   SUPPORTED_EXTENSIONS,
@@ -23,8 +23,8 @@ import {
   sliceGraphemeSafe,
   stats,
   truncateGraphemeSafe
-} from "./chunk-ZVWRIVWQ.js";
-import "./chunk-PEH54LYC.js";
+} from "./chunk-B4UOE64J.js";
+import "./chunk-645NBY6L.js";
 export {
   GraphStore,
   SUPPORTED_EXTENSIONS,

package/dist/mcp-client-ROOJF76V.js

@@ -0,0 +1,9 @@
+import {
+  __internalsForTesting,
+  createMcpProvider
+} from "./chunk-73IBCRFI.js";
+import "./chunk-ZUC6OXSL.js";
+export {
+  __internalsForTesting,
+  createMcpProvider
+};

package/dist/mcp-config-QD4NPVXB.js

@@ -0,0 +1,12 @@
+import {
+  applyArgTemplate,
+  getMcpConfigPath,
+  loadMcpConfigs,
+  validateProviderConfig
+} from "./chunk-ZUC6OXSL.js";
+export {
+  applyArgTemplate,
+  getMcpConfigPath,
+  loadMcpConfigs,
+  validateProviderConfig
+};

package/dist/{migrate-UKCO6BUU.js → migrate-KJ5K5NWO.js}

@@ -3,7 +3,7 @@ import {
   getSchemaVersion,
   rollback,
   runMigrations
-} from "./chunk-PEH54LYC.js";
+} from "./chunk-645NBY6L.js";
 export {
   CURRENT_SCHEMA_VERSION,
   getSchemaVersion,

package/dist/{plugin-loader-STTGYIL5.js → plugin-loader-SQQB6V74.js}

@@ -1,3 +1,10 @@
+import {
+  createMcpProvider
+} from "./chunk-73IBCRFI.js";
+import {
+  validateProviderConfig
+} from "./chunk-ZUC6OXSL.js";
+
 // src/providers/plugin-loader.ts
 import { existsSync, readdirSync, mkdirSync } from "fs";
 import { join } from "path";
@@ -23,34 +30,73 @@ function validatePlugin(mod) {
     return { plugin: null, reason: "default export is not an object" };
   }
   const p = candidate;
-  const required = [
-    "name",
-    "label",
-    "tier",
-    "tokenBudget",
-    "timeoutMs",
-    "version",
-    "resolve",
-    "isAvailable"
-  ];
-  for (const field of required) {
-    if (p[field] === void 0 || p[field] === null) {
-      return { plugin: null, reason: `missing required field: ${field}` };
-    }
+  if (typeof p.name !== "string" || p.name.length === 0) {
+    return { plugin: null, reason: "name must be a non-empty string" };
   }
-  if (typeof p.resolve !== "function") {
-    return { plugin: null, reason: "resolve must be a function" };
+  if (typeof p.label !== "string" || p.label.length === 0) {
+    return { plugin: null, reason: `[${p.name}] label must be a non-empty string` };
   }
-  if (typeof p.isAvailable !== "function") {
-    return { plugin: null, reason: "isAvailable must be a function" };
+  if (typeof p.version !== "string" || p.version.length === 0) {
+    return { plugin: null, reason: `[${p.name}] version must be a non-empty string` };
   }
-  if (p.tier !== 1 && p.tier !== 2) {
-    return { plugin: null, reason: `tier must be 1 or 2 (got ${String(p.tier)})` };
+  const hasMcpConfig = p.mcpConfig !== void 0 && p.mcpConfig !== null;
+  const hasResolve = typeof p.resolve === "function";
+  if (!hasMcpConfig && !hasResolve) {
+    return {
+      plugin: null,
+      reason: `[${p.name}] plugin needs either a resolve() function or an mcpConfig declaration`
+    };
   }
-  if (typeof p.name !== "string" || p.name.length === 0) {
-    return { plugin: null, reason: "name must be a non-empty string" };
+  if (hasResolve) {
+    const classicRequired = [
+      "tier",
+      "tokenBudget",
+      "timeoutMs",
+      "isAvailable"
+    ];
+    for (const field of classicRequired) {
+      if (p[field] === void 0 || p[field] === null) {
+        return { plugin: null, reason: `[${p.name}] missing required field: ${field}` };
+      }
+    }
+    if (typeof p.isAvailable !== "function") {
+      return { plugin: null, reason: `[${p.name}] isAvailable must be a function` };
+    }
+    if (p.tier !== 1 && p.tier !== 2) {
+      return { plugin: null, reason: `[${p.name}] tier must be 1 or 2 (got ${String(p.tier)})` };
+    }
+    return { plugin: candidate, reason: "" };
+  }
+  const rawConfig = p.mcpConfig;
+  const normalizedConfig = {
+    name: p.name,
+    label: p.label,
+    ...rawConfig
+  };
+  const validation = validateProviderConfig(normalizedConfig);
+  if (!validation.ok) {
+    return {
+      plugin: null,
+      reason: `[${p.name}] invalid mcpConfig: ${validation.reason}`
+    };
   }
-  return { plugin: candidate, reason: "" };
+  const mcpProvider = createMcpProvider(
+    validation.value
+  );
+  const merged = {
+    name: p.name,
+    label: p.label,
+    version: p.version,
+    description: p.description,
+    author: p.author,
+    mcpConfig: p.mcpConfig,
+    tier: p.tier ?? mcpProvider.tier,
+    tokenBudget: p.tokenBudget ?? mcpProvider.tokenBudget,
+    timeoutMs: p.timeoutMs ?? mcpProvider.timeoutMs,
+    resolve: mcpProvider.resolve.bind(mcpProvider),
+    isAvailable: mcpProvider.isAvailable.bind(mcpProvider)
+  };
+  return { plugin: merged, reason: "" };
 }
 async function loadPlugins(dir) {
   const pluginsDir = dir ?? getPluginsDir();

package/dist/resolver-H7GXVP73.js

@@ -0,0 +1,21 @@
+import {
+  _resetAvailabilityCache,
+  _resetMcpProvidersCache,
+  boostByMistakes,
+  enforcePerProviderBudget,
+  resolveRichPacket,
+  resolveRichPacketStreaming,
+  warmAllProviders
+} from "./chunk-RJC6RNXJ.js";
+import "./chunk-22INHMKB.js";
+import "./chunk-B4UOE64J.js";
+import "./chunk-645NBY6L.js";
+export {
+  _resetAvailabilityCache,
+  _resetMcpProvidersCache,
+  boostByMistakes,
+  enforcePerProviderBudget,
+  resolveRichPacket,
+  resolveRichPacketStreaming,
+  warmAllProviders
+};

package/dist/serve.js

@@ -9,8 +9,8 @@ import {
   query,
   stats,
   truncateGraphemeSafe
-} from "./chunk-ZVWRIVWQ.js";
-import "./chunk-PEH54LYC.js";
+} from "./chunk-B4UOE64J.js";
+import "./chunk-645NBY6L.js";
 
 // src/serve.ts
 function clampInt(value, defaultValue, min, max) {

package/dist/{server-A6MUVKQK.js → server-2ZQKXJ5M.js}

@@ -11,20 +11,20 @@ import {
 } from "./chunk-N6PPKOPK.js";
 import {
   summarizeHookLog
-} from "./chunk-XFE6ZANP.js";
-import {
-  getComponentStatus
-} from "./chunk-G4U3QOOW.js";
+} from "./chunk-FKY6HIT2.js";
 import {
   readHookLog
 } from "./chunk-KL6NSPVA.js";
+import {
+  getComponentStatus
+} from "./chunk-G4U3QOOW.js";
 import {
   getStore,
   learn,
   query,
   stats
-} from "./chunk-ZVWRIVWQ.js";
-import "./chunk-PEH54LYC.js";
+} from "./chunk-B4UOE64J.js";
+import "./chunk-645NBY6L.js";
 
 // src/server/http.ts
 import { createServer } from "http";
@@ -1093,6 +1093,72 @@ async function handleQuery(req, res, projectRoot) {
     json(res, 500, { error: "Query failed", detail: String(err) });
   }
 }
+async function handleContextStream(req, res, projectRoot) {
+  const url = parseUrl(req);
+  const filePath = url.searchParams.get("file");
+  if (!filePath) {
+    json(res, 400, { error: "Missing required query parameter 'file'" });
+    return;
+  }
+  const lastEventIdHeader = req.headers["last-event-id"];
+  const resumeAfter = (() => {
+    if (typeof lastEventIdHeader !== "string") return -1;
+    const n = parseInt(lastEventIdHeader, 10);
+    return isNaN(n) ? -1 : n;
+  })();
+  res.writeHead(200, {
+    "Content-Type": "text/event-stream",
+    "Cache-Control": "no-cache, no-transform",
+    Connection: "keep-alive",
+    "X-Accel-Buffering": "no",
+    ...corsHeaders(req)
+  });
+  if (typeof res.flushHeaders === "function") res.flushHeaders();
+  const context = {
+    filePath,
+    projectRoot,
+    nodeIds: [],
+    imports: [],
+    hasTests: false,
+    churnRate: 0
+  };
+  const { resolveRichPacketStreaming } = await import("./resolver-H7GXVP73.js");
+  let eventId = 0;
+  let disconnected = false;
+  req.on("close", () => {
+    disconnected = true;
+  });
+  try {
+    for await (const event of resolveRichPacketStreaming(
+      filePath,
+      context
+    )) {
+      if (disconnected) break;
+      if (eventId <= resumeAfter) {
+        eventId++;
+        continue;
+      }
+      const frame = `id: ${eventId}
+event: ${event.type}
+data: ${JSON.stringify(
+        event.type === "provider" ? event.result : { providerCount: event.providerCount, durationMs: event.durationMs }
+      )}
+
+`;
+      try {
+        res.write(frame);
+      } catch {
+        return;
+      }
+      eventId++;
+    }
+  } finally {
+    try {
+      res.end();
+    } catch {
+    }
+  }
+}
 async function handleStats(_req, res, projectRoot) {
   try {
     const result = await stats(projectRoot);
@@ -1405,6 +1471,8 @@ function createHttpServer(projectRoot, port) {
           await handleGraphGodNodes(req, res, projectRoot);
         } else if (req.method === "GET" && path === "/api/sse") {
           handleSSE(req, res, projectRoot);
+        } else if (req.method === "GET" && path === "/context/stream") {
+          await handleContextStream(req, res, projectRoot);
         } else if (req.method === "GET" && (path === "/ui" || path === "/ui/")) {
           res.writeHead(200, {
             "Content-Type": "text/html; charset=utf-8",

package/dist/{windsurf-rules-RWPKBHRD.js → windsurf-rules-XF7MYF6J.js}

@@ -7,7 +7,7 @@ function buildSection(heading, lines) {
   return [`## ${heading}`, "", ...lines, ""].join("\n");
 }
 async function generateWindsurfRules(projectRoot) {
-  const { getStore } = await import("./core-TSXA5XZH.js");
+  const { getStore } = await import("./core-77F2BVYV.js");
   const store = await getStore(projectRoot);
   try {
     const allNodes = store.getAllNodes();

package/dist/{wizard-AOXWMSXW.js → wizard-UH27IO4I.js}

@@ -9,8 +9,8 @@ import {
 import "./chunk-G4U3QOOW.js";
 import {
   init
-} from "./chunk-ZVWRIVWQ.js";
-import "./chunk-PEH54LYC.js";
+} from "./chunk-B4UOE64J.js";
+import "./chunk-645NBY6L.js";
 
 // src/setup/wizard.ts
 import chalk from "chalk";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "engramx",
-  "version": "2.1.0",
-  "description": "The context spine for AI coding agents. 8 providers + pluggable context sources, 3-layer memory cache, web dashboard, multi-IDE support (Claude Code, Cursor, Continue, Zed, Aider, Windsurf, Neovim, Emacs). 88.1% measured session-level token savings. Local SQLite, zero native deps, zero cloud.",
+  "version": "3.0.1",
+  "description": "The context spine for AI coding agents. 9 built-in providers + mcpConfig plugin contract (wrap any MCP server in 10 lines), generic MCP-client aggregator (stdio), pre-mortem mistake-guard, bi-temporal mistake memory, Anthropic Auto-Memory bridge, SSE streaming context packets, dual-emit AGENTS.md+CLAUDE.md. 90.8% measured real-world token savings (reproducible bench included). Local SQLite, zero cloud.",
   "repository": {
     "type": "git",
     "url": "https://github.com/NickCirv/engram.git"
@@ -25,7 +25,9 @@
     "lint": "tsc --noEmit",
     "prepublishOnly": "npm run build",
     "bench": "tsx bench/runner.ts",
-    "stress": "tsx bench/stress-test.ts"
+    "stress": "tsx bench/stress-test.ts",
+    "postinstall": "node scripts/postinstall.mjs",
+    "preuninstall": "node scripts/preuninstall.mjs"
   },
   "keywords": [
     "structural-code-graph",
@@ -51,11 +53,14 @@
   },
   "files": [
     "dist",
+    "scripts/preuninstall.mjs",
+    "scripts/postinstall.mjs",
     "LICENSE",
     "README.md",
     "CHANGELOG.md"
   ],
   "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
     "sql.js": "^1.14.1",

package/scripts/postinstall.mjs

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+/**
+ * postinstall — one-time info banner on `npm install -g engramx`.
+ * Prints the 'what to do next' hint + the clean-uninstall flow so users
+ * don't end up with orphaned hooks (see CHANGELOG v3.0.1 context).
+ *
+ * Contract:
+ *   - Never fails the install. Always exit 0.
+ *   - Respects $CI (quiet in CI environments).
+ *   - Respects $ENGRAM_NO_POSTINSTALL=1 (ops lever for automated rollouts).
+ */
+if (process.env.CI || process.env.ENGRAM_NO_POSTINSTALL === "1") {
+  process.exit(0);
+}
+
+const lines = [
+  "",
+  "  ✅ engramx installed.",
+  "",
+  "  Get started:",
+  "     cd <your-project> && engram setup",
+  "",
+  "  To remove cleanly later (avoids orphaned Claude Code hooks):",
+  "     engram uninstall-hook && npm uninstall -g engramx",
+  "     (npm uninstall -g engramx by itself also works now — preuninstall",
+  "      hook-cleanup is automatic in 3.0.1+)",
+  "",
+  "  Docs: https://github.com/NickCirv/engram",
+  "",
+];
+process.stdout.write(lines.join("\n"));
+process.exit(0);

package/scripts/preuninstall.mjs

@@ -0,0 +1,200 @@
+#!/usr/bin/env node
+/**
+ * preuninstall — cleans up engramx's hook entries in the user's
+ * Claude Code settings BEFORE the binary is removed by npm.
+ *
+ * Why this file exists: without it, `npm uninstall -g engramx` leaves
+ * stale hook entries in ~/.claude/settings.json pointing at a binary
+ * that no longer exists. Claude Code then fires those hooks on every
+ * tool call, exec fails with ENOENT, and user-visible behavior is
+ * "Claude Code stopped executing anything." Reported by @freenow82 in
+ * 3.0.0's post-launch window — see CHANGELOG v3.0.1.
+ *
+ * Contract (critical):
+ *   - NEVER fail the uninstall. We always exit 0. If cleanup hits any
+ *     problem, we print a one-line hint and move on. The user's goal is
+ *     to uninstall; we will not be the thing that blocks them.
+ *   - Self-contained: this script must work even if `engram` is not on
+ *     PATH at script time (npm's script env usually has it, but we're
+ *     defensive — edge cases exist).
+ *   - Scoped conservatively: only touch ~/.claude/settings.json (the
+ *     USER scope, which is what a global install writes to). Do not
+ *     walk arbitrary project directories.
+ *   - Back up before edit. Atomic rename on write.
+ */
+import { existsSync, readFileSync, writeFileSync, copyFileSync, renameSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+const SETTINGS_PATH = join(homedir(), ".claude", "settings.json");
+
+// ── safe helpers ────────────────────────────────────────────────────
+
+function parseJsonSafe(text) {
+  try {
+    return text.trim() ? JSON.parse(text) : {};
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * A hook entry is "engram-owned" if its command references the engram
+ * binary or any engram-related shell. We match conservatively: the
+ * substring "engram" (case-insensitive) anywhere in the command string.
+ * This is aggressive but safe on uninstall — if a user has a hook
+ * unrelated to engramx that happens to contain the word "engram", they
+ * wrote that themselves and can re-add it. On uninstall, err toward
+ * cleaning more rather than leaving orphans.
+ */
+function isEngramHook(entry) {
+  if (!entry || typeof entry !== "object") return false;
+  const cmd = typeof entry.command === "string" ? entry.command : "";
+  return /engram/i.test(cmd);
+}
+
+/**
+ * Walk the entire hooks structure. `hooks` may be:
+ *   hooks[event] = [{ matcher, hooks: [{ command, ... }, ...] }, ...]
+ * We rebuild each inner `hooks` array without engram entries, drop
+ * matchers whose inner array is now empty, drop event keys whose list
+ * is now empty.
+ */
+function stripEngramHooks(settings) {
+  const changes = { hooksRemoved: 0, eventsAffected: new Set() };
+  if (!settings || typeof settings !== "object") return { settings, changes };
+  const { hooks } = settings;
+  if (!hooks || typeof hooks !== "object") return { settings, changes };
+
+  for (const event of Object.keys(hooks)) {
+    const list = Array.isArray(hooks[event]) ? hooks[event] : null;
+    if (!list) continue;
+    const kept = [];
+    for (const matcher of list) {
+      if (!matcher || typeof matcher !== "object") {
+        kept.push(matcher);
+        continue;
+      }
+      const innerHooks = Array.isArray(matcher.hooks) ? matcher.hooks : null;
+      if (!innerHooks) {
+        kept.push(matcher);
+        continue;
+      }
+      const innerKept = innerHooks.filter((h) => {
+        if (isEngramHook(h)) {
+          changes.hooksRemoved++;
+          changes.eventsAffected.add(event);
+          return false;
+        }
+        return true;
+      });
+      if (innerKept.length > 0) {
+        kept.push({ ...matcher, hooks: innerKept });
+      } else {
+        // entire matcher was engram-only — drop it
+        changes.eventsAffected.add(event);
+      }
+    }
+    if (kept.length > 0) {
+      hooks[event] = kept;
+    } else {
+      delete hooks[event];
+    }
+  }
+
+  // If hooks is now empty, drop the key entirely
+  if (hooks && Object.keys(hooks).length === 0) {
+    delete settings.hooks;
+  }
+
+  // Also drop engram statusLine (HUD)
+  if (
+    settings.statusLine &&
+    typeof settings.statusLine === "object" &&
+    typeof settings.statusLine.command === "string" &&
+    /engram/i.test(settings.statusLine.command)
+  ) {
+    delete settings.statusLine;
+    changes.eventsAffected.add("statusLine");
+  }
+
+  return { settings, changes };
+}
+
+// ── main ────────────────────────────────────────────────────────────
+
+function main() {
+  // If no settings file, nothing to clean. Silent exit.
+  if (!existsSync(SETTINGS_PATH)) {
+    return;
+  }
+
+  let raw;
+  try {
+    raw = readFileSync(SETTINGS_PATH, "utf-8");
+  } catch {
+    return; // unreadable — leave alone, user will handle
+  }
+
+  const parsed = parseJsonSafe(raw);
+  if (parsed === null) {
+    console.log(
+      "[engramx preuninstall] skipped: could not parse " +
+        SETTINGS_PATH +
+        " (settings unchanged)."
+    );
+    return;
+  }
+
+  const { settings, changes } = stripEngramHooks(parsed);
+  if (changes.hooksRemoved === 0 && changes.eventsAffected.size === 0) {
+    return; // nothing to do
+  }
+
+  // Back up before any write.
+  const backupPath = `${SETTINGS_PATH}.engramx-preuninstall-${new Date()
+    .toISOString()
+    .replace(/[:.]/g, "-")}.bak`;
+  try {
+    copyFileSync(SETTINGS_PATH, backupPath);
+  } catch {
+    // if we can't back up, don't write — safety first
+    console.log(
+      "[engramx preuninstall] skipped: could not write backup next to " +
+        SETTINGS_PATH +
+        " (settings unchanged)."
+    );
+    return;
+  }
+
+  // Atomic write via rename.
+  try {
+    const tmp = `${SETTINGS_PATH}.engramx-preuninstall-tmp`;
+    writeFileSync(tmp, JSON.stringify(settings, null, 2) + "\n");
+    renameSync(tmp, SETTINGS_PATH);
+  } catch (err) {
+    console.log(
+      "[engramx preuninstall] skipped: " + String(err) + " (settings unchanged)."
+    );
+    return;
+  }
+
+  console.log(
+    `[engramx] cleaned up ${changes.hooksRemoved} hook entr${changes.hooksRemoved === 1 ? "y" : "ies"} from ${SETTINGS_PATH}`
+  );
+  console.log(`[engramx] backup saved: ${backupPath}`);
+  console.log(
+    "[engramx] if anything looks off, restore with: cp " +
+      backupPath +
+      " " +
+      SETTINGS_PATH
+  );
+}
+
+try {
+  main();
+} catch (err) {
+  // HARD REQUIREMENT: never fail uninstall. Swallow anything.
+  console.log("[engramx preuninstall] error (ignored): " + String(err));
+}
+process.exit(0);

package/dist/{tuner-KFNNGKG3.js → tuner-Y2YENAZC.js}

@@ -1,10 +1,10 @@
+import {
+  readHookLog
+} from "./chunk-KL6NSPVA.js";
 import {
   readConfig,
   writeConfig
 } from "./chunk-22INHMKB.js";
-import {
-  readHookLog
-} from "./chunk-KL6NSPVA.js";
 
 // src/tuner/index.ts
 var MIN_CONFIDENCE_SAMPLES = 10;