heyspex 0.1.0 → 0.2.0

package/scripts/hs-worktree.mjs

@@ -0,0 +1,201 @@
+#!/usr/bin/env node
+// scripts/hs-worktree.mjs — `hs worktree list|alloc|release|reap|rebind`.
+// Task: HS-V9XH (epic HS-03DO "Claim-bound worktree isolation for parallel agent
+// sessions"). Thin shell: parse argv (scripts/lib/hs-worktree-args.mjs), then call
+// dev-factory/lib/worktree-allocator.mjs's exported functions IN-PROCESS — never
+// shells out to the allocator's own CLI mode, so there is exactly one process per
+// invocation and JSON output never has to round-trip through a child's stdout.
+//
+// Exit codes:
+//   0  ok
+//   1  usage (unknown verb/flag — from the parser)
+//   2  check-failed — ONLY `reap --expect-removed` that removed nothing
+//   11 bad-arg (missing required flag / value-flag with no value — from the parser)
+//   13 write-failed (the allocator threw on a git/fs write — alloc or rebind)
+
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+
+import { parseWorktreeArgs } from "./lib/hs-worktree-args.mjs";
+import {
+  makeCtx,
+  DEFAULT_DEPS,
+  keyInfoFor,
+  worktreePathFor,
+  allocateForClaim,
+  markReleased,
+  rebind,
+  listWorktrees,
+  reapWorktrees,
+} from "../dev-factory/lib/worktree-allocator.mjs";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(__dirname, "..");
+
+const EXIT_OK = 0;
+const EXIT_CHECK_FAILED = 2;
+const EXIT_WRITE_FAILED = 13;
+
+// ── human-output formatting ─────────────────────────────────────────────────
+
+function formatAge(ms) {
+  if (ms == null || !Number.isFinite(ms) || ms < 0) return "-";
+  const s = Math.floor(ms / 1000);
+  if (s < 60) return `${s}s`;
+  const m = Math.floor(s / 60);
+  if (m < 60) return `${m}m`;
+  const h = Math.floor(m / 60);
+  if (h < 24) return `${h}h`;
+  const d = Math.floor(h / 24);
+  return `${d}d`;
+}
+
+function formatPid(pid, alive) {
+  if (pid == null) return "-";
+  return `${pid}(${alive ? "alive" : "dead"})`;
+}
+
+function renderTable(rows) {
+  const headers = ["PATH", "BRANCH", "KIND", "SPEC", "SESSION", "PID", "AGE", "DIRTY", "RELEASED"];
+  const data = rows.map((w) => [
+    w.path,
+    w.branch || "(detached)",
+    w.kind,
+    w.specId || "-",
+    w.sessionId || "-",
+    formatPid(w.pid, w.pidAlive),
+    formatAge(w.ageMs),
+    w.dirtyCount == null ? "?" : String(w.dirtyCount),
+    w.releasedAt ? "yes" : "-",
+  ]);
+  const widths = headers.map((h, i) => Math.max(h.length, ...data.map((r) => String(r[i]).length)));
+  const line = (cols) => cols.map((c, i) => String(c).padEnd(widths[i])).join("  ").trimEnd();
+  return [line(headers), ...data.map(line)];
+}
+
+// ── agent identity ──────────────────────────────────────────────────────────
+
+/**
+ * Session id default per task brief: env only, never the MCP's fuller
+ * detectAgentIdentity precedence (Cursor/CI vars, etc) — a --session flag
+ * always wins.
+ */
+function resolveSessionId(flags) {
+  return (
+    flags.session
+    || process.env.CLAUDE_CODE_SESSION_ID
+    || process.env.HEYSPEX_SESSION_ID
+    || "cli"
+  );
+}
+
+/**
+ * Agent default per task brief: the same detection the MCP uses
+ * (vendor/heyspex-mcp/mcp-config.mjs detectAgentIdentity) when it is
+ * trivially importable, else HEYSPEX_AGENT env or "cli". A --agent flag
+ * always wins over both.
+ */
+async function resolveAgent(flags, sessionId) {
+  if (flags.agent) return flags.agent;
+  try {
+    const mod = await import("../vendor/heyspex-mcp/mcp-config.mjs");
+    if (typeof mod.detectAgentIdentity === "function") {
+      const identity = mod.detectAgentIdentity(undefined, sessionId);
+      if (identity?.agent) return identity.agent;
+    }
+  } catch {
+    // Not importable in this install shape (e.g. a published package without
+    // vendor/heyspex-mcp) — fall back below.
+  }
+  return process.env.HEYSPEX_AGENT || "cli";
+}
+
+// ── main ─────────────────────────────────────────────────────────────────────
+
+async function main() {
+  const parsed = parseWorktreeArgs(process.argv.slice(2));
+  if (!parsed.ok) {
+    process.stderr.write(`hs worktree: ${parsed.message}\n`);
+    process.exitCode = parsed.code;
+    return;
+  }
+  const { verb, flags } = parsed;
+  const ctx = makeCtx({ repo: REPO_ROOT, worktreeRoot: flags.root || undefined });
+
+  const emit = (obj, lines) => {
+    if (flags.json) process.stdout.write(`${JSON.stringify(obj, null, 2)}\n`);
+    else for (const l of lines) process.stdout.write(`${l}\n`);
+  };
+
+  if (verb === "list") {
+    const worktrees = listWorktrees(ctx);
+    emit({ worktrees }, renderTable(worktrees));
+    process.exitCode = EXIT_OK;
+    return;
+  }
+
+  if (verb === "alloc") {
+    const info = keyInfoFor(flags.spec);
+    if (flags.dryRun) {
+      const wtPath = worktreePathFor(ctx, flags.spec);
+      const baseSha = (DEFAULT_DEPS.git(ctx, ctx.repo, "rev-parse", "HEAD").stdout || "").trim() || null;
+      emit(
+        { dryRun: true, path: wtPath, branch: info.branch, baseSha },
+        [`would allocate ${wtPath} on ${info.branch} from ${baseSha ?? "(unknown)"}`],
+      );
+      process.exitCode = EXIT_OK;
+      return;
+    }
+    const sessionId = resolveSessionId(flags);
+    const agent = await resolveAgent(flags, sessionId);
+    try {
+      const r = allocateForClaim(ctx, { specId: flags.spec, sessionId, agent, pid: process.pid });
+      emit(r, [`${r.created ? "allocated" : "re-attached"} ${r.path} on ${r.branch}`]);
+      process.exitCode = EXIT_OK;
+    } catch (e) {
+      process.stderr.write(`hs worktree alloc: ${e.message}\n`);
+      process.exitCode = EXIT_WRITE_FAILED;
+    }
+    return;
+  }
+
+  if (verb === "release") {
+    const r = markReleased(ctx, { specId: flags.spec });
+    emit(r, [
+      r.found
+        ? `${r.alreadyReleased ? "already released" : "released"} ${worktreePathFor(ctx, flags.spec)}`
+        : `no worktree for ${flags.spec}`,
+    ]);
+    process.exitCode = EXIT_OK;
+    return;
+  }
+
+  if (verb === "rebind") {
+    try {
+      const r = rebind(ctx, { fromSpecId: flags.spec, toSpecId: flags.to });
+      emit(r, [r.found ? `rebound ${flags.spec} -> ${flags.to} on ${r.branch}` : `no worktree for ${flags.spec}`]);
+      process.exitCode = EXIT_OK;
+    } catch (e) {
+      process.stderr.write(`hs worktree rebind: ${e.message}\n`);
+      process.exitCode = EXIT_WRITE_FAILED;
+    }
+    return;
+  }
+
+  // reap
+  const r = await reapWorktrees(ctx, {
+    dryRun: flags.dryRun,
+    includeForeign: flags.includeForeign,
+    yes: flags.yes,
+  });
+  emit(r, [
+    `${r.dryRun ? "would remove" : "removed"} ${r.removed.length}: ${r.removed.join(", ") || "(none)"}`,
+    ...r.skipped.map((s) => `  skipped ${s.path} - ${s.reason}`),
+  ]);
+  process.exitCode = flags.expectRemoved && r.removed.length === 0 ? EXIT_CHECK_FAILED : EXIT_OK;
+}
+
+main().catch((err) => {
+  process.stderr.write(`hs worktree: ${err?.stack ?? err}\n`);
+  process.exitCode = 1;
+});

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

@@ -0,0 +1,270 @@
+#!/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';
+
+/** 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 `node "$CLAUDE_PROJECT_DIR/${SHIM}" ${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();