beatrina 0.8.6

package/host/planes/journal.mjs

@@ -0,0 +1,53 @@
+// planes/journal.mjs — the FOURTH allow-list: the durable document journal.
+//
+// Answered by the HOST for the reason the file ops are (a kilobyte append is
+// not evaluation and must never queue behind a running cell — serve.R measured
+// 5 ms while a chunk sleeps), and page-only in BOTH senses:
+//
+//   · AGENT_REFUSED, because the journal holds every keystroke, INCLUDING
+//     deleted text — it is the user's, never an agent's to read or write;
+//   · PAGE_ONLY_CLASSES, because AGENT_REFUSED alone is an honour system: a
+//     client that simply never declared itself would sail through it, which is
+//     exactly the hole `ai-key` had until 0.60.89.
+//
+// The store is host/journal-store.mjs; this file is only the wire. The one rule
+// that looks like plumbing and is not: the reply is written by journalFrame(),
+// which splices each record's BYTES into the JSON by hand. Handing the parsed
+// records back to a serialiser is relay_frame's lesson one door over.
+
+import { createJournalStore, journalFrame } from "../journal-store.mjs";
+import { PAGE_ONLY_CLASSES } from "../server.mjs";
+
+export const JOURNAL_OPS = Object.freeze([
+  "journal_open", "journal_append", "journal_checkpoint", "journal_load",
+  "journal_read", "journal_versions", "journal_pin", "journal_unpin",
+  "journal_pin_read", "journal_list", "journal_delete", "journal_export",
+  "journal_archive", "journal_rename", "journal_probe",
+]);
+
+export function createPlane({ audit } = {}) {
+  const store = createJournalStore();
+  return {
+    name: "journal",
+    audits: true,          // the audit line carries the document key; see server.mjs
+    ops: JOURNAL_OPS,
+    agentRefused: JOURNAL_OPS,
+    commands: JOURNAL_OPS,
+    capabilities: ["document-journal-v1"],
+    store,
+    handle(cmd, rec, ctx) {
+      if (typeof cmd.id !== "string" || !cmd.id.length) return undefined;
+      // Class, not role: what the upgrade gate PROVED about the connection,
+      // which nothing the client says afterwards can change.
+      if (!PAGE_ONLY_CLASSES.includes(rec.class)) {
+        audit?.("journal-refused", { detail: cmd.type, class: rec.class || "unknown" });
+        rec.ws.send(ctx.enc({ type: cmd.type, id: cmd.id, code: "refused",
+          error: "The document journal is available to the notebook page only." }));
+        return undefined;
+      }
+      audit?.(cmd.type, { id: cmd.id, key: typeof cmd.key === "string" ? cmd.key : "" });
+      rec.ws.send(journalFrame(store.answerGuarded(cmd)));
+      return undefined;
+    },
+  };
+}

package/host/planes/latex.mjs

