@khanglvm/relay 0.13.6 → 0.13.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@khanglvm/relay",
-  "version": "0.13.6",
+  "version": "0.13.7",
   "description": "Question boards with rich blocks (markdown, charts, mermaid, tables, code, diffs, video, sandboxed HTML), clickable local file-links, and element-level annotations for AI coding agents (Claude Code, Codex, …): ask users structured questions, present interactive visuals, collect inline comments, read answers as JSON — in a local browser board OR rendered INLINE inside the Claude & Codex apps as an MCP App (SEP-1865).",
   "keywords": [
     "ai-agents",

package/src/cli.js

@@ -4,7 +4,7 @@ import os from 'node:os';
 import { spawn, spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { CliError, sleep, pollFor } from './util.js';
-import { normalizeSpec, questionFromInline, SPEC_SCHEMA } from './spec.js';
+import { assertSpecReady, normalizeSpec, questionFromInline, SPEC_SCHEMA } from './spec.js';
 import {
   createBoard,
   loadBoard,
@@ -197,6 +197,7 @@ function readFileOrThrow(p) {
 }
 
 async function runOrDetach(record, args) {
+  await assertSpecReady(record.spec);
   const timeoutSec = args.timeout !== undefined ? Math.max(0, Number.parseInt(args.timeout, 10) || 0) : 1800;
   const port = args.port !== undefined ? Number.parseInt(args.port, 10) || 0 : 0;
   const open = args.open !== false;
@@ -244,6 +245,7 @@ async function runOrDetach(record, args) {
 async function cmdAsk(args, mode) {
   const raw = await resolveSpecInput(args, mode);
   const spec = normalizeSpec(raw);
+  await assertSpecReady(spec);
   const record = createBoard(spec);
   return runOrDetach(record, args);
 }
@@ -275,6 +277,7 @@ async function cmdDiff(rest) {
   }
   const title = args.title || ('git diff' + (gitArgs.length ? ' ' + gitArgs.join(' ') : ''));
   const spec = normalizeSpec({ title, blocks: [{ type: 'diff', diff, view: args.split ? 'split' : 'unified' }] });
+  await assertSpecReady(spec);
   const record = createBoard(spec);
   return runOrDetach(record, args);
 }
@@ -299,6 +302,7 @@ async function cmdView(args) {
   raw.title = args.title || (multi ? `${files.length} files` : path.basename(files[0]));
   raw.submitLabel = args.submitLabel || 'Done';
   const spec = normalizeSpec(raw); // reads + validates each file, clear error if unreadable
+  await assertSpecReady(spec);
   const record = createBoard(spec);
   return runOrDetach(record, args);
 }
@@ -445,6 +449,7 @@ async function cmdUpdate(args) {
   } else {
     throw new CliError('update needs --file <spec.json>, --title, --intro, or -q "...".', 4);
   }
+  await assertSpecReady(spec);
 
   let res;
   try {

package/src/mcp.js

@@ -19,7 +19,7 @@ import path from 'node:path';
 import http from 'node:http';
 import crypto from 'node:crypto';
 import { fileURLToPath } from 'node:url';
-import { normalizeSpec, SPEC_SCHEMA } from './spec.js';
+import { assertSpecReady, normalizeSpec, SPEC_SCHEMA } from './spec.js';
 import { CliError } from './util.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -143,7 +143,7 @@ function resourceMeta() {
 }
 
 // ---------- request routing ----------
-function buildResult(method, params, clientProtocol) {
+async function buildResult(method, params, clientProtocol) {
   switch (method) {
     case 'initialize':
       return {
@@ -202,7 +202,7 @@ function readResource(params) {
 // ui/update-model-context as a best-effort context sync). Spec errors come back
 // as an isError tool result (not a protocol error) so the model can see and fix
 // them.
-function callTool(params) {
+async function callTool(params) {
   const name = params && params.name;
   if (name !== 'relay_ask' && name !== 'relay_show') {
     return { content: [{ type: 'text', text: 'unknown tool: ' + name }], isError: true };
@@ -211,6 +211,7 @@ function callTool(params) {
   let spec;
   try {
     spec = normalizeSpec(args);
+    await assertSpecReady(spec);
   } catch (err) {
     const msg = err instanceof CliError ? err.message : String((err && err.message) || err);
     return { content: [{ type: 'text', text: 'relay: invalid board spec — ' + msg }], isError: true };
@@ -265,7 +266,7 @@ export function runMcp() {
     catch { stdoutOpen = false; }
   };
 
-  function handleLine(line) {
+  async function handleLine(line) {
     let msg;
     try { msg = JSON.parse(line); } catch {
       send({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'parse error' } });
@@ -278,7 +279,7 @@ export function runMcp() {
       if (typeof m.method !== 'string') continue; // a response to us — we issue none
       let result;
       try {
-        result = buildResult(m.method, m.params || {});
+        result = await buildResult(m.method, m.params || {});
       } catch (err) {
         if (isRequest) {
           send({ jsonrpc: '2.0', id: m.id, error: { code: err.code || -32603, message: err.message || String(err) } });
@@ -290,6 +291,7 @@ export function runMcp() {
   }
 
   let buf = '';
+  let queue = Promise.resolve();
   process.stdin.setEncoding('utf8');
   process.stdin.on('data', (chunk) => {
     buf += chunk;
@@ -298,7 +300,7 @@ export function runMcp() {
       const line = buf.slice(0, idx);
       buf = buf.slice(idx + 1);
       const trimmed = line.trim();
-      if (trimmed) handleLine(trimmed);
+      if (trimmed) queue = queue.then(() => handleLine(trimmed)).catch(() => {});
     }
   });
 
@@ -406,7 +408,7 @@ export function runMcpHttp({ port = DEFAULT_HTTP_PORT, host = '127.0.0.1', token
     let body = '';
     let aborted = false;
     req.on('data', (c) => { body += c; if (body.length > MAX_BODY) { aborted = true; req.destroy(); } });
-    req.on('end', () => {
+    req.on('end', async () => {
       if (aborted) { res.writeHead(413, base); return res.end(); }
       let msg;
       try { msg = JSON.parse(body); } catch {
@@ -421,7 +423,7 @@ export function runMcpHttp({ port = DEFAULT_HTTP_PORT, host = '127.0.0.1', token
         if (m.method === 'initialize') isInit = true;
         const isRequest = m.id !== undefined && m.id !== null;
         try {
-          const result = buildResult(m.method, m.params || {});
+          const result = await buildResult(m.method, m.params || {});
           if (isRequest) responses.push({ jsonrpc: '2.0', id: m.id, result });
         } catch (err) {
           if (isRequest) responses.push({ jsonrpc: '2.0', id: m.id, error: { code: err.code || -32603, message: err.message || String(err) } });

package/src/server.js

@@ -7,6 +7,7 @@ import { spawn } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { loadBoard, saveBoard, saveRunning, removeRunning, loadPref, savePref } from './store.js';
 import { openUrl } from './open.js';
+import { assertSpecReady } from './spec.js';
 
 const UI_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), 'ui');
 const PKG_ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), '..');
@@ -592,6 +593,11 @@ export async function runBoard({ id, port = 0, open = true, timeoutSec = 1800, q
             !Array.isArray(next.questions) || !Array.isArray(next.blocks)) {
           return sendJson(res, 400, { error: 'spec must be an object with questions[] and blocks[] arrays' });
         }
+        try {
+          await assertSpecReady(next);
+        } catch (err) {
+          return sendJson(res, 400, { error: err && err.message ? err.message : String(err) });
+        }
         record.spec = next;
         rev++;
         saveBoard(record);

package/src/spec.js

@@ -1,5 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import vm from 'node:vm';
+import { fileURLToPath } from 'node:url';
 import { CliError } from './util.js';
 
 export const TYPES = ['single', 'multi', 'yesno', 'text', 'textarea', 'scale', 'color', 'rank', 'checklist', 'allocate'];
@@ -65,6 +67,9 @@ const IMAGE_MIMES = {
   webp: 'image/webp', svg: 'image/svg+xml', avif: 'image/avif', bmp: 'image/bmp',
 };
 const IMAGE_MAX_BYTES = 8 * 1024 * 1024;
+const VENDOR_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'vendor');
+
+let mermaidValidatorPromise = null;
 
 const asStr = (v) => (typeof v === 'string' ? v : v == null ? '' : String(v));
 
@@ -222,6 +227,99 @@ function parseVideoEmbed(src) {
   return null;
 }
 
+function compactError(err) {
+  const raw = err && (err.str || err.message) ? (err.str || err.message) : String(err || 'unknown error');
+  const msg = String(raw).replace(/\s+/g, ' ').trim();
+  return msg.length > 500 ? msg.slice(0, 497) + '...' : msg;
+}
+
+async function mermaidValidator() {
+  if (mermaidValidatorPromise) return mermaidValidatorPromise;
+  mermaidValidatorPromise = (async () => {
+    const sourcePath = path.join(VENDOR_DIR, 'mermaid.min.js');
+    let source;
+    try {
+      source = fs.readFileSync(sourcePath, 'utf8');
+    } catch {
+      throw new CliError('mermaid blocks need the vendored parser (vendor/mermaid.min.js is missing).');
+    }
+    const quietConsole = { log() {}, info() {}, warn() {}, error() {}, debug() {} };
+    const context = {
+      console: quietConsole,
+      setTimeout,
+      clearTimeout,
+    };
+    context.globalThis = context;
+    context.window = { addEventListener() {} };
+    vm.createContext(context);
+    try {
+      vm.runInContext(source, context, { filename: sourcePath });
+    } catch (err) {
+      throw new CliError(`could not load mermaid parser: ${compactError(err)}`);
+    }
+    if (!context.mermaid || typeof context.mermaid.parse !== 'function') {
+      throw new CliError('could not load mermaid parser: vendor/mermaid.min.js did not expose mermaid.parse.');
+    }
+    try {
+      context.mermaid.initialize({
+        startOnLoad: false,
+        securityLevel: 'strict',
+        suppressErrorRendering: true,
+      });
+    } catch {
+      // Some Mermaid versions dislike repeated initialize calls; parse below is
+      // the real readiness gate.
+    }
+    return context.mermaid;
+  })();
+  return mermaidValidatorPromise;
+}
+
+async function assertMermaidSyntax(code, where) {
+  const mermaid = await mermaidValidator();
+  try {
+    const parsed = mermaid.parse(code);
+    if (parsed && typeof parsed.then === 'function') await parsed;
+  } catch (err) {
+    throw new CliError(`${where}: invalid mermaid syntax — ${compactError(err)}`);
+  }
+}
+
+function* allBlocks(spec) {
+  const boardBlocks = Array.isArray(spec.blocks) ? spec.blocks : [];
+  for (let i = 0; i < boardBlocks.length; i++) {
+    yield { block: boardBlocks[i], where: `board.blocks[${i}]${boardBlocks[i]?.id ? ` (${boardBlocks[i].id})` : ''}` };
+  }
+  const questions = Array.isArray(spec.questions) ? spec.questions : [];
+  for (let qi = 0; qi < questions.length; qi++) {
+    const q = questions[qi] || {};
+    const qBlocks = Array.isArray(q.blocks) ? q.blocks : [];
+    for (let bi = 0; bi < qBlocks.length; bi++) {
+      yield { block: qBlocks[bi], where: `questions[${qi}].blocks[${bi}]${qBlocks[bi]?.id ? ` (${qBlocks[bi].id})` : ''}` };
+    }
+    const opts = Array.isArray(q.options) ? q.options : [];
+    for (let oi = 0; oi < opts.length; oi++) {
+      const oBlocks = Array.isArray(opts[oi]?.blocks) ? opts[oi].blocks : [];
+      for (let bi = 0; bi < oBlocks.length; bi++) {
+        yield {
+          block: oBlocks[bi],
+          where: `questions[${qi}].options[${oi}].blocks[${bi}]${oBlocks[bi]?.id ? ` (${oBlocks[bi].id})` : ''}`,
+        };
+      }
+    }
+  }
+}
+
+export async function assertSpecReady(spec) {
+  if (!spec || typeof spec !== 'object') return spec;
+  if (spec.__relayReady === true) return spec;
+  for (const { block, where } of allBlocks(spec)) {
+    if (block && block.type === 'mermaid') await assertMermaidSyntax(block.code || '', where);
+  }
+  Object.defineProperty(spec, '__relayReady', { value: true, enumerable: false, configurable: true });
+  return spec;
+}
+
 // Normalizes one block object. `id` is the already-assigned block id.
 // Returns the normalized block (with a guaranteed string `type` + `id`).
 function normalizeBlock(rawBlock, id, cwd, where) {