heyspex 0.1.0 → 0.2.1

package/vendor/heyspex-mcp/capture-outbox.mjs

@@ -31,9 +31,11 @@ import {
   renameSync,
   rmSync,
 } from 'node:fs';
-import { basename, join } from 'node:path';
+import { basename, join, isAbsolute, resolve, sep } from 'node:path';
 
 import { buildCaptureBufferPatches } from './capture-buffer-patches.mjs';
+import { assertPathUnderRoot } from '../../scripts/lib/shared-path-helpers.mjs';
+
 
 /**
  * Capture args that carry content worth preserving, in chronological write order.
@@ -87,12 +89,15 @@ export function stashCaptureArgs(vaultRoot, args = {}) {
   for (const kind of OUTBOX_KINDS) {
     const raw = args[kind];
     if (raw !== undefined && String(raw).trim()) {
-      entries.push({ kind, text: String(raw).trim() });
+      // user_quote is stashed verbatim (no trim) so an offline replay keeps the
+      // exact words (HS-TGHU).
+      entries.push({ kind, text: kind === 'user_quote' ? String(raw) : String(raw).trim() });
     }
   }
   if (entries.length === 0) return [];
 
   const dir = captureOutboxDir(vaultRoot);
+  assertPathUnderRoot(vaultRoot, dir, 'capture-outbox write');
   mkdirSync(dir, { recursive: true });
   const stampBase = new Date().toISOString().replace(/[:.]/g, '-');
   const written = [];
@@ -119,7 +124,10 @@ export function listOutbox(vaultRoot) {
       const kind = m ? m[1] : 'user_quote';
       let text = '';
       try {
-        text = readFileSync(join(dir, f), 'utf8').replace(/\n+$/, '');
+        // stash writes text + one newline: strip exactly that one so a verbatim
+        // quote's own trailing whitespace survives the round trip.
+        text = readFileSync(join(dir, f), 'utf8').replace(/\n$/, '');
+        if (kind !== 'user_quote') text = text.replace(/\n+$/, '');
       } catch {
         /* skip unreadable */
       }
