heyspex 0.1.0 → 0.2.0

package/scripts/install-cursor-hooks.mjs

@@ -0,0 +1,471 @@
+// Install the HeySpex lifecycle hooks into Cursor (`.cursor/hooks.json`), at
+// parity with what `.claude/settings.json` registers for Claude Code.
+//
+// The registration itself lives in scripts/cursor-hooks/manifest.mjs (shared
+// with heyspex-doctor.mjs and the smoke test); this file only knows how to
+// merge it into Cursor's config file without disturbing anything it does not
+// own. Idempotent, and self-heals command-string / timeout drift.
+//
+// Usage:
+//   node scripts/install-cursor-hooks.mjs           # install / repair
+//   node scripts/install-cursor-hooks.mjs --check   # exit 1 on drift
+//   node scripts/install-cursor-hooks.mjs --uninstall
+//   node scripts/install-cursor-hooks.mjs --json    # machine-readable report
+//
+// OWNERSHIP. Every entry this script writes runs through the shim
+// (`scripts/cursor-hooks/_run.mjs`), which is also how it recognizes its own
+// work on a re-run. Foreign hooks in the same file are never touched.
+//
+// LEGACY MIGRATION. Earlier versions registered a handful of hooks by pointing
+// Cursor straight at `scripts/claude-hooks/<hook>.mjs`. Those entries are
+// REMOVED on install rather than left alone: the manifest now registers the
+// same hooks through the shim, and leaving both would fire each one twice and
+// bypass the off-switch for the direct copy.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import {
+  CUSTOMER_LAUNCHER,
+  HOOKS,
+  SHIM,
+  UNPORTABLE,
+  commandFor,
+  commandForCustomer,
+  commandForPlugin,
+  identityFor,
+  timeoutFor,
+} from './cursor-hooks/manifest.mjs';
+import {
+  CUSTOMER_LAUNCHERS,
+  hookScope,
+  invokedDirectly,
+  planCustomerLauncherWrite,
+  samePlatformPath,
+} from './lib/customer-kit.mjs';
+
+const PLATFORM_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const REPO_ROOT = process.env.HS_SETUP_TARGET?.trim()
+  ? path.resolve(process.env.HS_SETUP_TARGET.trim())
+  : PLATFORM_ROOT;
+const SETTINGS_PATH = path.join(REPO_ROOT, '.cursor', 'hooks.json');
+
+// CUSTOMER TARGET (`hs setup cursor` / `hs doctor --fix` with HS_SETUP_TARGET
+// pointing at a repo other than this checkout, or `hs install`): only the
+// customer-scoped hooks of scripts/lib/customer-kit.mjs ship, addressed
+// through a committed LAUNCHER (`.cursor/heyspex/run-hook.mjs`, written here
+// too) that finds the heyspex package from the repo -- never this checkout's
+// absolute path, which exists on no other machine
+// ([[HS-EN4F-F4V2-DIAG-a-repo-set-up-with-hs-install-gets-no]],
+// [[HS-0AF8-WW9R-TASK-portable-hook-and-command-paths-in]]).
+
+/**
+ * The hook set + command renderer for a target repo. For a customer target
+ * `launcher` names the committed launcher file (relative segments + text) the
+ * rendered commands point at; the platform checkout has none.
+ * @param {string} targetRoot
+ * @param {string} [platformRoot]
+ */
+export function cursorKitFor(targetRoot, platformRoot = PLATFORM_ROOT) {
+  const customer = !samePlatformPath(targetRoot, platformRoot);
+  return {
+    customer,
+    hooks: customer ? HOOKS.filter((h) => hookScope(h.hook) === 'customer') : HOOKS,
+    commandFor: customer ? commandForCustomer : commandFor,
+    launcher: customer ? { rel: CUSTOMER_LAUNCHERS.cursor.rel, plan: planCustomerLauncherWrite } : null,
+  };
+}
+
+const KIT = cursorKitFor(REPO_ROOT);
+const ACTIVE_HOOKS = KIT.hooks;
+const LAUNCHER_PATH = path.join(REPO_ROOT, ...CUSTOMER_LAUNCHERS.cursor.rel);
+
+const LEGACY_MARKER = 'scripts/claude-hooks/';
+
+function readSettings() {
+  try {
+    const raw = fs.readFileSync(SETTINGS_PATH, 'utf8').trim();
+    if (!raw) return { version: 1, hooks: {} };
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed === 'object') {
+      parsed.version ??= 1;
+      parsed.hooks ??= {};
+      return parsed;
+    }
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return { version: 1, hooks: {} };
+    throw err;
+  }
+  return { version: 1, hooks: {} };
+}
+
+function writeSettings(settings) {
+  fs.mkdirSync(path.dirname(SETTINGS_PATH), { recursive: true });
+  fs.writeFileSync(SETTINGS_PATH, `${JSON.stringify(settings, null, 2)}\n`, 'utf8');
+}
+
+const commandOf = (entry) => (entry && typeof entry.command === 'string' ? entry.command : '');
+
+/** Ours = routed through the shim (any path form) or the committed customer launcher. */
+const isOurRunner = (token) => token.includes(SHIM) || token.includes(CUSTOMER_LAUNCHER);
+const isShimEntry = (raw) => isOurRunner(commandOf(raw));
+
+/** A pre-shim registration that the manifest now supersedes. */
+const isLegacyEntry = (raw) => !isShimEntry(raw) && commandOf(raw).includes(LEGACY_MARKER);
+
+/**
+ * Which manifest entry a shim command corresponds to. Matching on the parsed
+ * command (hook name + tool filter + forwarded args) rather than on the whole
+ * string is what lets a timeout or flag-order change -- or the 2026-10-02
+ * absolute platform path -- be REPAIRED instead of duplicated.
+ */
+function identityOfCommand(command) {
+  const tokens = command.trim().split(/\s+/);
+  const shimAt = tokens.findIndex(isOurRunner);
+  if (shimAt === -1) return null;
+  const rest = tokens.slice(shimAt + 1);
+  const hook = rest[0] ?? '';
+  let tool = '';
+  const args = [];
+  for (const token of rest.slice(1)) {
+    // The tool filter is quoted on disk; identityFor() works with the raw
+    // regex, so the quotes come off before comparing.
+    if (token.startsWith('--hs-tool=')) {
+      tool = token.slice('--hs-tool='.length).replace(/^"([\s\S]*)"$/, '$1');
+    } else if (token.startsWith('--hs-claude-event=')) continue;
+    else args.push(token);
+  }
+  return `${hook}::${tool}::${args.join(' ')}`;
+}
+
+function desiredEntry(entry, render = KIT.commandFor) {
+  return {
+    command: render(entry),
+    timeout: timeoutFor(entry),
+    ...(entry.matcher ? { matcher: entry.matcher } : {}),
+  };
+}
+
+function sameEntry(raw, entry, render = KIT.commandFor) {
+  const want = desiredEntry(entry, render);
+  return (
+    commandOf(raw) === want.command &&
+    raw.timeout === want.timeout &&
+    (raw.matcher ?? undefined) === (want.matcher ?? undefined)
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Plugin mirror
+// ---------------------------------------------------------------------------
+// plugins/heyspex ships the same hooks for a PLUGIN install (a consumer repo
+// that installs HeySpex from the marketplace rather than checking the platform
+// out). It is generated from the manifest above, not hand-mirrored — the Claude
+// equivalent (plugins/heyspex/hooks/hooks.json) was a dated hand mirror (now
+// generated from scripts/lib/customer-kit.mjs), and that
+// is exactly the drift this avoids.
+const PLUGIN_HOOKS_PATH = path.join(REPO_ROOT, 'plugins', 'heyspex', 'hooks', 'cursor-hooks.json');
+
+function pluginHooksDocument() {
+  const hooks = {};
+  for (const entry of HOOKS) {
+    hooks[entry.event] ??= [];
+    hooks[entry.event].push({
+      command: commandForPlugin(entry),
+      timeout: timeoutFor(entry),
+      ...(entry.matcher ? { matcher: entry.matcher } : {}),
+    });
+  }
+  return {
+    _comment:
+      'GENERATED by scripts/install-cursor-hooks.mjs from scripts/cursor-hooks/manifest.mjs — ' +
+      'do not edit by hand; run `npm run hooks:install-cursor`. Commands resolve through ' +
+      '$CURSOR_PROJECT_DIR because the shim and hook bodies live in the host vault checkout, ' +
+      'not the plugin cache. WARNING: enabling this plugin in a repo whose .cursor/hooks.json ' +
+      'still registers the same hooks runs every hook twice — validate in a fresh clone, or ' +
+      'run `node scripts/install-cursor-hooks.mjs --uninstall` there first.',
+    version: 1,
+    hooks,
+  };
+}
+
+function pluginHooksText() {
+  return `${JSON.stringify(pluginHooksDocument(), null, 2)}\n`;
+}
+
+function syncPluginHooks() {
+  const want = pluginHooksText();
+  let have = null;
+  try {
+    have = fs.readFileSync(PLUGIN_HOOKS_PATH, 'utf8');
+  } catch {
+    have = null;
+  }
+  if (have === want) return false;
+  fs.mkdirSync(path.dirname(PLUGIN_HOOKS_PATH), { recursive: true });
+  fs.writeFileSync(PLUGIN_HOOKS_PATH, want, 'utf8');
+  return true;
+}
+
+/**
+ * Merge a hook set into a parsed `.cursor/hooks.json` object, in place. Drops
+ * superseded direct registrations, adds/repairs every entry, and retires shim
+ * entries the set no longer registers (a renamed hook, or a platform-only one
+ * in a customer repo). Foreign entries are never touched.
+ * @returns {{ added: string[], repaired: string[], removed: string[] }}
+ */
+export function mergeCursorHooks(
+  settings,
+  { hooks = ACTIVE_HOOKS, commandFor: render = KIT.commandFor } = {},
+) {
+  settings.version = 1;
+  settings.hooks ??= {};
+
+  const added = [];
+  const repaired = [];
+  const removed = [];
+
+  // 1. Drop superseded direct registrations.
+  for (const [event, entries] of Object.entries(settings.hooks)) {
+    if (!Array.isArray(entries)) continue;
+    const keep = entries.filter((raw) => {
+      if (!isLegacyEntry(raw)) return true;
+      removed.push(`${event}: ${commandOf(raw)}`);
+      return false;
+    });
+    settings.hooks[event] = keep;
+  }
+
+  // 2. Add or repair every manifest entry.
+  for (const entry of hooks) {
+    settings.hooks[entry.event] ??= [];
+    const entries = settings.hooks[entry.event];
+    const identity = identityFor(entry);
+    const existing = entries.filter(
+      (raw) => isShimEntry(raw) && identityOfCommand(commandOf(raw)) === identity,
+    );
+
+    if (existing.length === 0) {
+      entries.push(desiredEntry(entry, render));
+      added.push(`${entry.event}/${entry.hook}`);
+      continue;
+    }
+
+    // More than one match means an earlier merge duplicated it; collapse to one.
+    for (const extra of existing.slice(1)) {
+      entries.splice(entries.indexOf(extra), 1);
+      removed.push(`${entry.event}: duplicate ${entry.hook}`);
+    }
+
+    const raw = existing[0];
+    if (!sameEntry(raw, entry, render)) {
+      Object.assign(raw, desiredEntry(entry, render));
+      // A matcher removed from the manifest must also disappear from disk.
+      if (!entry.matcher && 'matcher' in raw) delete raw.matcher;
+      repaired.push(`${entry.event}/${entry.hook}`);
+    }
+  }
+
+  // 3. Retire shim entries we no longer register (a hook renamed or dropped).
+  for (const [event, entries] of Object.entries(settings.hooks)) {
+    if (!Array.isArray(entries)) continue;
+    const wanted = new Set(hooks.filter((h) => h.event === event).map(identityFor));
+    settings.hooks[event] = entries.filter((raw) => {
+      if (!isShimEntry(raw)) return true;
+      if (wanted.has(identityOfCommand(commandOf(raw)))) return true;
+      removed.push(`${event}: retired ${commandOf(raw)}`);
+      return false;
+    });
+    if (settings.hooks[event].length === 0) delete settings.hooks[event];
+  }
+
+  return { added, repaired, removed };
+}
+
+/** The customer launcher's state on disk, without writing. */
+function launcherPlan() {
+  let existing = null;
+  try {
+    existing = fs.readFileSync(LAUNCHER_PATH, 'utf8');
+  } catch {
+    existing = null;
+  }
+  return planCustomerLauncherWrite(existing, 'cursor');
+}
+
+function install({ json = false } = {}) {
+  const settings = readSettings();
+  const { added, repaired, removed } = mergeCursorHooks(settings);
+
+  const settingsChanged = added.length + repaired.length + removed.length > 0;
+  if (settingsChanged) writeSettings(settings);
+  // The committed launcher every customer row points at. The platform checkout
+  // runs the shim directly and never gets one.
+  let launcherWritten = false;
+  if (KIT.customer) {
+    const plan = launcherPlan();
+    if (plan.write) {
+      fs.mkdirSync(path.dirname(LAUNCHER_PATH), { recursive: true });
+      fs.writeFileSync(LAUNCHER_PATH, plan.text, 'utf8');
+      launcherWritten = true;
+    }
+  }
+  // The plugin mirror lives in THIS checkout; a customer target never gets one.
+  const pluginChanged = KIT.customer ? false : syncPluginHooks();
+
+  if (json) {
+    console.log(
+      JSON.stringify(
+        {
+          ok: true,
+          changed: settingsChanged || pluginChanged || launcherWritten,
+          added,
+          repaired,
+          removed,
+          pluginChanged,
+          launcherWritten,
+          total: ACTIVE_HOOKS.length,
+          customer: KIT.customer,
+        },
+        null,
+        2,
+      ),
+    );
+    return;
+  }
+
+  if (pluginChanged) {
+    console.log(`install-cursor-hooks: regenerated ${path.relative(REPO_ROOT, PLUGIN_HOOKS_PATH)}`);
+  }
+  if (launcherWritten) {
+    console.log(`install-cursor-hooks: wrote ${path.relative(REPO_ROOT, LAUNCHER_PATH)} (resolves node_modules/heyspex)`);
+  }
+
+  if (!settingsChanged) {
+    console.log(`install-cursor-hooks: already installed (${ACTIVE_HOOKS.length} hooks, no changes).`);
+    return;
+  }
+
+  const parts = [];
+  if (added.length) parts.push(`added ${added.length}`);
+  if (repaired.length) parts.push(`repaired ${repaired.length}`);
+  if (removed.length) parts.push(`removed ${removed.length}`);
+  console.log(
+    `install-cursor-hooks: ${parts.join('; ')} → ${path.relative(REPO_ROOT, SETTINGS_PATH)} ` +
+      `(${ACTIVE_HOOKS.length} hooks registered)`,
+  );
+  for (const line of removed) console.log(`  - ${line}`);
+  console.log(
+    KIT.customer
+      ? `  Launcher: ${CUSTOMER_LAUNCHER} → node_modules/heyspex/${SHIM} (HeySpex off-switch + Cursor↔Claude payload translation)`
+      : `  Shim: ${SHIM} (HeySpex off-switch + Cursor↔Claude payload translation)`,
+  );
+  for (const gap of UNPORTABLE) {
+    console.log(`  Not registerable in Cursor: ${gap.hook} (${gap.reason}) → covered by ${gap.coveredBy}`);
+  }
+}
+
+function check({ json = false } = {}) {
+  const settings = readSettings();
+  const issues = [];
+  const entriesFor = (event) =>
+    Array.isArray(settings?.hooks?.[event]) ? settings.hooks[event] : [];
+
+  for (const entry of ACTIVE_HOOKS) {
+    const identity = identityFor(entry);
+    const ours = entriesFor(entry.event).filter(
+      (raw) => isShimEntry(raw) && identityOfCommand(commandOf(raw)) === identity,
+    );
+    if (ours.length === 0) {
+      issues.push(`${entry.event}: missing ${entry.hook}`);
+      continue;
+    }
+    if (ours.length > 1) issues.push(`${entry.event}: ${entry.hook} registered ${ours.length}×`);
+    for (const raw of ours) {
+      if (!sameEntry(raw, entry)) {
+        issues.push(
+          `${entry.event}/${entry.hook}: drift — expected \`${KIT.commandFor(entry)}\`` +
+            ` (timeout ${timeoutFor(entry)}, matcher ${entry.matcher ?? 'none'}), found` +
+            ` \`${commandOf(raw)}\` (timeout ${raw.timeout}, matcher ${raw.matcher ?? 'none'})`,
+        );
+      }
+    }
+  }
+
+  for (const [event, entries] of Object.entries(settings.hooks ?? {})) {
+    if (!Array.isArray(entries)) continue;
+    for (const raw of entries) {
+      if (isLegacyEntry(raw)) {
+        issues.push(`${event}: superseded direct registration — ${commandOf(raw)}`);
+      } else if (
+        isShimEntry(raw) &&
+        !ACTIVE_HOOKS.some((h) => h.event === event && identityFor(h) === identityOfCommand(commandOf(raw)))
+      ) {
+        issues.push(`${event}: not part of this repo's hook set — ${commandOf(raw)}`);
+      }
+    }
+  }
+
+  let pluginOnDisk = null;
+  try {
+    pluginOnDisk = fs.readFileSync(PLUGIN_HOOKS_PATH, 'utf8');
+  } catch {
+    pluginOnDisk = null;
+  }
+  if (!KIT.customer && pluginOnDisk !== pluginHooksText()) {
+    issues.push(
+      `plugins/heyspex/hooks/cursor-hooks.json: ${pluginOnDisk === null ? 'missing' : 'stale'} — regenerate with \`npm run hooks:install-cursor\``,
+    );
+  }
+  if (KIT.customer) {
+    const plan = launcherPlan();
+    if (plan.write) {
+      issues.push(`${CUSTOMER_LAUNCHER}: ${plan.reason === 'missing' ? 'missing' : 'stale'} — the hook rows point at it`);
+    }
+  }
+
+  if (json) {
+    console.log(JSON.stringify({ ok: issues.length === 0, issues, total: ACTIVE_HOOKS.length, customer: KIT.customer }, null, 2));
+    process.exit(issues.length === 0 ? 0 : 1);
+  }
+
+  if (issues.length === 0) {
+    console.log(`install-cursor-hooks --check: OK (${ACTIVE_HOOKS.length} hooks registered)`);
+    process.exit(0);
+  }
+  console.error('install-cursor-hooks --check: drift detected');
+  for (const issue of issues) console.error(`  - ${issue}`);
+  console.error('  Run `node scripts/install-cursor-hooks.mjs` to repair.');
+  process.exit(1);
+}
+
+function uninstall() {
+  const settings = readSettings();
+  if (!settings.hooks) {
+    console.log('install-cursor-hooks: nothing to uninstall (no hooks block).');
+    return;
+  }
+  let removed = 0;
+  for (const [event, entries] of Object.entries(settings.hooks)) {
+    if (!Array.isArray(entries)) continue;
+    const keep = entries.filter((raw) => !isShimEntry(raw) && !isLegacyEntry(raw));
+    removed += entries.length - keep.length;
+    if (keep.length === 0) delete settings.hooks[event];
+    else settings.hooks[event] = keep;
+  }
+  if (Object.keys(settings.hooks).length === 0) delete settings.hooks;
+  writeSettings(settings);
+  console.log(`install-cursor-hooks: uninstalled ${removed} hook entr${removed === 1 ? 'y' : 'ies'}.`);
+}
+
+// CLI only when run directly -- `hs install` imports mergeCursorHooks/cursorKitFor,
+// and inside the esbuild CLI bundle a plain `import.meta.url === argv[1]` test
+// is true for EVERY bundled module (see `invokedDirectly` in customer-kit.mjs).
+if (invokedDirectly(import.meta.url, 'install-cursor-hooks.mjs')) {
+  const argv = process.argv.slice(2);
+  const json = argv.includes('--json');
+  if (argv.includes('--uninstall')) uninstall();
+  else if (argv.includes('--check')) check({ json });
+  else install({ json });
+}

package/scripts/lib/agent-env-markers.mjs

@@ -0,0 +1,38 @@
+/**
+ * agent-env-markers.mjs — the ONE list of environment stamps that mean "an AI
+ * coding agent is driving this shell".
+ *
+ * Lifted out of scripts/guard-agent-commit.mjs (2026-09-19) so the git-identity
+ * command (`hs source identity set|clear`, scripts/lib/hs-source-identity.mjs)
+ * refuses on exactly the same evidence the commit guard refuses on — one list,
+ * two consumers, no drift. guard-agent-commit's behaviour is unchanged: it
+ * imports this list and filters it the same way it always did.
+ *
+ * Shipped in the published package (package.json `files`) because
+ * hs-source-identity.mjs is a packed `hs source` entrypoint and imports it.
+ */
+
+/** Environment stamps that mean "an AI coding agent is driving this shell". */
+export const AGENT_ENV_MARKERS = [
+  'CLAUDECODE', // Claude Code
+  'CLAUDE_CODE_ENTRYPOINT',
+  'CLAUDE_CODE_SESSION_ID',
+  'CURSOR_AGENT', // Cursor's agent / cursor-agent CLI — the actor in the 2026-07-12 incident
+  'CURSOR_TRACE_ID',
+  'CURSOR_SESSION_ID',
+  'COMPOSER_NO_INTERACTION',
+  'AIDER_MODEL',
+  'OPENAI_CODEX_SESSION',
+  'DEVIN_SESSION_ID',
+];
+
+/**
+ * The markers that are present (set to anything, including an empty string
+ * is NOT present — matches guard-agent-commit's `process.env[k]` truthiness).
+ *
+ * @param {Record<string, string | undefined>} [env]
+ * @returns {string[]}
+ */
+export function detectAgentMarkers(env = process.env) {
+  return AGENT_ENV_MARKERS.filter((k) => env[k]);
+}