engramx 3.0.0 → 3.0.1

package/CHANGELOG.md

@@ -6,6 +6,46 @@ All notable changes to engram are documented here. Format based on
 
 ## [Unreleased]
 
+## [3.0.1] — 2026-04-24 — "Clean Uninstall"
+
+**Patch release fixing the orphaned-hooks bug reported by @freenow82 within
+hours of 3.0.0 going live on npm. No feature changes — this release is
+purely about not leaving users stranded when they uninstall.**
+
+### The bug (what 3.0.0 shipped with)
+
+`npm uninstall -g engramx` removed the binary from PATH but left the hook
+entries in `~/.claude/settings.json` pointing at a `engram intercept`
+command that no longer existed. Claude Code fires those hooks on every
+tool call — the hook commands failed with ENOENT — and user-visible
+behaviour was "Claude Code stopped executing anything." Recovery required
+reinstalling engramx just to run `engram uninstall-hook` before
+uninstalling again.
+
+That is a bad experience. Sorry to anyone who hit it.
+
+### Fixed
+
+- **`scripts/preuninstall.mjs`** now runs automatically before `npm uninstall -g engramx`. It reads `~/.claude/settings.json`, strips every hook entry that references engram (case-insensitive match on the command string), drops engram's statusLine/HUD, backs up the original to a timestamped `.bak` file, and writes the result atomically via rename. It NEVER fails the uninstall — if the settings file is missing, unparseable, or unwritable, it logs a single-line hint and exits 0. Contract: the user's `npm uninstall` always succeeds, with or without hook cleanup.
+- **`scripts/postinstall.mjs`** prints a one-time info banner on `npm install -g engramx` showing the recommended next step (`engram setup`) and the clean-uninstall flow. Respects `$CI` and `$ENGRAM_NO_POSTINSTALL=1`.
+- **New `engram repair-hooks` alias** — literally the same as `engram uninstall-hook`, but named so users who ended up with orphaned hooks after a bad uninstall can find it by the word they'd actually search for. No code duplication — `commander.alias()`.
+- Both scripts included in the `files` allowlist of `package.json` so they ship in the tarball.
+
+### For users still stranded on 3.0.0
+
+If you ran `npm uninstall -g engramx` before this patch shipped and Claude Code is still broken, you have two paths:
+
+1. **Fast, no reinstall:** edit `~/.claude/settings.json` manually (or run the one-line `jq` filter posted in the 3.0.1 announcement thread) to strip every entry whose `command` contains the word `engram`.
+2. **Works from 3.0.1:** `npm install -g engramx@3.0.1 && engram repair-hooks --scope user` — the install no longer stops execution (hooks are in place), run repair-hooks, then `npm uninstall -g engramx` again if you want engramx gone. This time the preuninstall cleans up automatically.
+
+### Tests
+
+- New regression test: the preuninstall script on a fixture with a mix of engram hooks + unrelated hooks + a custom statusLine verifies 3 engram entries removed, unrelated keys preserved byte-for-byte, backup written, atomic rename completed.
+
+### Thanks
+
+[@freenow82](https://www.reddit.com/user/freenow82) for the bug report and the transparency about the pain it caused. That feedback is the entire point of a public launch — the tool is measurably better for it.
+
 ## [3.0.0] — 2026-04-24 — "Spine"
 
 The biggest engramx release since v1.0. One meticulous release, not a

package/README.md

@@ -99,6 +99,14 @@ It runs on your laptop. It doesn't send your code anywhere. It's Apache 2.0. The
 
 **Want even bigger savings?** Install a plugin. Each one closes a different context leak — see [Plugins multiply the savings](#plugins-multiply-the-savings) below. Drop a 10-line `.mjs` file in `~/.engram/plugins/` and the next session uses it.
 
+**Want out?** Clean uninstall is one command:
+
+```bash
+npm uninstall -g engramx     # 3.0.1+ auto-runs preuninstall hook-cleanup
+```
+
+If you installed 3.0.0 and ran `npm uninstall` before the 3.0.1 patch shipped, your Claude Code hooks may be orphaned. Run `engram repair-hooks --scope user` (install 3.0.1 first if needed) or see the [`CHANGELOG.md`](CHANGELOG.md#301--2026-04-24--clean-uninstall) for the manual `jq`-based recovery one-liner.
+
 ---
 
 ## Proof, not promises

package/dist/cli.js

@@ -2487,7 +2487,7 @@ program.command("install-hook").description("Install engram hook entries into Cl
     );
   }
 );
-program.command("uninstall-hook").description("Remove engram hook entries from Claude Code settings").option("--scope <scope>", "local | project | user", "local").option("-p, --project <path>", "Project directory", ".").action(async (opts) => {
+program.command("uninstall-hook").alias("repair-hooks").description("Remove engram hook entries from Claude Code settings (also: 'repair-hooks' \u2014 same thing, named for users who ended up with orphaned hooks after npm uninstall)").option("--scope <scope>", "local | project | user (default user on fresh runs)", "local").option("-p, --project <path>", "Project directory", ".").action(async (opts) => {
   const settingsPath = resolveSettingsPath(opts.scope, opts.project);
   if (!settingsPath) {
     console.error(chalk2.red(`Unknown scope: ${opts.scope}`));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "engramx",
-  "version": "3.0.0",
+  "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",
@@ -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,6 +53,8 @@
   },
   "files": [
     "dist",
+    "scripts/preuninstall.mjs",
+    "scripts/postinstall.mjs",
     "LICENSE",
     "README.md",
     "CHANGELOG.md"

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);