hypomnema 1.7.4 → 1.8.0

package/scripts/doctor.mjs

@@ -20,7 +20,11 @@ import { fileURLToPath } from 'url';
 import { resolveHypoRoot, expandHome } from './lib/hypo-root.mjs';
 import { loadHypoIgnore, isScanIgnored } from './lib/hypo-ignore.mjs';
 import { readRenameMarker, renameMarkerPath, RENAME_MARKER_REL } from './lib/rename-marker.mjs';
-import { resolveGitHooksDir, WIKI_PRE_COMMIT_MARKER_START } from './lib/git-hooks-dir.mjs';
+import {
+  resolveGitHooksDir,
+  WIKI_PRE_COMMIT_MARKER_START,
+  parseWikiPreCommitRoot,
+} from './lib/git-hooks-dir.mjs';
 import { parseFrontmatter } from './lib/frontmatter.mjs';
 import {
   readSyncState,
@@ -58,8 +62,14 @@ import {
   HOOKS_DIGEST_FIELD,
   computeHooksDigest,
 } from './lib/pkg-provenance.mjs';
-import { resolveCliOnPath, classifyInstall } from '../hooks/version-check.mjs';
-import { isHypomnemaPluginEnabled } from './lib/plugin-detect.mjs';
+import { resolveCliOnPath, classifyInstall, upgradeApplyHint } from '../hooks/version-check.mjs';
+import {
+  enabledHypomnemaPluginKey,
+  usablePkgRoot,
+  leafVersionDrift,
+  resolvePluginChannel,
+  resolveEnabledPluginEntry,
+} from './lib/plugin-detect.mjs';
 
 const HOME = homedir();
 const SCRIPT_DIR = fileURLToPath(new URL('.', import.meta.url));
@@ -68,7 +78,7 @@ const HOOKS_SRC = join(PKG_ROOT, 'hooks');
 
 // ── install channel ───────────────────────────────────────────────────────────
 //
-// A plugin-channel install registers its 14 core hooks straight out of the
+// A plugin-channel install registers the core hooks named in hooks/hooks.json straight out of the
 // package's own hooks/hooks.json (CLAUDE_PLUGIN_ROOT) — Claude Code auto-wires
 // them, they are never copied into ~/.claude/hooks and never listed in
 // ~/.claude/settings.json. checkHooks/checkSettingsJson used to treat that
@@ -80,11 +90,28 @@ const HOOKS_SRC = join(PKG_ROOT, 'hooks');
 // dual-install variant — a manual/npm doctor.mjs run while the plugin is ALSO
 // enabled in settings.json (see lib/plugin-detect.mjs; fails open on any
 // uncertainty). Either signal means Claude's core hook surface is
-// plugin-managed, not missing.
-const pluginMode = PKG_ROOT.replace(/\\/g, '/').includes('/.claude/plugins/');
-const hypomnemaPluginEnabled =
-  !pluginMode && isHypomnemaPluginEnabled(join(HOME, '.claude', 'settings.json'));
-const coreManagedByPlugin = pluginMode || hypomnemaPluginEnabled;
+// plugin-managed, not missing. resolvePluginChannel is the single place this
+// judgment is made — init.mjs and upgrade.mjs call the same function with their
+// own PKG_ROOT so all three tools agree.
+const pluginChannel = resolvePluginChannel({
+  pkgRoot: PKG_ROOT,
+  settingsPath: join(HOME, '.claude', 'settings.json'),
+  registryPath: join(HOME, '.claude', 'plugins', 'installed_plugins.json'),
+});
+const { pluginMode, hypomnemaPluginEnabled, coreManagedByPlugin } = pluginChannel;
+
+// The durable root the vault's pre-commit hook SHOULD embed, mirroring the same
+// rule upgrade.mjs's self-heal uses: in normal operation (plain plugin mode or
+// plain npm/manual) doctor's own PKG_ROOT already IS the active install, no
+// registry lookup needed or even possible to get wrong. In a dual install
+// (manual/npm doctor run while the plugin is also enabled) the active runtime
+// is the PLUGIN's, so only the registry's positive resolution can be trusted —
+// null means "cannot verify", never "matches", so checkGit below must skip the
+// comparison rather than report a false pass or a false drift.
+function resolveDurableHookRoot() {
+  if (!hypomnemaPluginEnabled) return PKG_ROOT;
+  return pluginChannel.root;
+}
 
 // Shown after every fatal package-integrity error. These conditions mean the
 // shipped hooks/hooks.json is missing or malformed — never a user mistake —
@@ -508,6 +535,23 @@ function checkGit(hypoDir) {
     );
   } else if (content.includes(WIKI_PRE_COMMIT_MARKER_START)) {
     pass(label, 'Hypomnema .hypoignore guard installed');
+    // A stale root never trips the marker check above (the marker itself never
+    // moves), so it is a SEPARATE, additive report, never a replacement for the
+    // pass — excluding a drifted root from consideration here would leave the
+    // exact silent-staleness failure this check exists to catch (see the
+    // plugin-cache leaf-drift precedent: reporting must never turn into
+    // filtering, or a still-real, still-resolvable root looks like it vanished).
+    const parsedRoot = parseWikiPreCommitRoot(content);
+    const wantRoot = resolveDurableHookRoot();
+    if (parsedRoot.ok && wantRoot !== null && wantRoot !== parsedRoot.root) {
+      warn(
+        `${label} root`,
+        `Points at an old install root (${parsedRoot.root}) — the active install is ` +
+          `${wantRoot}. To repoint it, run ${upgradeApplyHint(
+            pluginMode || hypomnemaPluginEnabled,
+          )}.`,
+      );
+    }
   } else {
     warn(label, 'Exists but not managed by Hypomnema — manual git add can bypass .hypoignore');
   }
