heyspex 0.1.0 → 0.2.1

package/scripts/claude-hooks/terminal-close-shared.mjs

@@ -0,0 +1,426 @@
+#!/usr/bin/env node
+// Shared auto-close terminal helpers — ship detection, pending arm, process kill,
+// debug trace. Used by close-terminal-on-ship.mjs (hooks) and terminal-close-watcher.mjs.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+import { getActiveConfig } from '../../vendor/heyspex-mcp/vault-resolve.mjs';
+
+export const STATUS_REVIEW_RE = /^\s*status:\s*in_review\s*$/m;
+export const STATUS_CLOSED_RE = /^\s*status:\s*closed\s*$/m;
+export const RECORD_WIP_TOOL_RE = /heyspex_record_wip/i;
+export const REVIEW_DOC_RE = /[\\/]specs[\\/]reviews[\\/]HS-REV-/i;
+
+const EDIT_TOOL_NAMES = new Set([
+  'Edit',
+  'Write',
+  'MultiEdit',
+  'StrReplace',
+  'search_replace',
+  'apply_patch',
+  'WriteFile',
+  'Replace',
+]);
+
+export function repoRoot() {
+  const fromEnv = process.env.CLAUDE_PROJECT_DIR?.trim();
+  if (fromEnv) return fromEnv.replace(/[\\/]+$/, '');
+  return path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+}
+
+const DEBUG_LOG_NAME = 'terminal-close-debug.jsonl';
+/** Opt-in only — default off so hooks never grow a multi-MB trace during normal agent work. */
+const DEBUG_LOG_MAX_BYTES = 256 * 1024;
+
+export function terminalCloseDebugEnabled() {
+  return process.env.HEYSPEX_TERMINAL_CLOSE_DEBUG === '1';
+}
+
+function trimDebugLogIfOversized(logPath) {
+  try {
+    const stat = fs.statSync(logPath);
+    if (stat.size <= DEBUG_LOG_MAX_BYTES) return;
+    const raw = fs.readFileSync(logPath, 'utf8');
+    const lines = raw.split('\n').filter(Boolean);
+    const keep = lines.slice(-200);
+    fs.writeFileSync(logPath, keep.join('\n') + (keep.length ? '\n' : ''));
+  } catch {
+    // absent or unreadable — append below will create it
+  }
+}
+
+export function debugLog(event, detail = {}) {
+  if (!terminalCloseDebugEnabled()) return;
+  try {
+    const logPath = path.join(repoRoot(), '.heyspex', DEBUG_LOG_NAME);
+    trimDebugLogIfOversized(logPath);
+    const line =
+      JSON.stringify({
+        at: new Date().toISOString(),
+        event,
+        pid: process.pid,
+        ppid: process.ppid,
+        ...detail,
+      }) + '\n';
+    fs.appendFileSync(logPath, line);
+  } catch {
+    // never block
+  }
+}
+
+export function resolveCloseTerminalOnTaskCompleteFromSettings() {
+  if (process.env.HEYSPEX_AUTO_CLOSE_TERMINAL === '0') return false;
+  try {
+    const raw = fs.readFileSync(path.join(repoRoot(), 'spex-console', 'settings.json'), 'utf8');
+    const parsed = JSON.parse(raw);
+    const launch = parsed?.launchModels;
+    if (typeof launch?.closeTerminalOnTaskComplete === 'boolean') {
+      return launch.closeTerminalOnTaskComplete;
+    }
+    if (typeof launch?.closeTerminalOnTaskCreation === 'boolean') {
+      return launch.closeTerminalOnTaskCreation;
+    }
+    return true;
+  } catch {
+    return true;
+  }
+}
+
+const PENDING_CLOSE_FILE = '.pending-terminal-close';
+
+export function pendingTerminalClosePath() {
+  return path.join(repoRoot(), '.heyspex', PENDING_CLOSE_FILE);
+}
+
+export function readPendingTerminalClose() {
+  try {
+    return JSON.parse(fs.readFileSync(pendingTerminalClosePath(), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+export function armPendingTerminalClose(sessionId, reason = 'ship') {
+  try {
+    fs.mkdirSync(path.join(repoRoot(), '.heyspex'), { recursive: true });
+    const body = {
+      armedAt: new Date().toISOString(),
+      sessionId: typeof sessionId === 'string' ? sessionId : null,
+      reason,
+    };
+    fs.writeFileSync(pendingTerminalClosePath(), JSON.stringify(body));
+    debugLog('armed', body);
+  } catch {
+    // never block the hook
+  }
+}
+
+export function clearPendingTerminalClose() {
+  try {
+    fs.unlinkSync(pendingTerminalClosePath());
+  } catch {
+    // absent is fine
+  }
+}
+
+export function isPendingTerminalCloseArmed() {
+  return readPendingTerminalClose() !== null;
+}
+
+/**
+ * Bases that can contain spec files. Since the repo split (2026-08-31) the
+ * vault lives outside the code repo, so spec edits arrive as paths under the
+ * registry-resolved vault root, not under CLAUDE_PROJECT_DIR — test both.
+ */
+export function specBaseRoots() {
+  const roots = [repoRoot()];
+  try {
+    const resolved = getActiveConfig();
+    if (resolved?.repoRootAbs && !roots.includes(resolved.repoRootAbs)) {
+      roots.push(resolved.repoRootAbs);
+    }
+  } catch {
+    // registry unreadable — the code-repo base still applies
+  }
+  return roots;
+}
+
+export function isUnderSpecsTaskOrEpic(filePath) {
+  if (typeof filePath !== 'string' || filePath.length === 0) return false;
+  const abs = path.resolve(filePath);
+  for (const root of specBaseRoots()) {
+    for (const sub of ['specs/tasks', 'specs/epics']) {
+      const base = path.join(root, sub);
+      const rel = path.relative(base, abs);
+      if (rel && !rel.startsWith('..') && !path.isAbsolute(rel)) return true;
+    }
+  }
+  return false;
+}
+
+export function isReviewDocPath(filePath) {
+  if (typeof filePath !== 'string' || filePath.length === 0) return false;
+  return REVIEW_DOC_RE.test(path.resolve(filePath));
+}
+
+function textFlipToShipped(prev, next) {
+  const wasShipped = STATUS_REVIEW_RE.test(prev) || STATUS_CLOSED_RE.test(prev);
+  const nowShipped = STATUS_REVIEW_RE.test(next) || STATUS_CLOSED_RE.test(next);
+  return nowShipped && !wasShipped;
+}
+
+export function detectShipFromEditLike(toolName, toolInput) {
+  if (!toolInput || typeof toolInput !== 'object') return false;
+  if (!isUnderSpecsTaskOrEpic(toolInput.file_path)) return false;
+
+  if (toolName === 'Edit' || toolName === 'StrReplace' || toolName === 'search_replace') {
+    const next = typeof toolInput.new_string === 'string' ? toolInput.new_string : '';
+    const prev = typeof toolInput.old_string === 'string' ? toolInput.old_string : '';
+    return textFlipToShipped(prev, next);
+  }
+
+  if (toolName === 'MultiEdit') {
+    const edits = Array.isArray(toolInput.edits) ? toolInput.edits : [];
+    return edits.some((edit) => {
+      const next = typeof edit?.new_string === 'string' ? edit.new_string : '';
+      const prev = typeof edit?.old_string === 'string' ? edit.old_string : '';
+      return textFlipToShipped(prev, next);
+    });
+  }
+
+  if (toolName === 'Write' || toolName === 'WriteFile') {
+    const content = typeof toolInput.content === 'string' ? toolInput.content : '';
+    return STATUS_REVIEW_RE.test(content) || STATUS_CLOSED_RE.test(content);
+  }
+
+  return false;
+}
+
+export function detectShipFromAfterFileEdit(payload) {
+  const filePath = payload?.file_path;
+  if (!isUnderSpecsTaskOrEpic(filePath)) return false;
+  const edits = Array.isArray(payload?.edits) ? payload.edits : [];
+  return edits.some((edit) => {
+    const next = typeof edit?.new_string === 'string' ? edit.new_string : '';
+    const prev = typeof edit?.old_string === 'string' ? edit.old_string : '';
+    return textFlipToShipped(prev, next);
+  });
+}
+
+export function normalizeHookEvent(payload) {
+  const raw = payload?.hook_event_name;
+  if (typeof raw === 'string' && raw.trim()) {
+    const key = raw.trim();
+    if (key === 'postToolUse' || key === 'PostToolUse') return 'postToolUse';
+    if (key === 'sessionEnd' || key === 'SessionEnd') return 'sessionEnd';
+    if (key === 'afterFileEdit') return 'afterFileEdit';
+    if (key === 'afterMCPExecution') return 'afterMCPExecution';
+    if (key === 'stop' || key === 'Stop') return 'stop';
+    return key;
+  }
+  if (Array.isArray(payload?.edits) && payload?.file_path) return 'afterFileEdit';
+  if (typeof payload?.tool_name === 'string') return 'postToolUse';
+  return null;
+}
+
+export function toolCallFailed(payload) {
+  const response = payload?.tool_response;
+  if (response && typeof response === 'object' && response.is_error === true) return true;
+  if (payload?.failure_type) return true;
+  const output = payload?.tool_output;
+  if (typeof output === 'string') {
+    try {
+      const parsed = JSON.parse(output);
+      if (parsed?.isError === true || parsed?.error) return true;
+    } catch {
+      // not json
+    }
+  }
+  return false;
+}
+
+export function isShipEvent(payload) {
+  const event = normalizeHookEvent(payload);
+  if (!event) return false;
+  if (toolCallFailed(payload)) return false;
+
+  if (event === 'afterFileEdit') {
+    return detectShipFromAfterFileEdit(payload);
+  }
+
+  if (event === 'postToolUse') {
+    const toolName = payload?.tool_name;
+    if (typeof toolName === 'string' && EDIT_TOOL_NAMES.has(toolName)) {
+      return detectShipFromEditLike(toolName, payload?.tool_input ?? {});
+    }
+  }
+
+  return false;
+}
+
+export function isRecordWipSuccess(payload) {
+  const event = normalizeHookEvent(payload);
+  if (event !== 'postToolUse' && event !== 'afterMCPExecution') return false;
+  if (toolCallFailed(payload)) return false;
+
+  const toolName = typeof payload?.tool_name === 'string' ? payload.tool_name : '';
+  if (!RECORD_WIP_TOOL_RE.test(toolName)) return false;
+  return true;
+}
+
+export function isReviewDocWriteSuccess(payload) {
+  const event = normalizeHookEvent(payload);
+  if (event !== 'postToolUse' && event !== 'afterFileEdit') return false;
+  if (toolCallFailed(payload)) return false;
+
+  if (event === 'afterFileEdit') {
+    return isReviewDocPath(payload?.file_path);
+  }
+
+  const toolName = payload?.tool_name;
+  if (toolName !== 'Write' && toolName !== 'WriteFile' && toolName !== 'Edit') return false;
+  return isReviewDocPath(payload?.tool_input?.file_path);
+}
+
+export function isSessionEndEvent(payload) {
+  return normalizeHookEvent(payload) === 'sessionEnd';
+}
+
+export function wipStateUpdatedAfter(armedAtIso) {
+  if (!armedAtIso) return false;
+  const armedMs = Date.parse(armedAtIso);
+  if (!Number.isFinite(armedMs)) return false;
+  // Since the repo split the ledger heyspex_record_wip writes lives in the VAULT.
+  // Watching only repoRoot() here meant a recorded WIP never satisfied the arm, so
+  // the ship-close never fired. Check every base that can hold a ledger.
+  for (const root of specBaseRoots()) {
+    try {
+      const raw = fs.readFileSync(path.join(root, '.heyspex', 'wip-state.json'), 'utf8');
+      const data = JSON.parse(raw);
+      if (!data || typeof data !== 'object') continue;
+      for (const entry of Object.values(data)) {
+        const updatedAt = entry?.updatedAt;
+        if (typeof updatedAt === 'string' && Date.parse(updatedAt) > armedMs) return true;
+      }
+    } catch {
+      // missing or unreadable at this root — try the next one
+    }
+  }
+  return false;
+}
+
+export function shouldCloseNow() {
+  const pending = readPendingTerminalClose();
+  if (!pending?.armedAt) return false;
+  return wipStateUpdatedAfter(pending.armedAt);
+}
+
+export function scheduleAgentHostExit(startPid = process.ppid) {
+  if (!Number.isFinite(startPid) || startPid <= 0) {
+    debugLog('kill_skipped', { reason: 'invalid_start_pid', startPid });
+    return;
+  }
+
+  debugLog('kill_scheduled', { startPid });
+
+  if (process.platform === 'win32') {
+    const ps = [
+      '-NoProfile',
+      '-WindowStyle',
+      'Hidden',
+      '-Command',
+      `
+$ErrorActionPreference = 'SilentlyContinue'
+$current = ${startPid}
+for ($i = 0; $i -lt 40; $i++) {
+  $p = Get-CimInstance Win32_Process -Filter "ProcessId=$current"
+  if (-not $p) { break }
+  $name = [string]$p.Name
+  $cmd = [string]$p.CommandLine
+  if ($name -ieq 'claude.exe') { Stop-Process -Id $current -Force; exit 0 }
+  if ($cmd -match 'cursor-agent|@anthropic-ai/claude-code|\\\\cursor-agent\\\\') { Stop-Process -Id $current -Force; exit 0 }
+  $parent = [int]$p.ParentProcessId
+  if ($parent -le 0 -or $parent -eq $current) { break }
+  $current = $parent
+}
+Stop-Process -Id ${startPid} -Force -ErrorAction SilentlyContinue
+`.trim(),
+    ];
+    try {
+      const child = spawn('powershell.exe', ps, {
+        detached: true,
+        stdio: 'ignore',
+        windowsHide: true,
+      });
+      child.unref();
+    } catch (err) {
+      debugLog('kill_failed', { message: err instanceof Error ? err.message : String(err) });
+    }
+    return;
+  }
+
+  const sh = `pid=${startPid}; for i in $(seq 1 30); do
+  line=$(ps -p "$pid" -o comm= 2>/dev/null) || break
+  case "$line" in *claude*|*Claude*) kill -TERM "$pid" 2>/dev/null; exit 0 ;; esac
+  cmd=$(ps -p "$pid" -o args= 2>/dev/null || true)
+  case "$cmd" in *cursor-agent*) kill -TERM "$pid" 2>/dev/null; exit 0 ;; esac
+  ppid=$(ps -p "$pid" -o ppid= 2>/dev/null | tr -d ' ')
+  [ -z "$ppid" ] || [ "$ppid" = "0" ] || [ "$ppid" = "$pid" ] && break
+  pid=$ppid
+done
+kill -TERM ${startPid} 2>/dev/null || true`;
+  try {
+    const child = spawn('sh', ['-c', sh], { detached: true, stdio: 'ignore' });
+    child.unref();
+  } catch (err) {
+    debugLog('kill_failed', { message: err instanceof Error ? err.message : String(err) });
+  }
+}
+
+export function tryCloseIfReady(reason) {
+  if (!resolveCloseTerminalOnTaskCompleteFromSettings()) {
+    debugLog('close_skipped', { reason: 'setting_disabled', trigger: reason });
+    return false;
+  }
+  if (!isPendingTerminalCloseArmed()) {
+    debugLog('close_skipped', { reason: 'not_armed', trigger: reason });
+    return false;
+  }
+  if (!shouldCloseNow() && reason !== 'session_end' && reason !== 'record_wip') {
+    debugLog('close_skipped', { reason: 'wip_not_updated', trigger: reason });
+    return false;
+  }
+  clearPendingTerminalClose();
+  debugLog('closing', { trigger: reason });
+  scheduleAgentHostExit();
+  return true;
+}
+
+export async function readStdin() {
+  if (process.stdin.isTTY) return null;
+  return new Promise((resolve) => {
+    let buf = '';
+    let resolved = false;
+    const finish = (value) => {
+      if (resolved) return;
+      resolved = true;
+      resolve(value);
+    };
+    const timer = setTimeout(() => finish(buf || null), 500);
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => {
+      buf += chunk;
+    });
+    process.stdin.on('end', () => {
+      clearTimeout(timer);
+      finish(buf || null);
+    });
+    process.stdin.on('error', () => {
+      clearTimeout(timer);
+      finish(buf || null);
+    });
+  });
+}

package/scripts/claude-hooks/terminal-close-watcher.mjs

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+// Spawn-side fallback when hooks miss ship/close events (external cursor-agent terminal).
+// Polls claimed spec status + wip-state.json; kills the agent host when close-out lands.
+//
+// Started detached from spawnNewAgent when auto-close is enabled.
+// Mute: HEYSPEX_AUTO_CLOSE_TERMINAL=0 or HEYSPEX_CLOSE_TERMINAL_ON_SHIP_OFF=1
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import {
+  armPendingTerminalClose,
+  debugLog,
+  clearPendingTerminalClose,
+  isPendingTerminalCloseArmed,
+  readPendingTerminalClose,
+  repoRoot,
+  resolveCloseTerminalOnTaskCompleteFromSettings,
+  specBaseRoots,
+  scheduleAgentHostExit,
+  shouldCloseNow,
+  STATUS_CLOSED_RE,
+  STATUS_REVIEW_RE,
+} from './terminal-close-shared.mjs';
+
+const POLL_MS = 3000;
+const MAX_MS = 8 * 60 * 60 * 1000;
+
+function readActiveClaimSpecId() {
+  try {
+    const raw = fs.readFileSync(path.join(repoRoot(), '.heyspex', 'active-claims.json'), 'utf8');
+    const claims = JSON.parse(raw);
+    const session =
+      process.env.CURSOR_TRACE_ID ??
+      process.env.CLAUDE_CODE_SESSION_ID ??
+      process.env.HEYSPEX_SESSION_ID ??
+      '';
+    if (!Array.isArray(claims)) return null;
+    const mine = claims.find(
+      (c) =>
+        c &&
+        (session
+          ? c.sessionId === session || c.session_id === session
+          : c.agent === process.env.HEYSPEX_AGENT),
+    );
+    return mine?.specId ?? mine?.spec_id ?? null;
+  } catch {
+    return null;
+  }
+}
+
+function findSpecFile(specId) {
+  for (const root of specBaseRoots()) {
+    for (const dir of ['specs/tasks', 'specs/epics']) {
+      const folder = path.join(root, dir);
+      let names;
+      try {
+        names = fs.readdirSync(folder);
+      } catch {
+        continue;
+      }
+      const hit = names.find((n) => n.startsWith(`${specId}-`) || n.startsWith(specId));
+      if (hit) return path.join(folder, hit);
+    }
+  }
+  return null;
+}
+
+function readSpecStatus(specPath) {
+  try {
+    const raw = fs.readFileSync(specPath, 'utf8');
+    const m = raw.match(/^\s*status:\s*(\S+)\s*$/m);
+    return m?.[1] ?? null;
+  } catch {
+    return null;
+  }
+}
+
+function isShippedStatus(status) {
+  return status === 'in_review' || status === 'closed' || status === 'review_pending';
+}
+
+function pollOnce() {
+  if (!resolveCloseTerminalOnTaskCompleteFromSettings()) return false;
+
+  const specId = readActiveClaimSpecId();
+  if (!specId) return false;
+
+  const specPath = findSpecFile(specId);
+  if (!specPath) return false;
+
+  const status = readSpecStatus(specPath);
+  if (!isShippedStatus(status)) return false;
+
+  if (!isPendingTerminalCloseArmed()) {
+    armPendingTerminalClose(null, `watcher:${status}`);
+  }
+
+  if (shouldCloseNow()) {
+    debugLog('watcher_close', { specId, status });
+    clearPendingTerminalClose();
+    scheduleAgentHostExit();
+    return true;
+  }
+
+  const pending = readPendingTerminalClose();
+  if (pending?.armedAt) {
+    debugLog('watcher_waiting_wip', { specId, status, armedAt: pending.armedAt });
+  }
+  return false;
+}
+
+const started = Date.now();
+debugLog('watcher_start', { pid: process.pid });
+
+while (Date.now() - started < MAX_MS) {
+  if (pollOnce()) break;
+  await new Promise((r) => setTimeout(r, POLL_MS));
+}
+
+debugLog('watcher_exit', {});

package/scripts/claude-hooks/vault-mirror-catchup.mjs

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+// GENERATED by scripts/generate-hook-shells.mjs (HS-IQBF) — do not hand-edit.
+// This file only wires Claude Code's hook stdin/stdout contract to the
+// spexharness engine port of this gate. To change what this gate DECIDES,
+// edit spexharness/src/gates/vault-mirror-catchup.mjs. To change the SHAPE of this shell,
+// edit the generator, then rerun: node scripts/generate-hook-shells.mjs
+
+import { runGateAsHook } from '../../spexharness/src/adapters/claude-code.mjs';
+import gate from '../../spexharness/src/gates/vault-mirror-catchup.mjs';
+
+await runGateAsHook(gate);

package/scripts/claude-hooks/vault-write-tier-guard.mjs

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+// GENERATED by scripts/generate-hook-shells.mjs (HS-IQBF) — do not hand-edit.
+// This file only wires Claude Code's hook stdin/stdout contract to the
+// spexharness engine port of this gate. To change what this gate DECIDES,
+// edit spexharness/src/gates/vault-write-tier-guard.mjs. To change the SHAPE of this shell,
+// edit the generator, then rerun: node scripts/generate-hook-shells.mjs
+
+import { runGateAsHook } from '../../spexharness/src/adapters/claude-code.mjs';
+import gate from '../../spexharness/src/gates/vault-write-tier-guard.mjs';
+
+await runGateAsHook(gate);