heyspex 0.1.0

package/vendor/heyspex-mcp/canvas-inbox.mjs

@@ -0,0 +1,130 @@
+// heyspex_canvas_inbox — agent-pull side of the session-mirror write-back
+// ([[HS-1ROV-EPIC]] stage 5c). An agent that polls calls this tool to claim any
+// pending HeySpex canvas messages for its session. The messages are claimed
+// THROUGH the companion daemon's localhost listener (`POST /outbox/claim`), which
+// dequeues from the daemon's single MirrorOutbox — the same queue the Stop-hook
+// drain and the idle injector pull from. That single ledger is what makes
+// delivery exactly-once across all three channels: a message this tool claims is
+// removed from the outbox, so the Stop drain / idle injection can never also
+// deliver it (and vice-versa).
+//
+// Daemon down / not running / unreachable are NORMAL states (Chrome closed, no
+// companion) — handled gracefully as an empty result with an honest note, never
+// an error.
+import fs from 'node:fs';
+import path from 'node:path';
+import http from 'node:http';
+
+const POST_TIMEOUT_MS = 2000;
+
+/** Read `mirrorListenerPort` from the companion settings file. 0 = no listener. */
+export function readMirrorListenerPort(settingsPath) {
+  try {
+    const raw = fs.readFileSync(settingsPath, 'utf8');
+    const parsed = JSON.parse(raw);
+    const port = parsed?.mirrorListenerPort;
+    return Number.isInteger(port) && port > 0 ? port : 0;
+  } catch {
+    return 0;
+  }
+}
+
+/**
+ * Resolve the companion settings path. Prefers the HEYSPEX_COMPANION_SETTINGS env
+ * override; otherwise the in-repo desktop install location
+ * (`<vaultRoot>/companion/companion.settings.json`). This is the ONE file
+ * that carries `mirrorListenerPort` — NOT `spex-console/companion-settings.json`.
+ */
+export function resolveCompanionSettingsPath(vaultRoot) {
+  const env = process.env.HEYSPEX_COMPANION_SETTINGS;
+  if (env && env.trim().length > 0) return env.trim();
+  return path.join(vaultRoot ?? '.', 'companion', 'companion.settings.json');
+}
+
+/** Default localhost POST to the companion listener; resolves the body text. */
+function defaultPost(port, urlPath, body) {
+  return new Promise((resolve, reject) => {
+    const payload = JSON.stringify(body);
+    const req = http.request(
+      {
+        method: 'POST',
+        hostname: '127.0.0.1',
+        port,
+        path: urlPath,
+        headers: {
+          'content-type': 'application/json',
+          'content-length': Buffer.byteLength(payload),
+        },
+        timeout: POST_TIMEOUT_MS,
+      },
+      (res) => {
+        let out = '';
+        res.setEncoding('utf8');
+        res.on('data', (c) => {
+          out += c;
+        });
+        res.on('end', () => resolve(out));
+        res.on('error', reject);
+      },
+    );
+    req.on('error', reject);
+    req.on('timeout', () => {
+      req.destroy();
+      reject(new Error('timeout'));
+    });
+    req.write(payload);
+    req.end();
+  });
+}
+
+/**
+ * Claim pending canvas messages for `sessionId`. `postImpl(port, urlPath, body)`
+ * is injectable for tests (returns the response body text). Never throws.
+ */
+export async function executeCanvasInbox({ vaultRoot, sessionId, settingsPath, postImpl } = {}) {
+  const sid = typeof sessionId === 'string' ? sessionId.trim() : '';
+  if (!sid) {
+    return {
+      ok: false,
+      error: 'NO_SESSION',
+      message:
+        'A session id is required. Pass session_id, or run inside a Claude Code session ' +
+        '(CLAUDE_CODE_SESSION_ID).',
+      messages: [],
+    };
+  }
+
+  const sp = settingsPath || resolveCompanionSettingsPath(vaultRoot);
+  const port = readMirrorListenerPort(sp);
+  if (!port) {
+    return {
+      ok: true,
+      messages: [],
+      note: 'The HeySpex companion daemon is not running (no listener port); no canvas messages.',
+    };
+  }
+
+  const post = postImpl || defaultPost;
+  let raw;
+  try {
+    raw = await post(port, '/outbox/claim', { session_id: sid });
+  } catch {
+    return {
+      ok: true,
+      messages: [],
+      note: 'The HeySpex companion daemon is unreachable; no canvas messages.',
+    };
+  }
+
+  let parsed = null;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    parsed = null;
+  }
+  const messages = Array.isArray(parsed?.messages)
+    ? parsed.messages.filter((m) => typeof m === 'string' && m.length > 0)
+    : [];
+
+  return { ok: true, sessionId: sid, delivered: messages.length, messages };
+}

