heyspex 0.1.0 → 0.2.1

package/spexharness/src/adapters/copilot.mjs

@@ -0,0 +1,236 @@
+// spexharness/src/adapters/copilot.mjs
+//
+// GitHub Copilot CLI front for the shared hook gates ([[HS-20SW-DRSM-DIAG-heyspex-capture-on-idea-and-workflow]];
+// contract: GitHub Docs "Hooks configuration" + "CLI plugin reference", fetched 2026-10-16;
+// [[HS-0GBS-CTF8-RES-copilot-plugin-parity-with-the-spexcode]]). Pure functions, no I/O.
+//
+// What Copilot does that Claude Code does not:
+//   INPUT   two shapes. camelCase config events `{ sessionId, timestamp, cwd, toolName, toolArgs }` and the
+//           PascalCase shape `.claude/settings.json` rows receive `{ hook_event_name, session_id, timestamp,
+//           cwd, tool_name, tool_input }` (tool names already mapped to Claude's: bash/powershell -> Bash,
+//           create -> Write, edit/apply_patch -> Edit, view -> Read, task -> Agent). No `transcript_path`.
+//   OUTPUT  ONE top-level JSON object on stdout: `{ permissionDecision: allow|deny|ask, permissionDecisionReason }`.
+//           It does NOT read `hookSpecificOutput`. Unparseable stdout is ignored.
+//   EXIT    0 -> stdout parsed. 2 -> always deny (stderr reason lost). ANY other non-zero -> deny ("hook
+//           errored"). Timeout -> fail open. So a Copilot hook prints its deny as JSON and exits 0, never 2.
+//
+// This module maps both directions; ./detect-harness.mjs decides WHEN it applies.
+
+// HeySpex MCP tool names arrive in several spellings depending on the Copilot host (the payload spelling is not
+// documented; [[HS-0GBS-CTF8-RES-copilot-plugin-parity-with-the-spexcode]] residual gap). Every spelling below maps
+// to the Claude-side `mcp__heyspex__<tool>` the gates and `.claude/settings.json` matchers already use:
+//   mcp__heyspex__heyspex_x  mcp__plugin_heyspex_heyspex__heyspex_x  heyspex/heyspex_x  heyspex.heyspex_x  heyspex_x
+const HEYSPEX_MCP_NAME = /^(?:mcp__plugin_heyspex_heyspex__|mcp__heyspex__|heyspex[/.:])?(heyspex_[A-Za-z0-9_]+)$/;
+
+/**
+ * @param {unknown} name
+ * @returns {{ name: string, suffix: string } | null} null when `name` is not a HeySpex MCP tool in a known spelling
+ */
+export function normalizeMcpToolName(name) {
+  if (typeof name !== 'string') return null;
+  const m = HEYSPEX_MCP_NAME.exec(name.trim());
+  return m ? { name: `mcp__heyspex__${m[1]}`, suffix: m[1] } : null;
+}
+
+const COPILOT_TOOL_TO_CLAUDE = {
+  bash: 'Bash',
+  powershell: 'PowerShell',
+  create: 'Write',
+  edit: 'Edit',
+  apply_patch: 'Edit',
+  view: 'Read',
+  task: 'Agent',
+};
+
+function parseArgs(value) {
+  if (value && typeof value === 'object') return value;
+  if (typeof value !== 'string' || !value.trim()) return {};
+  try {
+    const parsed = JSON.parse(value);
+    return parsed && typeof parsed === 'object' ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Either Copilot payload shape -> the Claude-shaped payload every hook already reads. Never throws; a payload
+ * that is already Claude-shaped passes through with its `hook_event_name`, and unknown fields stay untouched.
+ * @param {unknown} payload
+ * @returns {Record<string, unknown>}
+ */
+export function normalizeCopilotPayload(payload) {
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) return {};
+  const p = /** @type {Record<string, any>} */ (payload);
+  const out = { ...p };
+  if (out.session_id === undefined && typeof p.sessionId === 'string') out.session_id = p.sessionId;
+  if (out.tool_name === undefined && typeof p.toolName === 'string') {
+    out.tool_name = COPILOT_TOOL_TO_CLAUDE[p.toolName] ?? p.toolName;
+  }
+  if (out.tool_input === undefined && p.toolArgs !== undefined) {
+    const args = { ...parseArgs(p.toolArgs) };
+    if (args.file_path === undefined && typeof args.path === 'string') args.file_path = args.path;
+    out.tool_input = args;
+  }
+  if (typeof out.tool_name === 'string') {
+    const mcp = normalizeMcpToolName(out.tool_name);
+    if (mcp) {
+      if (mcp.name !== out.tool_name && out.tool_name_original === undefined) out.tool_name_original = out.tool_name;
+      out.tool_name = mcp.name;
+      out.tool_name_suffix = mcp.suffix;
+    }
+  }
+  if (out.tool_response === undefined && p.toolResult !== undefined) out.tool_response = p.toolResult;
+  if (typeof out.hook_event_name !== 'string') {
+    if (out.tool_response !== undefined) out.hook_event_name = 'PostToolUse';
+    else if (out.tool_name !== undefined) out.hook_event_name = 'PreToolUse';
+    else if (typeof p.prompt === 'string') out.hook_event_name = 'UserPromptSubmit';
+  }
+  return out;
+}
+
+const body = (decision, reason) => JSON.stringify({ permissionDecision: decision, permissionDecisionReason: reason });
+
+/**
+ * A gate decision (decide.mjs shape) -> what a Copilot hook process emits. A deny is ALWAYS exit 0 with the
+ * JSON on stdout (exit 2 would lose the reason). `allow`, `inject` and warn-only rewrites print nothing on
+ * stdout (Copilot has no additionalContext channel for tool hooks).
+ * @param {{ id?: string, event?: unknown }} _gate
+ * @param {{ point?: string }} engineEvent
+ * @param {{ decision?: string, reason?: string, rewrite?: { ask?: boolean, warn?: boolean } }} decision
+ * @returns {{ exitCode: 0, stdout: string, stderr: string }}
+ */
+export function toCopilotResponse(_gate, engineEvent, decision) {
+  const kind = decision?.decision ?? 'allow';
+  const reason = String(decision?.reason ?? 'Denied by a HeySpex hook.');
+  if (kind === 'deny') {
+    const o = { permissionDecision: 'deny', permissionDecisionReason: reason };
+    // a Stop-time deny is a re-drive: carry the Claude stop shape too so either reader acts on it
+    if (engineEvent?.point === 'stop') Object.assign(o, { decision: 'block', reason });
+    return { exitCode: 0, stdout: JSON.stringify(o), stderr: '' };
+  }
+  if (kind === 'rewrite' && decision.rewrite?.ask) return { exitCode: 0, stdout: body('ask', reason), stderr: '' };
+  if (kind === 'rewrite' && decision.rewrite?.warn) {
+    return { exitCode: 0, stdout: '', stderr: reason.endsWith('\n') ? reason : `${reason}\n` };
+  }
+  return { exitCode: 0, stdout: '', stderr: '' };
+}
+
+/**
+ * Rewrite a Claude-dialect stdout blob (`{"hookSpecificOutput":{"permissionDecision":...}}`) into Copilot's
+ * top-level object. Anything else (already top-level, Stop `{decision:"block"}`, additionalContext, plain
+ * text) is returned unchanged. Used by the shared runner for hand-written hooks that print Claude JSON.
+ * @param {string} text
+ * @returns {string}
+ */
+export function rewriteStdoutForCopilot(text) {
+  try {
+    const o = JSON.parse(text);
+    const h = o?.hookSpecificOutput;
+    if (h && typeof h.permissionDecision === 'string') {
+      return body(h.permissionDecision, h.permissionDecisionReason ?? 'Denied by a HeySpex hook.');
+    }
+  } catch {
+    /* not JSON: pass through */
+  }
+  return text;
+}
+
+/**
+ * A hand-written hook that decided "deny" the legacy way (exit 2, reason on stderr) -> the Copilot JSON deny.
+ * @param {string} stderrText
+ * @returns {string}
+ */
+export function denyFromLegacyExit(stderrText) {
+  const reason = String(stderrText ?? '').replace(/\r/g, '').trim() || 'Denied by a HeySpex hook.';
+  return body('deny', reason);
+}
+
+/**
+ * VS Code's Local harness ignores hook matchers, so the runner re-applies them. True when ANY matcher admits the
+ * tool (an empty / `*` / `.*` matcher admits everything; an invalid regex fails open to "admit"). Matchers are
+ * Claude Code's: a regex that must match the WHOLE tool name.
+ * @param {string[]} matchers
+ * @param {string[]} toolNames every spelling of the tool (normalized first, original after)
+ * @returns {boolean}
+ */
+export function toolMatchesAnyMatcher(matchers, toolNames) {
+  if (!Array.isArray(matchers) || matchers.length === 0) return true;
+  const names = toolNames.filter((n) => typeof n === 'string' && n);
+  for (const m of matchers) {
+    if (typeof m !== 'string' || m === '' || m === '*' || m === '**') return true;
+    try {
+      const re = new RegExp(`^(?:${m})$`);
+      if (names.some((n) => re.test(n))) return true;
+    } catch {
+      return true;
+    }
+  }
+  return false;
+}
+
+/** All spellings a gate matcher might name for this (normalized) payload's tool. */
+export function toolNameCandidates(payload) {
+  const names = [];
+  const add = (n) => { if (typeof n === 'string' && n && !names.includes(n)) names.push(n); };
+  add(payload?.tool_name);
+  add(payload?.tool_name_original);
+  if (typeof payload?.tool_name_suffix === 'string') add(`mcp__plugin_heyspex_heyspex__${payload.tool_name_suffix}`);
+  return names;
+}
+
+const CONTEXT_EVENTS = new Set(['SessionStart', 'PostToolUse', 'SubagentStart']);
+
+/**
+ * The ONE place the runner decides what a Copilot hook process may print. Guarantees: the result is '' or a
+ * single valid JSON object. Non-JSON output is dropped (Copilot ignores unparseable stdout anyway). Claude's
+ * `hookSpecificOutput` permission form becomes the top-level form. Copilot drops command-hook output on
+ * `UserPromptSubmit`, so a context-only result there prints nothing (a permission / block result still prints).
+ * For events that DO accept context (sessionStart, postToolUse, subagentStart) the Claude
+ * `hookSpecificOutput.additionalContext` is mirrored to the top-level `additionalContext` Copilot documents.
+ * @param {string} text raw buffered stdout
+ * @param {string} [eventName] normalized hook_event_name
+ * @returns {string}
+ */
+export function finalizeCopilotStdout(text, eventName) {
+  let o;
+  try {
+    o = JSON.parse(rewriteStdoutForCopilot(String(text ?? '')));
+  } catch {
+    return '';
+  }
+  if (!o || typeof o !== 'object' || Array.isArray(o)) return '';
+  const decided = typeof o.permissionDecision === 'string' || o.decision === 'block';
+  if (eventName === 'UserPromptSubmit' && !decided) return '';
+  const ctx = o.hookSpecificOutput?.additionalContext;
+  if (typeof ctx === 'string' && o.additionalContext === undefined && CONTEXT_EVENTS.has(String(eventName))) {
+    o = { ...o, additionalContext: ctx };
+  }
+  return JSON.stringify(o);
+}
+
+/**
+ * Append `extra` to a finished Copilot stdout blob's additionalContext (creating the object when stdout is
+ * empty). A permission decision is never touched. Returns the new stdout.
+ * @param {string} finalText '' or one JSON object
+ * @param {string} extra
+ * @returns {string}
+ */
+export function mergeAdditionalContext(finalText, extra) {
+  if (!extra) return finalText;
+  let o = {};
+  if (finalText) {
+    try { o = JSON.parse(finalText); } catch { return finalText; }
+    if (!o || typeof o !== 'object' || Array.isArray(o)) return finalText;
+  }
+  if (typeof o.permissionDecision === 'string') return finalText;
+  const prev = typeof o.additionalContext === 'string' ? o.additionalContext : o.hookSpecificOutput?.additionalContext;
+  const merged = typeof prev === 'string' && prev ? `${prev}
+
+${extra}` : extra;
+  o.additionalContext = merged;
+  if (o.hookSpecificOutput && typeof o.hookSpecificOutput === 'object') {
+    o.hookSpecificOutput = { ...o.hookSpecificOutput, additionalContext: merged };
+  }
+  return JSON.stringify(o);
+}

package/spexharness/src/adapters/detect-harness.mjs

@@ -0,0 +1,34 @@
+// spexharness/src/adapters/detect-harness.mjs
+//
+// Which agent harness is invoking this hook? ([[HS-20SW-DRSM-DIAG-heyspex-capture-on-idea-and-workflow]] Copilot
+// compatibility; contract: GitHub Docs "Hooks configuration", fetched 2026-10-16.) GitHub Copilot CLI runs the
+// hooks registered in `.claude/settings.json` too, but it speaks a different output dialect (ONE top-level
+// `{permissionDecision, permissionDecisionReason}` object, not `hookSpecificOutput`) and treats every
+// non-zero exit as a deny, so the shared runner must know when it is talking to Copilot.
+//
+// DETECTION IS POSITIVE-SIGNATURE ONLY - never "session_id missing". Pure: payload + env in, a string out.
+//   - explicit override  HEYSPEX_HARNESS = copilot | claude-code | cursor      (wins)
+//   - 'copilot'  the payload carries `timestamp` (absent from Claude Code payloads) AND no Cursor marker; or it
+//                is the camelCase config shape ({ sessionId, toolName, toolArgs } with no snake_case twins).
+//   - 'cursor'   `conversation_id` / `workspace_roots` / `cursor_version` present.
+//   - 'claude-code' a `hook_event_name` + `session_id` payload with none of the above.
+//   - 'unknown'  anything else (including a non-object payload). Callers treat unknown like claude-code.
+
+const OVERRIDES = new Set(['copilot', 'claude-code', 'cursor']);
+
+/**
+ * @param {unknown} payload parsed hook stdin (or null)
+ * @param {Record<string, string | undefined>} [env]
+ * @returns {'claude-code' | 'copilot' | 'cursor' | 'unknown'}
+ */
+export function detectHarness(payload, env = process.env) {
+  const forced = String(env?.HEYSPEX_HARNESS ?? '').trim().toLowerCase();
+  if (OVERRIDES.has(forced)) return forced;
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) return 'unknown';
+  const p = /** @type {Record<string, unknown>} */ (payload);
+  if ('conversation_id' in p || 'workspace_roots' in p || 'cursor_version' in p) return 'cursor';
+  const camel = ('toolName' in p || 'toolArgs' in p) && !('tool_name' in p);
+  if ('timestamp' in p || camel) return 'copilot';
+  if (typeof p.hook_event_name === 'string' && typeof p.session_id === 'string') return 'claude-code';
+  return 'unknown';
+}