justskill-design 0.0.1 → 3.2.0

package/lib/node/export-svg.mjs

@@ -0,0 +1,75 @@
+/**
+ * lib/node/export-svg.mjs — the half of image export that touches the machine.
+ *
+ * `lib/export-svg.mjs` builds an SVG document and decides how big a page renders; this
+ * writes bytes and may start a browser. The split is a purity boundary, not a taste
+ * boundary: every file directly under `lib/` is served to the canvas over HTTP, so a
+ * module that imports `node:fs` is a module the browser downloads and then dies on. The
+ * old single file dodged that with `await import("node:fs")` inside a function — which
+ * works, and hides the violation from a reader and from every check that looks at the top
+ * of a file.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+
+import { ExportFormatError, clampScale, pageToSvg, renderSize } from "../export-svg.mjs";
+
+/** A filename-safe fragment of a page id, for the intermediate file. */
+function slug(value) {
+  return String(value).replace(/[^A-Za-z0-9_-]/g, "-").slice(0, 40) || "page";
+}
+
+/**
+ * Write one export in whatever format was asked for.
+ *
+ * The format decision itself lives in `lib/raster.mjs`, which is why a missing browser
+ * produces a refusal naming the alternatives rather than a silent substitution.
+ *
+ * @param {object} options `{ html, page, format, out, scale, size, raster, tmpDir }`
+ */
+export async function exportFile(options) {
+  const format = String(options.format).toLowerCase();
+  const out = options.out;
+
+  fs.mkdirSync(path.dirname(out), { recursive: true });
+
+  if (format === "svg") {
+    const svg = pageToSvg(options);
+    fs.writeFileSync(out, svg, "utf8");
+    return { path: out, bytes: Buffer.byteLength(svg), route: null };
+  }
+
+  if (!["png", "jpeg", "jpg", "webp"].includes(format)) {
+    throw new ExportFormatError(
+      "export/unknown-format",
+      `There is no ${format} writer.`,
+      "Formats: html, svg, png, jpeg, webp, pen.",
+    );
+  }
+
+  // Everything below needs pixels, so the HTML has to exist somewhere the browser can
+  // open it.
+  const workDir = options.tmpDir ?? path.join(process.cwd(), ".justskill-design-tmp");
+  fs.mkdirSync(workDir, { recursive: true });
+  const htmlPath = path.join(workDir, `${slug(options.page?.id ?? "page")}-${Date.now()}.html`);
+  fs.writeFileSync(htmlPath, options.html, "utf8");
+
+  const { width, height } = renderSize(options.page, options.size);
+  const { renderToImage } = await import("./raster-run.mjs");
+  try {
+    const result = await renderToImage({
+      htmlPath,
+      outPath: out,
+      width,
+      height,
+      scale: clampScale(options.scale),
+      raster: options.raster,
+      canvasOnline: options.canvasOnline === true,
+    });
+    return { path: result.path, bytes: result.bytes, route: `${result.route} (${result.browser})` };
+  } finally {
+    // The intermediate page is scaffolding, not a deliverable.
+    try { fs.rmSync(htmlPath, { force: true }); } catch { /* best effort */ }
+  }
+}

package/lib/node/fs.mjs

