justskill-design 0.0.1 → 3.2.0

package/lib/node/static.mjs

@@ -0,0 +1,206 @@
+/**
+ * lib/node/static.mjs — the served-file whitelist for the canvas service.
+ *
+ * Two rules, and they are the whole file:
+ *
+ *   1. A route is a KEY in a Map, and a request path is only ever *looked up* in
+ *      it. A request therefore never becomes a filesystem path, which is why
+ *      `/lib/../package.json`, `/lib/%2e%2e%2fpackage.json` and every other
+ *      escaping spelling miss the table instead of escaping a directory.
+ *   2. The table is built from two literal sources: the list below, and a
+ *      listing of three literal directories (`canvas/`, `lib/`, `lib/readers/`).
+ *      Nothing under `lib/node/` is ever listed — those modules import `node:*`
+ *      and must never cross the wire — and no request can add an entry.
+ *
+ * The browser parses the design file itself, so `lib/parse.mjs`, `lib/render.mjs`
+ * and their neighbours are imported by the canvas as ES modules. That is why the
+ * route list is explicit: the canvas can only fetch what this file names.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+/** The repository root: `lib/node/static.mjs` → `../../`. */
+export const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
+
+/** The canvas shell. `/` and this file are the same asset. */
+export const SHELL_ROUTE = "/";
+export const SHELL_FILE = "canvas/index.html";
+
+/**
+ * The explicit table: route → path relative to the package root.
+ *
+ * Every target here exists, and `test/serve.test.mjs` holds it that way: a route whose
+ * file is not written yet belongs in `PLACEHOLDER_ROUTES`, where it answers 404 and says
+ * so. Listing a missing file here used to be allowed — it 404s the same way — but then
+ * the table could not be read as a promise, and nothing told the difference between "the
+ * module landed" and "the module was renamed".
+ *
+ * The canvas modules listed are the names the canvas agent is known to use; the directory
+ * listing in `buildRoutes` picks up any others it adds. That listing covers all of `lib/`,
+ * so an entry here is documentation rather than a requirement: a module the canvas imports
+ * is served whether or not it has a line in this table. Nothing needs a line added to
+ * become reachable, and no test would fail if one were left out.
+ */
+export const STATIC_ROUTES = new Map([
+  [SHELL_ROUTE, SHELL_FILE],
+  ["/canvas/index.html", "canvas/index.html"],
+  ["/canvas/styles.css", "canvas/styles.css"],
+  ["/canvas/app.mjs", "canvas/app.mjs"],
+
+  // The browser-side modules of the format. The design rule is that the canvas
+  // parses and renders the file itself, so it imports these directly.
+  ["/lib/parse.mjs", "lib/parse.mjs"],
+  ["/lib/serialize.mjs", "lib/serialize.mjs"],
+  ["/lib/render.mjs", "lib/render.mjs"],
+  ["/lib/table.mjs", "lib/table.mjs"],
+  ["/lib/validate.mjs", "lib/validate.mjs"],
+  ["/lib/geometry.mjs", "lib/geometry.mjs"],
+  ["/lib/normalize.mjs", "lib/normalize.mjs"],
+  ["/lib/diagnostics.mjs", "lib/diagnostics.mjs"],
+  ["/lib/spans.mjs", "lib/spans.mjs"],
+  ["/lib/detect.mjs", "lib/detect.mjs"],
+  ["/lib/levenshtein.mjs", "lib/levenshtein.mjs"],
+  ["/lib/ops.mjs", "lib/ops.mjs"],
+  ["/lib/fragment.mjs", "lib/fragment.mjs"],
+  ["/lib/receipt.mjs", "lib/receipt.mjs"],
+  ["/lib/tokens.mjs", "lib/tokens.mjs"],
+  ["/lib/icons.mjs", "lib/icons.mjs"],
+  ["/lib/readers/pen.mjs", "lib/readers/pen.mjs"],
+]);
+
+/**
+ * Routes with no file behind them yet.
+ *
+ * They answer 404 like any unlisted path, and they are listed because the contract names
+ * them: a reader of this file learns which modules are planned, and `test/serve.test.mjs`
+ * requires every entry here to still be missing, so one that lands has to move up into
+ * `STATIC_ROUTES` instead of quietly working.
+ *
+ * Empty on purpose. `lib/pointer.mjs` (RFC 6901 helpers, seventy lines nobody called) was
+ * in the real table and is gone; the entries that were waiting here — `lib/icons.mjs` and
+ * `lib/readers/pen.mjs` — both landed.
+ */
+export const PLACEHOLDER_ROUTES = new Map([]);
+
+/**
+ * Directories that are listed at start-up, literally.
+ *
+ * `lib/` is listed without recursion, so `lib/node/` stays unreachable. A file
+ * is only added when its name is a plain file name (no separators, no leading
+ * dot) and its resolved path stays inside the package root.
+ */
+export const SCANNED_DIRS = ["canvas", "lib", "lib/readers"];
+
+/** A plain file name: the only shape a scanned entry may have. */
+const SAFE_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+/** True when `file` is `root` itself or lives under it, symlinks included. */
+export function isInside(root, file) {
+  const base = path.resolve(String(root));
+  const target = path.resolve(String(file));
+  if (target !== base && !target.startsWith(base + path.sep)) return false;
+  try {
+    const real = fs.realpathSync(target);
+    if (real !== base && !real.startsWith(base + path.sep)) return false;
+  } catch {
+    // The file does not exist yet. The path check above already holds, and the
+    // route is re-checked at serve time, so a later symlink cannot slip through.
+  }
+  return true;
+}
+
+/**
+ * Build the served map: the explicit table first, then whatever the three
+ * literal directories hold. A request never contributes an entry.
+ *
+ * @param {string} [root] the package root, for tests that serve another tree
+ * @returns {Map<string, string>} route → absolute file path
+ */
+export function buildRoutes(root = PACKAGE_ROOT) {
+  const base = path.resolve(root);
+  const routes = new Map();
+
+  for (const [route, relative] of STATIC_ROUTES) {
+    const file = path.resolve(base, relative);
+    if (isInside(base, file)) routes.set(route, file);
+  }
+
+  for (const dir of SCANNED_DIRS) {
+    let entries;
+    try {
+      entries = fs.readdirSync(path.join(base, dir), { withFileTypes: true });
+    } catch {
+      continue; // the directory does not exist yet
+    }
+    for (const entry of entries) {
+      if (!entry.isFile()) continue; // no subdirectories, so lib/node/ stays out
+      if (!SAFE_NAME.test(entry.name)) continue;
+      const relative = `${dir}/${entry.name}`;
+      const route = `/${relative}`;
+      if (routes.has(route)) continue; // the explicit table wins
+      const file = path.resolve(base, relative);
+      if (!isInside(base, file)) continue;
+      routes.set(route, file);
+    }
+  }
+
+  return routes;
+}
+
+/**
+ * Resolve a request path against the map. A miss is `null`, never a path.
+ *
+ * The path arrives percent-encoded; it is decoded once so an escaped name still
+ * matches an entry, and then it is only used as a Map key. A decoded `..`, a
+ * backslash or a NUL simply does not match anything.
+ *
+ * @param {Map<string, string>} routes
+ * @param {string} pathname
+ * @returns {{route: string, file: string} | null}
+ */
+export function routeFor(routes, pathname) {
+  if (!routes || typeof pathname !== "string" || pathname === "") return null;
+  let decoded;
+  try {
+    decoded = decodeURIComponent(pathname);
+  } catch {
+    return null; // a malformed escape is not a route
+  }
+  if (decoded.includes("\0") || decoded.includes("\\")) return null;
+  const file = routes.get(decoded);
+  return file ? { route: decoded, file } : null;
+}
+
+const CONTENT_TYPES = {
+  ".html": "text/html; charset=utf-8",
+  ".htm": "text/html; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".mjs": "text/javascript; charset=utf-8",
+  ".js": "text/javascript; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".map": "application/json; charset=utf-8",
+  ".svg": "image/svg+xml",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".webp": "image/webp",
+  ".ico": "image/x-icon",
+  ".woff": "font/woff",
+  ".woff2": "font/woff2",
+  ".ttf": "font/ttf",
+  ".txt": "text/plain; charset=utf-8",
+};
+
+/**
+ * The MIME type for a served file. `.mjs` must be a JavaScript type or the
+ * browser refuses the module.
+ *
+ * @param {string} file
+ * @returns {string}
+ */
+export function contentTypeOf(file) {
+  return CONTENT_TYPES[path.extname(String(file)).toLowerCase()] || "application/octet-stream";
+}