package/vendor/heyspex-mcp/capture-active-rehydrate.mjs

@@ -0,0 +1,76 @@
+/**
+ * Resolve the content to report for the no-`spec_id` `heyspex_active_capture`
+ * path — extracted from cli.mjs so the decision is unit-testable without
+ * booting the MCP stdio server (mirrors the `capture-buffer-patches.mjs`
+ * factoring).
+ *
+ * Fixes [[HS-U29N-DIAG-T2DR-heyspex-active-capture-with-no-spec-id]]: the
+ * no-`spec_id` path attaches to whichever `capture_sessions` row was most
+ * recently active and used to trust its `content_buffer` at face value. A
+ * session whose capture is already materialized (`specPath` set) can carry a
+ * stale/empty `content_buffer` even though the FILE on disk holds the
+ * owner's real content — the DB buffer and the file can diverge (e.g. the
+ * file was authored/edited by a path that never PATCHed this session's
+ * buffer). Reporting the empty buffer as "this capture is empty" let an
+ * agent conclude it was safe to write fresh content, silently overwriting a
+ * live capture. This actually happened on 2026-07-13 to `HS-DN7D-CAP` and
+ * had to be restored from git.
+ *
+ * Two rules encoded here:
+ *  1. **Never trust an empty buffer when a spec file exists.** `specPath`
+ *     set means this capture is materialized — a real file exists. If the
+ *     buffer looks empty, read the file before concluding "empty".
+ *  2. **`is_new` is only true for a genuinely fresh capture** — no buffer
+ *     content AND no materialized file. Every other case (buffer has
+ *     content, or the file has content) is `is_new: false`, even when
+ *     rehydration was needed to see that content.
+ */
+
+/**
+ * @param {object} session - the capture_sessions row: { contentBuffer, specPath, id, ... }
+ * @param {object} deps
+ * @param {(contentBuffer: object) => { core: string, summary: string, notes: string }} deps.normalizeBuffer -
+ *   normalize a content_buffer (flat or structured shape) into plain text fields.
+ * @param {(specPath: string) => ({ body: string } | null)} deps.loadSpec - load a spec file by path; null if unreadable/missing.
+ * @param {(body: string) => string} deps.extractCore - extract the `# Core Idea` section from a spec body.
+ * @param {(body: string) => string} deps.extractNotes - extract the `## Notes` section from a spec body.
+ * @returns {{ contentBuffer: object, is_new: boolean, rehydrated_from_disk: boolean }}
+ */
+export function resolveActiveCaptureContent(session, deps) {
+  const rawBuffer = (session && session.contentBuffer) || {};
+  const norm = deps.normalizeBuffer(rawBuffer);
+  const bufferHasContent = Boolean(norm.core || norm.summary || norm.notes);
+
+  if (bufferHasContent) {
+    // Buffer already carries real content — nothing to rehydrate, and this
+    // is by definition not a fresh/empty capture.
+    return { contentBuffer: rawBuffer, is_new: false, rehydrated_from_disk: false };
+  }
+
+  const specPath = session && session.specPath;
+  if (!specPath) {
+    // No buffer content and no materialized file → genuinely new/empty.
+    return { contentBuffer: rawBuffer, is_new: true, rehydrated_from_disk: false };
+  }
+
+  // Buffer looks empty but the capture is materialized — read the file
+  // before trusting "empty". This is the exact clobber precondition from
+  // the incident: never skip this check.
+  const spec = deps.loadSpec(specPath);
+  if (spec) {
+    const core = deps.extractCore(spec.body) || '';
+    const notes = deps.extractNotes(spec.body) || '';
+    if (core || notes) {
+      return {
+        contentBuffer: { ...rawBuffer, core_idea: core, notes },
+        is_new: false,
+        rehydrated_from_disk: true,
+      };
+    }
+  }
+
+  // Materialized but genuinely empty on disk too (or the file is
+  // unreadable) — still NOT a fresh capture; a spec file already exists for
+  // this id, so a caller must not treat it as safe to write from scratch.
+  return { contentBuffer: rawBuffer, is_new: false, rehydrated_from_disk: false };
+}

