hypomnema 1.7.4 → 1.8.0

package/scripts/init.mjs

@@ -32,7 +32,7 @@ import {
   renameSync,
   unlinkSync,
 } from 'fs';
-import { join, basename, dirname, resolve } from 'path';
+import { join, basename, dirname } from 'path';
 import { homedir } from 'os';
 import { execSync, spawnSync } from 'child_process';
 import { fileURLToPath } from 'url';
@@ -47,6 +47,7 @@ import {
   SHELL_MARKER_START,
   SHELL_MARKER_END,
   SHELL_FUNCTION_BODY,
+  wikiPreCommitContent,
 } from './lib/git-hooks-dir.mjs';
 import { readCoreHooksConfig } from './lib/core-hooks.mjs';
 import {
@@ -60,11 +61,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 {
-  isHypomnemaPluginEnabled,
-  resolveEnabledPluginRoot as resolveEnabledPluginRootShared,
-  usablePkgRoot,
-} from './lib/plugin-detect.mjs';
+import { resolvePluginChannel, usablePkgRoot } from './lib/plugin-detect.mjs';
 
 const HOME = homedir();
 const SCRIPT_DIR = fileURLToPath(new URL('.', import.meta.url));
@@ -756,50 +753,12 @@ function installPkgGitHook(dryRun) {
 }
 
 // ── wiki pre-commit hook ─────────────────────────────────────────────────────
-
-// 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`;
-}
+// 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) {
   const { dir: hooksDir, skip } = hooksDirForInstall(hypoDir);
