heyspex 0.2.5 → 0.2.7

package/scripts/install-copilot-hooks.mjs

@@ -86,6 +86,7 @@ function parseArgs(argv) {
     else if (x === '--check') a.check = true;
     else if (x === '--uninstall') a.uninstall = true;
     else if (x === '--print') a.print = true;
+    else if (x === '--help' || x === '-h') a.help = true;
     else if (x === '--json') a.json = true;
     else if (x === '--target') {
       a.target = argv[++i] ?? null;
@@ -238,10 +239,25 @@ function manualCommands(spec) {
   ];
 }
 
+/** This package's own version (package.json), or null when unreadable. */
+function packageVersion() {
+  try {
+    const v = JSON.parse(fsDeps.readFile(path.join(PACKAGE_ROOT, 'package.json')) ?? 'null')?.version;
+    return typeof v === 'string' && v.trim() ? v.trim() : null;
+  } catch {
+    return null;
+  }
+}
+
+/** The install doc as printed: its `heyspex-<version>.tgz` placeholder names this package's real version. */
+export function renderInstallDoc(doc, version) {
+  return version ? doc.replace(/heyspex-<version>\.tgz/g, `heyspex-${version}.tgz`) : doc;
+}
+
 function doPrint(out) {
   out(`Next: run \`${nextCommand()}\` (plugin) or \`${nextCommand()} --hooks\` (cloud agent) in this repo, then /restart.`);
   const doc = fsDeps.readFile(path.join(PACKAGE_ROOT, 'docs', 'copilot-plugin-install.md'));
-  if (doc !== null) { out(''); out(doc.replace(/\s+$/, '')); return 0; }
+  if (doc !== null) { out(''); out(renderInstallDoc(doc, packageVersion()).replace(/\s+$/, '')); return 0; }
   const spec = resolvePluginSpec(PACKAGE_ROOT);
   out('');
   out('# Installing HeySpex in GitHub Copilot CLI (built-in fallback; docs/copilot-plugin-install.md not found)');
@@ -385,6 +401,10 @@ export function main(argv = process.argv.slice(2), io = {}) {
       err('usage: hs setup copilot [--hooks] [--statusline [--force]] [--check [--json]] [--uninstall] [--print] [--target <dir>]');
       return 2;
     }
+    if (a.help) {
+      out('usage: hs setup copilot [--hooks] [--statusline [--force]] [--check [--json]] [--uninstall] [--print] [--target <dir>]');
+      return 0;
+    }
     if (a.print) return doPrint(out);
     const target = a.target ? path.resolve(a.target) : findRepoRoot(process.env.HS_SETUP_TARGET?.trim() || process.cwd());
     if (a.check) return doCheck(a, target, out);

package/scripts/install-cursor-hooks.mjs

@@ -42,13 +42,14 @@ import {
   hookScope,
   invokedDirectly,
   planCustomerLauncherWrite,
+  resolveSetupTarget,
   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;
+// HS_SETUP_TARGET, else this checkout -- or, from an installed package, the
+// customer project found from cwd (never the package folder itself).
+const REPO_ROOT = resolveSetupTarget({ platformRoot: PLATFORM_ROOT });
 const SETTINGS_PATH = path.join(REPO_ROOT, '.cursor', 'hooks.json');
 
 // CUSTOMER TARGET (`hs setup cursor` / `hs doctor --fix` with HS_SETUP_TARGET

package/scripts/lib/capture-execution-guard.mjs

@@ -0,0 +1,221 @@
+// scripts/lib/capture-execution-guard.mjs
+//
+// [[HS-KNJ8-BQZC-DIAG-an-agent-session-executed-past-capture]] — the deterministic
+// "do not execute past an ungrounded capture" guard. Pure decision + tiny fs helpers.
+// Consumed by:
+//   - scripts/claude-hooks/capture-execution-gate.mjs   (PreToolUse, refuses)
+//   - scripts/lib/capture-verbatim-append.mjs           (UserPromptSubmit, writes the state)
+//   - scripts/record-grounding.mjs                      (/hs-ground helper, writes the record)
+//
+// WHERE THE GATE LEARNS CAPTURE STATE (cheap + offline): ONE local file,
+// `.heyspex/capture-gate-state.json` under the project root:
+//   { capture_id, session_id, expanded, written_at }
+// It is written ONLY by the UserPromptSubmit stage after a LIVE resolve of the on-deck
+// capture (console/Neon is the system of record; the offline capture-focus.yaml rots —
+// HS-O4U6 — so the gate never trusts it) and by record-grounding.mjs. The PreToolUse gate
+// reads nothing but that file and `.heyspex/research-grounding.json`: no network, no
+// MCP, no capture-focus.mjs import (a Bash-time hook must stay fast).
+//
+// FAIL OPEN whenever state is unknowable: no hook session id, no state file, unreadable or
+// malformed JSON, a state written by ANOTHER session, a state older than STATE_MAX_AGE_MS,
+// a state with no capture_id (the prompt stage writes capture_id:null when it verified
+// nothing is on deck for this session). Only a fresh, this-session, named, not-yet-cleared
+// capture can ever refuse anything.
+//
+// Self-clearing: while a state exists the prompt stage re-verifies it on EVERY substantive
+// prompt, so a promoted/closed capture stops gating at the next message; STATE_MAX_AGE_MS
+// bounds the worst case when no prompt arrives.
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+import {
+  GROUNDING_ARTIFACT_REL,
+  GROUNDING_FIELDS,
+  defaultReadGroundingArtifact,
+} from '../../spexharness/src/gates/deep-research-cost-gate.mjs';
+
+export const STATE_REL = path.join('.heyspex', 'capture-gate-state.json');
+export const STATE_MAX_AGE_MS = 6 * 60 * 60 * 1000;
+/** Owner/env kill switch for the gate; the config twin is agent_behaviors.capture_execution_gate.enabled. */
+export const GATE_OFF_ENV = 'HEYSPEX_CAPTURE_EXECUTION_GATE_OFF';
+export const GATE_CONFIG_KEY = 'agent_behaviors.capture_execution_gate.enabled';
+
+// ── state file ─────────────────────────────────────────────────────────────
+
+export function readGateState(root) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(path.join(root, STATE_REL), 'utf8'));
+    return parsed && typeof parsed === 'object' ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+export function writeGateState(root, state) {
+  try {
+    const full = path.join(root, STATE_REL);
+    fs.mkdirSync(path.dirname(full), { recursive: true });
+    fs.writeFileSync(
+      full,
+      JSON.stringify({ ...state, written_at: new Date().toISOString() }, null, 2) + '\n',
+      'utf8',
+    );
+    return true;
+  } catch {
+    return false; // best effort — a failed write only means the gate fails open
+  }
+}
+
+/** Does this capture body carry an agent expansion? (same two shapes capture-focus.mjs reads) */
+export function bodyHasExpansion(body) {
+  const text = String(body ?? '').replace(/\r\n/g, '\n');
+  if (/##[ \t]*Expanded[ \t]+Concept[ \t]*\n\s*\S/i.test(text)) return true;
+  return /<details>\s*\n<summary>\s*(?:Details|Expanded idea \(agent\))[^<\n]*<\/summary>\s*\n+\s*\S/i.test(text);
+}
+
+// ── grounding record ───────────────────────────────────────────────────────
+
+/** Is `artifact` a complete grounding record for `captureId`? Same predicate as deep-research-cost-gate's groundingBlock. */
+export function isGroundedFor(artifact, captureId) {
+  return Boolean(
+    artifact &&
+      typeof artifact === 'object' &&
+      captureId &&
+      artifact.source_idea_id === captureId &&
+      GROUNDING_FIELDS.every((k) => typeof artifact[k] === 'string' && artifact[k].trim()),
+  );
+}
+
+/**
+ * The /hs-ground helper's write: `.heyspex/research-grounding.json` in the EXACT shape
+ * deep-research-cost-gate reads, keyed to the capture, plus marks the gate state expanded
+ * (recording the grounding IS the expansion step of the Ground=Expand flow).
+ */
+export function recordGrounding(root, { source_idea_id, already_built, already_decided, owner_reference, residual_delta }, { sessionId } = {}) {
+  const record = { source_idea_id, already_built, already_decided, owner_reference, residual_delta };
+  const missing = ['source_idea_id', ...GROUNDING_FIELDS].filter((k) => typeof record[k] !== 'string' || !record[k].trim());
+  if (missing.length) return { ok: false, error: `missing or empty: ${missing.join(', ')}` };
+  const full = path.join(root, GROUNDING_ARTIFACT_REL);
+  fs.mkdirSync(path.dirname(full), { recursive: true });
+  fs.writeFileSync(full, JSON.stringify({ ...record, recorded_at: new Date().toISOString() }, null, 2) + '\n', 'utf8');
+  const prior = readGateState(root);
+  if (prior?.capture_id === source_idea_id) {
+    writeGateState(root, { ...prior, session_id: sessionId ?? prior.session_id, expanded: true });
+  }
+  return { ok: true, path: full };
+}
+
+// ── surface classification ─────────────────────────────────────────────────
+
+const PAID_SCRIPTS = ['firecrawl-cli', 'spexcrawl-cli', 'synthesize-cli', 'audit-via-deepseek', 'deepseek-build'];
+const SCRIPT_RE = new RegExp(`(^|[\\s/\\\\"'=])(?:${PAID_SCRIPTS.join('|')})(?:\\.mjs|\\.js|\\.ts)?(?=$|[\\s"';|&)])`, 'i');
+// :3002 on loopback OR any dotted-quad host (the owner's Firecrawl runs on the LAN, e.g. 192.168.1.252:3002).
+const FIRECRAWL_URL_RE = /(?:127\.0\.0\.1|localhost|\d{1,3}(?:\.\d{1,3}){3}):3002|api\.firecrawl\.dev/i;
+// A segment whose FIRST word is one of these only reads/inspects; never refused.
+const READ_ONLY_HEAD = new Set([
+  'cat', 'head', 'tail', 'less', 'more', 'grep', 'rg', 'egrep', 'fgrep', 'ls', 'dir', 'find', 'wc', 'type', 'echo',
+  'git', 'sed', 'awk', 'stat', 'file', 'diff', 'tree', 'pwd', 'cd', 'which', 'where', 'get-content', 'select-string',
+  'get-childitem', 'test-path', 'printf', 'sort', 'cut', 'jq',
+]);
+// Offline verification of the tools themselves — tests, self-tests, help.
+const OFFLINE_FLAG_RE = /(?:^|\s)(?:--test|--self-test|--help|-h)(?=\s|$)|\.(?:test|smoke)\.m?js\b/i;
+
+function splitSegments(command) {
+  return String(command).split(/&&|\|\||;|\||\r?\n/).map((s) => s.trim()).filter(Boolean);
+}
+
+function headWord(segment) {
+  // skip leading env assignments (FOO=1 node ...) and a leading "cd x" is its own segment already
+  const words = segment.split(/\s+/);
+  let i = 0;
+  while (i < words.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(words[i])) i++;
+  return (words[i] ?? '').replace(/^["']|["']$/g, '').toLowerCase();
+}
+
+/** Which gated Bash surface (if any) does this command invoke? */
+export function classifyBash(command) {
+  if (typeof command !== 'string' || !command.trim()) return null;
+  for (const seg of splitSegments(command)) {
+    if (READ_ONLY_HEAD.has(headWord(seg))) continue;
+    if (OFFLINE_FLAG_RE.test(seg)) continue;
+    if (FIRECRAWL_URL_RE.test(seg)) return { surface: 'firecrawl-api', detail: seg.slice(0, 120) };
+    if (SCRIPT_RE.test(seg)) {
+      const name = PAID_SCRIPTS.find((s) => seg.toLowerCase().includes(s));
+      return { surface: name ?? 'paid-research-script', detail: seg.slice(0, 120) };
+    }
+  }
+  return null;
+}
+
+// An Agent/Task prompt that tells a sub-agent to CHANGE research routing / the model catalog / a protocol.
+const ROUTING_TARGET_RE =
+  /routing[\s_-]*table|model[\s_-]*catalog|dev-factory-delegation-routing|research[\s_-]*(?:routing|seat)|routing[\s_-]*(?:pins?|rules?|seats?|defaults?)|seats\.json|specs[\\/]protocols[\\/]|protocol (?:file|edit)|edit(?:ing)? (?:the )?protocol|(?:default|always)[^.\n]{0,60}\b(?:research|synthesis)\b/i;
+const EDIT_VERB_RE =
+  /\b(?:edit|modify|change|update|rewrite|patch|set|make sure|ensure|always use|add|fix|implement|wire|configure|pin|route)\b/i;
+
+export function classifyAgent(input) {
+  const text = `${typeof input?.prompt === 'string' ? input.prompt : ''}\n${typeof input?.description === 'string' ? input.description : ''}`;
+  if (!text.trim()) return null;
+  if (ROUTING_TARGET_RE.test(text) && EDIT_VERB_RE.test(text)) {
+    return { surface: 'routing-edit-agent', detail: text.trim().slice(0, 120) };
+  }
+  return null;
+}
+
+export function classifySurface(toolName, toolInput) {
+  const name = String(toolName ?? '').trim();
+  if (name === 'Bash' || name === 'PowerShell') return classifyBash(toolInput?.command);
+  if (name === 'Agent' || name === 'Task') return classifyAgent(toolInput);
+  return null;
+}
+
+// ── decision ───────────────────────────────────────────────────────────────
+
+/**
+ * @param {{ toolName?: string, toolInput?: object, sessionId?: string }} evt
+ * @param {{ root: string, env?: object, now?: number, readState?: Function, readGrounding?: Function, configEnabled?: boolean }} ctx
+ * @returns {{ decision: 'allow'|'deny', reason?: string }}
+ */
+export function decideCaptureExecution(evt, ctx) {
+  const env = ctx.env ?? process.env;
+  if (String(env[GATE_OFF_ENV] ?? '') === '1' || ctx.configEnabled === false) return { decision: 'allow' };
+  const hit = classifySurface(evt?.toolName, evt?.toolInput);
+  if (!hit) return { decision: 'allow' };
+  const sessionId = typeof evt?.sessionId === 'string' ? evt.sessionId.trim() : '';
+  if (!sessionId) return { decision: 'allow' }; // cannot prove it is THIS session's capture
+
+  const state = (ctx.readState ?? readGateState)(ctx.root);
+  const now = ctx.now ?? Date.now();
+  const writtenAt = Date.parse(state?.written_at ?? '');
+  if (
+    !state ||
+    !state.capture_id ||
+    state.session_id !== sessionId ||
+    !Number.isFinite(writtenAt) ||
+    now - writtenAt > STATE_MAX_AGE_MS
+  ) {
+    return { decision: 'allow' };
+  }
+
+  const grounded = isGroundedFor((ctx.readGrounding ?? defaultReadGroundingArtifact)(ctx.root), state.capture_id);
+  const expanded = state.expanded === true;
+  if (expanded && grounded) return { decision: 'allow' };
+
+  const why = [!expanded && 'it is still unexpanded', !grounded && `no grounding record for ${state.capture_id} exists`]
+    .filter(Boolean)
+    .join(' and ');
+  return {
+    decision: 'deny',
+    reason:
+      `Execution blocked (${hit.surface}): capture ${state.capture_id} is on deck for this session but ${why}. ` +
+      `Capture, ground and expand FIRST, then execute: (1) the owner's words must be in the capture verbatim; ` +
+      `(2) run /hs-ground on it (route-1 plans, route-2 code, route-3 the owner's own working reference); ` +
+      `(3) record the result with  node scripts/record-grounding.mjs --capture ${state.capture_id} --built "..." --decided "..." --reference "..." --delta "..."  ` +
+      `(writes ${GROUNDING_ARTIFACT_REL} and marks the capture expanded); (4) retry this exact call. ` +
+      `If the owner said to discard the capture or to just do it, promote/close the capture first. ` +
+      `Read-only tools, capture writes, /hs-ground, git and test runs are never gated. ` +
+      `Only the owner can lift this gate wholesale: set ${GATE_OFF_ENV}=1 in their own environment ` +
+      `(or agent_behaviors.capture_execution_gate.enabled: false).`,
+  };
+}