slidemind 0.1.6 → 0.1.8

package/src/builders/gate-server.mjs

@@ -0,0 +1,223 @@
+// Shared low-level primitives for the CLI's blocking review gates (the spatial
+// preview gate in review.mjs and the plan sign-off gate in plan.mjs).
+//
+// These were lifted out of review.mjs so both gates share one implementation of
+// the MIME table, the traversal-guarded static responder, the decision promise +
+// timeout wrapper, and the port + tab-reuse machinery: a deterministic per-deck
+// per-gate port (so a tab left waiting from the previous round reconnects to the
+// same URL), a bind that never fails on a taken port (falls back to an
+// OS-assigned one with a stderr notice), and a heartbeat endpoint each gate
+// serves under its own service marker so a waiting tab only ever reloads into
+// its OWN gate's next round — never into the other gate or a foreign app.
+
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+// Tab-reuse timing contract, shared by both gates and injected into their
+// overlays as CFG.pollMs / CFG.pollTtlMs:
+//   GRACE_MS  > POLL_MS so a waiting tab always lands one poll inside the
+//              open-browser grace window;
+//   POLL_TTL_MS > the gates' 30-min decision timeout so an abandoned tab stops
+//              polling only after the server side has certainly given up.
+export const GRACE_MS = 1500;
+export const POLL_MS = 1000;
+export const POLL_TTL_MS = 35 * 60 * 1000;
+
+const PORT_BASE = 40000;
+const PORT_SPAN = 1000; // preferred ports live in 40000..40999
+
+// Extension → content-type table (lifted verbatim from review.mjs).
+export const MIME = {
+  ".html": "text/html; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".js": "text/javascript; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".svg": "image/svg+xml",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".webp": "image/webp",
+  ".woff": "font/woff",
+  ".woff2": "font/woff2",
+};
+
+// Traversal-guarded static responder, generalized to MULTIPLE roots. `pathname`
+// is expected already URL-decoded (review.mjs decodes once at the top of its
+// request handler and passes the decoded value in). Each root is tried in order:
+// the pathname is resolved within the root and required to stay inside it (via
+// path.sep so the boundary check is correct on Windows). The first root that
+// holds a matching file serves it (200 + MIME, default application/octet-stream)
+// and returns true. If no root matches — file missing everywhere, or a traversal
+// attempt escaped every root — returns false WITHOUT writing a response, leaving
+// the caller to send its own 404.
+export function serveStaticFile({ roots, pathname, res }) {
+  const rel = String(pathname).replace(/^\/+/, "");
+  for (const root of roots || []) {
+    if (!root) continue;
+    const base = path.resolve(root);
+    const resolved = path.resolve(base, rel);
+    if (resolved !== base && !resolved.startsWith(base + path.sep)) {
+      continue; // escaped this root — a later root might still legitimately match
+    }
+    let data;
+    try {
+      const st = fs.statSync(resolved);
+      if (!st.isFile()) continue;
+      data = fs.readFileSync(resolved);
+    } catch {
+      continue; // missing here — try the next root
+    }
+    const ext = path.extname(resolved).toLowerCase();
+    res.writeHead(200, { "Content-Type": MIME[ext] || "application/octet-stream" });
+    res.end(data);
+    return true;
+  }
+  return false;
+}
+
+// The decision promise + timeout wrapper both gates block on. `resolve(value)`
+// settles the internal promise once (a Promise never re-settles, so repeat calls
+// are no-ops). `waitForDecision({ timeoutMs })` returns the promise directly when
+// no/falsy timeout is given, otherwise races it against a setTimeout that rejects
+// with `timeoutMessage`. The timer is cleared the moment the decision wins so the
+// process can exit instead of being held open by a pending timeout.
+//
+// A timeout rejection carries `code: "GATE_TIMEOUT"` so gates can tell "the user
+// never answered" (an expected outcome with its own DECISION: pending contract)
+// apart from a real failure.
+export function createDecisionGate({
+  timeoutMessage = "review timed out — no decision received",
+} = {}) {
+  let resolveDecision;
+  const decisionPromise = new Promise((res) => {
+    resolveDecision = res;
+  });
+  return {
+    resolve(value) {
+      resolveDecision(value);
+    },
+    waitForDecision({ timeoutMs } = {}) {
+      if (!timeoutMs) return decisionPromise;
+      return new Promise((resolve, reject) => {
+        const t = setTimeout(() => {
+          const err = new Error(timeoutMessage);
+          err.code = "GATE_TIMEOUT";
+          reject(err);
+        }, timeoutMs);
+        decisionPromise.then((d) => {
+          clearTimeout(t);
+          resolve(d);
+        });
+      });
+    },
+  };
+}
+
+// Deterministic per-deck, per-gate preferred port so a tab left waiting from
+// the previous round can reconnect to the same URL. Stateless — derived purely
+// from the resolved deck path plus the gate name. The gate name is the salt:
+// the preview and plan gates of the SAME deck get independent ports, so their
+// waiting tabs can never sit on each other's URL.
+export function preferredGatePort(deckDir, gateName) {
+  const key = `${path.resolve(deckDir)}\u0000${gateName}`;
+  const n = crypto.createHash("sha1").update(key).digest().readUInt32BE(0);
+  return PORT_BASE + (n % PORT_SPAN);
+}
+
+// Bind `server` to `port`, falling back to an OS-assigned port when the
+// preferred one is taken or blocked. An http.Server is reusable after a failed
+// listen, so we retry listen(0) on the SAME instance. onFallback runs once,
+// before the retry, so the caller can warn on stderr. EADDRINUSE: port already
+// bound. EACCES: Windows excluded/reserved port range. Anything else (or a
+// fallback-attempt failure) is a real error and rejects.
+export function listenWithFallback(server, port, host, onFallback) {
+  return new Promise((resolve, reject) => {
+    const onFirstError = (err) => {
+      server.removeListener("listening", onFirstListening);
+      if (err && (err.code === "EADDRINUSE" || err.code === "EACCES")) {
+        onFallback(port, err);
+        const onFallbackError = (err2) => {
+          server.removeListener("listening", onFallbackListening);
+          reject(err2);
+        };
+        const onFallbackListening = () => {
+          server.removeListener("error", onFallbackError);
+          resolve();
+        };
+        server.once("error", onFallbackError);
+        server.once("listening", onFallbackListening);
+        server.listen(0, host);
+        return;
+      }
+      reject(err);
+    };
+    const onFirstListening = () => {
+      server.removeListener("error", onFirstError);
+      resolve();
+    };
+    server.once("error", onFirstError);
+    server.once("listening", onFirstListening);
+    server.listen(port, host);
+  });
+}
+
+// Per-run heartbeat state for one gate server. The gate mounts `respond` under
+// its own heartbeat path; a waiting tab polls it and reloads only when BOTH the
+// service marker matches its own gate (a foreign app or the other gate on this
+// port must never trigger a reload) AND the round nonce differs from the one it
+// was served with (same nonce = this run's own orphan — never self-reload).
+// `waitForHeartbeat(ms)` is the server side of the open-browser grace window.
+export function createHeartbeat({ service }) {
+  const round = crypto.randomUUID();
+  let seen = false;
+  const waiters = [];
+  return {
+    round,
+    respond(res) {
+      seen = true;
+      while (waiters.length) waiters.shift()();
+      res.writeHead(200, { "Content-Type": MIME[".json"], "Cache-Control": "no-store" });
+      res.end(JSON.stringify({ ok: true, service, round }));
+    },
+    waitForHeartbeat(ms) {
+      if (seen) return Promise.resolve(true);
+      return new Promise((resolve) => {
+        const t = setTimeout(() => resolve(false), ms);
+        waiters.push(() => {
+          clearTimeout(t);
+          resolve(true);
+        });
+      });
+    },
+  };
+}
+
+// Print the gate URL, then decide whether to open a browser. If a tab left
+// waiting from a previous comments round pings the gate's heartbeat within the
+// grace window, reuse it (it reloads itself) instead of opening a duplicate.
+// Returns true if an existing tab was reused. `open` is required — gates pass
+// their browser opener so this module stays dependency-light and tests inject
+// a fake. The message strings are per-gate; defaults speak the preview gate's.
+export async function serveAndOpen(server, {
+  open,
+  graceMs = GRACE_MS,
+  readyLabel = "Preview review",
+  reuseNoun = "review tab",
+  openedLine = "Opened your browser — leave comments or approve, then return here.",
+  waitLine = null,
+} = {}) {
+  process.stderr.write(`${readyLabel} ready at ${server.url}\n`); // URL always printed first
+  const reused = await server.waitForHeartbeat(graceMs);
+  if (reused) {
+    process.stderr.write(`Reusing your open ${reuseNoun} — no new browser window.\n`);
+  } else {
+    open(server.url);
+    process.stderr.write(`${openedLine}\n`);
+  }
+  // Spoken to the AGENT running this command: blocking here is the designed
+  // behavior, not a hang — don't kill the call because it sits quiet.
+  if (waitLine) process.stderr.write(`${waitLine}\n`);
+  return reused;
+}