@@ -1839,6 +1883,264 @@ function checkStaleSibling() {
   }
 }
 
+// ── plugin cache leaf version (plugin channel) ──────────────────────────────
+//
+// `/plugin marketplace update` names its cache directory after the release it
+// copies in (`cache/<marketplace>/hypo/<version>/`, per the plugin-channel
+// invariant in this repo's CLAUDE.md) and skips the copy whenever that version
+// string has not moved, so a leaf can end up naming an older release than the
+// package.json actually sitting inside it (2026-08-29 QA constructed that shape:
+// leaf "1.7.3", package.json "1.7.4"). This is the ONLY surface for that signal.
+// resolveEnabledPluginRoot (lib/plugin-detect.mjs) deliberately does NOT exclude a
+// drifted candidate: an earlier revision did, and excluding it makes that function
+// return null. init's resolveDurableRoot then tries the recorded pkgRoot and, when that
+// is unusable too, PKG_ROOT, which in a dual install is a removable npm checkout that
+// would get baked into the vault's git hook. So resolution stays permissive
+// and reporting lives here, named per-entry so a user can see exactly which registry
+// path disagrees with itself and what it actually contains.
+//
+// Only meaningful when the Hypomnema plugin is actually enabled: an entry in
+// installed_plugins.json for a disabled/other plugin proves nothing about this
+// install, so the check is silent (not even a pass) when the plugin key is not
+// enabled in settings.json.
+function checkPluginLeafVersion() {
+  const settingsPath = join(HOME, '.claude', 'settings.json');
+  const key = enabledHypomnemaPluginKey(settingsPath);
+  if (!key) return; // plugin not enabled, nothing to verify
+
+  const registryPath = join(HOME, '.claude', 'plugins', 'installed_plugins.json');
+  let reg;
+  try {
+    reg = JSON.parse(readFileSync(registryPath, 'utf-8'));
+  } catch {
+    warn(
+      'Plugin cache leaf version',
+      `Cannot read ${registryPath}, so the plugin cache directory's identity cannot be verified`,
+    );
+    return;
+  }
+  const entries =
+    reg &&
+    typeof reg.plugins === 'object' &&
+    !Array.isArray(reg.plugins) &&
+    Array.isArray(reg.plugins[key])
+      ? reg.plugins[key]
+      : null;
+  if (!entries || entries.length === 0) {
+    warn(
+      'Plugin cache leaf version',
+      `No registry entry for ${key} in ${registryPath}, so the plugin cache directory's identity cannot be verified`,
+    );
+    return;
+  }
+
+  // Deduped by installPath: one plugin key routinely carries several registry
+  // entries (a user-scope and a project-scope row) that name the SAME directory.
+  // Counting rows instead of paths reports "2 plugin cache path(s)" and lists the
+  // identical path twice — both the count and the list mislead about how many
+  // installs are actually drifted.
+  const driftedByPath = new Map();
+  const seen = new Set();
+  let compared = 0;
+  for (const e of entries) {
+    const installPath = e && typeof e.installPath === 'string' ? e.installPath : null;
+    if (!installPath || seen.has(installPath)) continue;
+    seen.add(installPath);
+    if (!usablePkgRoot(installPath)) continue;
+    const d = leafVersionDrift(installPath);
+    if (!d.checked) continue;
+    compared += 1;
+    if (d.drift) {
+      driftedByPath.set(
+        installPath,
+        `${installPath} (leaf says v${d.leaf}, package.json says v${d.manifestVersion})`,
+      );
+    }
+  }
+  const drifted = [...driftedByPath.values()];
+
+  // "Nothing drifted" and "nothing was comparable" are different answers, and this check
+  // used to give the same one for both. A path that is unreadable, or whose leaf is not
+  // version-named, was never compared — reporting "matches" there states a fact nobody
+  // established. The function already warns on its other two unverifiable states (an
+  // unreadable registry, a key with no entries), so passing here was the odd one out.
+  if (compared === 0) {
+    warn(
+      'Plugin cache leaf version',
+      `The plugin is enabled and the registry names ${key}, but no path it names could be ` +
+        `compared: none is a readable package dir with a version-named leaf. Common for a ` +
+        `local or dev marketplace checkout. The cache directory's identity is unverified; ` +
+        `this is not a statement that the installed version matches.`,
+    );
+  } else if (drifted.length === 0) {
+    pass(
+      'Plugin cache leaf version',
+      `Cache directory name matches the package installed inside it (${compared} path(s) compared)`,
+    );
+  } else {
+    // Scoped to the paths themselves. resolveEnabledPluginRoot picks ONE entry
+    // (user scope first, then any usable one), so a drifted project-scope row beside a
+    // healthy user-scope row is not the root Hypomnema actually runs from. Claiming
+    // "Hypomnema is silently running a different version" for every drifted row
+    // overstates what was measured.
+    warn(
+      'Plugin cache leaf version',
+      `${drifted.length} plugin cache path(s) whose directory name disagrees with the release ` +
+        `installed inside it: ${drifted.join(', ')}. Anything resolving through such a path ` +
+        `runs a different version than the name claims. Run ` +
+        `\`/plugin marketplace update hypomnema\` then \`/reload-plugins\`, or reinstall the plugin.`,
+    );
+  }
+}
+
+// ── installed cache vs marketplace clone (plugin channel) ──────────────────
+//
+// `/plugin marketplace update <marketplace>` pulls the marketplace repo to its
+// own clone at `~/.claude/plugins/marketplaces/<marketplace>/`, but only
+// re-copies that clone into the plugin CACHE (the directory hooks actually run
+// from) when plugin.json's version string has moved, the same skip-the-copy
+// behavior `checkPluginLeafVersion` above reports on. When the version string
+// has not moved, the marketplace clone can sit commits ahead of the cache with
+// no symptom anywhere: hooks run, slash commands resolve, the version string
+// still reads correctly, and a bug already fixed on `main` keeps reproducing.
+// Measured 2026-08-27: marketplace clone at one commit, install cache three
+// merges behind, same version string, no surface said so.
+//
+// `installed_plugins.json` records the exact commit each cache entry was
+// populated from (`gitCommitSha`); the marketplace clone's own `git rev-parse
+// HEAD` is the other half. Compared against the SAME row
+// `resolveEnabledPluginEntry` picks (user scope preferred, matching what
+// actually runs), this is the only place the two can be told apart. Never a
+// hard failure: a developer's checkout running ahead of an install is the
+// normal state while iterating, so this only makes the gap visible (warn),
+// with what the user can actually do about it (wait for the next version
+// bump, or replace the cache directory by hand knowing the next real update
+// overwrites it anyway); there is no way to force the copy to happen sooner.
+//
+// Reads the row through resolveEnabledPluginEntry rather than resolving a path
+// and then re-filtering the registry for the row that produced it (an earlier
+// revision of this function did exactly that, in the opposite order — filter
+// for a sha first, prefer user scope second — which silently swaps rows
+// whenever the user row has no gitCommitSha; see resolveEnabledPluginEntry's
+// own comment in lib/plugin-detect.mjs). One resolver call means one selection
+// rule and one registry read; there is no second row to disagree with.
+function checkPluginInstallDrift() {
+  const settingsPath = join(HOME, '.claude', 'settings.json');
+  const registryPath = join(HOME, '.claude', 'plugins', 'installed_plugins.json');
+  const resolved = resolveEnabledPluginEntry(settingsPath, registryPath);
+  if (resolved.reason === 'not-enabled') return; // plugin not enabled, nothing to verify
+
+  if (resolved.reason === 'registry-unreadable') {
+    warn(
+      'Installed cache vs marketplace HEAD',
+      `Cannot read ${registryPath}, so the installed cache's commit cannot be verified`,
+    );
+    return;
+  }
+  if (resolved.reason === 'unresolved') {
+    warn(
+      'Installed cache vs marketplace HEAD',
+      `${resolved.key} is enabled but no usable install root could be positively resolved from ` +
+        `${registryPath}, so the installed cache's commit cannot be verified`,
+    );
+    return;
+  }
+  const { key, entry, root: installRoot } = resolved;
+  if (!(typeof entry.gitCommitSha === 'string' && entry.gitCommitSha)) {
+    warn(
+      'Installed cache vs marketplace HEAD',
+      `The registry row for ${installRoot} carries no gitCommitSha, so the installed cache's ` +
+        `commit cannot be verified. Another row on the same path may have one, but it describes ` +
+        `a different install`,
+    );
+    return;
+  }
+  const installedSha = entry.gitCommitSha;
+
+  // `hypo@<marketplace>` / legacy `hypomnema@<marketplace>` → the marketplace
+  // clone lives at `~/.claude/plugins/marketplaces/<marketplace>/`.
+  const marketplaceName = key.slice(key.indexOf('@') + 1);
+  const marketplaceDir = join(HOME, '.claude', 'plugins', 'marketplaces', marketplaceName);
+  const headResult = spawnSync('git', ['-C', marketplaceDir, 'rev-parse', 'HEAD'], {
+    encoding: 'utf-8',
+  });
+  if (headResult.status !== 0 || !headResult.stdout.trim()) {
+    warn(
+      'Installed cache vs marketplace HEAD',
+      `Cannot read the marketplace clone's HEAD at ${marketplaceDir}, so the installed cache ` +
+        `cannot be compared to it`,
+    );
+    return;
+  }
+  const marketplaceHead = headResult.stdout.trim();
+
+  if (installedSha === marketplaceHead) {
+    pass(
+      'Installed cache vs marketplace HEAD',
+      `matches marketplace HEAD (${marketplaceHead.slice(0, 7)})`,
+    );
+    return;
+  }
+
+  // Which way the two shas sit is a question about ancestry, so ask git that
+  // directly instead of inferring it from a count. `A..B` returns 0 both when
+  // the install is ahead and when history is truncated so the walk cannot
+  // reach back, and those two want opposite advice: telling someone to
+  // overwrite a newer cache with an older clone is a downgrade. The
+  // marketplace clone on this machine is shallow (`.git/shallow` present), so
+  // the truncated case is the normal one here, not an edge.
+  const ancestor = (older, newer) =>
+    spawnSync('git', ['-C', marketplaceDir, 'merge-base', '--is-ancestor', older, newer], {
+      encoding: 'utf-8',
+    }).status === 0;
+
+  if (ancestor(marketplaceHead, installedSha)) {
+    warn(
+      'Installed cache vs marketplace HEAD',
+      `The installed cache (${installRoot}) is running ${installedSha.slice(0, 7)}, which is ` +
+        `ahead of the marketplace clone's HEAD (${marketplaceHead.slice(0, 7)}). That is the ` +
+        `normal state while developing against a local checkout; nothing to do.`,
+    );
+    return;
+  }
+
+  if (!ancestor(installedSha, marketplaceHead)) {
+    // Neither reaches the other. Divergent histories, a force-pushed branch, a
+    // commit that predates a shallow clone's graft point. The shas differ and
+    // that is worth saying, but any "N commits behind" or "replace it by hand"
+    // would be a guess about a direction git just declined to give.
+    warn(
+      'Installed cache vs marketplace HEAD',
+      `The installed cache (${installRoot}) is running ${installedSha.slice(0, 7)} and the ` +
+        `marketplace clone's HEAD is ${marketplaceHead.slice(0, 7)}. Neither commit reaches the ` +
+        `other in this clone, so which one is newer cannot be determined here (the clone may be ` +
+        `shallow, or the branch force-pushed). Compare them against the upstream repository ` +
+        `before changing anything.`,
+    );
+    return;
+  }
+
+  // Behind, established by ancestry. The count is a nice-to-have on top; a
+  // shallow clone can refuse to produce one and the sentence still holds.
+  const countResult = spawnSync(
+    'git',
+    ['-C', marketplaceDir, 'rev-list', '--count', `${installedSha}..${marketplaceHead}`],
+    { encoding: 'utf-8' },
+  );
+  const behindCount =
+    countResult.status === 0 && countResult.stdout.trim() !== '' ? countResult.stdout.trim() : null;
+  const behindText = behindCount !== null ? `${behindCount} commit(s) behind` : 'behind';
+  warn(
+    'Installed cache vs marketplace HEAD',
+    `The installed cache (${installRoot}) is running ${installedSha.slice(0, 7)}, ${behindText} ` +
+      `the marketplace clone's HEAD (${marketplaceHead.slice(0, 7)}). The version string did not ` +
+      `move, so \`/plugin marketplace update ${marketplaceName}\` pulled the marketplace clone ` +
+      `forward but skipped re-copying the cache hooks actually run from. Wait for the next ` +
+      `version bump, or replace ${installRoot} by hand with a copy of ${marketplaceDir} (a real ` +
+      `update will overwrite it anyway).`,
+  );
+}
+
 // ── provenance sidecar (manual/npm channel) ────────────────────────────────────
 //
 // `.hypo-provenance.json` lives next to a standalone-copied hooks/ dir