@@ -156,6 +164,7 @@ export function removeOutboxEntry(path) {
 export function quarantineOutboxEntry(vaultRoot, entryPath, metadata = {}) {
   try {
     const qdir = captureOutboxQuarantineDir(vaultRoot);
+    assertPathUnderRoot(vaultRoot, qdir, 'capture-outbox write');
     mkdirSync(qdir, { recursive: true });
     const name = basename(entryPath);
     const dest = join(qdir, name);
@@ -231,8 +240,9 @@ export function quarantineCount(vaultRoot) {
  * @returns {{path: string, value: unknown} | null}
  */
 export function outboxEntryToPatch(entry, iso, currentBuffer = {}) {
-  const text = String(entry.text ?? '').trim();
-  if (!text) return null;
+  const text =
+    entry.kind === 'user_quote' ? String(entry.text ?? '') : String(entry.text ?? '').trim();
+  if (!text.trim()) return null;
   if (!OUTBOX_KINDS.includes(entry.kind)) return null;
   const patches = buildCaptureBufferPatches({ [entry.kind]: text }, currentBuffer, iso);
   return patches[0] ?? null;

package/vendor/heyspex-mcp/capture-sources.mjs

@@ -0,0 +1,195 @@
+/**
+ * `sources` argument of `heyspex_update_capture`: links, original text
+ * documents and binary files saved WITH a capture
+ * ([[HS-9K12-ST07-TASK-heyspex-update-capture-sources-argument]], epic
+ * [[HS-WF23-ST07-EPIC-verbatim-words-and-source-files]]; owner 2026-10-10:
+ * "files/original docs etc saved as source").
+ *
+ * Entry forms (exactly one content key per entry):
+ *   { url, title? }                              -> link source (`## Source Material`, grain link)
+ *   { name, text, mime?, origin? }               -> original TEXT document, stored byte-for-byte
+ *   { name, content_base64, mime?, origin? }     -> binary file
+ *   { path, name?, mime? }                       -> the MCP reads the file at `path` itself (so the
+ *                                                  agent never has to pass the content through its context)
+ *
+ * Caps mirror the console (`spex-console/src/lib/capture-source-files.ts`),
+ * which re-validates server-side: 256 KiB per file, 1 MiB total, 20 files.
+ * Oversize / malformed entries are REFUSED by name; nothing is truncated.
+ */
+import { createHash } from 'node:crypto';
+import { readFileSync, statSync } from 'node:fs';
+import { basename } from 'node:path';
+
+export const SOURCE_FILE_MAX_BYTES = 256 * 1024;
+export const SOURCE_FILES_MAX_TOTAL_BYTES = 1024 * 1024;
+export const SOURCE_FILES_MAX_COUNT = 20;
+const BASE64_RE = /^[A-Za-z0-9+/]*={0,2}$/;
+
+/** Reduce a name to one safe path segment (mirrors the console). */
+export function sanitizeSourceFileName(raw) {
+  const segs = String(raw).split(/[\\/]/);
+  // eslint-disable-next-line no-control-regex
+  return (segs[segs.length - 1] ?? '').replace(/[\u0000-\u001f\u007f]/g, '').trim().slice(0, 200);
+}
+
+function defaultMime(name, encoding) {
+  if (encoding === 'base64') return 'application/octet-stream';
+  return /\.(md|markdown)$/i.test(name) ? 'text/markdown' : 'text/plain';
+}
+
+function fileFromBuffer(buf, { name, mime, origin, iso, encoding, content }) {
+  if (buf.length === 0) return { error: `source "${name}" is empty` };
+  if (buf.length > SOURCE_FILE_MAX_BYTES) {
+    return {
+      error: `source "${name}" is ${buf.length} bytes; the inline source-file cap is ${SOURCE_FILE_MAX_BYTES} bytes. Attach a smaller file or link it by url.`,
+    };
+  }
+  return {
+    file: {
+      name,
+      mime: mime || defaultMime(name, encoding),
+      bytes: buf.length,
+      sha256: createHash('sha256').update(buf).digest('hex'),
+      at: iso,
+      encoding,
+      content,
+      ...(origin ? { origin } : {}),
+    },
+  };
+}
+
+/** Decode bytes as UTF-8 text only when that is lossless; otherwise treat as binary. */
+function bufferToStored(buf) {
+  if (!buf.includes(0)) {
+    const text = buf.toString('utf8');
+    if (Buffer.from(text, 'utf8').equals(buf)) return { encoding: 'utf8', content: text };
+  }
+  return { encoding: 'base64', content: buf.toString('base64') };
+}
+
+/**
+ * Validate + normalize the `sources` argument.
+ * @returns {{ ok: true, links: object[], files: object[] } | { ok: false, error: object }}
+ */
+export function normalizeCaptureSources(sources, iso, deps = {}) {
+  const read = deps.readFile ?? ((p) => readFileSync(p));
+  const size = deps.fileSize ?? ((p) => statSync(p).size);
+  const refuse = (message, index) => ({
+    ok: false,
+    error: {
+      error: 'INVALID_SOURCES',
+      message: `${message} NOTHING WAS WRITTEN.`,
+      field: `sources[${index}]`,
+    },
+  });
+  if (!Array.isArray(sources)) return refuse('sources must be an array.', 0);
+  if (sources.length > SOURCE_FILES_MAX_COUNT) {
+    return refuse(`sources cannot exceed ${SOURCE_FILES_MAX_COUNT} entries.`, 0);
+  }
+  const links = [];
+  const files = [];
+  let total = 0;
+  for (let i = 0; i < sources.length; i += 1) {
+    const s = sources[i];
+    if (!s || typeof s !== 'object') return refuse(`sources[${i}] must be an object.`, i);
+    if (typeof s.url === 'string' && s.url.trim()) {
+      if (!/^https?:\/\//i.test(s.url.trim())) {
+        return refuse(`sources[${i}].url must be an http(s) URL.`, i);
+      }
+      links.push({
+        url: s.url.trim(),
+        ...(typeof s.title === 'string' && s.title.trim() ? { title: s.title.trim() } : {}),
+        added_at: iso,
+        grain: 'link',
+      });
+      continue;
+    }
+    let name = typeof s.name === 'string' ? sanitizeSourceFileName(s.name) : '';
+    const mime = typeof s.mime === 'string' && s.mime.trim() ? s.mime.trim().slice(0, 100) : '';
+    const origin =
+      typeof s.origin === 'string' && s.origin.trim() ? s.origin.trim().slice(0, 500) : '';
+    let r;
+    if (typeof s.path === 'string' && s.path.trim()) {
+      const p = s.path.trim();
+      let sz;
+      try {
+        sz = size(p);
+      } catch (e) {
+        return refuse(`sources[${i}].path could not be read (${e.code || e.message}).`, i);
+      }
+      if (sz > SOURCE_FILE_MAX_BYTES) {
+        return refuse(
+          `sources[${i}] (${basename(p)}) is ${sz} bytes; the inline source-file cap is ${SOURCE_FILE_MAX_BYTES} bytes.`,
+          i,
+        );
+      }
+      let buf;
+      try {
+        buf = read(p);
+      } catch (e) {
+        return refuse(`sources[${i}].path could not be read (${e.code || e.message}).`, i);
+      }
+      name = name || sanitizeSourceFileName(basename(p));
+      if (!name) return refuse(`sources[${i}] needs a name.`, i);
+      r = fileFromBuffer(buf, { name, mime, origin: origin || p, iso, ...bufferToStored(buf) });
+    } else if (typeof s.text === 'string') {
+      if (!name) return refuse(`sources[${i}].name is required for a text document.`, i);
+      r = fileFromBuffer(Buffer.from(s.text, 'utf8'), {
+        name,
+        mime,
+        origin,
+        iso,
+        encoding: 'utf8',
+        content: s.text,
+      });
+    } else if (typeof s.content_base64 === 'string') {
+      if (!name) return refuse(`sources[${i}].name is required for a binary file.`, i);
+      const b64 = s.content_base64.replace(/\s+/g, '');
+      if (b64.length % 4 !== 0 || !BASE64_RE.test(b64)) {
+        return refuse(`sources[${i}].content_base64 is not valid base64.`, i);
+      }
+      r = fileFromBuffer(Buffer.from(b64, 'base64'), {
+        name,
+        mime,
+        origin,
+        iso,
+        encoding: 'base64',
+        content: b64,
+      });
+    } else {
+      return refuse(`sources[${i}] needs one of url, path, text (+name) or content_base64 (+name).`, i);
+    }
+    if (r.error) return refuse(r.error, i);
+    total += r.file.bytes;
+    files.push(r.file);
+  }
+  if (total > SOURCE_FILES_MAX_TOTAL_BYTES) {
+    return refuse(
+      `sources total ${total} bytes exceeds the ${SOURCE_FILES_MAX_TOTAL_BYTES} byte per-capture cap.`,
+      0,
+    );
+  }
+  return { ok: true, links, files };
+}
+
+/** Patches for validated sources: prior-plus-new full array (old consoles) + append hint (new consoles). */
+export function buildSourcesPatches(normalized, currentBuffer = {}) {
+  const patches = [];
+  if (normalized.files.length > 0) {
+    const prior = Array.isArray(currentBuffer?.sourceFiles) ? currentBuffer.sourceFiles : [];
+    const fresh = normalized.files.filter(
+      (f) => !prior.some((p) => p && p.name === f.name && p.sha256 === f.sha256),
+    );
+    if (fresh.length > 0) {
+      patches.push({ path: 'sourceFiles', value: [...prior, ...fresh], op: 'append', items: fresh });
+    }
+  }
+  if (normalized.links.length > 0) {
+    const prior = Array.isArray(currentBuffer?.sources) ? currentBuffer.sources : [];
+    const fresh = normalized.links.filter((l) => !prior.some((p) => p && p.url === l.url));
+    if (fresh.length > 0) {
+      patches.push({ path: 'sources', value: [...prior, ...fresh], op: 'append', items: fresh });
+    }
+  }
+  return patches;
+}