hypomnema 1.8.2 → 1.9.0

package/scripts/init.mjs

@@ -48,8 +48,10 @@ import {
   SHELL_MARKER_END,
   SHELL_FUNCTION_BODY,
   wikiPreCommitContent,
+  uniqueBakPath,
 } from './lib/git-hooks-dir.mjs';
-import { readCoreHooksConfig } from './lib/core-hooks.mjs';
+import { loadHookInventory } from './lib/hook-inventory.mjs';
+import { formatRootHotProjection } from '../hooks/hypo-shared.mjs';
 import {
   readPkgJson as readPkgJsonSafe,
   writePkgJsonAtomic,
@@ -61,7 +63,7 @@ import { syncExtensions } from './lib/extensions.mjs';
 import { writeProvenanceSidecar } from './lib/pkg-provenance.mjs';
 import { templateSchemaVersion } from './lib/template-schema-version.mjs';
 import { classifyInstall, downgradeGuardMessage } from '../hooks/version-check.mjs';
-import { resolvePluginChannel, usablePkgRoot } from './lib/plugin-detect.mjs';
+import { resolvePluginChannel, isHypomnemaInstallRoot } from './lib/plugin-detect.mjs';
 
 const HOME = homedir();
 const SCRIPT_DIR = fileURLToPath(new URL('.', import.meta.url));
@@ -302,6 +304,22 @@ function copyTemplate(srcName, destPath, dryRun, transform) {
   log('created', destPath);
 }
 
+// Root hot.md is generated, not copied. The hooks rebuild it from
+// projects/*/hot.md with formatRootHotProjection, and the first rebuild in a new
+// vault treats any bytes it did not produce as a hand edit (backup file plus a
+// notice). A templates/hot.md kept equal to the generator by hand was a second
+// copy of that body, and every edit to the generator had to be mirrored into it.
+// Writing the generator's own empty-vault output here leaves one body.
+function writeRootHot(hypoDir, dryRun) {
+  const dest = join(hypoDir, 'hot.md');
+  if (existsSync(dest)) {
+    log('skipped', dest);
+    return;
+  }
+  if (!dryRun) writeFileSync(dest, formatRootHotProjection([]));
+  log('created', dest);
+}
+
 // ── hypo-config.md ───────────────────────────────────────────────────────────
 
 function writeHypoConfig(hypoDir, dryRun) {
@@ -367,90 +385,19 @@ function writeGitignore(hypoDir, dryRun) {
 // ── hook installation ────────────────────────────────────────────────────────
 
 function loadHookMap() {
-  // Read + parse via the exit-free shared helper; keep init's own validation and
-  // exit(1) behavior below. The helper omits `cfg` only on read/parse failure
-  // (JSON.parse never yields undefined), so key presence discriminates a
-  // read/parse failure from a parsed-but-malformed shape.
-  const res = readCoreHooksConfig(PKG_ROOT);
-  if (!('cfg' in res)) {
-    console.error(`Error: cannot read hooks/hooks.json from package root: ${PKG_ROOT}`);
-    console.error(PKG_INTEGRITY_HINT);
-    process.exit(1);
-  }
-  const cfg = res.cfg;
-  if (!cfg || typeof cfg !== 'object' || Array.isArray(cfg)) {
-    console.error('Error: hooks/hooks.json must be a JSON object');
+  // loadHookInventory (scripts/lib/hook-inventory.mjs) owns the grammar AND the
+  // existence check now: every consumer that installs, refreshes, or removes a
+  // hook file reads through the same parser, and a name on either list that does
+  // not resolve to a real file under hooks/ fails this call before init writes
+  // anything at all (major C — a hook file dropped from the shipped package used
+  // to install a broken settings.json registration with nothing behind it).
+  const res = loadHookInventory(PKG_ROOT);
+  if (!res.ok) {
+    console.error(`Error: ${res.error}`);
     console.error(PKG_INTEGRITY_HINT);
     process.exit(1);
   }
-  if (!cfg.hooks || typeof cfg.hooks !== 'object' || Array.isArray(cfg.hooks)) {
-    console.error('Error: hooks/hooks.json must contain a "hooks" object');
-    console.error(PKG_INTEGRITY_HINT);
-    process.exit(1);
-  }
-  function _extractCommandFileName(command) {
-    if (typeof command !== 'string') return null;
-    const matches = [...command.matchAll(/(?:^|[\/\\])([^\/\\\s"'`]+\.mjs)(?=$|[\s"'`])/g)];
-    if (matches.length > 0) return matches[matches.length - 1][1];
-    const bare = command.match(/(?:^|\s)([^\/\\\s"'`]+\.mjs)(?=$|[\s"'`])/);
-    return bare ? bare[1] : null;
-  }
-
-  function _isHookFileName(file) {
-    return typeof file === 'string' && /^[^/\\\s]+\.mjs$/.test(file.trim());
-  }
-
-  function _isHookGroup(group) {
-    return (
-      group &&
-      typeof group === 'object' &&
-      !Array.isArray(group) &&
-      Array.isArray(group.hooks) &&
-      group.hooks.length > 0 &&
-      group.hooks.every(
-        (hook) =>
-          hook &&
-          typeof hook === 'object' &&
-          !Array.isArray(hook) &&
-          hook.type === 'command' &&
-          _extractCommandFileName(hook.command),
-      )
-    );
-  }
-
-  // Extract .mjs file names from both old format (string[]) and new format (hook-group object[])
-  function _extractFileNames(groups) {
-    return groups.flatMap((group) => {
-      if (typeof group === 'string') return [group.trim()];
-      return group.hooks.map((hook) => _extractCommandFileName(hook.command));
-    });
-  }
-
-  for (const [event, groups] of Object.entries(cfg.hooks)) {
-    const valid =
-      Array.isArray(groups) &&
-      groups.length > 0 &&
-      groups.every((group) => _isHookFileName(group) || _isHookGroup(group)) &&
-      _extractFileNames(groups).length > 0;
-    if (!valid) {
-      console.error(
-        `Error: hooks/hooks.json "hooks.${event}" must be a non-empty array of .mjs file names or Claude hook groups`,
-      );
-      console.error(PKG_INTEGRITY_HINT);
-      process.exit(1);
-    }
-  }
-  if (
-    cfg.shared !== undefined &&
-    (!Array.isArray(cfg.shared) || !cfg.shared.every((f) => _isHookFileName(f)))
-  ) {
-    console.error('Error: hooks/hooks.json "shared" must be an array of .mjs file names');
-    console.error(PKG_INTEGRITY_HINT);
-    process.exit(1);
-  }
-  return Object.fromEntries(
-    Object.entries(cfg.hooks).map(([event, groups]) => [event, _extractFileNames(groups)]),
-  );
+  return res.hookMap;
 }
 
 function installHooks(targetDir, dryRun) {
@@ -459,8 +406,20 @@ function installHooks(targetDir, dryRun) {
     return;
   }
   if (!dryRun) mkdirSync(targetDir, { recursive: true });
-  for (const file of readdirSync(HOOKS_SRC)) {
-    if (!file.endsWith('.mjs')) continue;
+  // The canonical install order, not a directory listing. Reading the directory
+  // installed whatever happened to sit in hooks/, which is how every install
+  // ended up with a copy of hypo-pre-commit.mjs: it is invoked from the package
+  // root, never from the install, so upgrade would not refresh that copy,
+  // doctor would not report it, and uninstall would not take it away.
+  // installOrder also puts shared modules ahead of the entry hooks that import
+  // them, so an interrupted run cannot leave an entry hook live against a module
+  // that is not there yet.
+  const inventory = loadHookInventory(PKG_ROOT);
+  if (!inventory.ok) {
+    log('errors', `cannot read the hook inventory: ${inventory.error}`);
+    return;
+  }
+  for (const file of inventory.ordered) {
     const dest = join(targetDir, file);
     if (existsSync(dest)) {
       log('skipped', dest);
@@ -578,8 +537,9 @@ function readPkgVersionAt(root) {
   }
 }
 
-// usablePkgRoot now lives in ./lib/plugin-detect.mjs (imported above), shared with
-// upgrade.mjs's dualSkip provenance correction so both agree on what is real.
+// usablePkgRoot / isHypomnemaInstallRoot now live in ./lib/plugin-detect.mjs
+// (imported above), shared with upgrade.mjs's dualSkip provenance correction so
+// both agree on what is real.
 
 function writePkgJson(dryRun, extraFields = {}, root = PKG_ROOT) {
   const dest = pkgJsonPath();
@@ -759,12 +719,14 @@ function installPkgGitHook(dryRun) {
 // ── wiki pre-commit hook ─────────────────────────────────────────────────────
 //
 // shellSingleQuote and wikiPreCommitContent live in lib/git-hooks-dir.mjs, not
-// here: upgrade.mjs's self-heal (repointing an existing hook at the current
-// durable root) and doctor.mjs's drift check both need to build/parse the
-// exact same body this writer produces, so one copy is shared rather than
-// three independent copies silently drifting apart.
-
-function installWikiPreCommitHook(hypoDir, dryRun, force, root, lintStrict) {
+// here: upgrade.mjs's old-to-new-form migration and doctor.mjs's report both
+// need to build/parse the exact same body this writer produces, so one copy is
+// shared rather than three independent copies silently drifting apart.
+// wikiPreCommitContent no longer takes an install root: the body
+// it generates resolves that itself, at commit time, so there is nothing here
+// for a plugin-channel version bump to make stale.
+
+function installWikiPreCommitHook(hypoDir, dryRun, force, lintStrict) {
   const { dir: hooksDir, skip } = hooksDirForInstall(hypoDir);
   if (!hooksDir) {
     // no git repo — silently skip, as before; anything else is worth surfacing
@@ -772,7 +734,7 @@ function installWikiPreCommitHook(hypoDir, dryRun, force, root, lintStrict) {
     return;
   }
   const hookPath = join(hooksDir, 'pre-commit');
-  const newContent = wikiPreCommitContent(root, hypoDir, lintStrict);
+  const newContent = wikiPreCommitContent(hypoDir, lintStrict);
 
   // Before every branch below, including --force: a symlink here would send the
   // write through to an arbitrary external file.
@@ -789,20 +751,36 @@ function installWikiPreCommitHook(hypoDir, dryRun, force, root, lintStrict) {
         log('skipped', `${hookPath} (pre-commit up to date)`);
         return;
       }
+      // Back this up first. The marker's presence says our block is IN the
+      // file; it says nothing about what else is, and this branch replaces the
+      // whole file either way. upgrade.mjs refuses exactly this shape (content
+      // outside the marker span) and tells the user to run
+      // `init --force-commands` — so without a backup here, following our own
+      // recovery advice is what destroys their hook. Measured by a codex
+      // reviewer 2026-09-11; the `force` branch below already backed up, this
+      // one did not, and `force` is not even consulted here.
+      const bakPath = uniqueBakPath(hookPath);
+      if (!bakPath) {
+        log('skipped', `${hookPath} (unsafe backup path) — not overwriting without a safe backup`);
+        return;
+      }
       if (!dryRun) {
+        writeFileSync(bakPath, existing);
         writeFileSync(hookPath, newContent);
         chmodSync(hookPath, 0o755);
       }
-      log('merged', `${hookPath} (pre-commit updated)`);
+      log('merged', `${hookPath} (pre-commit updated, backup at ${basename(bakPath)})`);
     } else if (force) {
       // The .bak is a SECOND write to a DIFFERENT path, so the guard on
       // hookPath above says nothing about it. Left unchecked, a pre-commit.bak
       // symlink turns --force-commands into an overwrite of whatever it points
       // at — deterministically, not as a race.
-      const bakPath = hookPath + '.bak';
-      const unsafeBak = unsafeHookTargetReason(bakPath);
-      if (unsafeBak) {
-        log('skipped', `${bakPath} (${unsafeBak}) — not force-overwriting without a safe backup`);
+      const bakPath = uniqueBakPath(hookPath);
+      if (!bakPath) {
+        log(
+          'skipped',
+          `${hookPath} (unsafe backup path) — not force-overwriting without a safe backup`,
+        );
         return;
       }
       if (!dryRun) {
@@ -810,7 +788,7 @@ function installWikiPreCommitHook(hypoDir, dryRun, force, root, lintStrict) {
         writeFileSync(hookPath, newContent);
         chmodSync(hookPath, 0o755);
       }
-      log('merged', `${hookPath} (force-overwritten, backup at pre-commit.bak)`);
+      log('merged', `${hookPath} (force-overwritten, backup at ${basename(bakPath)})`);
     } else {
       log(
         'skipped',
@@ -1040,7 +1018,12 @@ function resolveDurableRoot() {
   if (!hypomnemaPluginEnabled) return PKG_ROOT;
   if (pluginChannel.root) return pluginChannel.root;
   const recorded = recordedPkgRoot();
-  if (usablePkgRoot(recorded)) return recorded;
+  // isHypomnemaInstallRoot, not the weak usablePkgRoot: this value is about to be
+  // adopted as the durable root and re-recorded (see writePkgJson's `root` param
+  // below), so a recorded pointer that merely resolves a readable version, without
+  // actually being a Hypomnema package, must not be trusted here (see
+  // lib/plugin-detect.mjs's comment on the two predicates).
+  if (isHypomnemaInstallRoot(recorded)) return recorded;
   // pluginChannel.root is null here because the channel JUDGMENT FAILED (reason
   // 'registry-unreadable' or 'unresolved'), not because no plugin is installed —
   // hypomnemaPluginEnabled is already true, and that case already returned
@@ -1127,7 +1110,7 @@ if (args.fromRemote) {
 
   // 2. template files
   copyTemplate('index.md', join(args.hypoDir, 'index.md'), args.dryRun);
-  copyTemplate('hot.md', join(args.hypoDir, 'hot.md'), args.dryRun);
+  writeRootHot(args.hypoDir, args.dryRun);
   copyTemplate('log.md', join(args.hypoDir, 'log.md'), args.dryRun);
   copyTemplate('SCHEMA.md', join(args.hypoDir, 'SCHEMA.md'), args.dryRun);
   copyTemplate('hypo-guide.md', join(args.hypoDir, 'hypo-guide.md'), args.dryRun);
@@ -1321,13 +1304,7 @@ if (args.hooks) {
 // any) is left exactly as-is, and channelUnresolvedNotice() above says what to
 // do next.
 if (!channelUnresolved) {
-  installWikiPreCommitHook(
-    args.hypoDir,
-    args.dryRun,
-    args.forceCommands,
-    durableRoot,
-    args.lintStrict,
-  );
+  installWikiPreCommitHook(args.hypoDir, args.dryRun, args.forceCommands, args.lintStrict);
 } else {
   log(
     'skipped',

package/scripts/lib/core-hooks.mjs

@@ -1,4 +1,5 @@
-// core-hooks.mjs - read the packaged hooks/hooks.json without side effects.
+// core-hooks.mjs - read the packaged hooks/hooks.json and hooks/shared.json
+// without side effects.
 //
 // The init installer (init.mjs loadHookMap) reads hooks.json, validates it, and
 // calls process.exit(1) on any malformation. That exit-on-error behavior is
@@ -12,28 +13,39 @@
 // hooks type when the result is not ok (better to capture nothing than to
 // capture a core hook).
 //
-// fail-closed: a result is ok only when the file reads, parses, AND has the
-// expected shape (a hooks registration map plus a shared array). A parsed but
-// oddly shaped hooks.json would yield a thin basename set, which is exactly the
-// gap through which a core hook could leak into capture. When the shape is off
-// we still attach the parsed cfg so init can run its own validation and emit its
+// The shared-file list used to live at hooks.json's own top-level "shared" key.
+// It moved to a sibling file, hooks/shared.json: the harness started
+// warning on hooks.json's unknown "shared" key once it began validating that
+// file against its own hook-registration schema, and "shared" was never part of
+// that schema, it was a Hypomnema-only convention the harness never asked for.
+// This module still folds shared.json's contents onto `cfg.shared` after
+// reading it, so every existing caller of deriveCoreHookBasenames keeps working
+// against the same shape without a signature change.
+//
+// fail-closed: a result is ok only when both files read, parse, AND have the
+// expected shape (a hooks registration map, and a shared array). A parsed but
+// oddly shaped input would yield a thin basename set, which is exactly the gap
+// through which a core hook could leak into capture. When the shape is off we
+// still attach the parsed cfg so init can run its own validation and emit its
 // own specific error, but ok is false so capture stays conservative.
 
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 
 /**
- * Read and JSON-parse hooks/hooks.json from a package root. No process.exit, no
- * top-level side effects.
+ * Read and JSON-parse hooks/hooks.json and hooks/shared.json from a package
+ * root. No process.exit, no top-level side effects.
  *
  * @param {string} pkgRoot  absolute path to the package root (contains hooks/)
  * @returns {{ ok: true, cfg: object }
  *   | { ok: false, error: string }
  *   | { ok: false, error: string, cfg: * }}
- *   On read or parse failure the `cfg` key is absent. On a successful parse the
- *   `cfg` key is always present (even for null/array/scalar/shape-off inputs),
- *   so a caller can discriminate read/parse failure from shape failure by the
- *   presence of the `cfg` key. `ok` is true only when the shape is as expected.
+ *   On read or parse failure of hooks.json the `cfg` key is absent. Once
+ *   hooks.json parses, `cfg` is always present (even for null/array/scalar/
+ *   shape-off inputs), so a caller can discriminate a hooks.json read/parse
+ *   failure from a shape failure (including a shared.json failure) by the
+ *   presence of the `cfg` key. `ok` is true only when both files' shapes are
+ *   as expected, and when true `cfg.shared` is the parsed shared.json array.
  */
 export function readCoreHooksConfig(pkgRoot) {
   let raw;
@@ -55,15 +67,12 @@ export function readCoreHooksConfig(pkgRoot) {
   if (!cfg.hooks || typeof cfg.hooks !== 'object' || Array.isArray(cfg.hooks)) {
     return { ok: false, error: 'hooks/hooks.json must contain a "hooks" object', cfg };
   }
-  if (!Array.isArray(cfg.shared)) {
-    return { ok: false, error: 'hooks/hooks.json must contain a "shared" array', cfg };
-  }
   // Nested shape: a structurally odd rung (event not an array, a group without a
-  // hooks array, a hook entry with no string command, a non-string shared element)
-  // is silently skipped by deriveCoreHookBasenames, yielding a THIN reserved set.
-  // That is the gap through which a core hook could leak into reverse-capture, so
-  // validate every rung and fail closed. cfg is still attached so init can run its
-  // own detailed validation and emit its own specific error.
+  // hooks array, a hook entry with no string command) is silently skipped by
+  // deriveCoreHookBasenames, yielding a THIN reserved set. That is the gap
+  // through which a core hook could leak into reverse-capture, so validate
+  // every rung and fail closed. cfg is still attached so init can run its own
+  // detailed validation and emit its own specific error.
   for (const groups of Object.values(cfg.hooks)) {
     if (!Array.isArray(groups)) {
       return { ok: false, error: 'each hooks event must map to an array of groups', cfg };
@@ -86,11 +95,28 @@ export function readCoreHooksConfig(pkgRoot) {
       }
     }
   }
-  for (const file of cfg.shared) {
+
+  let sharedRaw;
+  try {
+    sharedRaw = readFileSync(join(pkgRoot, 'hooks', 'shared.json'), 'utf-8');
+  } catch (err) {
+    return { ok: false, error: `cannot read hooks/shared.json: ${err.message}`, cfg };
+  }
+  let shared;
+  try {
+    shared = JSON.parse(sharedRaw);
+  } catch (err) {
+    return { ok: false, error: `hooks/shared.json is not valid JSON: ${err.message}`, cfg };
+  }
+  if (!Array.isArray(shared)) {
+    return { ok: false, error: 'hooks/shared.json must be a JSON array', cfg };
+  }
+  for (const file of shared) {
     if (typeof file !== 'string') {
-      return { ok: false, error: 'each "shared" entry must be a string', cfg };
+      return { ok: false, error: 'each hooks/shared.json entry must be a string', cfg };
     }
   }
+  cfg.shared = shared;
   return { ok: true, cfg };
 }