@@ -995,11 +954,16 @@ function gitSetup(hypoDir, remote, dryRun) {
 
 // ── first commit + push ──────────────────────────────────────────────────────
 
+// Returns true only when THIS run actually created a commit. The
+// channel-unresolved notice keys its "the commit this run just made was
+// unguarded" sentence off that, so a repo that already had commits, a dry run,
+// and a failed commit must all read as false — none of them produced an
+// unguarded commit to warn about.
 function firstCommit(hypoDir, remote, dryRun) {
   const logR = git(hypoDir, ['log', '--oneline', '-1']);
   if (logR.status === 0 && logR.stdout.trim()) {
     log('skipped', 'first commit (repo already has commits)');
-    return;
+    return false;
   }
   const today = new Date().toISOString().slice(0, 10);
   if (!dryRun) {
@@ -1007,7 +971,7 @@ function firstCommit(hypoDir, remote, dryRun) {
     const commitR = git(hypoDir, ['commit', '-m', `chore: init hypomnema (${today})`]);
     if (commitR.status !== 0) {
       log('errors', 'first commit failed');
-      return;
+      return false;
     }
     if (remote) {
       const actualOrigin = git(hypoDir, ['remote', 'get-url', 'origin']);
@@ -1018,6 +982,7 @@ function firstCommit(hypoDir, remote, dryRun) {
     }
   }
   log('created', `first commit (${today})`);
+  return !dryRun;
 }
 
 // ── main ─────────────────────────────────────────────────────────────────────
@@ -1026,7 +991,7 @@ const args = parseArgs(process.argv);
 
 // ── install channel ───────────────────────────────────────────────────────────
 //
-// A plugin-channel install already provides the 14 core hooks + slash commands
+// A plugin-channel install already provides the core hooks in hooks/hooks.json plus the 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
@@ -1035,22 +1000,15 @@ const args = parseArgs(process.argv);
 // `.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'),
-  );
-}
+// Claude's core hook/command surface is plugin-managed already. resolvePluginChannel
+// is the single place this judgment is made — doctor.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;
 
 // Non-mutating read of the recorded pkgRoot. resolveDurableRoot runs before init's
 // package validation and its "no writes before validation" guarantee, so it must
@@ -1076,13 +1034,55 @@ function recordedPkgRoot() {
 // only install.
 function resolveDurableRoot() {
   if (!hypomnemaPluginEnabled) return PKG_ROOT;
-  const pluginRoot = resolveEnabledPluginRoot(join(HOME, '.claude', 'settings.json'));
-  if (pluginRoot) return pluginRoot;
+  if (pluginChannel.root) return pluginChannel.root;
   const recorded = recordedPkgRoot();
   if (usablePkgRoot(recorded)) return recorded;
-  return PKG_ROOT;
+  // 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
+  // above. Falling back to PKG_ROOT would persist a GUESS as if it were the
+  // confirmed durable root; in a dual install PKG_ROOT is the manual/npm
+  // checkout the dual-install notice tells the user to remove, so that guess
+  // dangles the moment they do. A judge returning null here means "cannot
+  // positively resolve", never "resolved to nothing usable exists" — treating
+  // it as the latter is exactly the failure this fix closes.
+  // With no existing usable pointer to preserve either, leave the durable root
+  // UNRESOLVED (null) instead of guessing — the caller below skips writing the
+  // pointer and the pre-commit hook and prints recovery guidance rather than
+  // confirm a guess.
+  return null;
 }
 const durableRoot = resolveDurableRoot();
+// True only when the channel judgment itself failed and there was nothing usable
+// to fall back on (see resolveDurableRoot above) — never true for a genuinely
+// disabled/absent plugin, which resolves to PKG_ROOT and never reaches here.
+const channelUnresolved = durableRoot === null;
+let madeFirstCommit = false;
+
+function channelUnresolvedNotice(madeFirstCommit) {
+  // Step 9 (firstCommit) runs AFTER step 8b skipped the pre-commit hook install,
+  // so a commit this run created went out unguarded, not just future ones. Key
+  // this off what firstCommit actually did, never off the flags that merely make
+  // it eligible: --dry-run writes nothing, a repo with existing commits skips,
+  // and a failed commit produced none. Asserting "just made" in those cases
+  // sends the reader looking for a commit that does not exist.
+  const firstCommitCaveat = madeFirstCommit
+    ? ' The initial commit this run just made in the vault was not checked by that guard ' +
+      'either: it landed before any pre-commit hook existed to check it.'
+    : '';
+  return (
+    `⚠ Cannot positively resolve the enabled Hypomnema plugin's install root ` +
+    `(${pluginChannel.rootReason} — checked ~/.claude/plugins/installed_plugins.json). ` +
+    `Leaving the durable pointer UNSET rather than guessing the npm path at ${PKG_ROOT}: ` +
+    `that path is what a dual install's own notice tells you to remove, and baking it in ` +
+    `now would break every wiki commit the moment you do. hypo-pkg.json's pkgRoot and the ` +
+    `vault's git pre-commit hook are both skipped this run, so this wiki has no pre-commit ` +
+    `.hypoignore guard until this resolves.${firstCommitCaveat}\n` +
+    `  → Fix: repair or refresh ~/.claude/plugins/installed_plugins.json (reinstall the ` +
+    'plugin, or run `/plugin marketplace update hypomnema` then `/reload-plugins`), then ' +
+    're-run `hypomnema init` to record the confirmed root.'
+  );
+}
 
 // Validate hooks.json before any file writes so a bad package leaves no partial state
 const HOOK_MAP = args.hooks || args.codex ? loadHookMap() : null;
@@ -1206,7 +1206,20 @@ if (args.hooks) {
 // so this never clobbers a commands/extensions map written elsewhere.
 // 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);
+// A null durableRoot means the channel judgment failed with nothing usable to
+// preserve (see resolveDurableRoot) — skip the write rather than stamp a guess;
+// channelUnresolvedNotice() above explains why and what closes it. The
+// extensions sync below (step 4b) still runs unconditionally and can leave a
+// pkgRoot-less hypo-pkg.json on disk in this case; that is doctor.mjs's own
+// distinct reported state ("no pkgRoot field"), never a confirmed PKG_ROOT.
+if (!channelUnresolved) {
+  writePkgJson(args.dryRun, commandSHAs ? { commands: commandSHAs } : {}, durableRoot);
+} else {
+  log(
+    'skipped',
+    'hypo-pkg.json pkgRoot (plugin channel judgment failed — see notice above; re-run after fixing the registry)',
+  );
+}
 
 // 4b. user extensions companion sync. Runs after
 // writePkgJson so the per-target SHA map is merged into the same hypo-pkg.json
@@ -1298,23 +1311,35 @@ if (args.hooks) {
 
 // 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,
-);
+// embed a manual/npm path that dangles once the user uninstalls it. A null
+// durableRoot means the channel judgment failed with nothing usable to fall
+// back on — skip installing the hook with a guessed root; an existing hook (if
+// 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,
+  );
+} else {
+  log(
+    'skipped',
+    `${args.hypoDir} pre-commit hook (plugin channel judgment failed — see notice above)`,
+  );
+}
 
 // 9. first commit + push (skip when cloned from remote — already has commits)
 if (args.gitInit && !args.fromRemote) {
-  firstCommit(args.hypoDir, args.gitRemote, args.dryRun);
+  madeFirstCommit = firstCommit(args.hypoDir, args.gitRemote, args.dryRun);
 }
 
 // ── report ───────────────────────────────────────────────────────────────────
 
 const lines = [];
+if (channelUnresolved) lines.push(channelUnresolvedNotice(madeFirstCommit), '');
 if (results.created.length)
   lines.push(
     `✓ Created (${results.created.length}):\n${results.created.map((p) => `  ${p}`).join('\n')}`,

package/scripts/lib/crystallize-args.mjs

@@ -0,0 +1,50 @@
+import { resolveHypoRoot, expandHome } from './hypo-root.mjs';
+import { isValidProjectName } from './project-create.mjs';
+
+// ── arg parsing ──────────────────────────────────────────────────────────────
+
+export function parseArgs(argv) {
+  const args = {
+    hypoDir: null,
+    minGroup: 2,
+    json: false,
+    checkSessionClose: false,
+    applySessionClose: false,
+    markSessionClosed: false,
+    logOnly: false,
+    sessionId: null,
+    payload: null,
+    force: false,
+    transcriptPath: null,
+    project: null,
+  };
+  for (const arg of argv.slice(2)) {
+    if (arg.startsWith('--hypo-dir=')) args.hypoDir = expandHome(arg.slice(11));
+    else if (arg.startsWith('--min-group=')) args.minGroup = parseInt(arg.slice(12), 10) || 2;
+    else if (arg === '--check-session-close') args.checkSessionClose = true;
+    else if (arg === '--apply-session-close') args.applySessionClose = true;
+    else if (arg === '--mark-session-closed') args.markSessionClosed = true;
+    else if (arg === '--log-only') args.logOnly = true;
+    else if (arg.startsWith('--session-id=')) args.sessionId = arg.slice(13);
+    else if (arg.startsWith('--payload=')) args.payload = arg.slice(10);
+    else if (arg.startsWith('--transcript-path=')) args.transcriptPath = expandHome(arg.slice(18));
+    else if (arg.startsWith('--session-cwd=')) args.sessionCwd = expandHome(arg.slice(14));
+    else if (arg.startsWith('--project=')) args.project = arg.slice(10);
+    else if (arg === '--force') args.force = true;
+    else if (arg === '--json') args.json = true;
+  }
+  if (!args.hypoDir) args.hypoDir = resolveHypoRoot();
+  // --project=<slug> override (check/mark only). Validate the SYNTAX here so a
+  // traversal/charset attack (`--project=../x`) is rejected before any path is
+  // built from it — sessionCloseFileStatus(projectOverride) joins it directly.
+  // isValidProjectName is the SHARED validator (project-create.mjs), so the
+  // override accepts exactly the namespace createProject can scaffold. Existence
+  // (a real projects/<slug>/ directory) is checked in the run functions, where
+  // hypoDir is resolved and only the check/mark paths consume --project.
+  if (args.project != null && !isValidProjectName(args.project)) {
+    const msg = `--project "${args.project}" is not a valid project name (need a single segment with ≥1 alnum, charset A-Za-z0-9._-, not "."/"..")`;
+    console.log(args.json ? JSON.stringify({ ok: false, error: msg }, null, 2) : `✗ ${msg}`);
+    process.exit(1);
+  }
+  return args;
+}