package/lib/node/verbs/add.mjs

@@ -0,0 +1,220 @@
+/**
+ * `node design.mjs add <file> --html-file f | --html - [--in <parent>] [--as <id>] [--index n]`
+ *
+ * The modifier. This is the path a model uses: it writes an HTML fragment, the
+ * tool checks it, and only then does a byte of the file move.
+ *
+ * The funnel, in order:
+ *
+ *   1. read the file again            (another writer may have changed it)
+ *   2. validate it                    (so a pre-existing error is not blamed here)
+ *   3. compile the fragment to one op (parse, check, normalize, name, index)
+ *   4. apply the op
+ *   5. validate again, and refuse unless the edit made no NEW error
+ *   6. normalize the changed nodes only, then write atomically
+ *   7. print the receipt
+ *
+ * Step 5 is the important one. A file may already have errors: the model is
+ * allowed to fix one of them, and it is not allowed to add another. Refusing on
+ * any error at all would make a broken file impossible to repair through this
+ * tool.
+ */
+
+import process from "node:process";
+
+import {
+  CliError, EXIT_INVALID, EXIT_OK, SHARED_FLAGS, out, parseArgs, readDesignFile, loadExport,
+} from "../cli.mjs";
+import { readText, writeAtomic, revisionOf } from "../fs.mjs";
+import { refusedReceipt } from "../write-verbs.mjs";
+
+export const USAGE = `Usage: node design.mjs add <file> [options]
+
+  --html-file <path>   read the fragment from a file
+  --html -             read the fragment from stdin
+  --in <data-id>       the parent to insert into (default: the resolved page;
+                       a page fragment goes into <body>)
+  --page <data-id>     the page to insert into (default: inferred from --in,
+                       else the last page)
+  --as <data-id>       rename the fragment's root to this id
+  --index <n>          insert at this position (default: last)
+  --force              write even when the edit introduces a new error
+  --dry-run            compile and validate, print the receipt, write nothing
+  --json               print the receipt as JSON
+  --quiet              print nothing
+
+Exit codes: 0 added, 1 refused or invalid, 2 unreadable or bad arguments.`;
+
+async function readFragment(values) {
+  if (values["html-file"]) {
+    const text = readText(values["html-file"]);
+    return { html: text, from: values["html-file"] };
+  }
+  if (values.html === "-" || values.html === true) {
+    const chunks = [];
+    for await (const chunk of process.stdin) chunks.push(chunk);
+    return { html: Buffer.concat(chunks).toString("utf8"), from: "stdin" };
+  }
+  if (typeof values.html === "string") return { html: values.html, from: "--html" };
+  throw new CliError(
+    "No fragment given.",
+    EXIT_INVALID,
+    "cli/no-fragment",
+    "Use --html-file <path>, or --html - to read from stdin.",
+  );
+}
+
+export default async function run(argv) {
+  const { values, positionals } = parseArgs(argv, {
+    flags: {
+      ...SHARED_FLAGS,
+      html: { type: "string" },
+      "html-file": { type: "string" },
+      in: { type: "string" },
+      as: { type: "string" },
+      index: { type: "string" },
+      page: { type: "string" },
+    },
+    positionals: { min: 1, max: 1 },
+    usage: USAGE,
+  });
+
+  if (values.help) {
+    out(USAGE);
+    return EXIT_OK;
+  }
+
+  const file = positionals[0];
+  const fragment = await readFragment(values);
+  const loaded = await readDesignFile(file);
+
+  const compileFragment = await loadExport("fragment.mjs", ["compileFragment"], "compileFragment");
+  const validateDesign = await loadExport("validate.mjs", ["validateDesign"], "validateDesign");
+  const newErrors = await loadExport("validate.mjs", ["newErrors"], "newErrors");
+  const applyOps = await loadExport("ops.mjs", ["applyOps"], "applyOps");
+  const serialize = await loadExport("serialize.mjs", ["serialize"], "serialize");
+
+  const before = validateDesign(loaded.doc);
+
+  // The parent is the fragment compiler's decision, not this verb's. A page
+  // fragment with no `--in` belongs in `<body>`; anything else belongs in the
+  // resolved page (`--page` or `--in` names it, else the last page). Pre-filling
+  // `--in` with the first page made the CLI refuse the exact command the
+  // compiler documents — and the refusal's own hint says "Send the page without
+  // in" — so the default lives in one place now.
+  const compiled = compileFragment(loaded.doc, fragment.html, {
+    in: values.in,
+    as: values.as,
+    index: values.index === undefined ? undefined : Number(values.index),
+    page: values.page,
+  });
+
+  if (compiled.refused) {
+    return refuse(compiled, values, file);
+  }
+
+  const { doc: next, inverse } = applyOps(loaded.doc, compiled.ops);
+  const after = validateDesign(next);
+  const introduced = newErrors(before, after);
+
+  if (introduced.length && !values.force) {
+    const receipt = {
+      ok: false,
+      verb: "add",
+      applied: [],
+      added: [],
+      normalized: compiled.normalized,
+      dropped: compiled.dropped,
+      diagnostics: introduced,
+      revision: loaded.revision,
+      changed: false,
+    };
+    return refuse({ ...compiled, diagnostics: introduced, refused: { code: "cli/would-introduce-errors", message: "This edit would introduce a new error." } }, values, file, receipt);
+  }
+
+  const text = serialize(loaded.doc, next);
+
+  if (values["dry-run"]) {
+    const receipt = buildReceipt(compiled, { revision: revisionOf(text), changed: text !== loaded.text, inv: inverse, diagnostics: after });
+    print(receipt, values, file);
+    return EXIT_OK;
+  }
+
+  writeAtomic(file, text);
+  const receipt = buildReceipt(compiled, { revision: revisionOf(text), changed: text !== loaded.text, inverse, diagnostics: after });
+  print(receipt, values, file);
+  return EXIT_OK;
+}
+
+function buildReceipt(compiled, extra) {
+  return {
+    ok: true,
+    verb: "add",
+    applied: compiled.ops,
+    added: compiled.added,
+    normalized: compiled.normalized,
+    dropped: compiled.dropped,
+    // The file's diagnostics after the write, not the fragment's. `set` reports
+    // the file's, and the two must answer the same question the same way: a
+    // receipt that says "0 warnings" about a file that has 22 of them tells the
+    // model the opposite of the truth, and the receipt is all the model sees.
+    diagnostics: extra.diagnostics ?? compiled.diagnostics,
+    revision: extra.revision,
+    changed: extra.changed,
+  };
+}
+
+function print(receipt, values, file) {
+  if (values.json) {
+    out(JSON.stringify(receipt));
+    return;
+  }
+  const lines = [];
+  if (receipt.added.length) lines.push(`added:      ${receipt.added.join(", ")}  (${receipt.added.length} elements)`);
+  for (const item of receipt.normalized) lines.push(`normalized: ${item.from} → ${item.to}`);
+  for (const item of receipt.dropped) {
+    lines.push(`dropped:    ${item.prop}${item.value === undefined ? "" : `:${item.value}`} — ${item.reason}`);
+    if (item.replacement) lines.push(`            use ${item.replacement}`);
+  }
+  lines.push(`applied ${receipt.applied.length} op, revision ${receipt.revision} (${receipt.diagnostics.filter((d) => d.severity === "error").length} errors, ${receipt.diagnostics.filter((d) => d.severity === "warning").length} warnings)`);
+  out(lines.join("\n"), { quiet: values.quiet });
+}
+
+function refuse(compiled, values, file, receipt) {
+  // The JSON payload carries the same `refused` block the human text prints.
+  //
+  // It used to carry neither: a refusal from the compiler produced
+  // `{ok:false, applied:[], changed:false}` with no code and no message, so a caller
+  // reading `--json` could not tell "refused because the fragment declares a
+  // `<label data-type="text">`" from "the edit happened to change nothing". The human
+  // branch read `compiled.refused` and said `REFUSED …`, so the two readers of the same
+  // result disagreed about what happened. Format-v3 §6 and `lib/receipt.mjs` R2 both say
+  // a failure carries the block.
+  const refusal = compiled.refused || { code: "cli/refused", message: "Refused." };
+  const payload = receipt || {
+    ...refusedReceipt("add", refusal.message, {
+      code: refusal.code,
+      hint: refusal.hint,
+      suggestion: refusal.suggestion,
+      diagnostics: compiled.diagnostics,
+    }),
+    normalized: compiled.normalized,
+    dropped: compiled.dropped,
+  };
+  if (values.json) {
+    out(JSON.stringify(payload));
+  } else {
+    const lines = [`REFUSED  ${refusal.message}`];
+    if (refusal.hint) lines.push(`  ${refusal.hint}`);
+    if (refusal.suggestion) lines.push(`  ${refusal.suggestion}`);
+    for (const item of compiled.dropped) lines.push(`  dropped: ${item.prop} — ${item.reason}`);
+    for (const d of payload.diagnostics) {
+      if (d.severity !== "error") continue;
+      lines.push(`  error: ${d.code}${d.target ? ` at ${d.target}` : ""} — ${d.message}`);
+      if (d.hint) lines.push(`         ${d.hint}`);
+    }
+    lines.push(`${file} was not changed.`);
+    out(lines.join("\n"));
+  }
+  return EXIT_INVALID;
+}