@@ -1868,7 +2170,7 @@ function checkProvenanceSidecar(hooksDir, label) {
         label,
         `no provenance sidecar, and this install's hooks cannot self-locate their ` +
           `package — PKG_ROOT resolves to null for every hook running from ${hooksDir}; ` +
-          `run \`hypomnema upgrade --apply\` to write one`,
+          `run ${upgradeApplyHint(pluginMode || hypomnemaPluginEnabled)} to write one`,
       );
     }
     return;
@@ -1880,7 +2182,7 @@ function checkProvenanceSidecar(hooksDir, label) {
   } catch {
     warn(
       label,
-      `${sidecarPath} is not valid JSON — run \`hypomnema upgrade --apply\` to rewrite it`,
+      `${sidecarPath} is not valid JSON — run ${upgradeApplyHint(pluginMode || hypomnemaPluginEnabled)} to rewrite it`,
     );
     return;
   }
@@ -1934,7 +2236,7 @@ function checkProvenanceSidecar(hooksDir, label) {
   warn(
     label,
     `${sidecarPath} does not verify (${reasons.join('; ')}) — resolvePkgRoot() will treat ` +
-      `PKG_ROOT as unresolved this session; run \`hypomnema upgrade --apply\` to refresh it`,
+      `PKG_ROOT as unresolved this session; run ${upgradeApplyHint(pluginMode || hypomnemaPluginEnabled)} to refresh it`,
   );
 }
 
