hypomnema 1.7.3 → 1.8.0

package/hooks/version-check.mjs

@@ -156,16 +156,54 @@ export function selectPluginVersion(plugins) {
   return typeof v === 'string' ? v : null;
 }
 
-/** Channel-specific one-line update instruction. */
+/** The command that runs an upgrade apply, in the form the caller's channel can
+ *  actually run. A plugin-only install has no `hypomnema` on PATH: that binary is
+ *  the npm package's bin, while the plugin manifest ships commands only. And the
+ *  slash command takes no `--apply` argument, so naming the flag there describes
+ *  a call it does not make: it runs the check and appends --apply only after the
+ *  operator confirms.
+ *
+ *  Lives here because both hooks and scripts need it and the dependency only
+ *  runs one way (scripts import hooks, never the reverse). This file is already
+ *  in hooks.json's `shared` list, so it reaches every standalone install.
+ *
+ *  Use UPGRADE_APPLY_EITHER when the target channel is genuinely unknown, e.g.
+ *  an instruction about a DIFFERENT machine. */
+export function upgradeApplyHint(isPluginChannel) {
+  return isPluginChannel
+    ? '`/hypo:upgrade` (confirm the apply step)'
+    : '`hypomnema upgrade --apply`';
+}
+
+export const UPGRADE_APPLY_EITHER =
+  '`hypomnema upgrade --apply` (or `/hypo:upgrade` on a plugin install)';
+
+/** Channel-specific one-line update instruction.
+ *
+ *  Every channel ends with the same second step. Installing a release does NOT
+ *  repoint the vault's git pre-commit hook: that hook holds an absolute path
+ *  baked in at init time, and only `upgrade --apply` rewrites it. No hook can
+ *  do it either (a hook must never invoke an apply path). Without this line the
+ *  user updates, sees the new version string, and keeps committing through the
+ *  install they had when they first ran init. */
 export function buildUpdateLine(channel, current, latest) {
   const head = `[Hypomnema] Update available! ${current} → ${latest}`;
+  // The repoint step has to be RUNNABLE on the channel it is printed for. A
+  // plugin-only install has no `hypomnema` on PATH (that binary is the npm
+  // package's bin; the plugin manifest ships commands only), so its form is the
+  // slash command. And the slash command takes no --apply argument: that
+  // command runs the check first and only appends --apply after the operator
+  // confirms, so naming the flag there would describe a call the command does
+  // not make. Both mistakes are the same class as naming a flag no script parses.
+  const repoint = (cmd) => `\n  → then: ${cmd}  (repoints the vault's git hook at the new install)`;
   if (channel === 'plugin') {
-    return `${head}\n  → run: /plugin marketplace update hypomnema  then  /reload-plugins`;
-  }
-  if (channel === 'npm') {
-    return `${head}\n  → run: npm install -g hypomnema`;
+    return `${head}\n  → run: /plugin marketplace update hypomnema  then  /reload-plugins${repoint(upgradeApplyHint(true))}`;
   }
-  return `${head}\n  → npm i -g hypomnema  (or  /plugin marketplace update hypomnema && /reload-plugins)`;
+  // The only remaining displayed channel is npm: computeNotice drops 'unknown'
+  // before anything renders, and a dual install reports the channel of the hook
+  // root actually running, never a third "mixed" value. A branch for one would
+  // be code no user reaches.
+  return `${head}\n  → run: npm install -g hypomnema${repoint(upgradeApplyHint(false))}`;
 }
 
 // ── cache freshness + notice decision (pure) ─────────────────────────────────

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hypomnema",
-  "version": "1.7.3",
+  "version": "1.8.0",
   "description": "LLM-native personal wiki system for Claude Code",
   "type": "module",
   "license": "MIT",
@@ -28,6 +28,11 @@
     "scripts/verify.mjs",
     "scripts/weekly-report.mjs",
     "scripts/lib/core-hooks.mjs",
+    "scripts/lib/crystallize-args.mjs",
+    "scripts/lib/crystallize-close-apply.mjs",
+    "scripts/lib/crystallize-close-check.mjs",
+    "scripts/lib/crystallize-close-gate.mjs",
+    "scripts/lib/crystallize-helpers.mjs",
     "scripts/lib/design-history-stale.mjs",
     "scripts/lib/extensions.mjs",
     "scripts/lib/failure-type.mjs",
