heyspex 0.1.0 → 0.2.1

package/scripts/install-claude-code-hooks.mjs

@@ -0,0 +1,272 @@
+#!/usr/bin/env node
+// Install Claude Code lifecycle hooks that emit agent status to the console
+// (HS-TASK-P89W). Merges entries into `.claude/settings.json` without
+// clobbering existing hooks. Idempotent, and self-heals command-string drift.
+//
+// Usage:
+//   node scripts/install-claude-code-hooks.mjs           # install/repair
+//   node scripts/install-claude-code-hooks.mjs --check   # exit 1 on drift
+//   node scripts/install-claude-code-hooks.mjs --uninstall
+//
+// What it writes:
+//   - PreToolUse  → emit-claim-status.mjs --event=PreToolUse
+//   - Stop        → emit-claim-status.mjs --event=Stop
+//   - PostToolUse → emit-claim-status.mjs --event=PostToolUse
+//   - SessionEnd  → session-end.mjs            (release claim on clean exit)
+//   - PreToolUse + PostToolUse → log-session-activity.mjs   (agent.tool_called
+//     session log — HS-6QEW; reads hook_event_name from the stdin payload)
+//
+// Each hook command is identified by its script MARKER. On reinstall, any entry
+// matching the marker but whose command string diverges from the canonical
+// form is replaced — guards against the regression where the path got
+// rewritten to a CWD-relative form (see [[hook-paths]]).
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const SETTINGS_PATH = path.join(REPO_ROOT, '.claude', 'settings.json');
+const HOOK_TIMEOUT_SECONDS = 5;
+
+const CLAIM_STATUS_MARKER = 'scripts/claude-hooks/emit-claim-status.mjs';
+const SESSION_END_MARKER = 'scripts/claude-hooks/session-end.mjs';
+const SESSION_ACTIVITY_MARKER = 'scripts/claude-hooks/log-session-activity.mjs';
+
+// Anchor every script path via $CLAUDE_PROJECT_DIR so hooks resolve regardless
+// of the agent's cwd (it often drifts into spex-console/ during a session).
+// See [[HS-LES-hook-paths]] and the prior NIHZ regression.
+//
+// Hooks are not invoked directly — every one routes through the `_run.mjs`
+// shim, which is where the HeySpex master on/off switch lives (`hs mode off`
+// makes every hook exit 0 without the settings file changing). See
+// scripts/claude-hooks/_run.mjs and docs/claude-code-setup.md.
+const SHIM = 'scripts/claude-hooks/_run.mjs';
+// Self-locating, env-independent, fail-open command (Copilot compatibility): scripts/lib/customer-kit.mjs buildBootstrap().
+import { PLATFORM_RUNNER_PREFIX } from './lib/customer-kit.mjs';
+
+/** Canonical command string for a hook: `node "$CLAUDE_PROJECT_DIR/_run.mjs" <name> [args]`. */
+function shimCommand(scriptMarker, args = '') {
+  const name = scriptMarker.replace('scripts/claude-hooks/', '').replace(/\.mjs$/, '');
+  return `${PLATFORM_RUNNER_PREFIX} ${name}${args}`;
+}
+
+/**
+ * Markers that identify one of our entries inside an event's groups. The shim
+ * form is first (what we self-heal toward); the pre-shim direct form is kept so
+ * a checkout installed before the shim landed gets REPAIRED in place rather
+ * than growing a duplicate entry alongside the old one.
+ */
+function markersFor(scriptMarker, args = '') {
+  const name = scriptMarker.replace('scripts/claude-hooks/', '').replace(/\.mjs$/, '');
+  return [`${SHIM}" ${name}${args}`, `${scriptMarker}"${args}`];
+}
+
+// One descriptor per (event, script). `markers` identify our entry within an
+// event's groups; `command` is the canonical string we self-heal toward.
+const HOOKS = [
+  {
+    event: 'PreToolUse',
+    markers: markersFor(CLAIM_STATUS_MARKER, ' --event=PreToolUse'),
+    withMatcher: true,
+    command: shimCommand(CLAIM_STATUS_MARKER, ' --event=PreToolUse'),
+  },
+  {
+    event: 'Stop',
+    markers: markersFor(CLAIM_STATUS_MARKER, ' --event=Stop'),
+    withMatcher: false,
+    command: shimCommand(CLAIM_STATUS_MARKER, ' --event=Stop'),
+  },
+  {
+    event: 'PostToolUse',
+    markers: markersFor(CLAIM_STATUS_MARKER, ' --event=PostToolUse'),
+    withMatcher: true,
+    command: shimCommand(CLAIM_STATUS_MARKER, ' --event=PostToolUse'),
+  },
+  {
+    event: 'SessionEnd',
+    markers: markersFor(SESSION_END_MARKER),
+    withMatcher: false,
+    command: shimCommand(SESSION_END_MARKER),
+  },
+  {
+    event: 'PreToolUse',
+    markers: markersFor(SESSION_ACTIVITY_MARKER),
+    withMatcher: true,
+    command: shimCommand(SESSION_ACTIVITY_MARKER),
+  },
+  {
+    event: 'PostToolUse',
+    markers: markersFor(SESSION_ACTIVITY_MARKER),
+    withMatcher: true,
+    command: shimCommand(SESSION_ACTIVITY_MARKER),
+  },
+];
+
+const ALL_MARKERS = [...new Set(HOOKS.flatMap((h) => h.markers))];
+
+function readSettings() {
+  try {
+    const raw = fs.readFileSync(SETTINGS_PATH, 'utf8').trim();
+    if (!raw) return {};
+    return JSON.parse(raw);
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return {};
+    throw err;
+  }
+}
+
+function writeSettings(settings) {
+  fs.mkdirSync(path.dirname(SETTINGS_PATH), { recursive: true });
+  fs.writeFileSync(SETTINGS_PATH, `${JSON.stringify(settings, null, 2)}\n`, 'utf8');
+}
+
+function hookMatchesMarker(h, markers) {
+  if (!h || h.type !== 'command' || typeof h.command !== 'string') return false;
+  return [].concat(markers).some((m) => h.command.includes(m));
+}
+
+function isOurHook(h) {
+  return hookMatchesMarker(h, ALL_MARKERS);
+}
+
+function stripOurHooks(groups) {
+  if (!Array.isArray(groups)) return [];
+  return groups
+    .map((group) => {
+      if (!group || !Array.isArray(group.hooks)) return group;
+      const hooks = group.hooks.filter((h) => !isOurHook(h));
+      return { ...group, hooks };
+    })
+    .filter((group) => Array.isArray(group?.hooks) && group.hooks.length > 0);
+}
+
+// Returns 'added' (no entry existed), 'repaired' (entry existed with wrong
+// command string and was rewritten), or 'noop' (entry already canonical).
+function ensureHook(settings, { event, markers, command, withMatcher }) {
+  settings.hooks ??= {};
+  settings.hooks[event] ??= [];
+  const groups = settings.hooks[event];
+
+  let foundOurs = false;
+  let repaired = false;
+  for (const group of groups) {
+    if (!group || !Array.isArray(group.hooks)) continue;
+    for (const h of group.hooks) {
+      if (!hookMatchesMarker(h, markers)) continue;
+      foundOurs = true;
+      if (h.command !== command) {
+        h.command = command;
+        repaired = true;
+      }
+      if (h.timeout !== HOOK_TIMEOUT_SECONDS) {
+        h.timeout = HOOK_TIMEOUT_SECONDS;
+        repaired = true;
+      }
+    }
+  }
+  if (foundOurs) return repaired ? 'repaired' : 'noop';
+
+  const newGroup = {
+    ...(withMatcher ? { matcher: '.*' } : {}),
+    hooks: [{ type: 'command', command, timeout: HOOK_TIMEOUT_SECONDS }],
+  };
+  groups.push(newGroup);
+  return 'added';
+}
+
+function uninstall() {
+  const settings = readSettings();
+  if (!settings.hooks) {
+    console.log('install-claude-code-hooks: nothing to uninstall (no hooks block).');
+    return;
+  }
+  let removed = 0;
+  const events = [...new Set(HOOKS.map((h) => h.event))];
+  for (const name of events) {
+    const before = settings.hooks[name];
+    if (!Array.isArray(before)) continue;
+    const after = stripOurHooks(before);
+    const droppedHookCount =
+      before.reduce((n, g) => n + (Array.isArray(g?.hooks) ? g.hooks.length : 0), 0) -
+      after.reduce((n, g) => n + (Array.isArray(g?.hooks) ? g.hooks.length : 0), 0);
+    removed += droppedHookCount;
+    if (after.length === 0) {
+      delete settings.hooks[name];
+    } else {
+      settings.hooks[name] = after;
+    }
+  }
+  if (Object.keys(settings.hooks).length === 0) {
+    delete settings.hooks;
+  }
+  writeSettings(settings);
+  console.log(`install-claude-code-hooks: uninstalled ${removed} hook entr${removed === 1 ? 'y' : 'ies'}.`);
+}
+
+function install() {
+  const settings = readSettings();
+  const added = [];
+  const repaired = [];
+  for (const descriptor of HOOKS) {
+    const outcome = ensureHook(settings, descriptor);
+    if (outcome === 'added') added.push(descriptor.event);
+    else if (outcome === 'repaired') repaired.push(descriptor.event);
+  }
+  if (added.length === 0 && repaired.length === 0) {
+    console.log('install-claude-code-hooks: already installed (no changes).');
+    return;
+  }
+  writeSettings(settings);
+  const parts = [];
+  if (added.length > 0) parts.push(`installed ${added.join(', ')}`);
+  if (repaired.length > 0) parts.push(`repaired ${repaired.join(', ')}`);
+  console.log(`install-claude-code-hooks: ${parts.join('; ')} → ${path.relative(REPO_ROOT, SETTINGS_PATH)}`);
+  console.log('  Wrappers: scripts/claude-hooks/emit-claim-status.mjs, scripts/claude-hooks/session-end.mjs');
+  console.log('  Console URL: .heyspex/console-url (auto-written by `npm run dev`) → HEYSPEX_CONSOLE_URL env var → http://localhost:3000');
+}
+
+// Read-only audit: walks installed hooks and prints any drift without
+// writing. Exit code 1 if anything is missing or has a non-canonical
+// command string; 0 if everything is healthy. Intended for CI / preflight.
+function check() {
+  const settings = readSettings();
+  const issues = [];
+  const groupsFor = (event) =>
+    Array.isArray(settings?.hooks?.[event]) ? settings.hooks[event] : [];
+  for (const { event, markers, command } of HOOKS) {
+    const groups = groupsFor(event);
+    const ours = groups
+      .flatMap((g) => (Array.isArray(g?.hooks) ? g.hooks : []))
+      .filter((h) => hookMatchesMarker(h, markers));
+    if (ours.length === 0) {
+      issues.push(`${event}: missing hook for ${markers[0]}`);
+      continue;
+    }
+    for (const h of ours) {
+      if (h.command !== command) {
+        issues.push(`${event}: command drift — expected \`${command}\`, found \`${h.command}\``);
+      }
+      if (h.timeout !== HOOK_TIMEOUT_SECONDS) {
+        issues.push(`${event}: timeout drift — expected ${HOOK_TIMEOUT_SECONDS}, found ${h.timeout}`);
+      }
+    }
+  }
+  if (issues.length === 0) {
+    console.log('install-claude-code-hooks --check: OK');
+    process.exit(0);
+  }
+  console.error('install-claude-code-hooks --check: drift detected');
+  for (const issue of issues) console.error(`  - ${issue}`);
+  console.error('  Run `node scripts/install-claude-code-hooks.mjs` to repair.');
+  process.exit(1);
+}
+
+const mode = process.argv.includes('--uninstall')
+  ? 'uninstall'
+  : process.argv.includes('--check')
+    ? 'check'
+    : 'install';
+if (mode === 'uninstall') uninstall();
+else if (mode === 'check') check();
+else install();