hypomnema 1.6.2 → 1.7.0

package/scripts/doctor.mjs

@@ -25,6 +25,7 @@ import {
   projectSuggestionsPath,
   collectProjectWorkingDirs,
 } from '../hooks/hypo-shared.mjs';
+import { listProposals } from '../hooks/proposal-store.mjs';
 import {
   discoverExtensions,
   parseManifest,
@@ -35,16 +36,40 @@ import {
   resolveInstallFile,
   buildHookCommand,
   parseExtKey,
+  parseSkillKey,
+  parseSkillShaValue,
+  isFlatShaValue,
   EXT_TYPES,
   CODEX_TYPES,
 } from './lib/extensions.mjs';
 import { sha256, readFileIfRegular, readPkgJson } from './lib/pkg-json.mjs';
 import { resolveCliOnPath, classifyInstall } from '../hooks/version-check.mjs';
+import { isHypomnemaPluginEnabled } from './lib/plugin-detect.mjs';
 
 const HOME = homedir();
 const SCRIPT_DIR = fileURLToPath(new URL('.', import.meta.url));
 const PKG_ROOT = join(SCRIPT_DIR, '..');
 
+// ── install channel ───────────────────────────────────────────────────────────
+//
+// A plugin-channel install registers its 14 core hooks 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
+// empty state as "missing" and prescribe `/hypo:init`, which then copied +
+// registered the very same hooks a second time (every hook firing twice).
+//
+// `pluginMode` mirrors upgrade.mjs's own detector: this doctor.mjs is itself
+// running from a `.claude/plugins/…` root. `hypomnemaPluginEnabled` catches the
+// 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;
+
 // Shown after every fatal package-integrity error. These conditions mean the
 // shipped hooks/hooks.json is missing or malformed — never a user mistake —
 // so the only useful next step is a re-install of the package.
@@ -255,7 +280,17 @@ function checkFiles(hypoDir) {
   }
 }
 