package/lib/node/verbs/export.mjs

@@ -0,0 +1,161 @@
+/**
+ * `node design.mjs export <file> [--page <id>] [--all] [-o path] [--resolve-tokens]`
+ *
+ * A deliverable, not a design file. The output is a page a browser renders on
+ * its own: the design's markup and inline styles, the token block so the custom
+ * properties still resolve, and a viewport sized to the page.
+ *
+ * `--all` writes one file per page.
+ */
+
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+
+import { CliError, EXIT_INVALID, EXIT_OK, SHARED_FLAGS, out, parseArgs, readDesignFile } from "../cli.mjs";
+
+export const USAGE = `Usage: node design.mjs export <file> [options]
+
+  --page <data-id>     export this page (default: the first page)
+  --all                write one file per page
+  --format <name>      html (default), svg, png, jpeg or webp
+  -o, --out <path>     output file, or output directory with --all
+  --scale <n>          image scale, 1 to 3 (image formats)
+  --size WxH           override the image size (image formats)
+  --raster auto|chrome use a headless browser (default: auto)
+  --resolve-tokens     bake token values into the styles and drop the token block
+  --stdout             print the HTML instead of writing a file
+  --json               print a report as JSON
+  --quiet              print nothing
+
+Exit codes: 0 written, 1 refused, 2 unreadable or bad arguments.
+
+Only pages can be exported as HTML. A deliverable is a page or a site, not a
+subtree; use \`show <data-id>\` to read one element.`;
+
+export default async function run(argv) {
+  const { values, positionals } = parseArgs(argv, {
+    flags: {
+      ...SHARED_FLAGS,
+      page: { type: "string" },
+      all: { type: "boolean" },
+      out: { type: "string", alias: ["o"] },
+      "resolve-tokens": { type: "boolean" },
+      format: { type: "string" },
+      scale: { type: "string" },
+      size: { type: "string" },
+      raster: { type: "string" },
+      stdout: { type: "boolean" },
+      "keep-comments": { type: "boolean" },
+    },
+    positionals: { min: 1, max: 1 },
+    usage: USAGE,
+  });
+
+  if (values.help) {
+    out(USAGE);
+    return EXIT_OK;
+  }
+
+  const file = positionals[0];
+  const loaded = await readDesignFile(file);
+  const module = await import("../../export-html.mjs");
+  const options = {
+    page: values.page,
+    resolveTokens: values["resolve-tokens"] === true,
+    keepComments: values["keep-comments"] === true,
+  };
+
+  const outPath = values.out ?? values.o;
+
+  if (values.all) {
+    let results;
+    try {
+      results = module.exportAllPages(loaded.doc, options);
+    } catch (error) {
+      return refuse(error);
+    }
+    const dir = resolve(outPath ?? "dist");
+    mkdirSync(dir, { recursive: true });
+    const written = [];
+    for (const item of results) {
+      const target = join(dir, item.file);
+      writeFileSync(target, item.html, "utf8");
+      written.push({ file: target, page: item.page.id, bytes: Buffer.byteLength(item.html) });
+    }
+    report(written, values, `${written.length} page${written.length === 1 ? "" : "s"} written to ${dir}`);
+    return EXIT_OK;
+  }
+
+  let result;
+  try {
+    result = module.exportPage(loaded.doc, options);
+  } catch (error) {
+    return refuse(error);
+  }
+
+  const format = String(values.format ?? "html").toLowerCase();
+  if (format !== "html") {
+    return exportOtherFormat({ format, result, file, values, outPath, options });
+  }
+
+  if (values.stdout) {
+    process.stdout.write(result.html);
+    return EXIT_OK;
+  }
+
+  const target = resolve(outPath ?? `${result.page.id}.html`);
+  mkdirSync(dirname(target), { recursive: true });
+  writeFileSync(target, result.html, "utf8");
+  report([{ file: target, page: result.page.id, bytes: Buffer.byteLength(result.html) }], values, `${file} → ${target} (${result.page.id}, ${Buffer.byteLength(result.html)} bytes)`);
+  return EXIT_OK;
+}
+
+/**
+ * Everything that is not HTML.
+ *
+ * `svg` needs no browser: the page is wrapped in `<svg><foreignObject>`, which
+ * browsers render and other tools generally do not. The raster formats need a
+ * browser, and when none can be found the command FAILS rather than writing a
+ * different format than the one that was asked for.
+ */
+async function exportOtherFormat({ format, result, file, values, outPath, options }) {
+  const module = await import("../export-svg.mjs");
+  const target = resolve(outPath ?? `${result.page.id}.${format}`);
+
+  let written;
+  try {
+    written = await module.exportFile({
+      html: result.html,
+      page: result.page,
+      format,
+      out: target,
+      scale: values.scale === undefined ? 1 : Number(values.scale),
+      size: values.size,
+      raster: values.raster,
+      tmpDir: resolve(".justskill-design-tmp"),
+    });
+  } catch (error) {
+    return refuse(error);
+  }
+
+  report(
+    [{ file: written.path, page: result.page.id, bytes: written.bytes, route: written.route }],
+    values,
+    `${file} → ${written.path} (${result.page.id}, ${format}, ${written.bytes} bytes${written.route ? `, via ${written.route}` : ""})`,
+  );
+  return EXIT_OK;
+}
+
+function report(written, values, line) {
+  if (values.json) {
+    out(JSON.stringify({ ok: true, verb: "export", written }));
+    return;
+  }
+  out(line, { quiet: values.quiet });
+}
+
+function refuse(error) {
+  const hint = error.hint ? `\n  ${error.hint}` : "";
+  out(`REFUSED  ${error.message}${hint}`);
+  return EXIT_INVALID;
+}

