slidemind 0.1.7 → 0.1.9

package/src/builders/gate-server.mjs

@@ -0,0 +1,364 @@
+// 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 with its own round nonce and
+// visibility state, and the response's service marker + round nonce + `action`
+// tell it what to do (a foreign app or the other gate on this port must never
+// trigger a reload; same nonce = this run's own orphan — never a waiter).
+//
+// The gate must ALWAYS end up visibly open in front of the user, so tab reuse
+// is granted only to a waiting tab that reports itself VISIBLE (`visible: true`,
+// from the overlay's document.visibilityState) inside the grace window. A tab
+// buried in a background window must not silently swallow the round — it keeps
+// polling (`action: "wait"`) until the grace window decides, then either
+// reloads (`"reload"`, a visible tab won reuse — every waiter follows it into
+// the new round) or is told the round opened in a fresh browser tab and it
+// should retire (`"close"`).
+//
+// `waitForHeartbeat(ms)` is the server side of the open-browser grace window:
+// it resolves true the moment a visible waiter claims reuse, false when the
+// grace expires with none. The gate then calls `markFresh()` before opening a
+// new browser tab so late pollers get `action: "close"` instead of reloading
+// into a duplicate.
+//
+// `notePageLoad()` / `waitForPageLoad(ms)` / `pageLoaded()` track whether the
+// gate PAGE was ever actually fetched: the gate's request handler calls
+// `notePageLoad()` whenever it serves the root page, and serveAndOpen waits on
+// it after launching the opener — the only end-to-end proof that a browser
+// really opened the gate (a spawned opener exiting 0 proves nothing on a box
+// with a broken default-browser association). `pageLoaded()` is re-checked at
+// decision-timeout time so the DECISION: pending contract can tell the agent
+// whether the user ever saw the gate at all.
+export function createHeartbeat({ service }) {
+  const round = crypto.randomUUID();
+  // null = undecided (grace window running), "reuse" = a visible waiting tab
+  // reloads into this round, "fresh" = a new browser tab was opened for it.
+  let mode = null;
+  const waiters = [];
+  let pageSeen = false;
+  const pageWaiters = [];
+  return {
+    round,
+    notePageLoad() {
+      pageSeen = true;
+      while (pageWaiters.length) pageWaiters.shift()();
+    },
+    pageLoaded() {
+      return pageSeen;
+    },
+    waitForPageLoad(ms) {
+      if (pageSeen) return Promise.resolve(true);
+      if (!(ms > 0)) return Promise.resolve(false);
+      return new Promise((resolve) => {
+        const t = setTimeout(() => resolve(false), ms);
+        pageWaiters.push(() => {
+          clearTimeout(t);
+          resolve(true);
+        });
+      });
+    },
+    respond(res, { visible = false, tabRound = null } = {}) {
+      // A poll carrying THIS run's nonce is our own page (or an orphan of this
+      // run) — never a previous-round waiter, never a reuse claim.
+      const isWaiter = tabRound !== round;
+      if (isWaiter && mode === null && visible) {
+        mode = "reuse";
+        while (waiters.length) waiters.shift()();
+      }
+      const action = !isWaiter
+        ? "none"
+        : mode === "reuse"
+          ? "reload"
+          : mode === "fresh"
+            ? "close"
+            : "wait";
+      res.writeHead(200, { "Content-Type": MIME[".json"], "Cache-Control": "no-store" });
+      res.end(JSON.stringify({ ok: true, service, round, action }));
+    },
+    markFresh() {
+      if (mode === null) mode = "fresh";
+    },
+    waitForHeartbeat(ms) {
+      if (mode === "reuse") return Promise.resolve(true);
+      if (mode === "fresh" || !(ms > 0)) return Promise.resolve(false);
+      return new Promise((resolve) => {
+        const t = setTimeout(() => resolve(false), ms);
+        waiters.push(() => {
+          clearTimeout(t);
+          resolve(true);
+        });
+      });
+    },
+  };
+}
+
+// Browser-status lines for a gate's DECISION: pending output, shared by both
+// gates so the wording is identical. A pending decision has two very different
+// stories: the user saw the gate and hasn't answered (benign — just wait), or
+// no tab ever loaded it (the browser open failed and they never saw anything —
+// the agent must hand them the link). `pageLoaded` comes from the server's
+// page-load tracker re-checked at timeout time, so a tab that opened late still
+// counts. Returns [] when the caller has no status to report (url unknown),
+// keeping older call sites and tests valid.
+export function pendingBrowserLines({ pageLoaded = null, url = null } = {}) {
+  if (!url) return [];
+  if (pageLoaded) {
+    return [
+      `Browser status: the gate DID open in the user's browser (a tab loaded ${url})`,
+      "— they just haven't decided yet.",
+    ];
+  }
+  return [
+    "Browser status: NO tab ever loaded the gate — the browser most likely FAILED",
+    "to open on the user's machine, so they never saw it. When you tell the user,",
+    `give them the gate link to open manually once you re-run: ${url}`,
+    "(the re-run binds the same address when its port is free, and prints it again).",
+  ];
+}
+
+// How long serveAndOpen waits, after launching the opener, for the fresh tab
+// to actually fetch the gate page before reporting the open as unconfirmed.
+// Generous enough for a cold browser start; the gate blocks on the decision
+// anyway, so this delay only defers one status line.
+export const OPEN_CONFIRM_MS = 8000;
+
+// When the opener chain FAILED outright, the user will never see the gate on
+// their own — blocking the agent for the full decision timeout helps nobody.
+// The gates instead give a manually-opened tab this long to appear (the URL was
+// printed, the user may click it from the terminal), then return the pending
+// contract early so the agent can hand the user the link.
+export const OPEN_FAILED_GRACE_MS = 90 * 1000;
+
+// Print the gate URL, then decide whether to open a browser. If a VISIBLE 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.
+// In every other case — first run, no waiting tab, or only hidden/background
+// tabs polling — the browser is ALWAYS opened, and `markOpenedFresh` retires
+// the hidden waiters so they don't reload into a duplicate.
+//
+// Opening a browser from a CLI is error-prone, so the outcome is REPORTED, not
+// assumed: the opener's own result says whether anything launched, and the
+// server's page-load tracker (`waitForPageLoad`, fed by the gate serving its
+// root page) is the end-to-end proof a tab really opened. Every branch prints
+// one agent-facing `BROWSER:` line that (a) says explicitly whether the gate
+// auto-opened and (b) always carries the URL, so the agent can either tell the
+// user "it's on your screen" or hand them the link to open manually.
+//
+// Returns { reused, launched, confirmed, url }: `launched` = an opener
+// plausibly ran (null when reused — nothing was launched); `confirmed` = a tab
+// provably fetched the gate page (null when the server exposes no
+// waitForPageLoad, i.e. unknown). `open` is required — gates pass their browser
+// opener so this module stays dependency-light and tests inject a fake; a
+// legacy/fake opener returning undefined counts as launched (only an explicit
+// `false` means the chain failed). The message nouns are per-gate; defaults
+// speak the preview gate's.
+export async function serveAndOpen(server, {
+  open,
+  graceMs = GRACE_MS,
+  openConfirmMs = OPEN_CONFIRM_MS,
+  readyLabel = "Preview review",
+  reuseNoun = "review tab",
+  gateNoun = "review",
+  waitLine = null,
+} = {}) {
+  process.stderr.write(`${readyLabel} ready at ${server.url}\n`); // URL always printed first
+  const reused = await server.waitForHeartbeat(graceMs);
+  let launched = null;
+  let confirmed = null;
+  if (reused) {
+    process.stderr.write(
+      `BROWSER: reused the user's already-open ${reuseNoun} at ${server.url} — it reloaded into this round; no new window was opened.\n`,
+    );
+    confirmed = true;
+  } else {
+    if (server.markOpenedFresh) server.markOpenedFresh();
+    launched = (await open(server.url)) !== false;
+    if (launched && server.waitForPageLoad) {
+      confirmed = await server.waitForPageLoad(openConfirmMs);
+    }
+    if (!launched) {
+      process.stderr.write(
+        `BROWSER: could NOT be opened automatically (no opener worked on this machine). ` +
+          `The user must open the ${gateNoun} themselves — give them this link: ${server.url}\n`,
+      );
+    } else if (confirmed === false) {
+      process.stderr.write(
+        `BROWSER: open was attempted but NO tab has loaded the ${gateNoun} yet — it may not have opened. ` +
+          `If the user doesn't see it, give them this link to open manually: ${server.url}\n`,
+      );
+    } else {
+      // confirmed === true (a tab fetched the page) or null (server can't track
+      // page loads — trust the opener's success).
+      process.stderr.write(
+        `BROWSER: opened automatically — the ${gateNoun} is on the user's screen at ${server.url}.\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, launched, confirmed, url: server.url };
+}

package/src/builders/plan-markdown-edit.mjs

@@ -0,0 +1,120 @@
+/**
+ * Inline-edit round-trip for the plan gate's rendered markdown blocks.
+ *
+ * The plan preview renders each `contenteditable` block stamped with its
+ * on-disk source line (`data-md-line`, 1-based, from plan-md.mjs) and kind
+ * (`data-md-kind`). When the user commits an edit, `replaceRenderedMarkdownBlock`
+ * maps the block's edited innerText back into the markdown source at that
+ * line, preserving list markers, heading levels, and blockquote prefixes.
+ * `addEditableAttributes` injects the `contenteditable`/`spellcheck` attributes
+ * onto the editable block kinds only.
+ *
+ * Pure string logic — no DOM, no Office (unit-testable).
+ *
+ * 1:1 port of the add-in's plan-markdown-edit.ts. Top-level helpers are
+ * prefixed `pme…` to keep the single-IIFE browser bundle collision-free;
+ * exported API names match the add-in verbatim.
+ */
+
+export function isEditableKind(kind) {
+  return (
+    kind === "p" ||
+    kind === "li" ||
+    kind === "blockquote" ||
+    /^h[1-6]$/.test(kind)
+  );
+}
+
+function pmeIsBlockStart(line) {
+  return (
+    /^\s*$/.test(line) ||
+    /^(#{1,6})\s+/.test(line) ||
+    /^\s*```/.test(line) ||
+    /^\s*>/.test(line) ||
+    /^\s*(?:[-*]\s+|\d+[.)]\s+)/.test(line) ||
+    (line.includes("|") && /^\|?\s*:?-+:?\s*(\|\s*:?-+:?\s*)*\|?$/.test(line))
+  );
+}
+
+function pmeGetParagraphRange(lines, index) {
+  let end = index + 1;
+  while (end < lines.length && !pmeIsBlockStart(lines[end] ?? "")) {
+    end++;
+  }
+  return { start: index, end };
+}
+
+function pmeNormalizeEditableText(text) {
+  return text
+    .replace(/\u00a0/g, " ")
+    .replace(/[ \t]+\n/g, "\n")
+    .trim();
+}
+
+function pmeMarkdownForEdit(kind, existingLine, text) {
+  const normalized = pmeNormalizeEditableText(text);
+  if (!normalized) return null;
+
+  const heading = normalized.match(/^(#{1,6})\s+(.*)$/);
+  if (heading) {
+    return `${heading[1]} ${(heading[2] ?? "").trim()}`;
+  }
+
+  const list = normalized.match(/^((?:[-*])|\d+[.)])\s+(.*)$/);
+  if (list) {
+    return `${list[1]} ${(list[2] ?? "").trim()}`;
+  }
+
+  if (/^h[1-6]$/.test(kind)) {
+    const current = existingLine.match(/^(#{1,6})\s+/)?.[1] ?? "##";
+    return `${current} ${normalized}`;
+  }
+
+  if (kind === "li") {
+    const marker = existingLine.match(/^\s*((?:[-*])|\d+[.)])\s+/)?.[1] ?? "-";
+    return `${marker} ${normalized}`;
+  }
+
+  if (kind === "blockquote") {
+    return normalized
+      .split("\n")
+      .map((line) => `> ${line.trim()}`)
+      .join("\n");
+  }
+
+  return normalized;
+}
+
+/**
+ * Maps an edited rendered block's innerText back into the markdown source at
+ * the stamped 1-based line. Options: { markdown, line, kind, text }.
+ * No-op for non-editable kinds or out-of-range lines.
+ */
+export function replaceRenderedMarkdownBlock(options) {
+  const { markdown, line, kind, text } = options;
+  if (!isEditableKind(kind)) return markdown;
+
+  const lines = markdown.split("\n");
+  const index = line - 1;
+  if (index < 0 || index >= lines.length) return markdown;
+
+  const existingLine = lines[index] ?? "";
+  const range =
+    kind === "p"
+      ? pmeGetParagraphRange(lines, index)
+      : { start: index, end: index + 1 };
+  const replacement = pmeMarkdownForEdit(kind, existingLine, text);
+  const nextLines = [
+    ...lines.slice(0, range.start),
+    ...(replacement === null ? [] : replacement.split("\n")),
+    ...lines.slice(range.end),
+  ];
+  return nextLines.join("\n");
+}
+
+export function addEditableAttributes(html) {
+  return html.replace(
+    /data-md-kind="(h[1-6]|p|li|blockquote)"/g,
+    'data-md-kind="$1" contenteditable="true" spellcheck="true"',
+  );
+}