package/vendor/heyspex-mcp/capture-buffer-patches.mjs

@@ -0,0 +1,147 @@
+/**
+ * Build the `content_buffer` PATCH set for `heyspex_update_capture` — extracted
+ * from cli.mjs so the shape contract is unit-testable without booting the MCP
+ * stdio server (mirrors the console-fetch.mjs / capture-console-client.mjs
+ * factoring).
+ *
+ * Root cause this fixes ([[HS-CAP-BX1J]] empty-body bug, sibling of
+ * [[HS-TASK-CPLO]] / [[HS-TASK-MERC]] under [[HS-EPIC-CPMR]]): the tool used to
+ * emit flat strings (`user_quotes`/`core_idea`/`concept`/`agent_expansion`)
+ * which the console persisted verbatim but every downstream reader
+ * (`hasRealContent`, `renderCaptureBody`) rejected — they require the canonical
+ * STRUCTURED `CaptureContentBuffer` shapes (see console `types.ts`):
+ *   - userQuotes: Array<{ at, text }>
+ *   - coreIdea / summary / details: { at, text, confirmed }
+ * so the materialized markdown body rendered empty.
+ *
+ * Two correctness rules encoded here:
+ *  1. **Structured, camelCase paths.** `userQuotes` (array), `coreIdea`,
+ *     `summary` (renamed from `concept`, HS-EPIC-OED2), and `details` (objects).
+ *     `agent_expansion` is the `## Expanded Concept` deep-dive section → maps to
+ *     `details`. `agent_note` has no body section in the v2 shape (Notes is
+ *     user-verbatim only) → it lands in `chatTurns`, the schema's home for agent
+ *     coordination.
+ *  2. **Append, not overwrite.** The console PATCH route stores top-level keys
+ *     verbatim (last-write-wins), so multi-beat `user_quote` calls would clobber
+ *     each other. We read the prior buffer and append, sending the full array.
+ *
+ * `confirmed: true` is set on every agent-authored section because the MCP write
+ * is an explicit commit — the agent only calls this after the conversational
+ * confirm in the /hs-capture four-beat protocol.
+ */
+
+/** Keep only well-formed `{ at, text }` quote entries from a prior buffer. */
+function priorUserQuotes(currentBuffer) {
+  const raw = currentBuffer?.userQuotes ?? currentBuffer?.user_quotes;
+  if (!Array.isArray(raw)) return [];
+  return raw.filter(
+    (q) => q && typeof q === 'object' && typeof q.at === 'string' && typeof q.text === 'string',
+  );
+}
+
+/** Keep only well-formed chat turns from a prior buffer. */
+function priorChatTurns(currentBuffer) {
+  const raw = currentBuffer?.chatTurns ?? currentBuffer?.chat_turns;
+  if (!Array.isArray(raw)) return [];
+  return raw.filter(
+    (t) => t && typeof t === 'object' && typeof t.at === 'string' && typeof t.text === 'string',
+  );
+}
+
+function collapse(value) {
+  return String(value).trim().replace(/\n+/g, ' ');
+}
+
+/**
+ * @param {object} args - { user_quote, agent_note, core_idea, summary (alias: concept), agent_expansion, example, user_stories, kind, done_when, jtbd }
+ * @param {object} currentBuffer - the session's existing content_buffer (may be {})
+ * @param {string} iso - ISO timestamp to stamp on the new entries
+ * @returns {Array<{ path: string, value: unknown }>} canonical structured patches
+ */
+export function buildCaptureBufferPatches(args = {}, currentBuffer = {}, iso) {
+  const patches = [];
+
+  if (args.user_quote !== undefined && collapse(args.user_quote)) {
+    const next = [...priorUserQuotes(currentBuffer), { at: iso, text: collapse(args.user_quote) }];
+    patches.push({ path: 'userQuotes', value: next });
+  }
+
+  if (args.agent_note !== undefined && collapse(args.agent_note)) {
+    const next = [
+      ...priorChatTurns(currentBuffer),
+      { at: iso, who: 'agent', text: collapse(args.agent_note) },
+    ];
+    patches.push({ path: 'chatTurns', value: next });
+  }
+
+  if (args.core_idea !== undefined && String(args.core_idea).trim()) {
+    patches.push({ path: 'coreIdea', value: { at: iso, text: String(args.core_idea).trim(), confirmed: true } });
+  }
+
+  // `summary` is canonical; `concept` is the deprecated alias (HS-EPIC-OED2).
+  const summaryArg = args.summary ?? args.concept;
+  if (summaryArg !== undefined && String(summaryArg).trim()) {
+    patches.push({ path: 'summary', value: { at: iso, text: String(summaryArg).trim(), confirmed: true } });
+  }
+
+  // agent_expansion is the `## Expanded Concept` deep-dive section → buffer.details.
+  if (args.agent_expansion !== undefined && String(args.agent_expansion).trim()) {
+    patches.push({ path: 'details', value: { at: iso, text: String(args.agent_expansion).trim(), confirmed: true } });
+  }
+
+  // example is the `## Example` section (real or AI-illustrative) → buffer.example.
+  if (args.example !== undefined && String(args.example).trim()) {
+    patches.push({ path: 'example', value: { at: iso, text: String(args.example).trim(), confirmed: true } });
+  }
+
+  // user_stories is the `## User Stories` section → buffer.userStories. Root cause
+  // of [[HS-TXBY-DIAG-W32W-heyspex-update-capture-silently-drops]]: this patch was
+  // never emitted, so the tool accepted user_stories, returned success, but the
+  // console content_buffer (and therefore the materialized file) never saw it —
+  // silent data loss, unlike example which has always had this push.
+  if (args.user_stories !== undefined && String(args.user_stories).trim()) {
+    patches.push({
+      path: 'userStories',
+      value: { at: iso, text: String(args.user_stories).trim(), confirmed: true },
+    });
+  }
+
+  // kind re-classifies the capture's frontmatter `kind:` (idea/bug-fix/clip/
+  // reference/question). Simple scalar, not a timestamped section — mirrors
+  // the tool schema's enum contract. Root cause of
+  // [[HS-NR43-DIAG-CAIO-promote-sufficiency-gate-demands-kind]]: the tool
+  // schema already exposed `kind` but this builder never emitted a patch for
+  // it, so the argument was silently dropped and the promote sufficiency gate
+  // (which reads frontmatter.kind) was unsatisfiable through the documented
+  // tool path.
+  if (args.kind !== undefined && String(args.kind).trim()) {
+    patches.push({ path: 'kind', value: String(args.kind).trim() });
+  }
+
+  // done_when is the `## Done When` checklist section → buffer.doneWhen, same
+  // {at,text,confirmed} shape as the other agent-authored sections (example,
+  // user_stories, details) — sibling half of the HS-NR43 fix above.
+  if (args.done_when !== undefined && String(args.done_when).trim()) {
+    patches.push({
+      path: 'doneWhen',
+      value: { at: iso, text: String(args.done_when).trim(), confirmed: true },
+    });
+  }
+
+  // jtbd is the `## JTBD (job-to-be-done)` section → buffer.jtbd, same
+  // {at,text,confirmed} shape as example/userStories/doneWhen. Authored by the
+  // /hs-capture enhancement pass; replaces the interim Expanded-Concept-leading
+  // -block convention (owner ruling 2026-08-23) —
+  // [[HS-TIE7-PR20-TASK-jtbd-job-to-be-done-field-on-captures]]. `jtbd` is
+  // explicitly named in `UPDATE_CAPTURE_ACCEPTED_ARGS` (capture-focus.mjs) so it
+  // is refused by name at the handler's first hop, never silently dropped here
+  // — [[additionalproperties-false-in-an-mcp]].
+  if (args.jtbd !== undefined && String(args.jtbd).trim()) {
+    patches.push({
+      path: 'jtbd',
+      value: { at: iso, text: String(args.jtbd).trim(), confirmed: true },
+    });
+  }
+
+  return patches;
+}