-function checkHooks() {
+// .hyposcanignore is optional (scan-only exclusions, not a privacy boundary),
+// so its absence is info-level — pass either way, never warn/fail.
+function checkScanIgnoreFile(hypoDir) {
+  const present = existsSync(join(hypoDir, '.hyposcanignore'));
+  pass(
+    'File: .hyposcanignore',
+    present ? 'present' : 'optional — not present, no scan-only exclusions configured',
+  );
+}
+
+function checkHooks(coreManagedByPlugin) {
   const claudeHooks = join(HOME, '.claude', 'hooks');
   const allFiles = [...Object.values(HOOK_MAP).flat(), ...SHARED_FILES];
 
@@ -266,6 +301,13 @@ function checkHooks() {
 
   if (missing === 0) {
     pass('Hook files installed', claudeHooks);
+  } else if (coreManagedByPlugin && missing === allFiles.length) {
+    // Plugin channel: an empty ~/.claude/hooks is the expected, healthy state
+    // (the plugin loader provides the hooks), not a missing install.
+    pass(
+      'Hook files installed',
+      `provided by the plugin loader (hooks/hooks.json) — none copied to ${claudeHooks} (expected)`,
+    );
   } else if (missing < allFiles.length) {
     warn('Hook files installed', `${missing}/${allFiles.length} missing in ${claudeHooks}`);
   } else {
@@ -273,10 +315,17 @@ function checkHooks() {
   }
 }
 
-function checkSettingsJson() {
+function checkSettingsJson(coreManagedByPlugin) {
   const settingsPath = join(HOME, '.claude', 'settings.json');
   if (!existsSync(settingsPath)) {
-    warn('settings.json hook registrations', 'settings.json not found');
+    if (coreManagedByPlugin) {
+      pass(
+        'settings.json hook registrations',
+        'provided by the plugin loader (hooks/hooks.json) — settings.json entries not required',
+      );
+    } else {
+      warn('settings.json hook registrations', 'settings.json not found');
+    }
     return;
   }
 
@@ -310,6 +359,13 @@ function checkSettingsJson() {
       'settings.json hook registrations',
       `${registered}/${total} registered — run /hypo:init to merge missing entries`,
     );
+  } else if (coreManagedByPlugin) {
+    // Same reasoning as checkHooks: the plugin loader never touches settings.json,
+    // so 0/total here is the expected plugin-channel state, not a missing install.
+    pass(
+      'settings.json hook registrations',
+      `0/${total} registered in settings.json — provided by the plugin loader (hooks/hooks.json) instead (expected)`,
+    );
   } else {
     fail('settings.json hook registrations', `0/${total} registered — run /hypo:init`);
   }
@@ -669,6 +725,24 @@ function checkProjectSuggestions(hypoDir) {
   }
 }
 
+function checkProposals(hypoDir) {
+  // Vault-wide count of parked write-proposals (T8). listProposals is the
+  // count source rather than a raw readdir: it already skips malformed and
+  // spoofed-id artifacts, so the number matches exactly what `hypomnema proposal
+  // list/apply/discard` can act on. Surface only: warn (never fail), pass at 0,
+  // because a pending proposal is a normal state awaiting review, not a broken
+  // install, and the check discovers without changing any state.
+  const count = listProposals(hypoDir).length;
+  if (count === 0) {
+    pass('Pending proposals', 'No parked write-proposals');
+  } else {
+    warn(
+      'Pending proposals',
+      `${count} parked write-proposal(s) awaiting review; inspect with \`hypomnema proposal list\``,
+    );
+  }
+}
+
 function checkCodexPaths() {
   const codexHooks = join(HOME, '.codex', 'hooks');
   const allFiles = [...Object.values(HOOK_MAP).flat(), ...SHARED_FILES];
@@ -805,6 +879,58 @@ function checkExtensions(hypoDir, claudeHome, target = 'claude') {
     // Skip keys outside this target's covered types (defensive: a Claude run records
     // skills/agents that a codex target never installs — don't false-flag them).
     if (!types.includes(key.split('/')[0])) continue;
+
+    // A directory skill records one key whose value is a per-file SHA map. Joining
+    // that key straight onto root would land on the skill DIRECTORY and report it
+    // as "not a regular file" on every run. Check the subtree file by file instead.
+    const skillKey = parseSkillKey(key);
+    if (skillKey) {
+      const nested = parseSkillShaValue(recSHA);
+      if (!nested) {
+        problems.push({
+          severity: 'warn',
+          msg: `${key} has a corrupt ownership record — run upgrade --apply`,
+        });
+        continue;
+      }
+      const skillRoot = join(root, 'skills', skillKey.installDir);
+      for (const [rel, sha] of Object.entries(nested)) {
+        const filePath = join(skillRoot, ...rel.split('/'));
+        const label = `${key}/${rel}`;
+        if (!existsSync(filePath)) {
+          problems.push({
+            severity: 'warn',
+            msg: `${label} recorded but not installed — run upgrade --apply`,
+          });
+          continue;
+        }
+        const buf = readFileIfRegular(filePath);
+        if (buf === null) {
+          problems.push({
+            severity: 'warn',
+            msg: `${label} is not a regular file — left untouched`,
+          });
+          continue;
+        }
+        if (sha256(buf) !== sha) {
+          problems.push({
+            severity: 'warn',
+            msg: `${label} modified since install (drift) — use --force-extensions`,
+          });
+        }
+      }
+      continue;
+    }
+
+    // A flat key must carry a plain hex SHA; a wrong-shaped value is a corrupt
+    // record, not a drifted file.
+    if (!isFlatShaValue(recSHA)) {
+      problems.push({
+        severity: 'warn',
+        msg: `${key} has a corrupt ownership record — run upgrade --apply`,
+      });
+      continue;
+    }
     const destPath = join(root, key);
     if (!existsSync(destPath)) {
       problems.push({
@@ -1129,9 +1255,44 @@ function checkFeedbackProjection(hypoDir, claudeHome, projectId) {
       `${name}: ${reason} — run \`hypomnema feedback-sync --import-target-change\` to reconcile`,
     );
   } else {
-    // 2) build error → WARN
-    const buildErr = targets.find(([, t]) => t.buildError);
-    if (buildErr) {
+    // 2) build error. Split by kind:
+    //
+    //    'build-failed' → FAIL. The target file EXISTS but its
+    //      <learned_behaviors> container is gone, so the projection cannot be
+    //      built: NOT ONE L1 rule is loaded on that machine and every later sync
+    //      is a silent no-op. This was a warn, which made a structurally broken
+    //      projection near-invisible — nothing else reported it either (the
+    //      PreCompact gate classified it as "nothing to do" and failed open), and
+    //      it went unnoticed on a real machine. A projection that cannot be built
+    //      is a failure, not a note.
+    //
+    //    'target-missing' → WARN, as before. No ~/.claude/CLAUDE.md yet is the
+    //      ordinary first-run state, not a broken one; failing here would fail
+    //      every new user's doctor run.
+    //
+    // Select the build-failed target SPECIFICALLY rather than taking the first
+    // buildError of any kind: with more than one container target, a
+    // 'target-missing' one earlier in iteration order would otherwise mask a
+    // structurally broken one behind a warn — the exact invisibility this check
+    // exists to end. Only `claude` carries a container today, so that masking is
+    // latent, not live; the precompact gate filters the same way.
+    const failedErr = targets.find(([, t]) => t.buildErrorKind === 'build-failed');
+    const buildErr = failedErr || targets.find(([, t]) => t.buildError);
+    if (failedErr) {
+      const [name, t] = failedErr;
+      // Name the remedy for THIS cause, not a fixed one. `--ensure-container`
+      // restores a MISSING container; it cannot chmod an unreadable file, cannot
+      // repoint a dangling symlink, and refuses a corrupt container outright — so
+      // printing it for those causes hands the reader a command that does nothing
+      // and teaches them to ignore the next failure too. feedback-sync decides the
+      // remedy where it detects the cause and ships it as `buildErrorRemedy`; this
+      // just prints it (one judgment, several consumers).
+      fail(
+        'Feedback projection',
+        `${name}: ${t.buildError} — the projection cannot be built, so NO rules are loaded from it ` +
+          `and every sync is a silent no-op. ${t.buildErrorRemedy || ''}`.trimEnd(),
+      );
+    } else if (buildErr) {
       warn('Feedback projection', buildErr[1].buildError);
     } else if (targets.find(([, t]) => t.overCap)) {
       warn('Feedback projection', 'projection over cap — demote/archive feedback pages');
@@ -1144,7 +1305,23 @@ function checkFeedbackProjection(hypoDir, claudeHome, projectId) {
     }
   }
 
-  // 3) unresolved project-id is a separate, non-fatal concern (MEMORY skipped)
+  // 3) side-file I/O problems: a WARN, and additive rather than part of the
+  //    if/else chain above — an unreadable feedback_<slug>.md copy is orthogonal
+  //    to the primary target's health. It must not fail: the index line still
+  //    projects, every rule still loads, and the remedy is a permission bit on a
+  //    named path — nothing `--ensure-container` (the build-failed remedy) can
+  //    touch. feedback-sync already put the path in the message.
+  for (const [name, t] of targets) {
+    for (const w of t.sideWarnings || []) {
+      warn(
+        'Feedback projection side file',
+        `${name}: ${w} — fix the permissions on that path; the primary projection still loads ` +
+          `(\`--ensure-container\` does not fix this)`,
+      );
+    }
+  }
+
+  // 4) unresolved project-id is a separate, non-fatal concern (MEMORY skipped)
   if (report.projectIdResolved === false) {
     warn(
       'Feedback projection',
@@ -1187,6 +1364,121 @@ function checkStaleSibling() {
   }
 }
 
+// ── package integrity ─────────────────────────────────────────────────────────
+//
+// ~/.claude/hypo-pkg.json is a snapshot written once by init/upgrade and never
+// re-validated: nothing tracks whether pkgRoot still exists, whether its
+// package.json version still matches the recorded pkgVersion, or whether
+// pkgRoot points at a dev checkout instead of a distributed copy. Command and
+// skill script resolution was unified onto this one pointer, so a stale or
+// dev-pointing pkgRoot means the wiki silently runs uncommitted WIP.
+// All three checks are WARN, never FAIL — a dogfooding maintainer must be
+// able to ignore them on purpose.
+function checkPkgIntegrity(claudeHome) {
+  const pkgPath = join(claudeHome, 'hypo-pkg.json');
+  const meta = readPkgJson(pkgPath);
+  // Distinguish "no metadata file at all" (a fresh install — non-actionable, stay
+  // silent) from "a file is present but has no pkgRoot" (incomplete metadata that
+  // breaks runtime package resolution — warn rather than silently reading as OK).
+  // readPkgJson renames a corrupt file aside and returns {}, so after that the path
+  // no longer exists and this correctly falls into the silent fresh-install branch.
+  if (!existsSync(pkgPath)) return;
+  if (!meta || !meta.pkgRoot) {
+    warn(
+      'hypo-pkg.json pkgRoot',
+      `hypo-pkg.json has no pkgRoot field — metadata is incomplete; re-run /hypo:init or /hypo:upgrade`,
+    );
+    return;
+  }
+
+  const { pkgRoot, pkgVersion } = meta;
+
+  if (!existsSync(pkgRoot)) {
+    warn(
+      'hypo-pkg.json pkgRoot exists',
+      `${pkgRoot} does not exist — metadata is stale; re-run /hypo:init or /hypo:upgrade`,
+    );
+    return;
+  }
+  pass('hypo-pkg.json pkgRoot exists', pkgRoot);
+
+  let actualVersion = null;
+  let pkgJsonReadable = false;
+  try {
+    actualVersion = JSON.parse(readFileSync(join(pkgRoot, 'package.json'), 'utf-8')).version;
+    pkgJsonReadable = true;
+  } catch {
+    warn('hypo-pkg.json version match', `${pkgRoot}/package.json is unreadable — cannot verify`);
+  }
+  // Every reachable state emits exactly one line: a silent skip here would read as
+  // "verified" on the health report when nothing was actually checked.
+  if (actualVersion) {
+    if (pkgVersion && actualVersion !== pkgVersion) {
+      warn(
+        'hypo-pkg.json version match',
+        `recorded pkgVersion is ${pkgVersion}, but pkgRoot's package.json is v${actualVersion} — ` +
+          `stale metadata; re-run /hypo:init or /hypo:upgrade`,
+      );
+    } else if (pkgVersion) {
+      pass('hypo-pkg.json version match', `v${actualVersion}`);
+    } else {
+      warn(
+        'hypo-pkg.json version match',
+        `metadata records no pkgVersion — cannot verify against pkgRoot's v${actualVersion}; ` +
+          `re-run /hypo:init or /hypo:upgrade`,
+      );
+    }
+  } else if (pkgJsonReadable) {
+    warn(
+      'hypo-pkg.json version match',
+      `${pkgRoot}/package.json has no "version" field — cannot verify`,
+    );
+  }
+
+  // dev-repo check: pkgRoot is a git working tree that is dirty or sits on a
+  // commit with no exact release tag. Normal users should point at a
+  // distributed copy (plugin cache or npm install), not a source checkout.
+  if (existsSync(join(pkgRoot, '.git'))) {
+    const status = spawnSync('git', ['-C', pkgRoot, 'status', '--porcelain'], {
+      encoding: 'utf-8',
+    });
+    const tag = spawnSync('git', ['-C', pkgRoot, 'describe', '--tags', '--exact-match'], {
+      encoding: 'utf-8',
+    });
+    // A non-zero `git describe` exit is the real "HEAD is not an exact tag" signal,
+    // but a spawn failure (git not installed, ENOENT) sets `.error` / a null status
+    // too. Treat those as "cannot classify" instead of silently mislabeling the
+    // pkgRoot as an untagged dev checkout. `git status --porcelain` must exit 0 on
+    // any real repo (clean OR dirty), so a non-zero status there means the repo is
+    // corrupt/inaccessible — also "cannot classify", not "untagged". `git describe`
+    // legitimately exits non-zero when HEAD carries no exact tag, so only its spawn
+    // (error/null status) disqualifies it, not a non-zero exit.
+    const gitUsable =
+      status.error == null && status.status === 0 && tag.error == null && tag.status != null;
+    if (!gitUsable) {
+      warn(
+        'hypo-pkg.json pkgRoot install kind',
+        `pkgRoot has a .git directory but git could not be run — cannot classify the install kind`,
+      );
+      return;
+    }
+    const dirty = status.stdout.trim().length > 0; // gitUsable already asserts status 0
+    const untagged = tag.status !== 0;
+    if (dirty || untagged) {
+      const reasons = [];
+      if (dirty) reasons.push('uncommitted changes');
+      if (untagged) reasons.push('HEAD is not an exact release tag');
+      warn(
+        'hypo-pkg.json pkgRoot install kind',
+        `pkgRoot looks like a development checkout (${reasons.join(', ')}) — normal users should ` +
+          `point at a distributed copy (plugin cache or npm install), not a source repo`,
+      );
+    } else {
+      pass('hypo-pkg.json pkgRoot install kind', 'pkgRoot is a clean, tagged checkout');
+    }
+  }
+}
+
 // ── main ─────────────────────────────────────────────────────────────────────
 
 const args = parseArgs(process.argv);
@@ -1197,11 +1489,13 @@ const rootOk = checkHypoRoot(args.hypoDir);
 if (rootOk) {
   checkDirectories(args.hypoDir);
   checkFiles(args.hypoDir);
+  checkScanIgnoreFile(args.hypoDir);
   checkBrokenLinks(args.hypoDir, ignorePatterns);
   checkVerifyBy(args.hypoDir, ignorePatterns);
 }
-checkHooks();
-checkSettingsJson();
+checkHooks(coreManagedByPlugin);
+checkSettingsJson(coreManagedByPlugin);
+checkPkgIntegrity(args.claudeHome);
 checkStaleSibling();
 if (args.codex) checkCodexPaths();
 if (rootOk) checkExtensions(args.hypoDir, args.claudeHome, 'claude');
@@ -1209,6 +1503,7 @@ if (rootOk && args.codex) checkExtensions(args.hypoDir, args.claudeHome, 'codex'
 if (rootOk) checkProjectIndexAnchors(args.hypoDir);
 if (rootOk) checkSyncState(args.hypoDir);
 if (rootOk) checkProjectSuggestions(args.hypoDir);
+if (rootOk) checkProposals(args.hypoDir);
 if (rootOk) checkFeedbackProjection(args.hypoDir, args.claudeHome, args.projectId);
 checkGit(args.hypoDir);