package/lib/node/verbs/format.mjs

@@ -0,0 +1,106 @@
+/**
+ * `node design.mjs format <file> [--check] [--dry-run]` — canonical text.
+ *
+ * `lib/normalize.mjs` decides what has to change; `lib/serialize.mjs` renders
+ * the result. `--check` writes nothing and exits 1 when the file is not
+ * canonical, which is what CI and a pre-commit hook use.
+ */
+
+import process from "node:process";
+
+import { EXIT_INVALID, EXIT_OK, SHARED_FLAGS, loadExport, out, parseArgs, readDesignFile } from "../cli.mjs";
+import { writeAtomic } from "../fs.mjs";
+
+export const USAGE = `Usage: node design.mjs format <file> [options]
+
+  --check     write nothing; exit 1 when the file is not canonical
+  --dry-run   print the canonical text and write nothing
+  --json      print one line of JSON instead of a human line
+  --quiet     print nothing on success
+  --help      print this usage
+
+Exit codes: 0 canonical, 1 not canonical, 2 unreadable.`;
+
+/**
+ * Run both normalization layers and return the text to write.
+ *
+ * Layer one is semantic and lives in `lib/normalize.mjs`; it edits the document
+ * in place. Layer two is textual — LF line endings, one final newline — and is
+ * applied to the serialized result. `changed` is decided by comparing the final
+ * text with what is on disk, never by trusting a flag: that way a file whose
+ * only problem is a CRLF still counts as changed.
+ */
+async function normalize(loaded) {
+  const serialize = await loadExport("serialize.mjs", ["serialize", "default"], "serialize");
+  const normalizeDocument = await loadExport(
+    "normalize.mjs",
+    ["normalizeDocument", "normalize", "default"],
+    "normalizeDocument",
+  );
+  const normalizeText = await loadExport("normalize.mjs", ["normalizeText"], "normalizeText");
+
+  // `serialize(origin, next)` diffs `next` against the `_raw` snapshots on the
+  // document that was read, which is what keeps the edit minimal.
+  const produced = await normalizeDocument(loaded.doc, {
+    file: loaded.file,
+    text: loaded.text,
+    format: loaded.format,
+    serialize: (origin, next) => serialize(origin, next),
+  });
+
+  const nextDoc = produced && typeof produced === "object" && produced.doc ? produced.doc : produced;
+  if (!nextDoc || typeof nextDoc !== "object") {
+    throw new Error("normalizeDocument() returned no document");
+  }
+
+  let text = produced && typeof produced.text === "string" ? produced.text : serialize(loaded.doc, nextDoc);
+  if (typeof text !== "string") text = loaded.text;
+
+  const layered = normalizeText(text);
+  text = typeof layered === "string" ? layered : layered && typeof layered.text === "string" ? layered.text : text;
+
+  return { text, changed: text !== loaded.text };
+}
+
+export default async function run(argv) {
+  const { values, positionals } = parseArgs(argv, {
+    flags: { ...SHARED_FLAGS, check: { type: "boolean" } },
+    positionals: { min: 1, max: 1 },
+    usage: USAGE,
+  });
+
+  if (values.help) {
+    out(USAGE);
+    return EXIT_OK;
+  }
+
+  const file = positionals[0];
+  const loaded = await readDesignFile(file);
+  const { text, changed } = await normalize(loaded);
+  const canonical = !changed && text === loaded.text;
+
+  if (values.check) {
+    if (values.json) {
+      out(JSON.stringify({ file, canonical, changed: !canonical, revision: loaded.revision }));
+    } else {
+      out(`${file}: ${canonical ? "canonical" : "not canonical"}`);
+    }
+    return canonical ? EXIT_OK : EXIT_INVALID;
+  }
+
+  if (values["dry-run"]) {
+    // The dry run's whole value is the text, so it prints even under --quiet.
+    process.stdout.write(text.endsWith("\n") ? text : `${text}\n`);
+    out(`${file}: ${canonical ? "already canonical" : "would change"}`, { quiet: values.quiet });
+    return EXIT_OK;
+  }
+
+  if (canonical) {
+    out(`${file}: already canonical`, { quiet: values.quiet });
+    return EXIT_OK;
+  }
+
+  const written = writeAtomic(file, text);
+  out(`${file}: formatted (${written.bytes} bytes)`, { quiet: values.quiet });
+  return EXIT_OK;
+}