hypomnema 1.6.2 → 1.7.0

package/scripts/graph.mjs

@@ -16,7 +16,7 @@
 
 import { readFileSync } from 'fs';
 import { join } from 'path';
-import { resolveHypoRoot, expandHome } from './lib/hypo-root.mjs';
+import { resolveHypoRootInfo, checkVaultOrExit, expandHome } from './lib/hypo-root.mjs';
 import { loadHypoIgnore } from './lib/hypo-ignore.mjs';
 import { collectPagesGraph, extractWikilinks } from './lib/wikilink.mjs';
 
@@ -29,7 +29,11 @@ function parseArgs(argv) {
     else if (arg.startsWith('--format=')) args.format = arg.slice(9);
     else if (arg.startsWith('--min-edges=')) args.minEdges = parseInt(arg.slice(12), 10) || 0;
   }
-  if (!args.hypoDir) args.hypoDir = resolveHypoRoot();
+  if (!args.hypoDir) {
+    const info = resolveHypoRootInfo();
+    args.hypoDir = info.root;
+    args.hypoDirSource = info.source;
+  }
   return args;
 }
 
@@ -150,6 +154,9 @@ function formatDot(pages, graph, minEdges) {
 // ── main ──────────────────────────────────────────────────────────────────────
 
 const args = parseArgs(process.argv);
+// Only validate the auto-resolved path (env/marker/default). An explicit
+// --hypo-dir=<path> (tests, other tooling) is trusted as-is, valid or not.
+if (args.hypoDirSource) checkVaultOrExit(args.hypoDir, args.hypoDirSource);
 
 const ignorePatterns = loadHypoIgnore(args.hypoDir);
 const scanDirs = ['pages', 'projects'].map((d) => join(args.hypoDir, d));

package/scripts/init.mjs

@@ -32,7 +32,7 @@ import {
   renameSync,
   unlinkSync,
 } from 'fs';
-import { join, basename, dirname } from 'path';
+import { join, basename, dirname, resolve } from 'path';
 import { homedir } from 'os';
 import { execSync, spawnSync } from 'child_process';
 import { fileURLToPath } from 'url';
@@ -49,6 +49,11 @@ import {
 import { syncExtensions } from './lib/extensions.mjs';
 import { templateSchemaVersion } from './lib/template-schema-version.mjs';
 import { classifyInstall, downgradeGuardMessage } from '../hooks/version-check.mjs';
+import {
+  isHypomnemaPluginEnabled,
+  resolveEnabledPluginRoot as resolveEnabledPluginRootShared,
+  usablePkgRoot,
+} from './lib/plugin-detect.mjs';
 
 const HOME = homedir();
 const SCRIPT_DIR = fileURLToPath(new URL('.', import.meta.url));
@@ -93,6 +98,7 @@ const KNOWN_SUBCOMMANDS = new Set([
   'uninstall',
   'feedback-sync',
   'capture',
+  'proposal',
 ]);
 const _verb = process.argv[2];
 if (_verb && KNOWN_SUBCOMMANDS.has(_verb) && _verb !== 'init') {
@@ -119,6 +125,7 @@ function parseArgs(argv) {
     shellSetup: true,
     shellConfig: null,
     allowDowngrade: false,
+    lintStrict: false,
   };
   for (const arg of argv.slice(2)) {
     if (arg === '--help' || arg === '-h') {
@@ -132,6 +139,9 @@ Commands:
   uninstall               Remove hooks and registrations (dry-run by default; pass --apply)
   feedback-sync           Project feedback (SoT) → MEMORY.md / CLAUDE.md learned-behaviors
                           projection (--check default, --write to apply)
+  capture                 Reverse-capture ~/.claude/{commands,agents} extensions and
+                          settings.json hooks into the wiki for cross-machine sync
+                          (pass names or --all; --dry-run to preview)
 
   Running \`hypomnema\` with no command is equivalent to \`hypomnema init\`.
 
@@ -149,11 +159,15 @@ Init options:
   --shell-config=<path>  Shell config file path (default: auto-detect)
   --allow-downgrade      Override the guard that refuses to overwrite NEWER active
                          hooks with an older package (stale-PATH-CLI footgun)
+  --lint-strict          Opt-in: also gate the wiki pre-commit hook on
+                         \`lint --strict\` (promotes STRICT_PROMOTE_IDS warnings
+                         to a blocking error), sequenced after the .hypoignore
+                         guard. Off by default; re-run init to add or drop it.
   --dry-run              Show what would be done without making changes
   --help, -h             Show this help message
 
-Subcommand-specific flags (upgrade/doctor/uninstall) live in the
-docstring at the top of scripts/<command>.mjs.`);
+Subcommand-specific flags (upgrade/doctor/uninstall/capture) live in the
+docstring at the top of scripts/<command>.mjs; capture also accepts \`--help\`.`);
       process.exit(0);
     } else if (arg.startsWith('--hypo-dir=')) args.hypoDir = expandHome(arg.slice(11));
     else if (arg === '--no-hooks') args.hooks = false;
@@ -174,6 +188,7 @@ docstring at the top of scripts/<command>.mjs.`);
     else if (arg === '--no-shell') args.shellSetup = false;
     else if (arg.startsWith('--shell-config=')) args.shellConfig = expandHome(arg.slice(15));
     else if (arg === '--allow-downgrade') args.allowDowngrade = true;
+    else if (arg === '--lint-strict') args.lintStrict = true;
   }
   return args;
 }
@@ -286,6 +301,23 @@ function writeWikiignore(hypoDir, dryRun) {
   log('created', dest);
 }
 
+// ── .hyposcanignore ──────────────────────────────────────────────────────────
+// Scan-only exclusion sibling to .hypoignore. NOT a privacy boundary — see
+// templates/.hyposcanignore's header. Absence is fine: every scan-ignore
+// reader treats a missing file as an empty pattern list.
+
+function writeScanIgnore(hypoDir, dryRun) {
+  const dest = join(hypoDir, '.hyposcanignore');
+  if (existsSync(dest)) {
+    log('skipped', dest);
+    return;
+  }
+  const src = join(TEMPLATES, '.hyposcanignore');
+  const content = existsSync(src) ? readFileSync(src, 'utf-8') : '';
+  if (!dryRun) writeFileSync(dest, content);
+  log('created', dest);
+}
+
 // ── .gitignore ───────────────────────────────────────────────────────────────
 
 function writeGitignore(hypoDir, dryRun) {
@@ -468,34 +500,77 @@ function pkgJsonPath() {
  * install (no metadata), unparseable versions, the same package re-running itself,
  * --allow-downgrade, or --dry-run.
  */
-function maybeRefuseDowngrade(op, allowDowngrade, dryRun) {
-  if (allowDowngrade || dryRun) return;
+function maybeRefuseDowngrade(op, allowDowngrade, dryRun, durableRoot) {
+  if (allowDowngrade || dryRun || !PKG_VERSION) return;
   const active = readPkgJsonSafe(pkgJsonPath());
-  if (!active || !active.pkgVersion || !PKG_VERSION) return;
-  const verdict = classifyInstall(
-    { pkgRoot: PKG_ROOT, version: PKG_VERSION },
-    { pkgRoot: active.pkgRoot, version: active.pkgVersion },
-  );
-  if (verdict === 'downgrade') {
-    console.error(downgradeGuardMessage(PKG_VERSION, active.pkgVersion, op));
-    process.exit(2);
+  const candidates = [];
+  // The recorded metadata: catches a stale bin trying to downgrade a newer
+  // recorded install (the original guard).
+  if (active && active.pkgVersion) {
+    candidates.push({ pkgRoot: active.pkgRoot, version: active.pkgVersion });
+  }
+  // The positively-resolved durable (plugin) install, when it is a DIFFERENT root
+  // than this package. In an npm-first dual install the recorded pkgVersion is the
+  // stale npm one, so comparing only against it lets an OLDER npm init run against a
+  // NEWER plugin; also compare against the plugin's own version. readPkgVersionAt
+  // yields a version only for a usable root.
+  if (durableRoot && durableRoot !== PKG_ROOT) {
+    const durableVersion = readPkgVersionAt(durableRoot);
+    if (durableVersion) candidates.push({ pkgRoot: durableRoot, version: durableVersion });
+  }
+  for (const active of candidates) {
+    const verdict = classifyInstall(
+      { pkgRoot: PKG_ROOT, version: PKG_VERSION },
+      { pkgRoot: active.pkgRoot, version: active.version },
+    );
+    if (verdict === 'downgrade') {
+      console.error(downgradeGuardMessage(PKG_VERSION, active.version, op));
+      process.exit(2);
+    }
+  }
+}
+
+function readPkgVersionAt(root) {
+  try {
+    const v = JSON.parse(readFileSync(join(root, 'package.json'), 'utf-8')).version;
+    return typeof v === 'string' && v.length > 0 ? v : null;
+  } catch {
+    return null;
   }
 }
 
-function writePkgJson(dryRun, extraFields = {}) {
+// 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.
+
+function writePkgJson(dryRun, extraFields = {}, root = PKG_ROOT) {
   const dest = pkgJsonPath();
   const existing = readPkgJsonSafe(dest);
+  // `root` is the DURABLE install root the runtime resolves scripts through
+  // (hooks/hypo-shared.mjs reads pkgRoot): PKG_ROOT for a normal install, the
+  // positively-resolved plugin cache root for a dual install (see resolveDurableRoot).
+  // pkgVersion is read from `root` too — stamping a dual-install pointer at the
+  // plugin with THIS npm package's version would make doctor's own version-match
+  // check contradict itself. schemaVersion describes the templates init writes,
+  // which always come from PKG_ROOT regardless of where scripts resolve.
   const merged = {
     ...existing,
-    pkgRoot: PKG_ROOT,
-    pkgVersion: PKG_VERSION,
+    pkgRoot: root,
+    pkgVersion: readPkgVersionAt(root) ?? PKG_VERSION,
     schemaVersion: templateSchemaVersion(PKG_ROOT) ?? '2.1',
     ...extraFields,
   };
-  if (!dryRun) {
+  // Skip the write outright when the durable identity already matches what is on
+  // disk, rather than re-serialize an unchanged file. That keeps the dry-run and
+  // real write-sets identical: a real run must never silently rewrite a file a dry
+  // run reported as skipped. A genuine change (fresh identity, a version bump, or a
+  // dual-install correction from a stale npm pointer to the plugin root) is logged
+  // as "created" so it shows up in both write-sets. Log is emitted unconditionally
+  // (outside the dryRun guard) so a dry run previews exactly what a real run does.
+  const noWrite = JSON.stringify(merged) === JSON.stringify(existing);
+  if (!dryRun && !noWrite) {
     writePkgJsonAtomic(dest, merged);
-    log('created', dest);
   }
+  log(noWrite ? 'skipped' : 'created', noWrite ? `${dest} (durable pkgRoot unchanged)` : dest);
   return merged;
 }
 
@@ -638,19 +713,56 @@ function installPkgGitHook(dryRun) {
 const WIKI_PRE_COMMIT_MARKER_START = '# hypo-managed:pre-commit:start';
 const WIKI_PRE_COMMIT_MARKER_END = '# hypo-managed:pre-commit:end';
 
-function wikiPreCommitContent() {
-  const worker = join(PKG_ROOT, 'hooks', 'hypo-pre-commit.mjs');
-  // Single-quote escaping prevents shell expansion of special chars (e.g. $HOME, backticks) in path
-  const escaped = worker.replace(/'/g, "'\\''");
-  return `#!/bin/sh\n${WIKI_PRE_COMMIT_MARKER_START}\nnode '${escaped}'\nexit $?\n${WIKI_PRE_COMMIT_MARKER_END}\n`;
+// Single-quote escaping prevents shell expansion of special chars (e.g. $HOME, backticks) in path
+function shellSingleQuote(p) {
+  return `'${p.replace(/'/g, "'\\''")}'`;
+}
+
+// `root` is the DURABLE install root the hook should resolve hypo-pre-commit.mjs
+// (and, when opted in, lint.mjs) through — not necessarily PKG_ROOT. In a dual
+// install (a manual/npm init while the plugin is enabled) PKG_ROOT is the
+// manual/npm checkout the dual-install notice tells the user to uninstall;
+// embedding it here would leave the vault's git hook dangling the moment they
+// do, breaking every wiki commit. The caller passes the preserved plugin-owned
+// root instead (see `durableRoot`), so the hook points at the install that
+// actually persists.
+//
+// The block runs its steps sequentially rather than tail-calling `exit $?` on
+// the first one, so a second step (the opt-in --lint-strict gate below) can
+// run after the .hypoignore guard instead of being unreachable dead code.
+// `lintStrict` is baked into the generated shim at install time — the same
+// pattern already used for HYPOMNEMA_ROOT/HYPOMNEMA_GIT_DIR in
+// install-git-hooks.mjs — so toggling it means re-running init with/without
+// `--lint-strict`, not editing the hook by hand.
+//
+// `hypoDir` MUST be absolutized before it is baked in. Git runs a pre-commit
+// hook with cwd set to the wiki's own working-tree root, so a relative
+// `--hypo-dir` (e.g. from `hypo init --hypo-dir=wiki` run from its parent) is
+// re-resolved AT COMMIT TIME against that root instead of the directory the
+// caller meant — `wiki` becomes `<wiki-root>/wiki`, a path that doesn't exist,
+// and lint.mjs falls through to its own default resolution (HYPO_DIR/
+// hypo-config.md scan) and may silently lint an unrelated vault. `worker`
+// needs no such treatment: `root` is already realpath'd upstream (see
+// `durableRoot` / PKG_ROOT resolution), so it's absolute at every call site.
+function wikiPreCommitContent(root, hypoDir, lintStrict) {
+  const absHypoDir = resolve(hypoDir);
+  const worker = join(root, 'hooks', 'hypo-pre-commit.mjs');
+  const steps = [`node ${shellSingleQuote(worker)} || exit 1`];
+  if (lintStrict) {
+    const lintScript = join(root, 'scripts', 'lint.mjs');
+    steps.push(
+      `node ${shellSingleQuote(lintScript)} --hypo-dir=${shellSingleQuote(absHypoDir)} --strict || exit 1`,
+    );
+  }
+  return `#!/bin/sh\n${WIKI_PRE_COMMIT_MARKER_START}\n${steps.join('\n')}\nexit 0\n${WIKI_PRE_COMMIT_MARKER_END}\n`;
 }
 
-function installWikiPreCommitHook(hypoDir, dryRun, force) {
+function installWikiPreCommitHook(hypoDir, dryRun, force, root, lintStrict) {
   const gitDir = join(hypoDir, '.git');
   if (!existsSync(gitDir)) return; // no git repo — silently skip
   const hooksDir = join(gitDir, 'hooks');
   const hookPath = join(hooksDir, 'pre-commit');
-  const newContent = wikiPreCommitContent();
+  const newContent = wikiPreCommitContent(root, hypoDir, lintStrict);
 
   if (existsSync(hookPath)) {
     const existing = readFileSync(hookPath, 'utf-8');
@@ -837,6 +949,66 @@ function firstCommit(hypoDir, remote, dryRun) {
 
 const args = parseArgs(process.argv);
 
+// ── install channel ───────────────────────────────────────────────────────────
+//
+// A plugin-channel install already provides the 14 core hooks + slash commands
+// through the package's own hooks/hooks.json + commands/ (Claude Code auto-wires
+// them). Copying the same hooks into ~/.claude/hooks and registering the same
+// events in settings.json on top makes every core hook fire TWICE, the same
+// failure mode already fixed for `upgrade --apply`. `pluginMode` mirrors
+// upgrade.mjs's own detector (this init.mjs itself running from a
+// `.claude/plugins/…` root); `hypomnemaPluginEnabled` catches the dual-install
+// variant (a manual/npm init.mjs run while the plugin is ALSO enabled — see
+// lib/plugin-detect.mjs, fail-open on any uncertainty). Either signal means
+// Claude's core hook/command surface is plugin-managed already.
+const pluginMode = PKG_ROOT.replace(/\\/g, '/').includes('/.claude/plugins/');
+const hypomnemaPluginEnabled =
+  !pluginMode && isHypomnemaPluginEnabled(join(HOME, '.claude', 'settings.json'));
+const coreManagedByPlugin = pluginMode || hypomnemaPluginEnabled;
+
+// resolveEnabledPluginRoot lives in ./lib/plugin-detect.mjs (shared with
+// upgrade.mjs's dualSkip provenance correction, imported above as
+// resolveEnabledPluginRootShared). This wrapper binds it to init's own HOME-derived
+// settings/registry paths so callers below read the same as before the move.
+function resolveEnabledPluginRoot(settingsPath) {
+  return resolveEnabledPluginRootShared(
+    settingsPath,
+    join(HOME, '.claude', 'plugins', 'installed_plugins.json'),
+  );
+}
+
+// Non-mutating read of the recorded pkgRoot. resolveDurableRoot runs before init's
+// package validation and its "no writes before validation" guarantee, so it must
+// NOT use readPkgJsonSafe (which renames a corrupt hypo-pkg.json aside — a write).
+function recordedPkgRoot() {
+  try {
+    const v = JSON.parse(readFileSync(pkgJsonPath(), 'utf-8')).pkgRoot;
+    return typeof v === 'string' ? v : null;
+  } catch {
+    return null;
+  }
+}
+
+// The durable install root that persistent artifacts (the vault's git pre-commit
+// hook, hypo-pkg.json) should point at. In a dual install PKG_ROOT is the
+// manual/npm checkout the dual-install notice tells the user to uninstall, so
+// point at the plugin's REAL cache root, positively resolved from the registry —
+// NOT at whatever pkgRoot is already recorded, which after an npm-first sequence
+// (npm init, enable plugin, npm init again) may itself be that soon-to-be-removed
+// npm root. Only if the registry cannot positively identify the plugin do we fall
+// back to a usable recorded pointer, then PKG_ROOT (never worse than pre-fix). In
+// true plugin mode PKG_ROOT already IS the plugin path; for npm-only it is the
+// only install.
+function resolveDurableRoot() {
+  if (!hypomnemaPluginEnabled) return PKG_ROOT;
+  const pluginRoot = resolveEnabledPluginRoot(join(HOME, '.claude', 'settings.json'));
+  if (pluginRoot) return pluginRoot;
+  const recorded = recordedPkgRoot();
+  if (usablePkgRoot(recorded)) return recorded;
+  return PKG_ROOT;
+}
+const durableRoot = resolveDurableRoot();
+
 // Validate hooks.json before any file writes so a bad package leaves no partial state
 const HOOK_MAP = args.hooks || args.codex ? loadHookMap() : null;
 
@@ -849,7 +1021,7 @@ const HOOK_MAP = args.hooks || args.codex ? loadHookMap() : null;
 // and, with `--codex`, writes ~/.codex hooks/settings. The guard no-ops on a fresh
 // install, same realpath'd pkgRoot (dev re-run / npm-link / post-commit sync),
 // --allow-downgrade, or --dry-run, so legitimate flows are unaffected.
-maybeRefuseDowngrade('init', args.allowDowngrade, args.dryRun);
+maybeRefuseDowngrade('init', args.allowDowngrade, args.dryRun, durableRoot);
 
 if (args.fromRemote) {
   // ── from-remote path: clone → read config → install hooks ──────────────────
@@ -917,24 +1089,38 @@ if (args.fromRemote) {
     args.dryRun,
   );
 
-  // 3. hypo-config.md + .hypoignore + .gitignore
+  // 3. hypo-config.md + .hypoignore + .hyposcanignore + .gitignore
   writeHypoConfig(args.hypoDir, args.dryRun);
   writeWikiignore(args.hypoDir, args.dryRun);
+  writeScanIgnore(args.hypoDir, args.dryRun);
   writeGitignore(args.hypoDir, args.dryRun);
 }
 
 // 4. hooks
 
+if (coreManagedByPlugin) {
+  log(
+    'skipped',
+    `Claude core hooks/settings/commands — provided by the plugin loader (${
+      pluginMode
+        ? 'this script is running from a Claude Code plugin install'
+        : 'the Hypomnema plugin is enabled in settings.json'
+    }); installing them here would register every hook twice. Use \`claude plugin update\` to upgrade instead.`,
+  );
+}
+
 let commandSHAs = null;
-if (args.commands) {
+if (args.commands && !coreManagedByPlugin) {
   const claudeCommands = join(HOME, '.claude', 'commands', 'hypo');
   commandSHAs = installCommands(claudeCommands, args.dryRun, args.forceCommands);
 }
 
 if (args.hooks) {
-  const claudeHooks = join(HOME, '.claude', 'hooks');
-  installHooks(claudeHooks, args.dryRun);
-  mergeSettingsJson(join(HOME, '.claude', 'settings.json'), claudeHooks, args.dryRun, HOOK_MAP);
+  if (!coreManagedByPlugin) {
+    const claudeHooks = join(HOME, '.claude', 'hooks');
+    installHooks(claudeHooks, args.dryRun);
+    mergeSettingsJson(join(HOME, '.claude', 'settings.json'), claudeHooks, args.dryRun, HOOK_MAP);
+  }
 }
 
 // Always record the active install identity (pkgRoot + pkgVersion), even for a
@@ -943,7 +1129,9 @@ if (args.hooks) {
 // the downgrade guard has nothing to compare against, so a later stale
 // sibling could repoint those surfaces unguarded. writePkgJson merges (...existing),
 // so this never clobbers a commands/extensions map written elsewhere.
-writePkgJson(args.dryRun, commandSHAs ? { commands: commandSHAs } : {});
+// Record hypo-pkg.json against the durable root (the plugin's real cache root in a
+// dual install, PKG_ROOT otherwise), the same root the wiki pre-commit hook uses.
+writePkgJson(args.dryRun, commandSHAs ? { commands: commandSHAs } : {}, durableRoot);
 
 // 4b. user extensions companion sync. Runs after
 // writePkgJson so the per-target SHA map is merged into the same hypo-pkg.json
@@ -1033,8 +1221,16 @@ if (args.hooks) {
   installPkgGitHook(args.dryRun);
 }
 
-// 8b. wiki pre-commit hook (.hypoignore last-line-of-defence guard — §6.8)
-installWikiPreCommitHook(args.hypoDir, args.dryRun, args.forceCommands);
+// 8b. wiki pre-commit hook (.hypoignore last-line-of-defence guard — §6.8).
+// Point it at the durable install root, not PKG_ROOT, so a dual install does not
+// embed a manual/npm path that dangles once the user uninstalls it.
+installWikiPreCommitHook(
+  args.hypoDir,
+  args.dryRun,
+  args.forceCommands,
+  durableRoot,
+  args.lintStrict,
+);
 
 // 9. first commit + push (skip when cloned from remote — already has commits)
 if (args.gitInit && !args.fromRemote) {