heyspex 0.1.0

package/scripts/check-mcp-freshness.mjs

@@ -0,0 +1,379 @@
+#!/usr/bin/env node
+/**
+ * check-mcp-freshness — cheap ground-truth answer to "is the RUNNING heyspex
+ * MCP server (vendor/heyspex-mcp/cli.mjs) the same build as the code on disk?"
+ *
+ * Why this exists: the MCP server is a long-running stdio process. MCP tool
+ * schemas are registered once at process start, so an edit to
+ * `vendor/heyspex-mcp/*.mjs` (yours or the overnight factory's) does NOT reach
+ * the running server until it restarts. On 2026-07-12 this produced a
+ * promotion deadlock — the running server enforced a newly-shipped
+ * sufficiency gate but silently stripped the `force_promote` override that
+ * shipped with it, because its in-memory tool schema predated the param.
+ * See [[HS-G263-DIAG-2F0X-stale-heyspex-mcp-server-enforces-new]] /
+ * [[mcp-server-restart-after-vendor-updates]].
+ *
+ * The fix: a freshness handshake.
+ *   1. At server startup, cli.mjs calls `writeBuildRecord()` here, which
+ *      hashes the CONTENTS of every `vendor/heyspex-mcp/*.mjs` file (sorted by
+ *      name for a stable digest) and writes the fingerprint + startedAt + pid
+ *      to `.heyspex/mcp-server-build.json`.
+ *   2. Any time later, `checkFreshness()` recomputes the fingerprint from disk
+ *      and compares it to that recorded build — a mismatch means vendor code
+ *      changed since the server started, i.e. the running process is stale.
+ *
+ * Per-process scoping ([[HS-H29P-8XLD-DIAG-mcp-freshness-handshake-is-a-single]]):
+ * the single shared record is last-writer-wins, so with several concurrent
+ * cli.mjs processes a stale-but-running server could read "fresh" off another
+ * process's restart. writeBuildRecord() therefore ALSO writes
+ * `.heyspex/mcp-server-builds/<pid>.json` ({ pid, sessionId, startedAt,
+ * fingerprint }) and prunes dead-pid records, and `checkFreshness({ pid })`
+ * (or `{ sessionId }`, or CLI `--pid <n>`) answers for that one process.
+ * Unscoped verdicts carry scope: "machine-wide (unscoped — may be another
+ * process)".
+ *
+ * Three faces share this core (per the "capability = core → MCP + CLI" rule):
+ *   - Server startup   vendor/heyspex-mcp/cli.mjs calls writeBuildRecord()
+ *   - SessionStart hook scripts/claude-hooks/check-mcp-freshness-hook.mjs
+ *   - CLI              node scripts/check-mcp-freshness.mjs [--json]
+ *
+ * Run directly:  node scripts/check-mcp-freshness.mjs [--json]
+ *   exit 0 + "fresh"            recorded fingerprint matches code on disk
+ *   exit 0 + "unknown freshness" no build record (server predates this
+ *                                feature, or the file is missing/corrupt) —
+ *                                safe: never crashes, never false-flags stale
+ *   exit 1 + loud one-line warning   recorded fingerprint disagrees with code
+ *                                    on disk — the running server is STALE
+ */
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+function defaultVaultRoot() {
+  // Honor the same override the hs CLI / dev-server-status.mjs use; otherwise
+  // fall back to this file's own location (it lives at <vaultRoot>/scripts/,
+  // so one level up is the root).
+  if (process.env.HS_VAULT_ROOT) return process.env.HS_VAULT_ROOT;
+  return path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+}
+
+function defaultVendorDir(vaultRoot) {
+  return path.join(vaultRoot, 'vendor', 'heyspex-mcp');
+}
+
+function defaultBuildFile(vaultRoot) {
+  return path.join(vaultRoot, '.heyspex', 'mcp-server-build.json');
+}
+
+function defaultBuildsDir(vaultRoot) {
+  return path.join(vaultRoot, '.heyspex', 'mcp-server-builds');
+}
+
+/**
+ * Best-effort session id from the environment. Deliberately dependency-free
+ * (no vendor/ import): the MCP server's own identity detection lives in
+ * vendor/heyspex-mcp, but this module must stay importable standalone.
+ */
+function detectSessionIdFromEnv(env = process.env) {
+  return (
+    env.CLAUDE_CODE_SESSION_ID ||
+    env.CLAUDE_SESSION_ID ||
+    env.HS_SESSION_ID ||
+    null
+  );
+}
+
+/**
+ * Is `pid` a live process? `process.kill(pid, 0)` sends no signal, only
+ * checks existence. EPERM means "exists but not ours" — that is alive.
+ */
+export function pidAlive(pid) {
+  if (typeof pid !== 'number' || !Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err && err.code === 'EPERM';
+  }
+}
+
+/**
+ * Opportunistic hygiene: delete per-process records in `buildsDir` whose pid
+ * is no longer alive. `keepPid` (the record about to be written) is never
+ * pruned. Never throws.
+ */
+function pruneDeadRecords(buildsDir, keepPid) {
+  let entries;
+  try {
+    entries = fs.readdirSync(buildsDir, { withFileTypes: true });
+  } catch {
+    return; // directory missing — nothing to prune
+  }
+  for (const e of entries) {
+    if (!e.isFile() || !/^\d+\.json$/.test(e.name)) continue;
+    const recordPid = Number(e.name.slice(0, -'.json'.length));
+    if (recordPid === keepPid) continue;
+    if (pidAlive(recordPid)) continue;
+    try {
+      fs.rmSync(path.join(buildsDir, e.name), { force: true });
+    } catch {
+      // best-effort — a locked/vanished file must not break startup
+    }
+  }
+}
+
+/**
+ * sha256 over the sorted (name, content) pairs of every `*.mjs` file directly
+ * under `vendorDir` (no recursion — matches the vendor/heyspex-mcp/*.mjs glob
+ * this class of bug is scoped to). Contents, not mtimes, so a checkout/rebase
+ * that preserves bytes but changes mtimes never false-flags stale, and a
+ * whitespace-only edit correctly does flag stale.
+ */
+export function computeFingerprint(vendorDir) {
+  let entries;
+  try {
+    entries = fs.readdirSync(vendorDir, { withFileTypes: true });
+  } catch {
+    return { fingerprint: null, fileCount: 0, files: [] };
+  }
+  const files = entries
+    .filter((e) => e.isFile() && e.name.endsWith('.mjs'))
+    .map((e) => e.name)
+    .sort();
+  const hash = createHash('sha256');
+  for (const name of files) {
+    let content;
+    try {
+      content = fs.readFileSync(path.join(vendorDir, name));
+    } catch {
+      content = Buffer.from(''); // vanished mid-scan — hash the miss, don't crash
+    }
+    hash.update(name);
+    hash.update('\0');
+    hash.update(content);
+    hash.update('\0');
+  }
+  return { fingerprint: hash.digest('hex'), fileCount: files.length, files };
+}
+
+/**
+ * Called by vendor/heyspex-mcp/cli.mjs at server startup. Writes the current
+ * fingerprint + startedAt + pid to .heyspex/mcp-server-build.json (atomic
+ * write via tmp+rename, mirroring writeConsoleUrlFile in dev-server-status.mjs)
+ * AND a per-process record at .heyspex/mcp-server-builds/<pid>.json so
+ * freshness can be answered for THIS process instead of last-writer-wins
+ * ([[HS-H29P-8XLD-DIAG-mcp-freshness-handshake-is-a-single]]). Dead-pid
+ * records in that directory are pruned opportunistically on each write.
+ * Never throws — startup must not fail because this bookkeeping failed.
+ */
+export function writeBuildRecord({ vaultRoot, vendorDir, buildFile, buildsDir, pid, startedAt, sessionId } = {}) {
+  const root = vaultRoot || defaultVaultRoot();
+  const vDir = vendorDir || defaultVendorDir(root);
+  const target = buildFile || defaultBuildFile(root);
+  const perDir = buildsDir || defaultBuildsDir(root);
+  const { fingerprint, fileCount } = computeFingerprint(vDir);
+  const recordPid = typeof pid === 'number' ? pid : process.pid;
+  const record = {
+    fingerprint,
+    fileCount,
+    startedAt: startedAt || new Date().toISOString(),
+    pid: recordPid,
+    vendorDir: path.relative(root, vDir).split(path.sep).join('/'),
+  };
+  // Legacy machine-wide record — kept for back-compat readers.
+  const dir = path.dirname(target);
+  fs.mkdirSync(dir, { recursive: true });
+  const tmp = `${target}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, `${JSON.stringify(record, null, 2)}\n`, 'utf8');
+  fs.renameSync(tmp, target);
+
+  // Per-process record + opportunistic dead-pid pruning. Best-effort: a
+  // failure here must never take server startup down with it.
+  try {
+    fs.mkdirSync(perDir, { recursive: true });
+    pruneDeadRecords(perDir, recordPid);
+    const perRecord = {
+      pid: recordPid,
+      sessionId: sessionId !== undefined ? sessionId : detectSessionIdFromEnv(),
+      startedAt: record.startedAt,
+      fingerprint,
+      fileCount,
+      vendorDir: record.vendorDir,
+    };
+    const perTarget = path.join(perDir, `${recordPid}.json`);
+    const perTmp = `${perTarget}.${process.pid}.tmp`;
+    fs.writeFileSync(perTmp, `${JSON.stringify(perRecord, null, 2)}\n`, 'utf8');
+    fs.renameSync(perTmp, perTarget);
+    record.perProcessRecord = perRecord;
+  } catch {
+    // legacy record already landed — per-process bookkeeping is best-effort
+  }
+  return record;
+}
+
+/** Verdict label for legacy unscoped checks — the single shared file answers
+ *  for the whole machine, not necessarily the caller's own server process. */
+export const UNSCOPED_SCOPE_LABEL = 'machine-wide (unscoped — may be another process)';
+
+/** Read + JSON-parse a per-process record file; null on any failure. */
+function readRecordFile(file) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+    return parsed && typeof parsed === 'object' ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Find the per-process record for a sessionId (latest startedAt wins). */
+function findRecordBySession(buildsDir, sessionId) {
+  let entries;
+  try {
+    entries = fs.readdirSync(buildsDir, { withFileTypes: true });
+  } catch {
+    return null;
+  }
+  let best = null;
+  for (const e of entries) {
+    if (!e.isFile() || !/^\d+\.json$/.test(e.name)) continue;
+    const rec = readRecordFile(path.join(buildsDir, e.name));
+    if (!rec || rec.sessionId !== sessionId) continue;
+    if (!best || String(rec.startedAt || '') > String(best.startedAt || '')) best = rec;
+  }
+  return best;
+}
+
+/**
+ * Ground-truth freshness verdict: recompute the fingerprint from disk and
+ * compare to the recorded build. Never throws.
+ *
+ * Optional scoping (`{ pid }` or `{ sessionId }`) answers for ONE server
+ * process via its `.heyspex/mcp-server-builds/<pid>.json` record: the pid
+ * must be alive, and ITS fingerprint is compared against current code — so a
+ * live-but-stale process reads stale even when another process restarted
+ * fresh more recently. Unscoped calls keep legacy single-file behavior but
+ * the verdict carries `scope: UNSCOPED_SCOPE_LABEL`.
+ *
+ * Returns { status: 'fresh' | 'stale' | 'unknown', message, scope, current, recorded }.
+ */
+export function checkFreshness({ vaultRoot, vendorDir, buildFile, buildsDir, pid, sessionId } = {}) {
+  const root = vaultRoot || defaultVaultRoot();
+  const vDir = vendorDir || defaultVendorDir(root);
+  const current = computeFingerprint(vDir);
+
+  // ---- Scoped path: answer for one specific server process ----------------
+  if (pid !== undefined || sessionId !== undefined) {
+    const perDir = buildsDir || defaultBuildsDir(root);
+    const scope = pid !== undefined ? `process ${pid}` : `session ${sessionId}`;
+    const recorded =
+      pid !== undefined
+        ? readRecordFile(path.join(perDir, `${pid}.json`))
+        : findRecordBySession(perDir, sessionId);
+
+    if (!recorded || typeof recorded.fingerprint !== 'string') {
+      return {
+        status: 'unknown',
+        message:
+          `heyspex MCP server freshness (${scope}): unknown — no per-process build ` +
+          'record in .heyspex/mcp-server-builds/ (that server predates the per-process ' +
+          'handshake, or never started). Restart it to establish one.',
+        scope,
+        current,
+        recorded: null,
+      };
+    }
+
+    if (!pidAlive(recorded.pid)) {
+      return {
+        status: 'unknown',
+        message:
+          `heyspex MCP server freshness (${scope}): unknown — recorded pid ${recorded.pid} ` +
+          'is no longer alive; the record is an orphan, not a running server.',
+        scope,
+        current,
+        recorded,
+      };
+    }
+
+    if (recorded.fingerprint === current.fingerprint) {
+      return {
+        status: 'fresh',
+        message: `heyspex MCP server (${scope}) is fresh.`,
+        scope,
+        current,
+        recorded,
+      };
+    }
+
+    const startedAt = recorded.startedAt || 'unknown time';
+    return {
+      status: 'stale',
+      message:
+        `heyspex MCP server (${scope}) is STALE — restart it: pid ${recorded.pid} started ` +
+        `${startedAt}, code changed since (another process restarting fresh does not make it fresh).`,
+      scope,
+      current,
+      recorded,
+    };
+  }
+
+  // ---- Unscoped legacy path: last-writer-wins machine-wide record ---------
+  const target = buildFile || defaultBuildFile(root);
+  let recorded = null;
+  try {
+    recorded = JSON.parse(fs.readFileSync(target, 'utf8'));
+  } catch {
+    recorded = null; // missing / unreadable / malformed — treated as "no record"
+  }
+
+  const scope = UNSCOPED_SCOPE_LABEL;
+
+  if (!recorded || typeof recorded.fingerprint !== 'string') {
+    return {
+      status: 'unknown',
+      message:
+        'heyspex MCP server freshness: unknown freshness (no build record at ' +
+        '.heyspex/mcp-server-build.json — the running server predates the freshness ' +
+        'handshake, or the file is missing/corrupt). Restart the server to establish one.',
+      scope,
+      current,
+      recorded: null,
+    };
+  }
+
+  if (recorded.fingerprint === current.fingerprint) {
+    return { status: 'fresh', message: 'heyspex MCP server is fresh.', scope, current, recorded };
+  }
+
+  const startedAt = recorded.startedAt || 'unknown time';
+  return {
+    status: 'stale',
+    message: `heyspex MCP server is STALE — restart it: started ${startedAt}, code changed since.`,
+    scope,
+    current,
+    recorded,
+  };
+}
+
+// ---- CLI entrypoint --------------------------------------------------------
+
+const invokedDirectly = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (invokedDirectly) {
+  const argv = process.argv.slice(2);
+  const asJson = argv.includes('--json');
+  // Optional scoping: --pid=<n> / --pid <n> answers for that server process
+  // via its per-process record; default stays the legacy unscoped check.
+  let pid;
+  for (let i = 0; i < argv.length; i += 1) {
+    if (argv[i] === '--pid' && argv[i + 1] !== undefined) pid = Number(argv[i + 1]);
+    else if (argv[i].startsWith('--pid=')) pid = Number(argv[i].slice('--pid='.length));
+  }
+  const result = checkFreshness(Number.isInteger(pid) && pid > 0 ? { pid } : {});
+  if (asJson) {
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  } else {
+    process.stdout.write(`${result.message}\n`);
+  }
+  process.exit(result.status === 'stale' ? 1 : 0);
+}