@@ -0,0 +1,201 @@
+// latex.mjs — the LaTeX live preview: pandoc over the root .tex, its includes
+// pulled in, its figures inlined. A port of spike/latex.R `latex_preview()`
+// and serve.R's `latex_preview` handler, rule for rule.
+//
+// Three rules carried over, because each is a security or honesty decision:
+//   - No path travels on the wire in either direction. Includes resolve
+//     against the ROOT's own directory whatever a buffer is called, and
+//     figures come back as data: URIs the host built from files it resolved.
+//   - Everything is BOUNDED: source, output, one figure, all figures, files
+//     followed, include depth. A cycle costs a stack frame, never the session.
+//   - A pandoc parse failure is `partial`, not an error: an unclosed group is
+//     the ordinary state of a document being typed, and the page keeps the
+//     last good render behind the note.
+//
+// Page-only in both senses (role AND class), like serve.R.
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import crypto from "node:crypto";
+import { findPandoc, run } from "./cite.mjs";
+
+export const LATEX_PREVIEW_TIMEOUT_MS = 8000;
+export const LATEX_PREVIEW_MAX_SOURCE = 2e6;
+export const LATEX_PREVIEW_MAX_HTML = 6e6;
+export const LATEX_PREVIEW_MAX_IMAGE = 1.5e6;
+export const LATEX_PREVIEW_MAX_ASSETS = 8e6;
+export const LATEX_PREVIEW_MAX_FILES = 40;
+export const LATEX_PREVIEW_DEPTH = 6;
+export const LATEX_PREVIEW_IMAGE_TYPES = Object.freeze({
+  png: "image/png", jpg: "image/jpeg", jpeg: "image/jpeg",
+  gif: "image/gif", svg: "image/svg+xml", webp: "image/webp",
+});
+
+const OPS = ["latex_preview"];
+const AGENT_WHY = { latex_preview: "Agents cannot render a LaTeX preview; read the .tex instead." };
+const PAGE_ONLY_CLASSES = ["served", "file", "local"];
+const scalar = (x) => typeof x === "string";
+const bytes = (s) => Buffer.byteLength(s, "utf8");
+
+/**
+ * Is `p` inside `dir`, both canonicalised? The trailing separator matters:
+ * without it /p/figs would admit /p/figs-private.
+ * @returns {string} the resolved path, or "" when outside or absent.
+ */
+export function latexWithin(dir, p) {
+  if (!scalar(dir) || !dir || !scalar(p) || !p) return "";
+  let root;
+  try { if (!fs.statSync(dir).isDirectory()) return ""; root = fs.realpathSync(dir); } catch { return ""; }
+  const full0 = /^([A-Za-z]:)?[/\\]/.test(p) ? p : path.join(root, p);
+  let full;
+  try { full = fs.realpathSync(full0); } catch { return ""; }
+  if (full !== root && !full.startsWith(root + path.sep)) return "";
+  return full;
+}
+
+/** Pull \input/\include/\subfile bodies into one source. Buffers win over disk. */
+export function latexPreviewExpand(source, dir, buffers = {}, seen = [], depth = LATEX_PREVIEW_DEPTH) {
+  if (depth <= 0) return source;
+  const pattern = /\\(?:input|include|subfile)\{([^{}]{1,200})\}/g;
+  let out = "";
+  let at = 0;
+  let m;
+  let any = false;
+  while ((m = pattern.exec(source)) !== null) {
+    any = true;
+    let rel = m[1];
+    if (!/\.[A-Za-z0-9]{1,5}$/.test(rel)) rel += ".tex";
+    let body = null;
+    if (!seen.includes(rel) && seen.length < LATEX_PREVIEW_MAX_FILES) {
+      if (Object.hasOwn(buffers, rel) && typeof buffers[rel] === "string") body = buffers[rel];
+      else {
+        const hit = latexWithin(dir, rel);
+        if (hit) {
+          try { if (fs.statSync(hit).size <= LATEX_PREVIEW_MAX_SOURCE) body = fs.readFileSync(hit, "utf8").replace(/\r?\n$/, ""); } catch { body = null; }
+        }
+      }
+    }
+    out += source.slice(at, m.index) + (body === null ? "" : latexPreviewExpand(body, dir, buffers, [...seen, rel], depth - 1));
+    at = m.index + m[0].length;
+  }
+  return any ? out + source.slice(at) : source;
+}
+
+/** The .bib files a source names, resolved and bounded. */
+export function latexPreviewBibliography(source, dir) {
+  const named = [];
+  for (const m of source.matchAll(/\\(?:bibliography|addbibresource)(?:\[[^\]]*\])?\{([^{}]{1,300})\}/g)) {
+    m[1].split(",").map((s) => s.trim()).filter(Boolean).forEach((n) => named.push(/\.[A-Za-z0-9]{1,5}$/.test(n) ? n : `${n}.bib`));
+  }
+  return [...new Set(named)].map((n) => latexWithin(dir, n)).filter(Boolean);
+}
+
+const extOf = (s) => { const m = s.match(/\.([A-Za-z0-9]+)$/); return m ? m[1].toLowerCase() : null; };
+
+/** Turn every local <img src> into a data: URI, within budget. */
+export function latexPreviewInline(html, dir) {
+  let inlined = 0;
+  let budget = LATEX_PREVIEW_MAX_ASSETS;
+  const dropped = [];
+  const out = html.replace(/src="([^"]{1,400})"/g, (whole, src) => {
+    if (/^(?:data:|https?:|\/\/)/.test(src)) return whole;
+    const ext = extOf(src);
+    let mime = ext ? LATEX_PREVIEW_IMAGE_TYPES[ext] : undefined;
+    const candidates = !ext || !mime
+      ? Object.keys(LATEX_PREVIEW_IMAGE_TYPES).map((t) => `${src.replace(/\.[A-Za-z0-9]+$/, "")}.${t}`)
+      : [src];
+    let hit = "";
+    for (const cand of candidates) {
+      hit = latexWithin(dir, cand);
+      if (hit) { mime = LATEX_PREVIEW_IMAGE_TYPES[extOf(cand)]; break; }
+    }
+    if (!hit || !mime) { dropped.push(path.basename(src)); return whole; }
+    let size;
+    try { size = fs.statSync(hit).size; } catch { dropped.push(path.basename(src)); return whole; }
+    if (!Number.isFinite(size) || size > LATEX_PREVIEW_MAX_IMAGE || size > budget) { dropped.push(path.basename(src)); return whole; }
+    let data;
+    try { data = fs.readFileSync(hit); } catch { dropped.push(path.basename(src)); return whole; }
+    budget -= size;
+    inlined += 1;
+    return `src="data:${mime};base64,${data.toString("base64")}"`;
+  });
+  return { html: out, inlined, dropped: [...new Set(dropped)] };
+}
+
+/** Render one LaTeX source to HTML for the preview pane. */
+export async function latexPreview(source, docPath, buffers, { pandoc, timeoutMs = LATEX_PREVIEW_TIMEOUT_MS } = {}) {
+  if (!scalar(source) || source.length === 0) return { ok: false, error: "No LaTeX source to preview." };
+  if (bytes(source) > LATEX_PREVIEW_MAX_SOURCE) return { ok: false, error: "This document is too large to preview while you type." };
+  const bin = pandoc;
+  if (!bin) return { ok: false, error: "pandoc is not installed, or CarmaR could not find it. Compile still works; only the live preview needs pandoc." };
+  let dir = "";
+  if (scalar(docPath) && docPath) { try { if (fs.existsSync(docPath)) dir = path.dirname(fs.realpathSync(docPath)); } catch { dir = ""; } }
+  const keep = {};
+  if (buffers && typeof buffers === "object" && !Array.isArray(buffers)) {
+    Object.keys(buffers).filter(Boolean).slice(0, LATEX_PREVIEW_MAX_FILES).forEach((k) => { if (typeof buffers[k] === "string") keep[k] = buffers[k]; });
+  }
+  const expanded = dir ? latexPreviewExpand(source, dir, keep) : source;
+  const started = process.hrtime.bigint();
+  const args = ["--from=latex", "--to=html5", "--mathml", "--wrap=none", "--standalone", "--sandbox"];
+  if (dir) latexPreviewBibliography(expanded, dir).forEach((bib) => args.push("--citeproc", `--bibliography=${bib}`));
+  // A 0600 temp file, as cite does; HOME and the data dir moved aside so a
+  // render never reads or writes this user's pandoc configuration.
+  const scratch = fs.mkdtempSync(path.join(os.tmpdir(), "carmar-preview-"));
+  const input = path.join(scratch, `carmar-preview-${crypto.randomBytes(4).toString("hex")}.tex`);
+  try {
+    fs.writeFileSync(input, expanded + "\n", { mode: 0o600 });
+    const ran = await run(bin, [...args, input], { timeoutMs, env: { ...process.env, PANDOC_DATA_DIR: scratch, HOME: scratch } });
+    if (ran.error) return { ok: false, error: /timeout/i.test(ran.error) ? "The preview took too long and was stopped." : `preview: ${ran.error}` };
+    if (ran.timeout) return { ok: false, error: "The preview took too long and was stopped." };
+    if (ran.status !== 0) {
+      let first = String(ran.stderr || "").split("\n")[0] || "";
+      const shown = scalar(docPath) && docPath ? path.basename(docPath) : "the document";
+      first = first.split(input).join(shown);
+      return { ok: false, partial: true, error: `pandoc could not read this document${first ? `: ${first}` : "."}` };
+    }
+    const html = ran.stdout || "";
+    if (bytes(html) > LATEX_PREVIEW_MAX_HTML) return { ok: false, error: "The rendered preview is too large to show." };
+    const figures = dir ? latexPreviewInline(html, dir) : { html, inlined: 0, dropped: [] };
+    return {
+      ok: true, html: figures.html, warnings: String(ran.stderr || "").trim(),
+      elapsed_ms: Number(process.hrtime.bigint() - started) / 1e6,
+      inlined: figures.inlined, dropped: figures.dropped,
+    };
+  } finally {
+    fs.rmSync(scratch, { recursive: true, force: true });
+  }
+}
+
+export function createPlane({ env, audit }) {
+  let pandocBin = null;
+  const pandoc = () => { if (pandocBin === null) pandocBin = findPandoc(env); return pandocBin; };
+  return {
+    name: "latex",
+    ops: OPS,
+    agentRefused: OPS,
+    agentReason: (op) => AGENT_WHY[op],
+    commands: OPS,
+    capabilities: ["latex-preview-v1"],
+    handle(cmd, rec, ctx) {
+      const { enc, scalarChr } = ctx;
+      if (rec.role !== "page" || !scalarChr(cmd.id)) return undefined;
+      const reply = (payload) => rec.ws.send(enc({ type: "latex_preview", id: cmd.id, ...payload }));
+      if (!PAGE_ONLY_CLASSES.includes(rec.class)) {
+        audit("latex-preview-refused", { reason: "class", class: rec.class || "unknown" });
+        reply({ error: "Only the local notebook page may render a preview." });
+        return undefined;
+      }
+      // `version` is the page's own token, echoed so it can drop a stale reply.
+      const version = cmd.version ?? null;
+      return latexPreview(cmd.source, cmd.path ?? "", cmd.buffers, { pandoc: pandoc() })
+        .catch((e) => ({ ok: false, error: e.message }))
+        .then((out) => {
+          if (out.ok !== true) reply({ error: out.error, partial: out.partial === true, version });
+          else reply({ ok: true, html: out.html, warnings: out.warnings, elapsed_ms: out.elapsed_ms, inlined: out.inlined, dropped: out.dropped, version });
+        });
+    },
+  };
+}
+
+export default { createPlane };