@@ -43,6 +48,7 @@
     "scripts/lib/project-create.mjs",
     "scripts/lib/rename-marker.mjs",
     "scripts/lib/schema-vocab.mjs",
+    "scripts/lib/slug-resolver.mjs",
     "scripts/lib/template-schema-version.mjs",
     "scripts/lib/wd-match.mjs",
     "scripts/lib/wikilink.mjs",
@@ -52,7 +58,8 @@
     "templates/",
     "docs/",
     ".claude-plugin/",
-    "README.md"
+    "README.md",
+    "CHANGELOG.md"
   ],
   "keywords": [
     "wiki",
@@ -91,6 +98,6 @@
     "prepublishOnly": "npm test && npm run lint && npm run check:versions && npm run smoke:plugin && node scripts/check-pack-surface.mjs && npm run smoke-pack && npm run check:bilingual && npm run check:tracker-ids"
   },
   "devDependencies": {
-    "prettier": "^3.8.3"
+    "prettier": "3.8.3"
   }
 }

package/scripts/capture.mjs

@@ -32,6 +32,7 @@
  * acquired through the normal sync path, never by injecting a SHA directly.
  */
 
+import { UPGRADE_APPLY_EITHER } from '../hooks/version-check.mjs';
 import {
   existsSync,
   readFileSync,
@@ -45,7 +46,8 @@ import {
   openSync,
   closeSync,
   statSync,
-  chmodSync,
+  fstatSync,
+  fchmodSync,
 } from 'fs';
 import { randomBytes } from 'crypto';
 import { join, dirname, relative, sep } from 'path';
@@ -75,6 +77,8 @@ import {
   scanSettingsHooks,
   parseCapturableHookCommand,
   HOOK_EVENT_ALLOWLIST,
+  HOOK_INTERPRETER_EXT,
+  DEFAULT_HOOK_INTERPRETER,
   SKILL_ROOT_FILE,
   EXT_PREFIX,
   withSrcExecBits,
@@ -89,8 +93,9 @@ const HOME = homedir();
 const PKG_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
 
 // Captured types and their singular manifest `type` value. commands/agents install
-// as top-level `.md` files; hooks install as `.mjs` and additionally register a
-// settings.json entry (reverse of forward-sync); skills install as a DIRECTORY.
+// as top-level `.md` files; hooks install as an interpreter-specific executable
+// (.mjs/.py/.sh) and additionally register a settings.json entry
+// (reverse of forward-sync); skills install as a DIRECTORY.
 const CAPTURE_TYPES = ['commands', 'agents', 'hooks', 'skills'];
 // The flat, single-file types. `TYPE_EXT` has no `skills` entry on purpose: a skill
 // has no install extension, and letting it through a flat helper would silently
@@ -100,7 +105,20 @@ const FLAT_TYPES = ['commands', 'agents', 'hooks'];
 // registration instead, and skills have their own directory scanner.
 const READDIR_TYPES = ['commands', 'agents'];
 const TYPE_SINGULAR = { commands: 'command', agents: 'agent', hooks: 'hook', skills: 'skill' };
-const TYPE_EXT = { commands: '.md', agents: '.md', hooks: '.mjs' };
+// `TYPE_EXT` has no `hooks` entry either, for the same reason as skills: a hook's
+// extension depends on its interpreter (HOOK_INTERPRETER_EXT), not its type.
+// captureFileExt() is the one place that resolves it; every hook-touching call
+// site below goes through that, not this map.
+const TYPE_EXT = { commands: '.md', agents: '.md' };
+
+/** The install/wiki-storage extension for one capture candidate. hooks vary by
+ * interpreter (mirrors buildHookCommand/parseCapturableHookCommand in
+ * extensions.mjs); the other flat types have one fixed extension. */
+function captureFileExt(c) {
+  return c.type === 'hooks'
+    ? HOOK_INTERPRETER_EXT[c.interpreter ?? DEFAULT_HOOK_INTERPRETER]
+    : TYPE_EXT[c.type];
+}
 
 // Ceilings for a captured skill subtree (skills-capture design §3). A hand-authored
 // skill is a handful of files; a vendored one (gstack: 14,311 files / 1.1GB, mostly
@@ -123,9 +141,14 @@ function pkgJsonPath() {
  * hooks/commands + already-synced hypo-ext-* copies), anything already owned
  * (a recorded SHA for its install path means the wiki already manages it), and
  * non-.md files. Symlink/non-regular is checked by the caller (needs an fs stat).
+ * `type` must be a flat readdir type with a single fixed extension (TYPE_EXT);
+ * hooks have no entry there (extension depends on interpreter) and are never
+ * routed through this function — scanCandidates only calls it for READDIR_TYPES.
  */
 export function isCaptureCandidate(type, file, recorded) {
-  if (!file.endsWith(TYPE_EXT[type])) return { ok: false, reason: `not a ${TYPE_EXT[type]} file` };
+  const ext = TYPE_EXT[type];
+  if (!ext) return { ok: false, reason: `capture-by-readdir does not cover ${type}` };
+  if (!file.endsWith(ext)) return { ok: false, reason: `not a ${ext} file` };
   const lower = file.toLowerCase();
   if (lower === 'hypo' || lower.startsWith('hypo-')) {
     return { ok: false, reason: 'reserved hypo namespace' };
@@ -295,10 +318,14 @@ export function planSkillCapture({
 /**
  * Reverse-generate the sidecar manifest for a capture candidate. commands/agents
  * carry only `{ type, installName }`; hooks additionally carry the settings
- * registration fields `{ event, matcher?, timeout? }`. matcher/timeout are omitted
- * when absent (an empty-string matcher is already normalized to undefined by the
- * scanner) via conditional spread, so the in-memory object never carries an
- * `undefined`-valued key that would break the planCapture deep-equality check.
+ * registration fields `{ event, matcher?, timeout?, interpreter? }`. Every
+ * optional field is omitted when it would equal its default (an empty-string
+ * matcher is already normalized to undefined by the scanner; `node` is the
+ * default interpreter) via conditional spread, so the in-memory object never
+ * carries an `undefined`-valued key or a redundant explicit default, either of
+ * which would break the planCapture deep-equality check against a manifest
+ * captured before interpreter support landed (a `.mjs` hook's manifest must stay byte-for-byte
+ * identical, or every prior capture becomes a false conflict).
  */
 function buildWantManifest(c) {
   const manifest = { type: TYPE_SINGULAR[c.type], installName: c.stem };
@@ -306,6 +333,9 @@ function buildWantManifest(c) {
     manifest.event = c.event;
     if (c.matcher !== undefined && c.matcher !== '') manifest.matcher = c.matcher;
     if (c.timeout !== undefined) manifest.timeout = c.timeout;
+    if (c.interpreter !== undefined && c.interpreter !== DEFAULT_HOOK_INTERPRETER) {
+      manifest.interpreter = c.interpreter;
+    }
   }
   return manifest;
 }
@@ -437,8 +467,9 @@ function subsetOf(keys, allowed) {
  * canonical.
  *
  * A candidate must satisfy ALL of: strict command grammar
- * (`parseCapturableHookCommand`) resolving under `~/.claude/hooks/`; the resolved
- * `.mjs` is a real regular file (no symlink / non-regular); `type === 'command'`;
+ * (`parseCapturableHookCommand`, which also recovers the interpreter — node,
+ * python3, or bash) resolving under `~/.claude/hooks/`; the resolved
+ * file is a real regular file (no symlink / non-regular); `type === 'command'`;
  * the event is in `HOOK_EVENT_ALLOWLIST`; a preservable shape (F3); the case-folded
  * basename appears exactly once across all settings hooks (F6); and the stem is not
  * a core hook, not the reserved hypo namespace, and not already wiki-owned.
@@ -478,7 +509,7 @@ export function scanHookCandidates(claudeHome, settingsPath, recorded, coreBasen
       skipped.push({ type: 'hooks', command: rec.command, reason: parsed.reason });
       continue;
     }
-    const { stem, basename } = parsed;
+    const { stem, basename, interpreter } = parsed;
     const label = `hooks/${basename}`;
 
     // Duplicate first: a basename registered 2+ times is uniformly skipped so both
@@ -546,6 +577,7 @@ export function scanHookCandidates(claudeHome, settingsPath, recorded, coreBasen
       event: rec.event,
       matcher: rec.matcher,
       timeout: rec.timeout,
+      interpreter,
       label,
     });
   }
@@ -589,17 +621,27 @@ function log(msg) {
 // so this still has to be a separate chmod). Omitted for a manifest write: that
 // content is JSON we generated, not a copy of something with a mode worth
 // keeping.
+//
+// The mode is set on the open FD (`fchmodSync`), before the FD is closed, the
+// same ordering the forward writer (extensions.mjs's writeFreshAtomic) already
+// uses. A pathname-based `chmodSync(tmp, ...)` run after `closeSync` reopens
+// `tmp` by name, and a competing process racing this write could have already
+// deleted `tmp` and planted a symlink at that name in the gap between close
+// and chmod — `wx` only protects the file's creation, not everything after it.
+// Chmod-ing the FD closes that window: it always addresses the file this
+// process itself just created, never whatever a symlink at the same name
+// might point to by the time the pathname is looked up again.
 function writeAtomic(dest, buf, srcMode) {
   const tmp = `${dest}.tmp.${process.pid}.${randomBytes(6).toString('hex')}`;
   const fd = openSync(tmp, 'wx');
   try {
     writeFileSync(fd, buf);
+    if (srcMode != null) {
+      fchmodSync(fd, withSrcExecBits(fstatSync(fd).mode, srcMode));
+    }
   } finally {
     closeSync(fd);
   }
-  if (srcMode != null) {
-    chmodSync(tmp, withSrcExecBits(statSync(tmp).mode, srcMode));
-  }
   try {
     renameSync(tmp, dest);
   } catch (err) {
@@ -982,7 +1024,7 @@ function run(args, { claudeHome = join(HOME, '.claude') } = {}) {
       captureOneSkill({ c, extDir, guard, wikiRoot, args, captured, skipped, created });
       continue;
     }
-    const fileExt = TYPE_EXT[c.type];
+    const fileExt = captureFileExt(c);
     const wikiStem = `${EXT_PREFIX}${c.stem}`;
     const typeDir = join(extDir, c.type);
     const filePath = join(typeDir, `${wikiStem}${fileExt}`);
@@ -1013,11 +1055,12 @@ function run(args, { claudeHome = join(HOME, '.claude') } = {}) {
     const plan = planCapture({ wantManifest, srcSha, existingFileSha, existingManifestRaw });
 
     // installFile is the ORIGINAL name the far machine installs under (installName
-    // adoption); for hooks that is `<stem>.mjs`, for commands/agents `<stem>.md`.
+    // adoption); for hooks that is `<stem>` plus its interpreter's extension
+    // (`.mjs`/`.py`/`.sh`), for commands/agents `<stem>.md`.
     const installFile = `${c.stem}${fileExt}`;
     // Ownership keys sync must record for the adoption to count. Hooks track BOTH
-    // the `.mjs` and its `.manifest.json` sidecar under the install path (success
-    // criterion d); commands/agents track only the single install file.
+    // the main file and its `.manifest.json` sidecar under the install path
+    // (success criterion d); commands/agents track only the single install file.
     const requiredKeys =
       c.type === 'hooks'
         ? [`hooks/${installFile}`, `hooks/${c.stem}.manifest.json`]
@@ -1162,7 +1205,7 @@ function report(captured, skipped, failed, dryRun) {
       const dest =
         c.type === 'skills'
           ? `extensions/skills/${EXT_PREFIX}${c.stem}/`
-          : `extensions/${c.type}/${EXT_PREFIX}${c.stem}${TYPE_EXT[c.type]}`;
+          : `extensions/${c.type}/${EXT_PREFIX}${c.stem}${captureFileExt(c)}`;
       log(`  ${c.type}/${c.file} → ${dest}`);
     }
   }
@@ -1171,7 +1214,7 @@ function report(captured, skipped, failed, dryRun) {
     log(`Failed to adopt ${failed.length} (see sync warnings; wiki files rolled back).`);
   if (!dryRun && captured.some((c) => c.status === 'captured')) {
     log('');
-    log('Next: commit + push the wiki, then run `hypomnema upgrade --apply` on another machine.');
+    log(`Next: commit + push the wiki, then run ${UPGRADE_APPLY_EITHER} on another machine.`);
   }
 }