package/src/builders/lint.mjs

@@ -76,8 +76,8 @@ function resolveEngine(deckDir) {
 export async function lintSlidesOrThrow({ deckDir, slideFiles, layoutSources }) {
   const { enginePath, version, primitives } = resolveEngine(deckDir);
 
-  // `?v=` busts Node's per-process module cache so a long-lived process (the
-  // MCP server) picks up a refreshed engine at the same path.
+  // `?v=` busts Node's per-process module cache so a re-import picks up a
+  // refreshed engine at the same path after a bundle sync.
   const engine = await import(
     `${pathToFileURL(enginePath).href}?v=${encodeURIComponent(version)}`
   );

package/src/builders/plan-md.mjs

@@ -0,0 +1,216 @@
+// A tiny, self-contained markdown → HTML renderer for the constrained subset an
+// agent-authored plan.md uses. Deliberately NO CDN and no dependencies: the plan
+// gate ships this exact source into the browser (exports stripped, exposed as
+// window.__SLIDEMIND_RENDER_MD__) so the editor's live preview renders with the
+// SAME renderer as the served page. Every block still carries its on-disk source
+// line/kind/section stamps — cheap, tested metadata for tooling.
+//
+// Supported blocks: ATX headings (#..######), blank-line-separated paragraphs,
+// unordered (-/*) and ordered (1.) lists with each <li> stamped individually,
+// > blockquotes, ``` fenced code, and simple pipe tables. Inline: **bold**,
+// *italic*, `code`. All text is HTML-escaped BEFORE inline formatting is applied
+// (defense in depth — the content is model/user-authored). Anything unrecognized
+// degrades to a paragraph. One level of nesting only (nested lists may flatten).
+
+function escapeHtml(s) {
+  return String(s)
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
+}
+
+// For an HTML attribute value: escape as text, then also quotes.
+function escapeAttr(s) {
+  return escapeHtml(s).replace(/"/g, "&quot;");
+}
+
+// Escape first, THEN apply inline formatting. Code spans are handled before
+// bold/italic so their contents aren't re-interpreted; bold before italic so a
+// **run** isn't half-consumed by the single-* rule.
+function renderInline(text) {
+  let s = escapeHtml(text);
+  s = s.replace(/`([^`]+)`/g, (_m, c) => `<code>${c}</code>`);
+  s = s.replace(/\*\*([^*]+)\*\*/g, "<strong>$1</strong>");
+  s = s.replace(/\*([^*]+)\*/g, "<em>$1</em>");
+  return s;
+}
+
+// Plain-text form of a heading (markers stripped) for the breadcrumb attribute.
+function stripInlineMarkers(text) {
+  return String(text)
+    .replace(/`([^`]+)`/g, "$1")
+    .replace(/\*\*([^*]+)\*\*/g, "$1")
+    .replace(/\*([^*]+)\*/g, "$1")
+    .trim();
+}
+
+function isListItem(line) {
+  return /^\s*(?:[-*]\s+|\d+[.)]\s+)/.test(line);
+}
+
+// A table separator row: pipes and dashes only, optional alignment colons.
+function isTableSeparator(line) {
+  const s = line.trim();
+  if (!s.includes("-")) return false;
+  return /^\|?\s*:?-+:?\s*(\|\s*:?-+:?\s*)*\|?$/.test(s);
+}
+
+function splitTableRow(line) {
+  let s = line.trim();
+  if (s.startsWith("|")) s = s.slice(1);
+  if (s.endsWith("|")) s = s.slice(0, -1);
+  return s.split("|").map((c) => c.trim());
+}
+
+// The three stamp attributes carried by every block.
+function stamp(absLine, kind, section) {
+  return (
+    ` data-md-line="${absLine}" data-md-kind="${kind}"` +
+    ` data-md-section="${escapeAttr(section)}"`
+  );
+}
+
+export function renderPlanMarkdown(body, { lineOffset = 0 } = {}) {
+  const lines = String(body).split("\n");
+  const out = [];
+  let section = ""; // nearest preceding heading text (breadcrumb)
+  let i = 0;
+  // idx is 0-based into `lines`; local line number is idx+1, absolute adds the
+  // frontmatter offset.
+  const abs = (idx) => lineOffset + idx + 1;
+
+  while (i < lines.length) {
+    const line = lines[i];
+
+    if (/^\s*$/.test(line)) {
+      i++;
+      continue;
+    }
+
+    // Fenced code — stamped on the opening fence, contents escaped verbatim.
+    if (/^\s*```/.test(line)) {
+      const startIdx = i;
+      i++;
+      const code = [];
+      while (i < lines.length && !/^\s*```\s*$/.test(lines[i])) {
+        code.push(lines[i]);
+        i++;
+      }
+      if (i < lines.length) i++; // consume the closing fence
+      out.push(
+        `<pre${stamp(abs(startIdx), "code", section)}><code>` +
+          escapeHtml(code.join("\n")) +
+          `</code></pre>`,
+      );
+      continue;
+    }
+
+    // ATX heading.
+    const heading = line.match(/^(#{1,6})\s+(.*)$/);
+    if (heading) {
+      const level = heading[1].length;
+      const raw = heading[2].replace(/\s+#+\s*$/, "").trim(); // drop optional closing #
+      section = stripInlineMarkers(raw);
+      const kind = "h" + level;
+      out.push(
+        `<${kind}${stamp(abs(i), kind, section)}>` +
+          renderInline(raw) +
+          `</${kind}>`,
+      );
+      i++;
+      continue;
+    }
+
+    // Pipe table — header row followed by a separator row.
+    if (
+      line.includes("|") &&
+      i + 1 < lines.length &&
+      isTableSeparator(lines[i + 1])
+    ) {
+      const headerIdx = i;
+      const header = splitTableRow(line);
+      i += 2; // skip header + separator
+      const rows = [];
+      while (i < lines.length && !/^\s*$/.test(lines[i]) && lines[i].includes("|")) {
+        rows.push(splitTableRow(lines[i]));
+        i++;
+      }
+      let html = `<table${stamp(abs(headerIdx), "table", section)}>`;
+      html +=
+        "<thead><tr>" +
+        header.map((c) => `<th>${renderInline(c)}</th>`).join("") +
+        "</tr></thead>";
+      html +=
+        "<tbody>" +
+        rows
+          .map(
+            (r) => "<tr>" + r.map((c) => `<td>${renderInline(c)}</td>`).join("") + "</tr>",
+          )
+          .join("") +
+        "</tbody>";
+      html += "</table>";
+      out.push(html);
+      continue;
+    }
+
+    // Blockquote — consecutive > lines, joined.
+    if (/^\s*>/.test(line)) {
+      const startIdx = i;
+      const quote = [];
+      while (i < lines.length && /^\s*>/.test(lines[i])) {
+        quote.push(lines[i].replace(/^\s*>\s?/, ""));
+        i++;
+      }
+      out.push(
+        `<blockquote${stamp(abs(startIdx), "blockquote", section)}>` +
+          renderInline(quote.join(" ")) +
+          `</blockquote>`,
+      );
+      continue;
+    }
+
+    // List — each <li> stamped with its own line; the wrapper is unstamped.
+    if (isListItem(line)) {
+      const ordered = /^\s*\d+[.)]\s+/.test(line);
+      const tag = ordered ? "ol" : "ul";
+      const items = [];
+      while (i < lines.length && isListItem(lines[i])) {
+        const content = lines[i].replace(/^\s*(?:[-*]|\d+[.)])\s+/, "");
+        items.push(
+          `<li${stamp(abs(i), "li", section)}>` + renderInline(content) + `</li>`,
+        );
+        i++;
+      }
+      out.push(`<${tag}>` + items.join("") + `</${tag}>`);
+      continue;
+    }
+
+    // Paragraph (and the degrade-to-<p> fallback for anything unrecognized):
+    // gather until a blank line or the start of another block.
+    const startIdx = i;
+    const para = [];
+    while (
+      i < lines.length &&
+      !/^\s*$/.test(lines[i]) &&
+      !/^(#{1,6})\s+/.test(lines[i]) &&
+      !/^\s*```/.test(lines[i]) &&
+      !/^\s*>/.test(lines[i]) &&
+      !isListItem(lines[i]) &&
+      !(
+        lines[i].includes("|") &&
+        i + 1 < lines.length &&
+        isTableSeparator(lines[i + 1])
+      )
+    ) {
+      para.push(lines[i]);
+      i++;
+    }
+    out.push(
+      `<p${stamp(abs(startIdx), "p", section)}>` +
+        renderInline(para.join(" ")) +
+        `</p>`,
+    );
+  }
+
+  return out.join("\n");
+}