@@ -1968,7 +2270,7 @@ function hooksDigestMismatch(hooksDir, recordedDigest) {
   return (
     `hooksDigest mismatch: ${diverged.length}/${allFiles.length} hook file(s) differ from ` +
     `the current package source${examples ? ` (e.g. ${examples})` : ''} — run ` +
-    `\`hypomnema upgrade --apply\``
+    `${upgradeApplyHint(pluginMode || hypomnemaPluginEnabled)}`
   );
 }
 
@@ -1992,9 +2294,25 @@ function checkPkgIntegrity(claudeHome) {
   // no longer exists and this correctly falls into the silent fresh-install branch.
   if (!existsSync(pkgPath)) return;
   if (!meta || !meta.pkgRoot) {
+    // A missing pkgRoot has two distinct causes with different fixes. Re-running
+    // /hypo:init or /hypo:upgrade only helps the ordinary one (a corrupt or
+    // never-written file). When the enabled plugin's channel judgment itself
+    // failed ('registry-unreadable'/'unresolved'), init/upgrade skip the very
+    // same write on every re-run until the registry is fixed first (see
+    // resolveDurableRoot in init.mjs and the dualSkip branch in upgrade.mjs).
+    const channelJudgmentFailed =
+      hypomnemaPluginEnabled &&
+      (pluginChannel.rootReason === 'registry-unreadable' ||
+        pluginChannel.rootReason === 'unresolved');
     warn(
       'hypo-pkg.json pkgRoot',
-      `hypo-pkg.json has no pkgRoot field — metadata is incomplete; re-run /hypo:init or /hypo:upgrade`,
+      channelJudgmentFailed
+        ? `hypo-pkg.json has no pkgRoot field because the enabled plugin's channel judgment failed ` +
+            `(${pluginChannel.rootReason}): re-running /hypo:init or /hypo:upgrade will skip the same ` +
+            `write until this resolves. Fix: repair or refresh ~/.claude/plugins/installed_plugins.json ` +
+            '(reinstall the plugin, or run `/plugin marketplace update hypomnema` then `/reload-plugins`), ' +
+            'then re-run /hypo:init or /hypo:upgrade to record the confirmed root.'
+        : `hypo-pkg.json has no pkgRoot field — metadata is incomplete; re-run /hypo:init or /hypo:upgrade`,
     );
     return;
   }
@@ -2106,6 +2424,8 @@ checkHooks(coreManagedByPlugin);
 checkSettingsJson(coreManagedByPlugin);
 checkPkgIntegrity(args.claudeHome);
 checkStaleSibling();
+checkPluginLeafVersion();
+checkPluginInstallDrift();
 if (args.codex) checkCodexPaths();
 if (rootOk) checkExtensions(args.hypoDir, args.claudeHome, 'claude');
 if (rootOk && args.codex) checkExtensions(args.hypoDir, args.claudeHome, 'codex');