engramx 2.0.2 → 2.1.0

package/CHANGELOG.md

@@ -4,6 +4,207 @@ All notable changes to engram are documented here. Format based on
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versioning follows
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [2.1.0] — 2026-04-21 — "Reliability + Zero-Friction Install"
+
+First release in the v2.1 / v2.2 / v3.0 elevation trilogy. Design spec
+at `docs/superpowers/specs/2026-04-20-engram-elevation-trilogy-design.md`.
+
+Headline: `engram setup` is the new one-command first-run flow. Users
+go from `npm install -g engramx` to a working Sentinel hook + indexed
+graph in under 30 seconds. `engram doctor` reports component health
+with remediation hints. `engram update` ships future hotfixes to every
+install without surprise — passive notify, zero telemetry, one-command
+upgrade. Plus fixes for issue #11 (AST/LSP path bug in flattened
+bundles) and issue #14's Bash-ops half (auto-reindex on `rm`/`mv`/
+`git rm` via an opt-in PostToolUse gate).
+
+Contributor credit this release: [@gabiudrescu](https://github.com/gabiudrescu)
+for PR #13 (reindex CLI + `install-hook --auto-reindex`), PR #12
+(watcher prune on delete/rename), and the original v2.0.2 security
+disclosure. [@ttessarolo](https://github.com/ttessarolo) for precise
+forensics + suggested fix on issue #11.
+
+### Added — v2.1 "Reliability + Zero-Friction Install" track
+
+- **`engram update`** — one-command self-upgrade.
+  Passive notify on every `engram *` invocation when a newer version is
+  available (cached, at most one line on stderr, throttled to a 7-day
+  registry check). Manual trigger detects the package manager that owns
+  the engram install (npm / pnpm / yarn / bun via install-path markers)
+  and shells out to its global-upgrade command. `--check` for dry-probe,
+  `--force` to bypass the 7-day throttle, `--dry-run` to print the
+  upgrade command without executing it, `--manager <mgr>` override.
+  Zero telemetry: the only network call is an anonymous GET to
+  `registry.npmjs.org/engramx/latest`. `ENGRAM_NO_UPDATE_CHECK=1` and
+  `$CI` disable the entire subsystem. Addresses the "1,300 weekly
+  downloads, 10/day organic, near-zero hotfix reach" problem.
+
+- **`engram doctor`** — component health report with remediation hints.
+  Wraps existing probes (HTTP, LSP, AST, IDE adapters) plus four new
+  checks: engram version freshness, `.engram/graph.db` presence,
+  Sentinel hook installation, IDE adapter count. Each check emits
+  severity (ok / warn / fail) + detail + optional remediation. Exit
+  code reflects overall severity (0 ok, 1 warn, 2 fail) so `doctor`
+  is CI-friendly. `--verbose` shows remediation hints; `--json` /
+  `--export` emits redacted JSON for bug-report attachment
+  (`projectRoot` intentionally omitted — can contain usernames).
+
+- **`engram setup`** — zero-friction first-run wizard. One command for
+  "go from cloned repo to working engram in under 30 seconds."
+  Runs `init` (if `.engram/graph.db` missing) → `install-hook` (with
+  prompted scope, `local` default) → detects IDE adapters (Cursor,
+  Windsurf, Continue.dev, Aider) and suggests the matching `gen-*`
+  command for each → finishes with a `doctor` summary. Each step is
+  idempotent. `--yes` runs with defaults; `--dry-run` prints intent
+  without acting; `--scope` controls the install-hook scope. Drops
+  install-to-first-value from 4 commands to 1.
+
+- **`engram init --with-hook`** — shorthand for `init` followed by
+  `install-hook` (local scope, idempotent). The #1 thing every user
+  does after `init` was `install-hook`; now it's one step.
+
+- **First-run hint.** On any `engram` subcommand invoked in a repo
+  lacking `.engram/graph.db`, print one line on stderr:
+  `💡 First time in this repo? Run 'engram setup' for a zero-friction install.`
+  Throttled via `~/.engram/first-run-shown` (fires once per machine,
+  not per repo). Silenced in `$CI`, under `ENGRAM_NO_UPDATE_CHECK=1`,
+  and under the JSON-stdout commands (`intercept`, `cursor-intercept`,
+  `hud-label`, `setup`, `init`, `update`, `doctor`) so neither
+  pollutes the hook protocol.
+
+- **Bash PostToolUse parser for auto-reindex** — closes half of
+  [#14](https://github.com/NickCirv/engram/issues/14).
+  `src/intercept/handlers/bash-postool.ts` parses file-mutating Bash
+  commands (`rm`, `mv`, `cp`, `git rm`, `git mv`, single-redirect
+  `<cmd> > <dst>`) into `FileOp { action, path }` records. Strict
+  parser: globs, pipes, subshells, command-substitution, directory
+  ops, and `touch` all pass through untouched. Wired into the
+  PostToolUse observer path in `handlers/post-tool.ts` — on Bash
+  PostToolUse events, each op is handed to `syncFile()` fire-and-forget.
+  Gated by `ENGRAM_AUTO_REINDEX=1` opt-in until
+  [#13](https://github.com/NickCirv/engram/pull/13)'s install-hook
+  `--auto-reindex` flag lands; that flag will toggle the env gate
+  implicitly.
+
+### Fixed — v2.1 reliability
+
+- **AST grammar detection in flattened bundles**
+  ([#11](https://github.com/NickCirv/engram/issues/11) partial).
+  When `tsup`/`esbuild` flattens chunks to `engramx/dist/chunk-*.js`,
+  `import.meta.url` resolves to `engramx/dist` and the previous
+  candidates (`../grammars` and `../../dist/grammars`) both missed the
+  actual grammar dir. Added `join(here, "grammars")` as the first
+  candidate; dev-time layout (`src/intercept/`) still works via the
+  third candidate. Thanks [@ttessarolo](https://github.com/ttessarolo).
+
+- **LSP socket candidate coverage**
+  ([#11](https://github.com/NickCirv/engram/issues/11) partial).
+  `checkLsp` was looking for two socket names while
+  `lsp-connection.ts::candidateSockets()` probes six. Synced the list
+  so HUD availability matches actual provider availability. Kept
+  `.engram/lsp-available` as an explicit user opt-in marker for
+  back-compat.
+
+### Fixed
+
+- **Locale-independent number formatting across the codebase.** All 10
+  `Number.prototype.toLocaleString()` callsites in `src/cli.ts`,
+  `src/serve.ts`, `src/dashboard.ts`, and `src/intercept/stats.ts` have
+  been migrated to a shared `formatThousands()` helper in
+  `src/graph/render-utils.ts`. Two wins:
+
+  1. **Deterministic performance.** First-call ICU init on Windows Node
+     has been observed to take multiple seconds in GitHub Actions VMs,
+     flaking tests at the 5000ms default timeout (seen on
+     `tests/intercept/stats.test.ts > formatStatsSummary` post-merge on
+     `9f99f5b`). The regex-based helper runs in microseconds with no
+     ICU dependency.
+  2. **Locale independence.** `toLocaleString()` emits `"1,234"` on
+     en-US but `"1.234"` on de-DE and `"1 234"` on fr-FR, giving users
+     running engram in non-US shells inconsistent output. All CLI +
+     MCP server + dashboard numbers now render with commas regardless
+     of system locale.
+
+  Added `tests/render-utils.test.ts > formatThousands` — 6 tests
+  covering single-digit, multi-group, negative, and locale-stable cases.
+  Also added `vitest.config.ts` with CI-only `retry: 1` +
+  `testTimeout: 15000ms` as defense-in-depth against other cold-worker
+  flakes.
+
+- **`engram watch` now prunes graph nodes when watched files are deleted
+  or renamed** ([#9](https://github.com/NickCirv/engram/issues/9),
+  [#12](https://github.com/NickCirv/engram/pull/12)). Previously the
+  watcher only subscribed to `change` events, silently ignoring the
+  `rename` events that `fs.watch` fires for create/unlink across all
+  platforms. Deletions left stale nodes in the graph until the next
+  `engram init`; renames produced duplicate nodes under the old and new
+  `sourceFile` paths. Thanks [@gabiudrescu](https://github.com/gabiudrescu).
+
+### Added
+
+- **`syncFile(absPath, root)`** exported from `src/watcher.ts` — the shared
+  "exists → reindex; gone (and was indexed) → prune" primitive reused by
+  the upcoming `engram reindex` CLI subcommand ([#8](https://github.com/NickCirv/engram/issues/8)).
+  Returns a discriminated `SyncResult` (`indexed` | `pruned` | `skipped`).
+- **`GraphStore.countBySourceFile(relPath)`** — noise-reduction gate so
+  `onDelete` only fires for files the graph actually indexed.
+- **`onDelete` callback on `WatchOptions`** — fires with `(filePath, prunedCount)`
+  when the watcher prunes a deleted file's nodes.
+- **`× <path> pruned (N nodes)`** log line in `engram watch`, distinct from
+  the existing green `↻` reindex line.
+- **`gen-cursor --watch`, `gen-aider --watch`, `gen-windsurfrules --watch`**
+  now regenerate their output files on source-file delete (not just on
+  reindex), so generated artifacts no longer keep stale references to
+  deleted sources.
+- **`engram reindex <file>` CLI subcommand**
+  ([#8](https://github.com/NickCirv/engram/issues/8)) — re-indexes a
+  single file into the knowledge graph. The missing primitive for per-
+  edit freshness: Claude Code PostToolUse hooks, editor plugins, and CI
+  can now keep the graph in sync without running a long-lived watcher.
+  Reuses `syncFile()` so semantics match `engram watch`: exists →
+  reindex; missing-but-previously-indexed → prune; unsupported ext or
+  ignored directory → silent exit 0 (safe to fire on every edit). On
+  success prints a single line `engram: reindexed <file> (<N> nodes)`
+  (or `pruned`) using locale-stable `formatThousands`. `--verbose`
+  surfaces stack traces; default error output is a single stderr line.
+  Missing graph exits 1 with `engram: no graph found at <root>. Run
+  'engram init' first.`, matching `engram watch`.
+- **`formatReindexLine(result, displayPath)`** exported from
+  `src/watcher.ts` — pure formatter shared by the new subcommand. Returns
+  `null` for skipped results so callers stay silent.
+- **`engram reindex-hook` subcommand + `engram install-hook --auto-reindex`**
+  ([#8](https://github.com/NickCirv/engram/issues/8), opt-in auto-wire).
+  `reindex-hook` reads Claude Code's PostToolUse payload from stdin and
+  re-indexes `tool_input.file_path` via the shared `syncFile()` primitive.
+  Contract: ALWAYS exits 0 — malformed JSON, missing fields, non-project
+  `cwd`, and all internal errors resolve to a silent no-op so the hook
+  can never fail Claude Code's tool cycle. `install-hook --auto-reindex`
+  appends a second PostToolUse entry with matcher `Edit|Write|MultiEdit`
+  calling `engram reindex-hook`; off by default so existing users aren't
+  surprised. The new entry is recognized by `isEngramHookEntry()` so
+  `engram uninstall-hook` strips it alongside the primary intercept
+  entries. Idempotent — reinstalling with `--auto-reindex` is a no-op
+  when the entry already exists.
+- **`runReindexHook(payload)`** exported from `src/watcher.ts` — the
+  pure async handler behind the `reindex-hook` subcommand. Validates
+  payload shape, resolves project root from `cwd`, delegates to
+  `syncFile`. Swallows every error.
+- **`buildReindexHookEntry()` + `ENGRAM_REINDEX_HOOK_MATCHER`
+  (`"Edit|Write|MultiEdit"`) + `DEFAULT_ENGRAM_REINDEX_HOOK_COMMAND`
+  (`"engram reindex-hook"`)** exported from `src/intercept/installer.ts`
+  — the data primitives for the optional entry. Added
+  `InstallOptions.autoReindex` and `InstallResult.autoReindexAdded` to
+  thread the opt-in through the existing installer surface.
+
+### Notes
+
+- Directory deletion (`rm -rf src/foo`) is intentionally not handled by the
+  watcher — `fs.watch` fires a single rename event on the directory path
+  with no per-file information. A full `engram init` handles that case
+  today; per-file directory-prefix pruning is tracked for v2.2.
+
 ## [2.0.2] — 2026-04-18 — Security hotfix: HTTP server auth & CORS
 
 **This is a security release. Upgrade immediately if you run `engram server`

package/README.md

@@ -2,6 +2,35 @@
   <img src="assets/banner.png" alt="engram — AI coding memory" width="100%">
 </p>
 
+<!-- ============================================================
+     24-second product showcase (Hyperframes-rendered MP4 + WebM).
+     Source: docs/demos/showcase.html · scenes drive both the
+     live HTML player and this MP4. Edit scene-table.md to change.
+     If the MP4 isn't rendered yet, GitHub gracefully shows the
+     poster image and links to the live HTML player.
+     ============================================================ -->
+<p align="center">
+  <video src="https://raw.githubusercontent.com/NickCirv/engram/main/docs/demos/showcase.mp4"
+         controls
+         muted
+         playsinline
+         poster="docs/demos/poster.svg"
+         width="100%">
+    <a href="docs/demos/showcase.html">
+      <img src="docs/demos/poster.svg" alt="engram — 24-second showcase (click to open the live HTML player)" width="100%">
+    </a>
+  </video>
+</p>
+
+<p align="center">
+  <sub>
+    <a href="docs/install.html"><strong>Install Page</strong></a> ·
+    <a href="docs/demos/showcase.html"><strong>Live Demo</strong></a> ·
+    <a href="docs/demos/scene-table.md"><strong>Scene Table</strong></a> ·
+    rendered with <a href="https://github.com/heygen-com/hyperframes">Hyperframes</a>
+  </sub>
+</p>
+
 <p align="center">
   <a href="#install"><strong>Install</strong></a> ·
   <a href="#quickstart"><strong>Quickstart</strong></a> ·
@@ -175,10 +204,23 @@ npm install -g engramx
 
 Requires Node.js 20+. Zero native dependencies. No build tools. Local SQLite via sql.js WASM — no Rust, no Python, no system libs.
 
+> **Prefer a designed walkthrough?** Open [**docs/install.html**](docs/install.html) — three-step install, benefits matrix, IDE coverage, FAQ. Local file, opens in any browser. Brand-matched terminal-mono aesthetic.
+
 ---
 
 ## Quickstart
 
+**One command, zero friction:**
+
+```bash
+cd ~/my-project
+engram setup                     # init + install-hook + adapter detect + doctor
+```
+
+`engram setup` runs the whole first-run flow interactively (or pass `-y` for defaults, `--dry-run` to preview). It is idempotent — safe to re-run, and skips any step already done.
+
+<sub>Prefer the individual commands?</sub>
+
 ```bash
 cd ~/my-project
 engram init                      # scan codebase → .engram/graph.db (~40ms, 0 tokens)
@@ -186,6 +228,16 @@ engram install-hook              # wire the Sentinel into Claude Code
 engram ui                        # open the web dashboard in your browser
 ```
 
+**Diagnostics + self-update:**
+
+```bash
+engram doctor                    # component health + remediation hints (0=ok, 1=warn, 2=fail)
+engram update                    # check + upgrade via detected pkg manager (no telemetry)
+engram update --check            # check only, dry-probe the registry
+```
+
+Set `ENGRAM_NO_UPDATE_CHECK=1` to disable the passive "newer version available" hint on every CLI invocation. `$CI` does the same automatically.
+
 Open a Claude Code session. When the agent reads a well-covered file you will see a system-reminder with the structural summary instead of file contents. After the session:
 
 ```bash
@@ -275,6 +327,7 @@ engram install-hook                  # default: .claude/settings.local.json (git
 engram install-hook --scope project  # .claude/settings.json (committed)
 engram install-hook --scope user     # ~/.claude/settings.json (global)
 engram install-hook --dry-run        # preview changes without writing
+engram install-hook --auto-reindex   # also keep the graph fresh after every Edit/Write/MultiEdit (#8)
 ```
 
 **Kill switch (if anything goes wrong):**
@@ -336,6 +389,8 @@ engram hook-enable               # remove kill switch
 
 ```bash
 engram watch [path]              # live file watcher — incremental re-index on save
+engram reindex <file>            # re-index one file (editor/hook/CI primitive, issue #8)
+engram reindex-hook              # PostToolUse hook entry point (reads JSON from stdin, always exits 0)
 engram dashboard [path]          # live terminal dashboard
 engram hud-label [path]          # JSON label for Claude HUD --extra-cmd integration
 engram hooks install             # install post-commit + post-checkout git hooks

package/dist/{aider-context-BC5R2ZTA.js → aider-context-J557IHIP.js}

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

package/dist/check-2Z3MPZEJ.js

@@ -0,0 +1,12 @@
+import {
+  cachePath,
+  checkForUpdate,
+  isNewer,
+  optedOut
+} from "./chunk-RM2TBOVW.js";
+export {
+  cachePath,
+  checkForUpdate,
+  isNewer,
+  optedOut
+};

package/dist/{chunk-C6GBUOAL.js → chunk-4XA6ENNL.js}

@@ -310,7 +310,7 @@ function writeToFile(filePath, summary) {
   writeFileSync2(filePath, newContent);
 }
 async function autogen(projectRoot, target, task) {
-  const { getStore } = await import("./core-6IY5L6II.js");
+  const { getStore } = await import("./core-TSXA5XZH.js");
   const store = await getStore(projectRoot);
   try {
     let view = VIEWS.general;

package/dist/{chunk-533LR4I7.js → chunk-G4U3QOOW.js}

@@ -1,93 +1,3 @@
-// src/intercept/stats.ts
-var ESTIMATED_TOKENS_PER_READ_DENY = 1200;
-function summarizeHookLog(entries) {
-  const byEvent = {};
-  const byTool = {};
-  const byDecision = {};
-  let readDenyCount = 0;
-  let firstEntryTs = null;
-  let lastEntryTs = null;
-  for (const entry of entries) {
-    const event = entry.event ?? "unknown";
-    byEvent[event] = (byEvent[event] ?? 0) + 1;
-    const tool = entry.tool ?? "unknown";
-    byTool[tool] = (byTool[tool] ?? 0) + 1;
-    if (entry.decision) {
-      byDecision[entry.decision] = (byDecision[entry.decision] ?? 0) + 1;
-    }
-    if (event === "PreToolUse" && tool === "Read" && entry.decision === "deny") {
-      readDenyCount += 1;
-    }
-    const ts = entry.ts;
-    if (typeof ts === "string") {
-      if (firstEntryTs === null || ts < firstEntryTs) firstEntryTs = ts;
-      if (lastEntryTs === null || ts > lastEntryTs) lastEntryTs = ts;
-    }
-  }
-  return {
-    totalInvocations: entries.length,
-    byEvent: Object.freeze(byEvent),
-    byTool: Object.freeze(byTool),
-    byDecision: Object.freeze(byDecision),
-    readDenyCount,
-    estimatedTokensSaved: readDenyCount * ESTIMATED_TOKENS_PER_READ_DENY,
-    firstEntry: firstEntryTs,
-    lastEntry: lastEntryTs
-  };
-}
-function formatStatsSummary(summary) {
-  if (summary.totalInvocations === 0) {
-    return "engram hook stats: no log entries yet.\n\nRun engram install-hook in a project, then use Claude Code to see interceptions.";
-  }
-  const lines = [];
-  lines.push(`engram hook stats (${summary.totalInvocations} invocations)`);
-  lines.push("\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500");
-  if (summary.firstEntry && summary.lastEntry) {
-    lines.push(`Time range: ${summary.firstEntry} \u2192 ${summary.lastEntry}`);
-    lines.push("");
-  }
-  lines.push("By event:");
-  const eventEntries = Object.entries(summary.byEvent).sort(
-    (a, b) => b[1] - a[1]
-  );
-  for (const [event, count] of eventEntries) {
-    const pct = (count / summary.totalInvocations * 100).toFixed(1);
-    lines.push(`  ${event.padEnd(18)} ${String(count).padStart(5)} (${pct}%)`);
-  }
-  lines.push("");
-  lines.push("By tool:");
-  const toolEntries = Object.entries(summary.byTool).filter(([k]) => k !== "unknown").sort((a, b) => b[1] - a[1]);
-  for (const [tool, count] of toolEntries) {
-    lines.push(`  ${tool.padEnd(18)} ${String(count).padStart(5)}`);
-  }
-  if (toolEntries.length === 0) {
-    lines.push("  (no tool-tagged entries)");
-  }
-  lines.push("");
-  const decisionEntries = Object.entries(summary.byDecision);
-  if (decisionEntries.length > 0) {
-    lines.push("PreToolUse decisions:");
-    for (const [decision, count] of decisionEntries.sort(
-      (a, b) => b[1] - a[1]
-    )) {
-      lines.push(`  ${decision.padEnd(18)} ${String(count).padStart(5)}`);
-    }
-    lines.push("");
-  }
-  if (summary.readDenyCount > 0) {
-    lines.push(
-      `Estimated tokens saved: ~${summary.estimatedTokensSaved.toLocaleString()}`
-    );
-    lines.push(
-      `  (${summary.readDenyCount} Read denies \xD7 ${ESTIMATED_TOKENS_PER_READ_DENY} tok/deny avg)`
-    );
-  } else {
-    lines.push("Estimated tokens saved: 0");
-    lines.push("  (no PreToolUse:Read denies recorded yet)");
-  }
-  return lines.join("\n");
-}
-
 // src/intercept/component-status.ts
 import { existsSync, readFileSync, writeFileSync } from "fs";
 import { join, dirname } from "path";
@@ -112,10 +22,16 @@ function checkHttp(projectRoot) {
 }
 function checkLsp(projectRoot) {
   if (existsSync(join(projectRoot, ".engram", "lsp-available"))) return true;
+  const uid = typeof process.getuid === "function" ? process.getuid() : 0;
   const tmp = tmpdir();
   const candidates = [
-    join(tmp, "tsserver.sock"),
-    join(tmp, "typescript-language-server.sock")
+    join(tmp, `tsserver-${uid}.sock`),
+    join(tmp, "lsp-server.sock"),
+    join(tmp, "typescript-language-server.sock"),
+    join(tmp, `pyright-${uid}.sock`),
+    join(tmp, "rust-analyzer.sock"),
+    // Legacy name kept for back-compat with older tsserver installs.
+    join(tmp, "tsserver.sock")
   ];
   return candidates.some((c) => existsSync(c));
 }
@@ -123,10 +39,12 @@ function checkAst(projectRoot) {
   try {
     const here = dirname(fileURLToPath(import.meta.url));
     const candidates = [
+      join(here, "grammars"),
+      // flattened bundle
       join(here, "..", "grammars"),
-      // from dist/intercept/
+      // nested bundle
       join(here, "..", "..", "dist", "grammars")
-      // from src/intercept/ dev
+      // dev-time
     ];
     for (const dir of candidates) {
       if (existsSync(dir)) return true;
@@ -212,9 +130,7 @@ function formatHudStatus(report) {
 }
 
 export {
-  ESTIMATED_TOKENS_PER_READ_DENY,
-  summarizeHookLog,
-  formatStatsSummary,
+  refreshComponentStatus,
   getComponentStatus,
   formatHudStatus
 };

package/dist/chunk-RM2TBOVW.js

@@ -0,0 +1,121 @@
+// src/update/check.ts
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "fs";
+import { homedir } from "os";
+import { dirname, join } from "path";
+var REGISTRY_URL = "https://registry.npmjs.org/engramx/latest";
+var CHECK_INTERVAL_MS = 7 * 24 * 60 * 60 * 1e3;
+var FETCH_TIMEOUT_MS = 1500;
+function cachePath() {
+  return join(homedir(), ".engram", "last-update-check");
+}
+function readCache() {
+  const path = cachePath();
+  if (!existsSync(path)) return null;
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf-8"));
+    if (typeof parsed?.latest === "string" && typeof parsed?.checkedAt === "number") {
+      return parsed;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+function writeCache(entry) {
+  try {
+    const path = cachePath();
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(entry), "utf-8");
+  } catch {
+  }
+}
+function isNewer(a, b) {
+  const parse = (v) => {
+    const m = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?/.exec(v.trim());
+    if (!m) return null;
+    return {
+      major: Number(m[1]),
+      minor: Number(m[2]),
+      patch: Number(m[3]),
+      pre: m[4] ?? null
+    };
+  };
+  const pa = parse(a);
+  const pb = parse(b);
+  if (!pa || !pb) return false;
+  if (pa.major !== pb.major) return pa.major > pb.major;
+  if (pa.minor !== pb.minor) return pa.minor > pb.minor;
+  if (pa.patch !== pb.patch) return pa.patch > pb.patch;
+  if (pa.pre === null && pb.pre !== null) return true;
+  if (pa.pre !== null && pb.pre === null) return false;
+  if (pa.pre === null && pb.pre === null) return false;
+  return (pa.pre ?? "") > (pb.pre ?? "");
+}
+function optedOut() {
+  if (process.env.ENGRAM_NO_UPDATE_CHECK === "1") return true;
+  if (process.env.CI) return true;
+  return false;
+}
+async function fetchLatestFromRegistry() {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+  try {
+    const res = await fetch(REGISTRY_URL, {
+      signal: controller.signal,
+      headers: { accept: "application/json" }
+    });
+    if (!res.ok) return null;
+    const body = await res.json();
+    if (typeof body?.version !== "string") return null;
+    return body.version;
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+async function checkForUpdate(currentVersion, opts = {}) {
+  const base = {
+    skipped: false,
+    current: currentVersion,
+    latest: null,
+    updateAvailable: false,
+    checkedAt: null,
+    fromCache: false
+  };
+  if (!opts.force && optedOut()) {
+    return { ...base, skipped: true };
+  }
+  if (!opts.force) {
+    const cached = readCache();
+    if (cached && Date.now() - cached.checkedAt < CHECK_INTERVAL_MS) {
+      return {
+        ...base,
+        latest: cached.latest,
+        updateAvailable: isNewer(cached.latest, currentVersion),
+        checkedAt: cached.checkedAt,
+        fromCache: true
+      };
+    }
+  }
+  const latest = await fetchLatestFromRegistry();
+  if (!latest) {
+    return { ...base, skipped: !opts.force };
+  }
+  const now = Date.now();
+  writeCache({ latest, checkedAt: now });
+  return {
+    ...base,
+    latest,
+    updateAvailable: isNewer(latest, currentVersion),
+    checkedAt: now,
+    fromCache: false
+  };
+}
+
+export {
+  cachePath,
+  isNewer,
+  optedOut,
+  checkForUpdate
+};