@pcircle/memesh 4.1.2 → 4.1.4

package/scripts/hooks/session-start.js

@@ -1,16 +1,19 @@
 #!/usr/bin/env node
 
 import { createRequire } from 'module';
+import { spawn } from 'child_process';
 import { createHash } from 'crypto';
 import { homedir } from 'os';
 import { join, basename } from 'path';
-import { existsSync, unlinkSync, rmSync, appendFileSync, chmodSync } from 'fs';
+import { pathToFileURL } from 'url';
+import { existsSync, readFileSync, unlinkSync, rmSync, appendFileSync, chmodSync } from 'fs';
 import {
   buildReferenceContext,
   ensurePrivateDir,
   getMemeshDir,
   isAgenticOrchestrationEnabled,
   isTrustedForAutoContext,
+  readUpdateCheckCache,
   resolvePluginRoot,
   resolveSessionLimit,
   writePrivateJson,
@@ -18,16 +21,326 @@ import {
 
 const require = createRequire(import.meta.url);
 
+// Codex round 37: dist/core/install-channel.js is emitted as ESM
+// (the project's tsconfig produces NodeNext modules). On Node 20.x
+// `require()` against an ESM file throws ERR_REQUIRE_ESM, which
+// silently downgraded all install-channel detection to 'unknown' on
+// the supported floor. Pre-load the module via dynamic `import()`
+// at hook startup using a top-level await — once at process init,
+// not on every call. Falls back to null if the dist file is
+// missing (source checkout pre-build) or fails to load.
+let _installChannelMod = null;
+try {
+  const _pluginRootForInit = resolvePluginRoot(import.meta.url);
+  const _modPath = join(_pluginRootForInit, 'dist/core/install-channel.js');
+  if (existsSync(_modPath)) {
+    _installChannelMod = await import(pathToFileURL(_modPath).href);
+  }
+} catch { /* best-effort — fall through to 'unknown' channel */ }
+
 const dbPath = process.env.MEMESH_DB_PATH || join(homedir(), '.memesh', 'knowledge-graph.db');
 const memeshDir = getMemeshDir(process.env);
 const throttlePath = join(memeshDir, 'session-recalled-files.json');
 const nudgeFlagsDir = join(memeshDir, 'agent-nudge-flags');
 
+/**
+ * Build the strong deprecation warning lines to prepend to the
+ * session-start banner when the installed version has been flagged
+ * by maintainers (typically a security advisory). Returns an empty
+ * array when the cache says nothing to warn about.
+ */
+function buildDeprecationBanner(currentVersion, cache) {
+  if (!cache || cache.currentVersion !== currentVersion) return [];
+  const msg = cache.currentVersionDeprecation;
+  if (typeof msg !== 'string' || msg.length === 0) {
+    // Partial-failure state ONLY: the version lookup answered but
+    // the deprecation sub-call did not. checkSucceeded stays true
+    // exactly in that case. A full registry failure (offline,
+    // blocked) leaves checkSucceeded=false with a generic lastError,
+    // and we must not surface that as a security-style warning —
+    // it's just regular "couldn't reach npm". Gate the banner
+    // strictly on checkSucceeded=true + lastError populated.
+    if (
+      cache.checkSucceeded === true
+      && typeof cache.lastError === 'string'
+      && cache.lastError.length > 0
+    ) {
+      return [
+        '',
+        `ℹ️  MeMesh deprecation status unknown for ${currentVersion}: ${cache.lastError}`,
+        `    Run: memesh status   (retry the lookup once back online)`,
+      ];
+    }
+    return [];
+  }
+  const lines = [
+    '',
+    `⚠️  MeMesh ${currentVersion} is DEPRECATED by maintainers.`,
+    `    ${msg}`,
+  ];
+  // Codex round 36: emit a remediation line for EVERY deprecation
+  // banner — including the cases where the cached `latestVersion`
+  // is null, equal to current, or stale. The previous gate omitted
+  // the action line whenever the cache didn't yet show a strictly-
+  // newer version, leaving users with a security warning and no
+  // follow-up step. doctor / CLI status / dashboard already point
+  // at `memesh update` (or channel equivalents) in those uncertain
+  // cases, and the session-start banner should match — `npm`
+  // resolves @latest at install time, so the command works even
+  // when our local cache is uncertain.
+  const knownUpgradeTarget = Boolean(
+    cache.latestVersion && cache.latestVersion !== currentVersion,
+  );
+  // Codex round 39: the SessionStart hook reads ONLY cached cache
+  // data — there's no fresh lookup happening on this code path.
+  // That means `freshness === 'fresh'` (the strict rule the
+  // dashboard / `memesh status` use to authoritatively say
+  // "no upgrade target yet") can never apply here. Round 38 used a
+  // 24h-window heuristic to fire the no-target message anyway, but
+  // codex correctly flagged that as suppressing the upgrade hint
+  // exactly when a security-advisory fix could ship within the
+  // window. Conservative remediation: always recommend
+  // `memesh update` (which is a harmless no-op when there's truly
+  // no target, and immediately applies a freshly-published fix
+  // when there is one). The "no target yet" message remains
+  // available in `memesh status` (fresh lookup) and the dashboard
+  // (after a Check now click).
+  // Tailor the remediation hint to the install channel. `memesh
+  // update` and `autoUpdate` only work for npm-global installs;
+  // pointing source-checkout / project-local users at those
+  // commands is misleading (especially when the deprecation is a
+  // security advisory). Detect the channel and suggest the
+  // remediation that actually applies.
+  let channel = 'unknown';
+  try {
+    const pluginRoot = resolvePluginRoot(import.meta.url);
+    channel = detectInstallChannelHook(pluginRoot);
+  } catch { /* best-effort — fall through to generic guidance */ }
+
+  if (channel === 'npm-global') {
+    lines.push(
+      knownUpgradeTarget
+        ? `    Run: memesh update   (or set autoUpdate: memesh config set autoUpdate patch)`
+        : `    Run: memesh update   (resolves @latest — or set: memesh config set autoUpdate patch)`,
+    );
+  } else if (channel === 'source-checkout') {
+    lines.push(`    Source checkout: pull and rebuild (\`git pull && npm install && npm run build\`).`);
+  } else if (channel === 'npm-local') {
+    // Codex round 30: the cached `latestVersion` may itself be
+    // stale (cache TTL is 24h and we're already showing a stale
+    // banner). Pinning a specific version risks installing an
+    // already-superseded build that's part of the same security
+    // advisory. `@latest` always resolves to the registry's
+    // current dist-tag at install time, which is the right
+    // remediation for a deprecation/security-advisory banner.
+    lines.push(
+      knownUpgradeTarget
+        ? `    Project-local install: run \`npm install @pcircle/memesh@latest\` in this project (cached upgrade target was ${cache.latestVersion}).`
+        : `    Project-local install: run \`npm install @pcircle/memesh@latest\` in this project.`,
+    );
+  } else {
+    lines.push(
+      knownUpgradeTarget
+        ? `    Upgrade via the install path you used: fetch the latest @pcircle/memesh from npm (cached upgrade target was ${cache.latestVersion}).`
+        : `    Upgrade via the install path you used: fetch the latest @pcircle/memesh from npm.`,
+    );
+  }
+  return lines;
+}
+
+/**
+ * Detect the install channel of the running memesh binary by
+ * delegating to src/core/install-channel.ts via the dist build. The
+ * core helper resolves `npm root -g` so it correctly classifies:
+ *   - POSIX globals at the default prefix (`/usr/local/lib/...`)
+ *   - Windows globals (`%AppData%\npm\...`)
+ *   - Globals at custom prefixes set via `npm config set prefix`
+ *   - Project-local deps under any directory name (no false-positive
+ *     'npm-global' from a path that merely contains `lib`)
+ *
+ * Earlier hook-side regex heuristics agreed with the core logic on
+ * the common cases but disagreed on custom prefixes (false negative
+ * → auto-update silently broken) and on project-local deps living
+ * under `lib/node_modules/...` (false positive → spawning a global
+ * `npm install -g` while the active copy is the local one). Using
+ * the dist module here keeps the hook in lockstep with whatever
+ * `memesh status` says, paying the one-time `npm root -g` cost
+ * (~50-200ms) only on auto-update decision.
+ *
+ * Returns 'npm-global' | 'npm-local' | 'source-checkout' | 'unknown'.
+ * Synchronous + best-effort: any failure in the dist import or the
+ * underlying `npm root -g` call returns 'unknown', and the auto-
+ * update spawn refuses to fire on 'unknown' so we never run
+ * `npm install -g` when we can't confirm it would land where the
+ * user expects.
+ */
+function detectInstallChannelHook(pluginRoot) {
+  if (!_installChannelMod) return 'unknown';
+  try {
+    return _installChannelMod.getCurrentInstallChannel({ packageRoot: pluginRoot });
+  } catch {
+    return 'unknown';
+  }
+}
+
+// Don't fire a fresh-check more often than this. Two parallel
+// session-starts both spawning `memesh status` could otherwise race
+// the cache: a later writer that hits a deprecation-only timeout
+// would overwrite an earlier writer's successful deprecation flag,
+// because each child reads `previous` from the cache *before* its
+// own npm call. The TTL bounds concurrency to one refresh per
+// window per machine, which is enough for the staleness window
+// (24h) to stay accurate.
+const FRESH_CHECK_THROTTLE_MS = 5 * 60 * 1000;
+
+function spawnFreshUpdateCheck(installedVersion) {
+  try {
+    const pluginRoot = resolvePluginRoot(import.meta.url);
+    const cliPath = join(pluginRoot, 'dist/transports/cli/cli.js');
+    if (!existsSync(cliPath)) return false;
+    const fs = require('fs');
+    const dir = join(homedir(), '.memesh');
+    try { ensurePrivateDir(dir); } catch { /* best-effort */ }
+    // Codex round 37: scope the throttle marker to the installed
+    // version. The marker was machine-global, so a refresh started
+    // by a global 4.1.3 install would suppress refreshes for a
+    // sibling project-local 4.1.1 for the next 5 minutes — and the
+    // shared cache it wrote would carry version 4.1.3, so the
+    // 4.1.1 session would skip its banner because
+    // `cache.currentVersion !== currentVersion`. Per-version
+    // markers ensure each install gets its own refresh window.
+    // Sanitize version for filesystem (semver chars only, no path
+    // separators); fall back to 'unknown' if missing.
+    const versionTag = typeof installedVersion === 'string'
+      && /^[0-9A-Za-z.+-]+$/.test(installedVersion)
+      ? installedVersion
+      : 'unknown';
+    const markerPath = join(dir, `last-fresh-refresh.${versionTag}.lock`);
+    // Single-owner claim: O_EXCL atomic create. Codex round 27
+    // caught that the previous temp+rename+readback pattern was
+    // racy — both peers' renames are destructive, so each could
+    // read its own token back and both would spawn a refresh.
+    // O_EXCL is the standard POSIX/libuv primitive that lets at
+    // most one process succeed. Same pattern as
+    // tryAcquireAutoUpdateLock above.
+    const token = `${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
+    const claim = () => {
+      try {
+        const fd = fs.openSync(
+          markerPath,
+          fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL,
+          0o600,
+        );
+        try { fs.writeFileSync(fd, token); } finally { fs.closeSync(fd); }
+        return 'won';
+      } catch (err) {
+        if (err?.code === 'EEXIST') return 'exists';
+        return 'error';
+      }
+    };
+    let result = claim();
+    if (result === 'exists') {
+      // Marker already there. Honor the throttle window: if it's
+      // fresh, a peer owns this slot. If it's stale, take it over
+      // by removing the marker and retrying ONCE — best-effort,
+      // multiple processes may race the unlink but only one can
+      // win the subsequent O_EXCL.
+      let stat;
+      try { stat = fs.statSync(markerPath); } catch { return false; }
+      if (Date.now() - stat.mtimeMs < FRESH_CHECK_THROTTLE_MS) {
+        return false;
+      }
+      try { fs.unlinkSync(markerPath); } catch { /* peer already removed */ }
+      result = claim();
+    }
+    if (result !== 'won') return false;
+    const child = spawn(
+      process.execPath,
+      [cliPath, 'status'],
+      // windowsHide prevents a console-window flash on every session
+      // start on Windows; harmless on POSIX.
+      {
+        detached: true,
+        stdio: 'ignore',
+        env: { ...process.env, MEMESH_UPDATE_REFRESH: '1' },
+        windowsHide: true,
+      },
+    );
+    child.unref();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Run the post-banner update tasks: spawn auto-update if policy + cache
+ * permit, and always refresh the cache for the next session.
+ *
+ * Known one-session delay (documented):
+ *   The very first session after install (or after the cache file is
+ *   deleted) emits the recall summary BEFORE this finally clause
+ *   runs, so a freshly-installed deprecated version sees no
+ *   deprecation banner on session 1. The detached refresh below
+ *   populates the cache for session 2, where the banner and the
+ *   security override fire normally. We deliberately don't do an
+ *   inline synchronous npm fetch here because that would block every
+ *   cold-cache session-start by ~3s for users whose installed version
+ *   is healthy — a worse trade for the common case.
+ *
+ * Idempotent guard: callers should not invoke twice for the same
+ * session — duplicated `npm install -g` spawns would race. We use a
+ * one-shot flag rather than a no-op-on-second-call lock so a coding
+ * mistake produces visible breakage during testing instead of silent
+ * over-spawning.
+ */
+let __postBannerRan = false;
+function runPostBannerUpdateTasks() {
+  if (__postBannerRan) return;
+  __postBannerRan = true;
+  try {
+    let installedVersion = null;
+    try {
+      const pluginRoot = resolvePluginRoot(import.meta.url);
+      const pkg = JSON.parse(readFileSync(join(pluginRoot, 'package.json'), 'utf8'));
+      installedVersion = typeof pkg.version === 'string' ? pkg.version : null;
+    } catch { /* best-effort */ }
+    if (!installedVersion) return;
+    // Auto-update spawn moved to Stop hook (v4.1.4) to avoid TOCTOU race
+    // where npm install -g overwrites dist/ while peer hooks are still reading it.
+    spawnFreshUpdateCheck(installedVersion);
+  } catch {
+    // Best-effort — never crash the hook on a network or fs hiccup.
+  }
+}
+
+/**
+ * Build a "base message + optional deprecation banner" combined
+ * single-line systemMessage payload. Keeps stdout a single JSON
+ * object on every empty/no-DB exit path so Claude Code's hook
+ * contract holds.
+ */
+function combineWithBanner(baseMessage) {
+  let lines = [];
+  try {
+    const pluginRoot = resolvePluginRoot(import.meta.url);
+    const pkg = JSON.parse(readFileSync(join(pluginRoot, 'package.json'), 'utf8'));
+    const installedVersion = typeof pkg.version === 'string' ? pkg.version : null;
+    const cache = readUpdateCheckCache(installedVersion);
+    lines = installedVersion ? buildDeprecationBanner(installedVersion, cache) : [];
+  } catch {
+    // Best-effort — fall through to base message only.
+  }
+  if (lines.length === 0) return baseMessage;
+  return [...lines.filter((l) => l.length > 0), '', baseMessage].join('\n');
+}
+
 let input = '';
 process.stdin.setEncoding('utf8');
 process.stdin.on('data', (chunk) => { input += chunk; });
 process.stdin.on('end', async () => {
   try {
+    try {
     const data = JSON.parse(input);
     const projectName = basename(data.cwd || process.cwd());
 
@@ -48,7 +361,10 @@ process.stdin.on('end', async () => {
     }
 
     if (!existsSync(dbPath)) {
-      output('MeMesh: No database found. Memories will be created as you work.');
+      // Combine deprecation banner (if any) into the same
+      // systemMessage so stdout stays a single JSON document. Outer
+      // finally runs runPostBannerUpdateTasks().
+      output(combineWithBanner('MeMesh: No database found. Memories will be created as you work.'));
       return;
     }
 
@@ -62,7 +378,7 @@ process.stdin.on('end', async () => {
         "SELECT name FROM sqlite_master WHERE type='table' AND name='entities'"
       ).get();
       if (!tableCheck) {
-        output('MeMesh: Database exists but no memories stored yet.');
+        output(combineWithBanner('MeMesh: Database exists but no memories stored yet.'));
         return;
       }
 
@@ -157,8 +473,15 @@ process.stdin.on('end', async () => {
         }
       }
 
-      // No memories at all — output nothing (don't clutter session)
+      // No memories at all — surface only the deprecation banner if
+      // active (so a flagged install still warns the user) and skip
+      // the rest of the recall-summary work. The outer finally still
+      // runs runPostBannerUpdateTasks().
       if (lines.length === 0) {
+        const bannerOnly = combineWithBanner('');
+        if (bannerOnly && bannerOnly.trim().length > 0) {
+          output(bannerOnly.trim());
+        }
         return;
       }
 
@@ -294,14 +617,28 @@ process.stdin.on('end', async () => {
         // Non-critical — don't break session start
       }
 
-      const hookOutput = {
-        suppressOutput: true,
-        hookSpecificOutput: {
-          hookEventName: 'SessionStart',
-          additionalContext: buildReferenceContext(memorySummary.split('\n')),
-        },
-      };
-      console.log(JSON.stringify(hookOutput));
+      // Deprecation-aware banner. Reads the cache produced by the
+      // last `getUpdateCheck` (CLI or background refresh). When the
+      // installed version was flagged by maintainers (typically a
+      // security advisory), prepend a strong warning so the user sees
+      // it on every session start until they upgrade.
+      let installedVersion = null;
+      try {
+        const pluginRoot = resolvePluginRoot(import.meta.url);
+        const pkg = JSON.parse(readFileSync(join(pluginRoot, 'package.json'), 'utf8'));
+        installedVersion = typeof pkg.version === 'string' ? pkg.version : null;
+      } catch {
+        // Best-effort — without the version we can't compare to cache.
+      }
+      const updateCache = readUpdateCheckCache(installedVersion);
+      const deprecationLines = installedVersion
+        ? buildDeprecationBanner(installedVersion, updateCache)
+        : [];
+      const memorySummaryWithBanner = deprecationLines.length > 0
+        ? [...deprecationLines, '', ...memorySummary.split('\n')].join('\n')
+        : memorySummary;
+
+      output(buildReferenceContext(memorySummaryWithBanner.split('\n')));
     } finally {
       db.close();
     }
@@ -323,9 +660,21 @@ process.stdin.on('end', async () => {
     } catch {
       // Non-critical — noise compression failed, will retry next session
     }
-  } catch (err) {
-    // Hooks must never crash Claude Code — but report honestly
-    console.log(JSON.stringify({ systemMessage: `MeMesh: Session start failed (${err?.message || 'unknown error'}). Memories not loaded.` }));
+
+    } catch (err) {
+      // Hooks must never crash Claude Code — but report honestly.
+      // Inner catch so the outer finally can still run the post-
+      // banner update tasks even when the recall flow blew up.
+      console.log(JSON.stringify({ systemMessage: `MeMesh: Session start failed (${err?.message || 'unknown error'}). Memories not loaded.` }));
+    }
+  } finally {
+    // ── Auto-update + cache refresh ──────────────────────────────
+    // Outer finally guarantees this runs on every exit path — no-DB
+    // short-circuit, empty-DB return, no-memories return, recall
+    // happy path, or even a thrown error caught above. The
+    // function is single-shot per process so the duplicated
+    // late-path call from older versions is now idempotent.
+    runPostBannerUpdateTasks();
   }
 });