beatrina 0.8.6

package/host/planes/cite.mjs

@@ -0,0 +1,517 @@
+// cite.mjs — citations rendered by pandoc, in the style the document chose.
+//
+// A port of spike/cite.R and the `cite` / `cite_styles` / `csl_*` half of
+// spike/serve.R. Six CSL files ship BESIDE the kernel (spike/plugins/csl/,
+// 324 KB the page never loads), pandoc's own citeproc renders with them, and
+// the page inserts what comes back. No CSL engine in the page. Any other style
+// is a PLUGIN — found in the CSL repository and imported through the plugin
+// store's one door (host/plugin-store.mjs).
+//
+// What pandoc is given, and what it is not. The page sends the cited entries as
+// CSL-YAML (the same `references:` block the .carmd keeps) and the citation
+// groups in document order; the supervisor writes ONE markdown file — the YAML
+// as front matter, one paragraph per group — and runs pandoc over it with
+// `--sandbox`, so a hostile field cannot make pandoc read a file, and with raw
+// HTML disabled in the READER, so a title cannot smuggle markup through
+// metadata. The page scrubs the HTML it gets back all the same: two doors,
+// because a title is imported data from someone's .bib.
+//
+// Who may ask: `cite_styles` is open to any socket (six file names and a
+// version). `cite`, `csl_place`, `csl_search`, `csl_import` and `csl_remove`
+// spawn a process, write a file or touch the network, so they are page-only in
+// BOTH senses — PAGE_ONLY_CLASSES here, agentRefused at the seam.
+//
+// One deliberate difference from serve.R, in mechanism and not in behaviour:
+// `processx::run` BLOCKS the R loop for the render's duration, which is what
+// makes "one request at a time" the shape of the thing there. Here a spawn is
+// asynchronous, so the same shape is kept explicitly — every cite render is
+// queued behind the previous one — rather than being lost as an accident of
+// the language.
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import crypto from "node:crypto";
+import { spawn } from "node:child_process";
+import { appId } from "../user-dirs.mjs";
+import {
+  CSL_NAME_RE, cslInfo, cslIndexUrl, pluginFetch, pluginIdOk, pluginInstall,
+  pluginPolicyOnce, pluginPolicyReason, pluginRemove, pluginRows, rUserDir,
+} from "../plugin-store.mjs";
+
+export { cslInfo, cslLooksLikeStyle } from "../plugin-store.mjs";
+
+const CITE_MAX_YAML_BYTES = 1000000;
+const CITE_MAX_GROUPS = 2000;
+const CITE_MAX_KEYS_PER_GROUP = 50;
+const CITE_TIMEOUT_MS = 20000;
+// pandoc's citation-key alphabet (the page's CITE_KEY, restated): word
+// characters, then internal punctuation, never a final one.
+const CITE_KEY_RE = /^[A-Za-z0-9_]([A-Za-z0-9_:.#$%&+?<>~/-]*[A-Za-z0-9_])?$/;
+
+const CSL_MAX_INDEX_BYTES = 8000000;
+const CSL_INDEX_MAX_AGE_DAYS = 7;
+const CSL_SEARCH_LIMIT = 40;
+
+const PAGE_ONLY_CLASSES = ["served", "file", "local"];
+const OPS = ["cite", "cite_styles", "csl_place", "csl_search", "csl_import", "csl_remove"];
+/** Every op but `cite_styles`: a process, a file, or the network. */
+const AGENT_REFUSED = ["cite", "csl_place", "csl_search", "csl_import", "csl_remove"];
+const AGENT_WHY = {
+  cite: "Agents cannot render citations; the page does, and shows the result.",
+  csl_place: "Agents cannot place a style file beside a document.",
+  csl_search: "Agents cannot search for citation styles; ask the user to.",
+  csl_import: "Agents cannot import a citation style.",
+  csl_remove: "Agents cannot remove a citation style.",
+};
+
+/* ── the styles are PLUGINS ───────────────────────────────────────────────── */
+
+/**
+ * Every style this kernel can render with: the ACTIVE csl plugins.
+ *
+ * READ from the store, never declared — a style staged beside the kernel is
+ * offered the moment it is there, and one whose file no longer matches its
+ * manifest is ABSENT from this list rather than promised and broken.
+ */
+export function cslStyles(here, policy, env) {
+  return pluginRows(here, policy, env, "csl").filter((r) => r.active).map((r) => ({
+    file: r.file,
+    name: r.name || r.id,
+    layer: r.layer,
+    dependent_on: r.requires.length ? `${r.requires[0]}.csl` : "",
+    path: r.dir ? path.join(r.dir, r.file) : "",
+  }));
+}
+
+/**
+ * The .csl file a request may name, resolved in a layer or refused.
+ *
+ * A bare file name from the list, nothing else. "default" (or nothing) means
+ * pandoc's built-in Chicago author-date, which needs no file at all.
+ *
+ * @returns {string|null} the absolute path, "" for the default, null when refused.
+ */
+export function cslResolve(here, policy, env, style) {
+  if (style == null || style === "" || style === "default") return "";
+  if (typeof style !== "string") return null;
+  if (!/\.csl$/.test(style) || !pluginIdOk(style.replace(/\.csl$/, ""))) return null;
+  const row = cslStyles(here, policy, env).find((s) => s.file === style);
+  if (!row) return null;
+  return path.resolve(row.path);
+}
+
+/**
+ * The file pandoc is actually handed: a dependent style's PARENT, resolved
+ * locally in any layer — pandoc would otherwise go looking for it, which the
+ * sandbox forbids. The formatting of a dependent style IS its parent's.
+ */
+export function cslEnginePath(here, policy, env, p) {
+  if (p == null || !p) return p;
+  const parent = cslInfo(p).parent;
+  if (!parent) return p;
+  return cslResolve(here, policy, env, parent);
+}
+
+/* ── the repository index ─────────────────────────────────────────────────── */
+
+const indexCache = { rows: null };
+
+async function cslIndex(policy, env) {
+  if (indexCache.rows) return { rows: indexCache.rows };
+  const dir = rUserDir(appId(env), "cache", env);
+  const disk = path.join(dir, "csl-index.json");
+  let fresh = false;
+  try {
+    const age = (Date.now() - fs.statSync(disk).mtimeMs) / 86400000;
+    fresh = age < CSL_INDEX_MAX_AGE_DAYS;
+  } catch { fresh = false; }
+  if (!fresh) {
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const tmp = path.join(os.tmpdir(), `csl-index-${crypto.randomBytes(8).toString("hex")}.json`);
+    const err = await pluginFetch(policy, cslIndexUrl(env), tmp, CSL_MAX_INDEX_BYTES);
+    if (err) {
+      if (!fs.existsSync(disk)) return { error: `The style index could not be fetched: ${err}` };
+    } else {
+      fs.copyFileSync(tmp, disk);
+      try { fs.unlinkSync(tmp); } catch { /* gone */ }
+      fs.chmodSync(disk, 0o600);
+    }
+  }
+  let raw = null;
+  try { raw = JSON.parse(fs.readFileSync(disk, "utf8")); } catch { raw = null; }
+  if (!Array.isArray(raw) || !raw.every((r) => r && typeof r === "object")
+      || !raw.some((r) => "name" in r && "title" in r)) {
+    return { error: "The style index did not read as a list of styles." };
+  }
+  const rows = raw.map((r) => ({
+    name: String(r.name ?? ""),
+    title: String(r.title ?? ""),
+    dependent: Number(r.dependent) === 1,
+    format: String((r.categories && r.categories.format) || ""),
+  })).filter((r) => CSL_NAME_RE.test(r.name) && r.title);
+  indexCache.rows = rows;
+  return { rows };
+}
+
+/**
+ * Search the repository index: every term must appear in the title or the name,
+ * case-insensitively; titles that START with the query come first.
+ */
+export async function cslSearch(policy, env, q, limit = CSL_SEARCH_LIMIT) {
+  const query = (typeof q === "string" ? q : "").trim();
+  if (query.length < 2) return { ok: true, total: 0, rows: [] };
+  if (policy.network !== true) return { ok: false, error: pluginPolicyReason(policy, "network") };
+  const idx = await cslIndex(policy, env);
+  if (idx.error) return { ok: false, error: idx.error };
+  const terms = query.toLowerCase().split(/\s+/);
+  const found = idx.rows.filter((r) => {
+    const hay = `${r.title} ${r.name}`.toLowerCase();
+    return terms.every((t) => hay.includes(t));
+  });
+  const lower = query.toLowerCase();
+  const starts = (r) => r.title.toLowerCase().startsWith(lower);
+  found.sort((a, b) => (Number(starts(b)) - Number(starts(a)))
+    || (Number(a.dependent) - Number(b.dependent))
+    || a.title.toLowerCase().localeCompare(b.title.toLowerCase()));
+  return {
+    ok: true,
+    total: found.length,
+    rows: found.slice(0, limit).map((r) => ({ name: r.name, title: r.title, dependent: r.dependent, format: r.format })),
+  };
+}
+
+/** Import one style from the repository: `plugin_install` by registry name. */
+export async function cslImport(here, policy, env, name) {
+  if (typeof name !== "string" || !CSL_NAME_RE.test(name)) {
+    return { ok: false, error: "That is not a style name from the repository." };
+  }
+  const r = await pluginInstall(here, policy, env, "csl", { registry: name });
+  if (r.ok !== true) return r;
+  return {
+    ok: true, file: r.file, name: r.name,
+    dependent_on: r.requires && r.requires.length ? `${r.requires[0]}.csl` : "",
+    already: r.already === true,
+  };
+}
+
+/** Remove a style from the user layer — `plugin_remove`, by file name. */
+export function cslRemove(here, policy, env, file) {
+  if (typeof file !== "string" || !/\.csl$/.test(file) || !pluginIdOk(file.replace(/\.csl$/, ""))) {
+    return { ok: false, error: "That is not a style file name." };
+  }
+  const r = pluginRemove(here, policy, env, "csl", file.replace(/\.csl$/, ""));
+  if (r.ok !== true) return r;
+  return { ok: true, file };
+}
+
+/* ── pandoc ───────────────────────────────────────────────────────────────── */
+
+const isExecutable = (p) => { try { fs.accessSync(p, fs.constants.X_OK); return fs.statSync(p).isFile(); } catch { return false; } };
+
+/**
+ * Locate pandoc, the ladder spike/cite.R climbs: an explicit override, what
+ * RStudio sets, PATH, then the bundles known by name. Measured on a normal
+ * RStudio machine: no pandoc on PATH, one inside RStudio's Quarto.
+ *
+ * The rung this ladder does NOT have is R's `rmarkdown::pandoc_exec()`, which
+ * sits between RSTUDIO_PANDOC and PATH there. Asking R for it would mean
+ * starting an R process to find a binary — the host would spawn a worker to
+ * answer a question about the file system — so the bundle list below carries
+ * the same answers rmarkdown reaches for. On this machine both resolve to the
+ * same binary; where they could differ, CARMAR_PANDOC settles it.
+ *
+ * @returns {string} the path, or "".
+ */
+export function findPandoc(env) {
+  const explicit = env("CARMAR_PANDOC", "");
+  if (explicit && fs.existsSync(explicit)) return explicit;
+  const fromEnv = env("RSTUDIO_PANDOC", "");
+  if (fromEnv) {
+    const cand = path.join(fromEnv, process.platform === "win32" ? "pandoc.exe" : "pandoc");
+    if (fs.existsSync(cand)) return cand;
+  }
+  const exe = process.platform === "win32" ? "pandoc.exe" : "pandoc";
+  for (const dir of String(env("PATH", "")).split(path.delimiter).filter(Boolean)) {
+    const cand = path.join(dir, exe);
+    if (isExecutable(cand)) return cand;
+  }
+  const arch = ["arm64"].includes(process.arch) ? "aarch64" : "x86_64";
+  const bundles = [
+    `/Applications/RStudio.app/Contents/Resources/app/quarto/bin/tools/${arch}/pandoc`,
+    `/Applications/Positron.app/Contents/Resources/app/quarto/bin/tools/${arch}/pandoc`,
+    `/Applications/quarto/bin/tools/${arch}/pandoc`,
+    "/usr/local/bin/pandoc", "/opt/homebrew/bin/pandoc",
+    "C:/Program Files/RStudio/resources/app/bin/quarto/bin/tools/pandoc.exe",
+    "C:/Program Files/Pandoc/pandoc.exe",
+  ];
+  return bundles.find((p) => fs.existsSync(p)) || "";
+}
+
+/** Run a command, bounded, and give back its streams. Never a shell. */
+export function run(bin, args, { timeoutMs, env: childEnv } = {}) {
+  return new Promise((resolve) => {
+    let child;
+    try { child = spawn(bin, args, { stdio: ["ignore", "pipe", "pipe"], env: childEnv }); }
+    catch (e) { resolve({ error: e.message }); return; }
+    let out = "";
+    let err = "";
+    let timedOut = false;
+    child.stdout.setEncoding("utf8");
+    child.stderr.setEncoding("utf8");
+    child.stdout.on("data", (d) => { out += d; });
+    child.stderr.on("data", (d) => { err += d; });
+    const timer = timeoutMs ? setTimeout(() => { timedOut = true; try { child.kill("SIGKILL"); } catch { /* gone */ } }, timeoutMs) : null;
+    child.once("error", (e) => { if (timer) clearTimeout(timer); resolve({ error: e.message }); });
+    child.once("close", (code) => {
+      if (timer) clearTimeout(timer);
+      resolve({ status: code, stdout: out, stderr: err, timeout: timedOut });
+    });
+  });
+}
+
+/** pandoc's version, or "" when it is absent or does not answer. */
+export async function pandocVersion(bin) {
+  if (!bin) return "";
+  const ran = await run(bin, ["--version"], { timeoutMs: 5000 });
+  if (ran.error || ran.status !== 0) return "";
+  const first = String(ran.stdout || "").split("\n")[0] || "";
+  return first.replace(/^pandoc\s+/, "").trim();
+}
+
+/**
+ * Validate a `cite` request. The whole contract, in one place.
+ *
+ * @returns {{ok:true, yaml:string, groups:object[], style:string}|{ok:false, error:string}}
+ */
+export function citeValidate(here, policy, env, cmd) {
+  const refuse = (error) => ({ ok: false, error });
+  const yaml = cmd.yaml;
+  if (typeof yaml !== "string") return refuse("cite: `yaml` must be a string.");
+  if (Buffer.byteLength(yaml, "utf8") > CITE_MAX_YAML_BYTES) return refuse("cite: the reference block is too large.");
+  // The block is one YAML document whose only top-level key is `references:`.
+  // A second top-level key would be metadata injection — a `csl:` or
+  // `bibliography:` smuggled in by a field — so the first line is pinned and
+  // every later line must be indented or a list item.
+  const lines = yaml.split("\n");
+  if (!lines.length || lines[0].trim() !== "references:") {
+    return refuse("cite: the reference block must start with `references:`.");
+  }
+  if (lines.slice(1).some((l) => l.trim() !== "" && !/^[ -]/.test(l))) {
+    return refuse("cite: the reference block carries a key that is not a reference.");
+  }
+  let style = cslResolve(here, policy, env, cmd.style);
+  if (style == null) return refuse("cite: that style is not one this kernel has.");
+  style = cslEnginePath(here, policy, env, style);
+  if (style == null) return refuse("cite: that style depends on a parent style that is not on this machine.");
+  const groups = cmd.groups == null ? [] : cmd.groups;
+  if (!Array.isArray(groups)) return refuse("cite: `groups` must be a list.");
+  if (groups.length > CITE_MAX_GROUPS) return refuse("cite: too many citations in one request.");
+  const clean = [];
+  for (const g of groups) {
+    const keys = [].concat((g && g.keys) || []).map(String);
+    if (!keys.length || keys.length > CITE_MAX_KEYS_PER_GROUP) {
+      return refuse("cite: a citation must name between one and fifty keys.");
+    }
+    if (!keys.every((k) => CITE_KEY_RE.test(k))) return refuse("cite: a citation key has characters pandoc would not read.");
+    clean.push({ keys, narrative: Boolean(g && g.narrative) });
+  }
+  return { ok: true, yaml, groups: clean, style };
+}
+
+/**
+ * The markdown pandoc renders: front matter, then one paragraph per group.
+ * Each paragraph is wrapped in a span with a known class so the answer can be
+ * split back into groups by position, whatever the style did inside.
+ */
+export function citeDocument(yaml, groups) {
+  const paras = groups.map((g) => {
+    const cite = g.narrative ? `@${g.keys[0]}` : `[${g.keys.map((k) => `@${k}`).join("; ")}]`;
+    return `[${cite}]{.carmar-cite-group}`;
+  });
+  return `---\n${yaml}\n---\n\n${paras.join("\n\n")}\n`;
+}
+
+/**
+ * Split pandoc's HTML into the group labels and the bibliography.
+ *
+ * Positional: the i-th `carmar-cite-group` span is the i-th group. A group span
+ * holds nested spans of its own, so the closing tag is found by WALKING span
+ * tags and counting depth, never by a non-greedy match.
+ */
+export function citeSplit(html, nGroups) {
+  const labels = new Array(nGroups).fill("");
+  const open = '<span class="carmar-cite-group">';
+  const starts = [];
+  for (let at = html.indexOf(open); at !== -1; at = html.indexOf(open, at + 1)) starts.push(at);
+  for (let i = 0; i < Math.min(starts.length, nGroups); i += 1) {
+    const rest = html.slice(starts[i] + open.length);
+    const tags = /<span\b[^>]*>|<\/span>/g;
+    let depth = 1;
+    let pos = -1;
+    let m = tags.exec(rest);
+    while (m) {
+      depth += m[0].startsWith("</") ? -1 : 1;
+      if (depth === 0) { pos = m.index; break; }
+      m = tags.exec(rest);
+    }
+    labels[i] = pos >= 0 ? rest.slice(0, pos) : "";
+  }
+  let refs = "";
+  const at = html.indexOf('<div id="refs"');
+  if (at !== -1) {
+    const tail = html.slice(at);
+    const last = tail.lastIndexOf("</div>");
+    if (last !== -1) refs = tail.slice(0, last + 6);
+  }
+  return { labels, bibliography: refs };
+}
+
+/** Run pandoc over one validated request. */
+export async function citeRun(bin, valid, timeoutMs = CITE_TIMEOUT_MS) {
+  if (!bin) return { ok: false, error: "pandoc is not installed, or CarmaR could not find it." };
+  const input = path.join(os.tmpdir(), `carmar-cite-${crypto.randomBytes(8).toString("hex")}.md`);
+  try {
+    fs.writeFileSync(input, citeDocument(valid.yaml, valid.groups));
+    fs.chmodSync(input, 0o600);
+    const args = [
+      // raw_html and raw_tex OFF in the reader: a title in the metadata is
+      // parsed as markdown, and raw HTML in it would otherwise pass straight
+      // through to the output. Smart quotes on, as in every render.
+      "--from", "markdown-raw_html-raw_tex",
+      "--to", "html", "--citeproc", "--wrap", "none", "--sandbox",
+      // A citation to a key the block does not hold must still render as
+      // SOMETHING (pandoc prints `[@key]` with a warning) rather than fail.
+      input,
+    ];
+    if (valid.style) args.push(`--csl=${valid.style}`);
+    const scratch = os.tmpdir();
+    const ran = await run(bin, args, {
+      timeoutMs,
+      env: { ...process.env, PANDOC_DATA_DIR: scratch, HOME: scratch },
+    });
+    if (ran.timeout) return { ok: false, error: "cite: pandoc took too long and was stopped." };
+    if (ran.error) return { ok: false, error: `cite: ${ran.error}` };
+    if (ran.status !== 0) {
+      const first = String(ran.stderr || "").split("\n")[0] || "";
+      return { ok: false, error: `cite: pandoc exited ${ran.status}${first ? `: ${first}` : ""}` };
+    }
+    return { ok: true, ...citeSplit(String(ran.stdout || ""), valid.groups.length) };
+  } finally {
+    try { fs.unlinkSync(input); } catch { /* never written */ }
+  }
+}
+
+/* ── the plane ────────────────────────────────────────────────────────────── */
+
+export function createPlane({ spike, env, audit }) {
+  const here = spike;
+  const policy = pluginPolicyOnce(env);
+  let pandocBin = null;
+  // pandoc, found once and kept. Absent stays absent for the session — a pandoc
+  // installed mid-session shows up after a restart, which is the rule R itself
+  // applies to a package installed under a running session.
+  const pandoc = () => { if (pandocBin === null) pandocBin = findPandoc(env); return pandocBin; };
+  let chain = Promise.resolve();
+  /** One pandoc at a time, as serve.R's blocking run makes it there. */
+  const queued = (fn) => { const next = chain.then(fn, fn); chain = next.catch(() => {}); return next; };
+
+  return {
+    name: "cite",
+    ops: OPS,
+    agentRefused: AGENT_REFUSED,
+    agentReason: (op) => AGENT_WHY[op],
+    commands: OPS,
+    capabilities: ["citations-v1"],
+
+    handle(cmd, rec, ctx) {
+      const { enc, scalarChr } = ctx;
+      if (!scalarChr(cmd.id)) return undefined;
+      const reply = (payload) => rec.ws.send(enc({ type: cmd.type, id: cmd.id, ...payload }));
+
+      if (cmd.type === "cite_styles") {
+        // Open to any socket: the style plugins, a pandoc version and the name
+        // of the default — an agent that knows which styles exist writes
+        // `csl: apa.csl` instead of guessing.
+        const styles = cslStyles(here, policy, env);
+        return pandocVersion(pandoc()).then((version) => reply({
+          pandoc: version,
+          default: "Chicago Manual of Style (author-date)",
+          styles: styles.map((s) => ({ file: s.file, name: s.name, layer: s.layer, dependent_on: s.dependent_on })),
+        }));
+      }
+
+      // Everything below is page-only in both senses. A declared agent was
+      // already answered by name at the seam; this is the CLASS half.
+      if (rec.role !== "page") return undefined;
+      if (!PAGE_ONLY_CLASSES.includes(rec.class)) {
+        audit("cite-refused", { op: cmd.type, reason: "class", class: rec.class || "unknown" });
+        reply({ error: "Only the local notebook page may render citations." });
+        return undefined;
+      }
+
+      if (cmd.type === "cite") {
+        const valid = citeValidate(here, policy, env, cmd);
+        if (valid.ok !== true) { reply({ error: valid.error }); return undefined; }
+        return queued(() => citeRun(pandoc(), valid).then((out) => {
+          if (out.ok !== true) reply({ error: out.error });
+          else reply({ labels: out.labels, bibliography: out.bibliography, style: cmd.style ?? "default" });
+        }));
+      }
+
+      // The repository door: search its index, import a style (a dependent
+      // brings its parent), remove one of the user's. Network only here, only
+      // on these clicks — "nothing at start" stays true.
+      if (cmd.type === "csl_search") {
+        return cslSearch(policy, env, cmd.q).then((r) => {
+          if (r.ok !== true) reply({ error: r.error }); else reply({ total: r.total, rows: r.rows });
+        });
+      }
+      if (cmd.type === "csl_import") {
+        return cslImport(here, policy, env, cmd.name).then((r) => {
+          audit("csl-import", { name: cmd.name ?? "", ok: r.ok === true });
+          if (r.ok !== true) reply({ error: r.error });
+          else reply({ ok: true, file: r.file, name: r.name, dependent_on: r.dependent_on, already: r.already === true });
+        });
+      }
+      if (cmd.type === "csl_remove") {
+        const r = cslRemove(here, policy, env, cmd.file);
+        if (r.ok !== true) reply({ error: r.error }); else reply({ ok: true, file: r.file });
+        return undefined;
+      }
+
+      // csl_place: the style beside the document, as a .bib sits beside a .tex
+      // — what makes `csl: apa.csl` in the front matter render the same style
+      // with no CarmaR present. A dependent style's parent goes too, or pandoc
+      // would go looking for it. NEVER overwrites: a different file of that
+      // name beside the document is the author's, and is reported.
+      const style = cslResolve(here, policy, env, cmd.name);
+      if (style == null || !style) { reply({ error: "csl_place: that style is not one this kernel has." }); return undefined; }
+      const dir = cmd.dir;
+      if (!scalarChr(dir) || !isDir(dir)) { reply({ error: "csl_place: `dir` must be an existing folder." }); return undefined; }
+      const parent = cslEnginePath(here, policy, env, style);
+      if (parent == null) { reply({ error: "csl_place: that style depends on a parent style that is not on this machine." }); return undefined; }
+      const sources = [...new Set([style, parent])];
+      const target = fs.realpathSync(dir);
+      let placed = false;
+      for (const src of sources) {                    // two files at most
+        const dest = path.join(target, path.basename(src));
+        if (fs.existsSync(dest)) {
+          if (sameBytes(dest, src)) continue;
+          reply({ error: `A different ${path.basename(src)} already sits beside the document; it was left alone.` });
+          return undefined;
+        }
+        try { fs.copyFileSync(src, dest, fs.constants.COPYFILE_EXCL); }
+        catch { reply({ error: "csl_place: the copy failed." }); return undefined; }
+        placed = true;
+      }
+      reply({ ok: true, path: path.join(target, path.basename(style)), placed });
+      return undefined;
+    },
+  };
+}
+
+const isDir = (p) => { try { return fs.statSync(p).isDirectory(); } catch { return false; } };
+const sameBytes = (a, b) => {
+  try { return fs.readFileSync(a).equals(fs.readFileSync(b)); } catch { return false; }
+};