@@ -0,0 +1,309 @@
+/**
+ * Node-only file helpers: reading, atomic writing, hashing, watching.
+ *
+ * This module and the rest of `lib/node/` are the only places that import
+ * `node:*`. Keep it that way — the browser canvas imports the other `lib/`
+ * modules directly.
+ *
+ * Every failure is an `FsError` with a code the CLI can map to an exit code:
+ * `fs/not-found`, `fs/unreadable`, `fs/no-write`.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+
+export const MIN_NODE_MAJOR = 18;
+
+export class FsError extends Error {
+  /**
+   * @param {string} code  `fs/not-found` | `fs/unreadable` | `fs/no-write` | …
+   * @param {string} message
+   * @param {string} [file]
+   */
+  constructor(code, message, file) {
+    super(message);
+    this.name = "FsError";
+    this.code = code;
+    if (file !== undefined) this.file = file;
+  }
+}
+
+function errnoOf(error) {
+  return error && typeof error.code === "string" ? error.code : "";
+}
+
+/** Node's major version, as a number. */
+export function nodeMajor(version = process.versions.node) {
+  return Number(String(version).split(".")[0]);
+}
+
+/** True when the runtime is new enough for this tool. */
+export function nodeVersionOk(version = process.versions.node) {
+  return nodeMajor(version) >= MIN_NODE_MAJOR;
+}
+
+/** Throw when the runtime is too old. */
+export function assertNodeVersion() {
+  if (nodeVersionOk()) return;
+  throw new FsError(
+    "fs/node-version",
+    `justSkill needs Node ${MIN_NODE_MAJOR} or newer, but this is Node ${process.versions.node}.\n` +
+      "Install a current Node release (https://nodejs.org) and run the command again.",
+  );
+}
+
+/**
+ * Read a text file.
+ *
+ * @param {string} file
+ * @returns {string}
+ * @throws {FsError} `fs/not-found` when it does not exist, `fs/unreadable`
+ *   otherwise (a directory, a permission problem, a broken link)
+ */
+export function readText(file) {
+  try {
+    return fs.readFileSync(file, "utf8");
+  } catch (error) {
+    const errno = errnoOf(error);
+    if (errno === "ENOENT" || errno === "ENOTDIR") {
+      throw new FsError("fs/not-found", `No such file: ${file}`, file);
+    }
+    if (errno === "EISDIR") {
+      throw new FsError("fs/unreadable", `Cannot read ${file}: it is a directory`, file);
+    }
+    if (errno === "EACCES") {
+      throw new FsError("fs/unreadable", `Cannot read ${file}: permission denied`, file);
+    }
+    throw new FsError("fs/unreadable", `Cannot read ${file}: ${error.message}`, file);
+  }
+}
+
+/** True when anything exists at `file` (a file or a directory). */
+export function fileExists(file) {
+  try {
+    fs.statSync(file);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The content hash of a text: the first 8 hex digits of sha256.
+ *
+ * Short on purpose — it labels a revision in a message, it does not guard a
+ * download.
+ *
+ * @param {string} text
+ * @returns {string}
+ */
+export function hashText(text) {
+  return crypto.createHash("sha256").update(String(text), "utf8").digest("hex").slice(0, 8);
+}
+
+/**
+ * The revision of a design file's text.
+ *
+ * Accepts a string, and tolerates a document object by hashing its `source` —
+ * the text the document was parsed from.
+ *
+ * @param {string|{source?: string}} text
+ * @returns {string}
+ */
+export function revisionOf(text) {
+  if (typeof text === "string") return hashText(text);
+  if (text && typeof text.source === "string") return hashText(text.source);
+  return hashText(String(text));
+}
+
+/**
+ * Write `text` to `file` atomically: write a sibling temp file, fsync it,
+ * rename it over the target. A rename within one directory is atomic on POSIX,
+ * so a reader never sees a half-written design file, and the file's mode is the
+ * usual 0644 whatever the process umask says.
+ *
+ * @param {string} file
+ * @param {string} text
+ * @returns {{file: string, bytes: number}}
+ * @throws {FsError} `fs/no-write`
+ */
+export function writeAtomic(file, text) {
+  const target = String(file);
+  const dir = path.dirname(target);
+  const base = path.basename(target);
+  const tmp = path.join(dir, `.${base}.tmp-${process.pid}-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`);
+  const body = String(text);
+
+  let fd = null;
+  try {
+    fd = fs.openSync(tmp, "wx", 0o644);
+    fs.writeFileSync(fd, body, "utf8");
+    fs.fsyncSync(fd);
+    fs.closeSync(fd);
+    fd = null;
+    fs.renameSync(tmp, target);
+  } catch (error) {
+    if (fd !== null) {
+      try {
+        fs.closeSync(fd);
+      } catch {
+        /* the descriptor may already be gone */
+      }
+    }
+    try {
+      fs.unlinkSync(tmp);
+    } catch {
+      /* the temp file may never have been created */
+    }
+    const errno = errnoOf(error);
+    if (errno === "ENOENT") {
+      throw new FsError("fs/no-write", `Cannot write ${target}: no such directory ${dir}`, target);
+    }
+    if (errno === "EACCES" || errno === "EPERM" || errno === "EROFS") {
+      throw new FsError("fs/no-write", `Cannot write ${target}: permission denied`, target);
+    }
+    if (errno === "EISDIR") {
+      throw new FsError("fs/no-write", `Cannot write ${target}: it is a directory`, target);
+    }
+    throw new FsError("fs/no-write", `Cannot write ${target}: ${error.message}`, target);
+  }
+
+  return { file: target, bytes: Buffer.byteLength(body, "utf8") };
+}
+
+/**
+ * A small line diff, enough for a CLI preview.
+ *
+ * The common prefix and suffix are found, and everything between them becomes
+ * one hunk of `-` and `+` lines with `context` unchanged lines around it. This
+ * is not a general-purpose diff: a preview of a targeted edit is what it is for.
+ *
+ * @param {string} before
+ * @param {string} after
+ * @param {string} [labelA]
+ * @param {string} [labelB]
+ * @returns {string} `""` when nothing changed
+ */
+export function unifiedDiff(before, after, labelA = "before", labelB = "after") {
+  if (labelA && typeof labelA === "object") {
+    const options = labelA;
+    labelA = options.labelA || options.label || "before";
+    labelB = options.labelB || options.label || "after";
+  }
+  const a = String(before).split("\n");
+  const b = String(after).split("\n");
+  if (String(before) === String(after)) return "";
+  const context = 3;
+
+  let head = 0;
+  while (head < a.length && head < b.length && a[head] === b[head]) head += 1;
+
+  let aEnd = a.length;
+  let bEnd = b.length;
+  while (aEnd > head && bEnd > head && a[aEnd - 1] === b[bEnd - 1]) {
+    aEnd -= 1;
+    bEnd -= 1;
+  }
+
+  const from = Math.max(0, head - context);
+  const aTo = Math.min(a.length, aEnd + context);
+  const bTo = Math.min(b.length, bEnd + context);
+
+  const lines = [
+    `--- ${labelA}`,
+    `+++ ${labelB}`,
+    `@@ -${from + 1},${aTo - from} +${from + 1},${bTo - from} @@`,
+  ];
+  for (let i = from; i < head; i += 1) lines.push(` ${a[i]}`);
+  for (let i = head; i < aEnd; i += 1) lines.push(`-${a[i]}`);
+  for (let i = head; i < bEnd; i += 1) lines.push(`+${b[i]}`);
+  for (let i = aEnd; i < aTo; i += 1) lines.push(` ${a[i]}`);
+
+  return `${lines.join("\n")}\n`;
+}
+
+/**
+ * Watch a directory, debounced.
+ *
+ * `onChange` is called at most once per 100 ms of quiet with the batch of
+ * events that arrived in that window:
+ *
+ *   onChange([{ eventType: "change", filename: "home.html", file: "/abs/home.html" }])
+ *
+ * Recursive watching is used where the platform supports it (macOS, Windows,
+ * and Linux on Node 20+) and falls back to the immediate directory otherwise.
+ *
+ * @param {string} dir
+ * @param {(events: {eventType: string, filename: string, file: string}[]) => void} onChange
+ * @returns {() => void} close the watcher
+ * @throws {FsError} `fs/not-found` / `fs/unreadable`
+ */
+export function walkWatch(dir, onChange) {
+  const root = String(dir);
+
+  // `fs.watch` reports a missing directory differently per platform: macOS
+  // throws ENOENT synchronously, Linux hands back a watcher that emits the
+  // error later. The caller cannot act on an async error, so ask the
+  // filesystem first and answer the same way everywhere.
+  try {
+    fs.statSync(root);
+  } catch (error) {
+    if (errnoOf(error) === "ENOENT") throw new FsError("fs/not-found", `No such directory: ${root}`, root);
+    throw new FsError("fs/unreadable", `Cannot watch ${root}: ${error.message}`, root);
+  }
+
+  const pending = new Map();
+  let timer = null;
+  let watcher = null;
+
+  const flush = () => {
+    timer = null;
+    const events = [...pending.values()];
+    pending.clear();
+    if (events.length === 0) return;
+    try {
+      onChange(events);
+    } catch {
+      /* a listener that throws must not kill the watcher */
+    }
+  };
+
+  const listener = (eventType, filename) => {
+    const name = filename === null || filename === undefined ? "" : String(filename);
+    pending.set(name, { eventType: String(eventType), filename: name, file: name ? path.join(root, name) : root });
+    if (timer === null) timer = setTimeout(flush, 100);
+  };
+
+  const open = (options) => fs.watch(root, options, listener);
+
+  try {
+    watcher = open({ recursive: true });
+  } catch (error) {
+    if (errnoOf(error) === "ENOENT") throw new FsError("fs/not-found", `No such directory: ${root}`, root);
+    try {
+      watcher = open({});
+    } catch (fallbackError) {
+      const errno = errnoOf(fallbackError);
+      if (errno === "ENOENT") throw new FsError("fs/not-found", `No such directory: ${root}`, root);
+      throw new FsError("fs/unreadable", `Cannot watch ${root}: ${fallbackError.message}`, root);
+    }
+  }
+
+  watcher.on("error", () => {
+    /* a watcher error is not a reason to crash the process */
+  });
+
+  return function close() {
+    if (timer !== null) {
+      clearTimeout(timer);
+      timer = null;
+    }
+    pending.clear();
+    try {
+      watcher.close();
+    } catch {
+      /* already closed */
+    }
+  };
+}

package/lib/node/op-json.mjs

@@ -0,0 +1,75 @@
+/**
+ * lib/node/op-json.mjs — an op list as it can leave this process.
+ *
+ * An op list is not JSON, and the reason is worth writing down. An inverse — the
+ * op list that undoes a gesture — carries the removed or replaced content as
+ * *live* node objects, so `applyOps` can put the exact object back: same source
+ * offsets, which is what keeps a later save minimal, same attribute order. Those
+ * objects hold `parent` links (and the serializer's `_raw` snapshot), so they
+ * close a cycle through `children` and `JSON.stringify` throws on them.
+ *
+ * Two callers need the same projection, and neither should own it: the CLI's
+ * `--json` output, and the canvas service, whose response is JSON. The server
+ * used to send `result.inverse` as it stood, which meant a *text* edit — the one
+ * op whose inverse is a whole node — wrote the file, failed to serialize the
+ * response, and answered 500; the canvas then said "Refused: internal" about an
+ * edit that had landed.
+ *
+ * Only the fields that define an op survive. A node's content is already
+ * available as its `html` bytes, so nothing a caller needs is lost, and the
+ * receipt stays a document a reader can act on.
+ */
+
+/**
+ * The fields that may survive.
+ *
+ * This is a whitelist rather than a blacklist on purpose: the point is to keep
+ * `parent` and `_raw` out, and a node carries a closed set of fields, so a
+ * whitelist cannot leak a cycle. It must include an attribute's `name` and
+ * `value`, or an inverse that reinserts a removed subtree would produce
+ * attributes with no names.
+ */
+const OP_FIELDS = new Set([
+  "op", "target", "prop", "value", "index", "html", "children", "node",
+  "kind", "raw", "tag", "attrs", "selfClosing", "before", "after", "into",
+  "name", "rawName", "quote",
+  // A token op's exact bytes. Without these the receipt would print an inverse that
+  // no longer says where a removed token came from, and re-applying it would put the
+  // declaration back at the end of the block instead of where it was read.
+  "at", "span", "restore",
+]);
+
+/**
+ * A text or comment node inside a subtree keeps its content.
+ *
+ * The op fields above are a whitelist, and a text node's content lives in
+ * `value` and `raw` — which the op's own `value` shadows, so the key has to be
+ * kept for the node's sake. Dropping these does not lose a declaration, it loses
+ * the indentation between elements, and an undo that restores the structure but
+ * not the whitespace is not an undo.
+ */
+const ALWAYS_KEEP = new Set(["value", "raw"]);
+
+/** Deep limits: a subtree is a few levels, and a cycle guard costs nothing. */
+const MAX_DEPTH = 12;
+
+export function jsonOps(ops) {
+  if (ops === undefined || ops === null) return null;
+  const walk = (value, depth) => {
+    if (depth > MAX_DEPTH) return null;
+    if (value === null || typeof value !== "object") {
+      return typeof value === "function" ? null : value;
+    }
+    if (Array.isArray(value)) return value.map((entry) => walk(entry, depth + 1));
+    const out = {};
+    for (const [key, entry] of Object.entries(value)) {
+      // `parent` closes a cycle through children; `_raw` is the parse-time
+      // snapshot, which is internal to the serializer.
+      if (key === "parent" || key === "_raw") continue;
+      if (depth > 0 && !OP_FIELDS.has(key) && !ALWAYS_KEEP.has(key)) continue;
+      out[key] = walk(entry, depth + 1);
+    }
+    return out;
+  };
+  return walk(ops, 0);
+}

package/lib/node/raster-run.mjs

@@ -0,0 +1,115 @@
+/**
+ * lib/node/raster-run.mjs — the part of rasterisation that starts a process.
+ *
+ * `lib/raster.mjs` decides; this runs. The split is what keeps the policy
+ * testable without launching a browser in a test.
+ *
+ * The browser is given a `--screenshot` path and a window size, waits for fonts,
+ * and exits. Nothing is installed and nothing is left running.
+ */
+
+import { spawn } from "node:child_process";
+import { existsSync, statSync } from "node:fs";
+import path from "node:path";
+import process from "node:process";
+
+import { findBrowser, planRaster, screenshotArgs, RasterError } from "../raster.mjs";
+
+/**
+ * The machine, as `lib/raster.mjs` needs to see it.
+ *
+ * That module is served to the canvas, so it may not import `node:fs` or read `process`.
+ * The three facts it needs to look for a browser are handed to it here instead, and this
+ * is the only place in the tree that answers them — which is what keeps "is there a
+ * browser" a policy question with one implementation.
+ */
+const MACHINE = {
+  exists: existsSync,
+  platform: process.platform,
+  which(name) {
+    for (const dir of (process.env.PATH ?? "").split(path.delimiter).filter(Boolean)) {
+      const candidate = path.join(dir, name);
+      if (existsSync(candidate)) return candidate;
+    }
+    return null;
+  },
+};
+
+/** `findBrowser` bound to this machine, in the shape `planRaster` asks for. */
+const onThisMachine = () => findBrowser(MACHINE);
+
+/**
+ * Render one HTML file to one image.
+ *
+ * @param {object} options `{ htmlPath, outPath, width, height, scale, raster, canvasOnline, timeoutMs }`
+ * @returns {Promise<{ path: string, bytes: number, route: string, browser: string }>}
+ */
+export async function renderToImage(options) {
+  const plan = planRaster(
+    { raster: options.raster, canvasOnline: options.canvasOnline },
+    { findBrowser: onThisMachine },
+  );
+
+  if (plan.route === "canvas") {
+    // The canvas is a browser that already has the page mounted. It rasterises
+    // and posts the bytes back, which is the same route the service offers for a
+    // machine with no Chrome-family browser installed.
+    throw new RasterError(
+      "raster/canvas-not-wired",
+      "The canvas route needs a canvas to be open and reachable.",
+      "Run `design.mjs serve <file>` and leave the tab open, or install a Chrome-family browser.",
+    );
+  }
+
+  const args = screenshotArgs({
+    file: options.htmlPath,
+    out: options.outPath,
+    width: options.width,
+    height: options.height,
+    scale: options.scale ?? 1,
+    budgetMs: options.budgetMs ?? 6000,
+  });
+
+  const result = await run(plan.browser.path, args, options.timeoutMs ?? 60000);
+  if (result.code !== 0 && !existsSync(options.outPath)) {
+    throw new RasterError(
+      "raster/browser-failed",
+      `${plan.browser.name} exited ${result.code} without writing an image.`,
+      result.stderr.trim().split("\n").slice(-3).join(" ") || "Run the same command by hand to see the browser's output.",
+    );
+  }
+  if (!existsSync(options.outPath)) {
+    throw new RasterError("raster/no-output", `${plan.browser.name} wrote no image.`, "Check that the page is a file the browser can open.");
+  }
+
+  return {
+    path: options.outPath,
+    bytes: statSync(options.outPath).size,
+    route: plan.route,
+    browser: plan.browser.name,
+  };
+}
+
+/** Spawn, collect, never reject on a non-zero exit: the caller reads the code. */
+function run(command, args, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, { stdio: ["ignore", "pipe", "pipe"] });
+    let stdout = "";
+    let stderr = "";
+    const timer = setTimeout(() => {
+      child.kill("SIGKILL");
+      reject(new RasterError("raster/timeout", `${command} did not finish within ${timeoutMs} ms.`, "Raise the timeout, or check the page for a request that never settles."));
+    }, timeoutMs);
+
+    child.stdout.on("data", (chunk) => { stdout += chunk; });
+    child.stderr.on("data", (chunk) => { stderr += chunk; });
+    child.on("error", (error) => {
+      clearTimeout(timer);
+      reject(new RasterError("raster/spawn-failed", `Cannot run ${command}: ${error.message}`, "Check the browser path with `which google-chrome`."));
+    });
+    child.on("close", (code) => {
+      clearTimeout(timer);
+      resolve({ code, stdout, stderr });
+    });
+  });
+}