justskill-design 0.0.1 → 3.2.0

package/lib/node/verbs/import.mjs

@@ -0,0 +1,126 @@
+/**
+ * `node design.mjs import pen <file> [-o design.html] [--report r.json]`
+ *
+ * Direction is one way, and the command says so: pen in, design file out. The
+ * ledger prints on every run, because an import that loses a gradient and says
+ * nothing is worse than one that refuses.
+ */
+
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+
+import { CliError, EXIT_INVALID, EXIT_OK, SHARED_FLAGS, loadExport, out, parseArgs } from "../cli.mjs";
+import { readText } from "../fs.mjs";
+
+export const USAGE = `Usage: node design.mjs import pen <file> [options]
+
+  -o, --out <path>     output design file (default: <name>.html)
+  --report <path>      also write the ledger as JSON
+  --title <name>       file title (default: the pen document's own name, else the file name)
+  --stdout             print the design file instead of writing it; the report goes to stderr
+  --json               print the ledger as JSON
+  --quiet              print only the ledger line
+
+Exit codes: 0 imported, 1 refused, 2 unreadable or bad arguments.
+
+The ledger names every loss and every value that was rewritten. A loss is
+something this format has no spelling for, such as a mesh gradient or an inner
+shadow. There is no HTML to pen direction.`;
+
+export default async function run(argv) {
+  const { values, positionals } = parseArgs(argv, {
+    flags: {
+      ...SHARED_FLAGS,
+      out: { type: "string", alias: ["o"] },
+      report: { type: "string" },
+      title: { type: "string" },
+      stdout: { type: "boolean" },
+    },
+    positionals: { min: 2, max: 2 },
+    usage: USAGE,
+  });
+
+  if (values.help) {
+    out(USAGE);
+    return EXIT_OK;
+  }
+
+  const [format, file] = positionals;
+  if (format !== "pen") {
+    out(`REFUSED  There is no ${format} reader. The only input format is pen.`);
+    return EXIT_INVALID;
+  }
+
+  const text = readText(file);
+  const { importPen, ledgerLine } = await import("../../readers/pen.mjs");
+  const parse = await loadExport("parse.mjs", ["parse"], "parse");
+  const validateDesign = await loadExport("validate.mjs", ["validateDesign"], "validateDesign");
+  // The reader is handed text, so it cannot know the file's name; the verb supplies it as
+  // the last resort. Without it a `.pen` with no `name` of its own was titled literally
+  // "imported", which tells a reader of the file nothing at all.
+  const fallbackTitle = String(file).replace(/\.pen$/i, "").split("/").pop();
+  let html;
+  let ledger;
+  let diagnostics;
+  try {
+    ({ html, ledger, diagnostics } = importPen(text, { title: values.title, fallbackTitle }));
+  } catch (error) {
+    // A reader refusal is a result, not a crash: it prints the same way every
+    // other refusal does, and it keeps the code, which is what a caller branches
+    // on. `design.mjs` would turn it into one line on stderr with the code lost.
+    if (typeof error?.code === "string" && error.code.startsWith("pen/")) {
+      if (values.json) {
+        out(JSON.stringify({ ok: false, verb: "import", format, file, refused: { code: error.code, message: error.message } }));
+      } else {
+        out(`REFUSED  ${error.message}\n  ${error.code}`);
+      }
+      return EXIT_INVALID;
+    }
+    throw error;
+  }
+
+  // `diagnostics` is the parser's, and this check read as a guarantee while it was
+  // only a syntax test: the reader never ran the validator, so a document the next
+  // `validate` would refuse imported clean and exited 0. The gate asks the validator
+  // directly now, and it asks about the bytes about to be written — `parse(html)`,
+  // not a second rendering of the same tree.
+  const errors = [
+    ...(diagnostics ?? []),
+    ...validateDesign(parse(html)),
+  ].filter((d) => d.severity === "error");
+  if (errors.length) {
+    const shown = errors.slice(0, 3).map((d) => `${d.code} — ${d.message}`).join("; ");
+    out(`REFUSED  The imported file would not validate: ${errors.length} error(s). ${shown}`);
+    return EXIT_INVALID;
+  }
+
+  if (values.report) {
+    mkdirSync(dirname(resolve(values.report)), { recursive: true });
+    writeFileSync(resolve(values.report), `${JSON.stringify({ file, ledger, diagnostics }, null, 2)}\n`, "utf8");
+  }
+
+  if (values.stdout) {
+    process.stdout.write(html);
+    // stdout carries the document and nothing else. `--stdout` exists to be piped, and a
+    // pipe cannot tell a line of HTML from a line of ledger: this wrote the ledger line to
+    // stdout, so `import pen x.pen --stdout > design.html` produced a file whose last line
+    // was a sentence about pages. The report goes to stderr instead — silencing it would
+    // hide the losses, which are the point of this verb.
+    out(values.json
+      ? JSON.stringify({ ok: true, verb: "import", format, file, out: null, bytes: Buffer.byteLength(html), ledger })
+      : ledgerLine(ledger), { quiet: values.quiet, stream: process.stderr });
+    return EXIT_OK;
+  }
+
+  const target = resolve(values.out ?? values.o ?? `${String(file).replace(/\.pen$/i, "").split("/").pop()}.html`);
+  mkdirSync(dirname(target), { recursive: true });
+  writeFileSync(target, html, "utf8");
+
+  if (values.json) {
+    out(JSON.stringify({ ok: true, verb: "import", format, file, out: target, bytes: Buffer.byteLength(html), ledger }));
+  } else {
+    out(`${file} → ${target} (${Buffer.byteLength(html)} bytes)`);
+    out(ledgerLine(ledger));
+  }
+  return EXIT_OK;
+}

package/lib/node/verbs/ls.mjs

@@ -0,0 +1,98 @@
+/**
+ * `node design.mjs ls <file> [--pages] [--in <data-id>] [--depth n] [--json]`
+ *
+ * Two shapes, one line per node:
+ *
+ *   ls home.html                     every page, in document order
+ *   ls home.html --in home__root     the node tree under one data-id
+ *
+ * A line is `data-id  data-type  tag  name`, indented two spaces per level
+ * beneath the root of the listing.
+ */
+
+import { CliError, EXIT_INVALID, EXIT_OK, SHARED_FLAGS, out, parseArgs, readDesignFile } from "../cli.mjs";
+import { attrValue, collectElements, isPageElement } from "../../diagnostics.mjs";
+
+export const USAGE = `Usage: node design.mjs ls <file> [options]
+
+  --pages        list pages only (the default when --in is absent)
+  --in <data-id> list the node tree under one element
+  --depth n      how many levels below the root to print (default: all)
+  --json         print one line of JSON instead of text
+  --help         print this usage
+
+Exit codes: 0 listed, 1 no such data-id, 2 unreadable.`;
+
+function rowsOf(node, depth, maxDepth, rows) {
+  const id = attrValue(node, "data-id") || "";
+  const dataType = attrValue(node, "data-type") || "";
+  rows.push({
+    dataId: id,
+    dataType,
+    tag: typeof node.tag === "string" ? node.tag : "",
+    name: attrValue(node, "data-name") || "",
+    depth,
+  });
+  if (depth >= maxDepth) return rows;
+  const children = Array.isArray(node.children) ? node.children : [];
+  for (const child of children) {
+    if (!child || typeof child !== "object") continue;
+    if (child.kind !== "element" && !(typeof child.tag === "string" && Array.isArray(child.attrs))) continue;
+    rowsOf(child, depth + 1, maxDepth, rows);
+  }
+  return rows;
+}
+
+/** One report line: `data-id  data-type  tag  name`, indented by depth. */
+export function lineOf(row) {
+  const fields = [row.dataId, row.dataType, row.tag];
+  if (row.name) fields.push(row.name);
+  return `${"  ".repeat(row.depth)}${fields.join("  ")}`;
+}
+
+export default async function run(argv) {
+  const { values, positionals } = parseArgs(argv, {
+    flags: {
+      ...SHARED_FLAGS,
+      pages: { type: "boolean" },
+      in: { type: "string" },
+      depth: { type: "number" },
+    },
+    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 index = collectElements(loaded.doc);
+
+  let rows;
+  if (values.in !== undefined && values.in !== null) {
+    const root = index.byId.get(String(values.in));
+    if (!root) throw new CliError(`No element with data-id ${JSON.stringify(String(values.in))} in ${file}`, EXIT_INVALID);
+    if (Number.isFinite(values.depth) && values.depth < 0) throw new CliError("--depth needs a number of 0 or more");
+    const maxDepth = Number.isFinite(values.depth) ? Math.trunc(values.depth) : Infinity;
+    rows = rowsOf(root, 0, maxDepth, []);
+  } else {
+    rows = index.elements.filter(isPageElement).map((page) => ({
+      dataId: attrValue(page, "data-id") || "",
+      dataType: attrValue(page, "data-type") || "page",
+      tag: typeof page.tag === "string" ? page.tag : "section",
+      name: attrValue(page, "data-name") || "",
+      depth: 0,
+    }));
+  }
+
+  if (values.json) {
+    out(JSON.stringify(rows));
+  } else if (!values.quiet) {
+    for (const row of rows) out(lineOf(row), { quiet: false });
+  }
+
+  return EXIT_OK;
+}

package/lib/node/verbs/migrate.mjs

@@ -0,0 +1,236 @@
+/**
+ * `node design.mjs migrate <file>`
+ *
+ * Move a file onto the schema this build reads, by fixing the one thing that
+ * carries the version: the `<meta name="design-schema">` marker.
+ *
+ * Why this exists at all: `version/unsupported` prints the hint
+ * "Run `design migrate` to move the file to 3.0", and that command did not
+ * exist. A hint that names a command nobody can run is a dead end, and a dead
+ * end is the one failure this tool promises not to hand back.
+ *
+ * There is no older *HTML* schema in this repository, so this is not a format
+ * translator and must not pretend to be one. It fixes the marker, revalidates,
+ * and reports. If the file has other problems they are reported, not repaired.
+ *
+ * It does not go through the op layer, and it cannot: an op is addressed by
+ * `data-id`, `resolveAddress` accepts nothing else, and a `<meta>` has no
+ * `data-id`. So the marker is edited the way the serializer edits anything —
+ * one byte range.
+ */
+
+import { EXIT_INVALID, EXIT_OK, SHARED_FLAGS, out, parseArgs, readDesignFile } from "../cli.mjs";
+import { refusedReceipt, reportRefusal } from "../write-verbs.mjs";
+import { revisionOf, unifiedDiff, writeAtomic } from "../fs.mjs";
+import { SCHEMA_META_NAME, SCHEMA_VERSION, findMeta, newErrors, validateDesign } from "../../validate.mjs";
+import { getAttrNode, parse } from "../../parse.mjs";
+import { applyEdits } from "../../spans.mjs";
+
+export const USAGE = `Usage: node design.mjs migrate <file> [options]
+
+  --force      write even when the edit introduces a new error
+  --dry-run    print the diff, write nothing
+  --json       print the receipt as JSON
+  --quiet      print nothing
+
+Exit codes: 0 already current, or migrated; 1 refused and unchanged; 2 unreadable
+or bad arguments.
+
+This fixes the version marker only. It is not a format translator: there is no
+older HTML schema, so there is nothing to translate from. A file that is already
+current is left byte for byte alone, down to its modification time.`;
+
+/** The marker, spelled the way `new` and the pen importer spell it. */
+function markerText() {
+  return `<meta name="${SCHEMA_META_NAME}" content="${SCHEMA_VERSION}">`;
+}
+
+/**
+ * The whitespace a line starts with, so an inserted line sits where a person
+ * would have put it. Canonical form does not care, but a file someone reads does.
+ */
+function indentAt(text, offset) {
+  const lineStart = text.lastIndexOf("\n", Math.max(0, offset - 1)) + 1;
+  return (/^[ \t]*/.exec(text.slice(lineStart, offset)) ?? [""])[0];
+}
+
+/**
+ * Where to put the marker when the file has none.
+ *
+ * Inside `<head>`, after the `<title>` when there is one — that is where every
+ * file in this repository already has it, so the result looks like the files a
+ * person writes. Falls back outward: end of `<head>`, then a `<head>` of its
+ * own, then the top of the file.
+ *
+ * @returns {{ at: number, text: string }}
+ */
+function insertionPoint(doc, text) {
+  const head = doc.head;
+  if (head) {
+    const title = (head.children || []).find((c) => c.kind === "element" && c.tag === "title");
+    if (title) return { at: title.end, text: `\n${indentAt(text, title.start)}${markerText()}` };
+    const elements = (head.children || []).filter((c) => c.kind === "element");
+    const last = elements[elements.length - 1];
+    if (last) return { at: last.end, text: `\n${indentAt(text, last.start)}${markerText()}` };
+    return { at: head.openEnd, text: `\n${markerText()}\n` };
+  }
+
+  const html = doc.html;
+  if (html) {
+    // No `<head>` to write into, so make one. A browser invents a head anyway;
+    // writing it down means the next reader does not have to.
+    return { at: html.openEnd, text: `\n<head>\n${markerText()}\n</head>` };
+  }
+
+  return { at: 0, text: `${markerText()}\n` };
+}
+
+/**
+ * The new text, or `null` when the marker is already right.
+ *
+ * @returns {{ text: string, from: string|null, how: string }|null}
+ */
+function migrateText(doc, text) {
+  const meta = findMeta(doc, SCHEMA_META_NAME);
+
+  if (!meta) {
+    const { at, text: insertion } = insertionPoint(doc, text);
+    return { text: applyEdits(text, [{ start: at, end: at, text: insertion }]), from: null, how: "added" };
+  }
+
+  if (meta.value === SCHEMA_VERSION) return null;
+
+  const content = getAttrNode(meta.node, "content");
+  if (content && content.valueStart >= 0) {
+    // `valueStart` points at the opening quote when there is one — the parser
+    // spans `"3.0` rather than `3.0` — so step past it. An unquoted value has no
+    // quote and starts where it says. Leave the tag's own spelling alone.
+    const start = content.valueStart + (content.quote ? 1 : 0);
+    return {
+      text: applyEdits(text, [{ start, end: content.valueEnd, text: SCHEMA_VERSION }]),
+      from: meta.value ?? null,
+      how: "rewritten",
+    };
+  }
+
+  // A marker with no readable `content`: give it one, right after the `name`
+  // attribute, rather than rewriting the whole tag.
+  const name = getAttrNode(meta.node, "name");
+  const at = name ? name.end : meta.node.start + 1 + String(meta.node.rawTag ?? meta.node.tag).length;
+  return {
+    text: applyEdits(text, [{ start: at, end: at, text: ` content="${SCHEMA_VERSION}"` }]),
+    from: null,
+    how: "added",
+  };
+}
+
+/** The one line a human reads, in the house shape. */
+function report(receipt, values, file) {
+  if (values.json) {
+    out(JSON.stringify(receipt));
+    return;
+  }
+  const { errors, warnings } = receipt.summary;
+  const tail = `(${errors} errors, ${warnings} warnings)`;
+  if (!receipt.changed) {
+    out(`${file}: already ${SCHEMA_VERSION} ${tail}`, { quiet: values.quiet });
+    return;
+  }
+  const from = receipt.from === null ? "no marker" : `schema ${receipt.from}`;
+  out(`${file}: ${from} → ${SCHEMA_VERSION}, revision ${receipt.revision} ${tail}`, { quiet: values.quiet });
+  if (values["dry-run"] && receipt.diff) out(receipt.diff);
+}
+
+export default async function run(argv) {
+  const { values, positionals } = parseArgs(argv, {
+    flags: { ...SHARED_FLAGS },
+    positionals: { min: 1, max: 1 },
+    usage: USAGE,
+  });
+
+  if (values.help) {
+    out(USAGE);
+    return EXIT_OK;
+  }
+
+  const [file] = positionals;
+  const loaded = await readDesignFile(file);
+
+  if (loaded.format !== "html") {
+    const receipt = refusedReceipt("migrate", `${file} is not an HTML design file.`, {
+      code: "cli/not-a-design-file",
+      diagnostics: [],
+      hint: "Only .html design files carry a design-schema marker.",
+    });
+    reportRefusal(receipt, values, loaded.file);
+    return EXIT_INVALID;
+  }
+
+  const before = validateDesign(loaded.doc);
+  const change = migrateText(loaded.doc, loaded.text);
+
+  if (!change) {
+    // Already current. Report the state and touch nothing: not the bytes, not
+    // the modification time, not the inode. Re-running a migration must be free.
+    const errors = before.filter((d) => d.severity === "error").length;
+    const warnings = before.filter((d) => d.severity === "warning").length;
+    const receipt = {
+      ok: true,
+      verb: "migrate",
+      applied: [],
+      added: [],
+      normalized: [],
+      dropped: [],
+      diagnostics: before,
+      revision: revisionOf(loaded.text),
+      changed: false,
+      from: SCHEMA_VERSION,
+      to: SCHEMA_VERSION,
+      summary: { errors, warnings },
+    };
+    report(receipt, values, loaded.file);
+    return EXIT_OK;
+  }
+
+  // Re-read the result the way any other write does, so a migration is held to
+  // the same rule: it may not introduce an error. `migrate` refuses every format
+  // but HTML above, so the HTML reader is the one to re-read with.
+  const reparsed = parse(change.text, { file: loaded.file, format: "html", source: change.text });
+  if (typeof reparsed.source !== "string") reparsed.source = change.text;
+  const after = validateDesign(reparsed);
+  const introduced = newErrors(before, after);
+
+  if (introduced.length && !values.force) {
+    const receipt = refusedReceipt("migrate", "This migration would introduce a new error.", {
+      code: "cli/would-introduce-errors",
+      diagnostics: introduced,
+      hint: introduced[0]?.hint ?? null,
+    });
+    reportRefusal(receipt, values, loaded.file);
+    return EXIT_INVALID;
+  }
+
+  if (!values["dry-run"]) writeAtomic(loaded.file, change.text);
+
+  const receipt = {
+    ok: true,
+    verb: "migrate",
+    applied: [],
+    added: [],
+    normalized: [],
+    dropped: [],
+    diagnostics: after,
+    revision: revisionOf(change.text),
+    changed: true,
+    from: change.from,
+    to: SCHEMA_VERSION,
+    how: change.how,
+    summary: {
+      errors: after.filter((d) => d.severity === "error").length,
+      warnings: after.filter((d) => d.severity === "warning").length,
+    },
+  };
+  if (values["dry-run"]) receipt.diff = unifiedDiff(loaded.text, change.text, loaded.file, "migrated");
+  report(receipt, values, loaded.file);
+  return EXIT_OK;
+}

package/lib/node/verbs/move.mjs

@@ -0,0 +1,76 @@
+/**
+ * `node design.mjs move <file> <data-id> [--before X] [--after X] [--index n] [--into P]`
+ *
+ * One op. A move is addressed by data-id, never by a CSS selector, so it is
+ * unambiguous and it survives a sibling being inserted or removed.
+ */
+
+import { EXIT_OK, SHARED_FLAGS, out, parseArgs, readDesignFile } from "../cli.mjs";
+import { applyAndWrite, reportWrite } from "../write-verbs.mjs";
+
+export const USAGE = `Usage: node design.mjs move <file> <data-id> [options]
+
+  --before <data-id>   put it immediately before this sibling
+  --after <data-id>    put it immediately after this sibling
+  --index <n>          put it at this position (0 is first)
+  --into <data-id>     put it inside this element, last
+  --force              write even when the edit introduces a new error
+  --dry-run            report what would change, write nothing
+  --json               print the receipt as JSON
+  --quiet              print nothing
+
+Exactly one destination is required.
+
+Exit codes: 0 moved, 1 refused, 2 unreadable or bad arguments.
+
+A move cannot put an element inside its own subtree, and it cannot make a
+non-container hold children. Both are refused by name.`;
+
+export default async function run(argv) {
+  const { values, positionals } = parseArgs(argv, {
+    flags: {
+      ...SHARED_FLAGS,
+      before: { type: "string" },
+      after: { type: "string" },
+      index: { type: "string" },
+      into: { type: "string" },
+    },
+    positionals: { min: 2, max: 2 },
+    usage: USAGE,
+  });
+
+  if (values.help) {
+    out(USAGE);
+    return EXIT_OK;
+  }
+
+  const [file, target] = positionals;
+  const destinations = ["before", "after", "index", "into"].filter((key) => values[key] !== undefined);
+  if (destinations.length === 0) {
+    out("REFUSED  Where should it go? Use --before, --after, --index or --into.");
+    return 1;
+  }
+  if (destinations.length > 1) {
+    out(`REFUSED  One destination at a time, and ${destinations.length} were given: ${destinations.join(", ")}.`);
+    return 1;
+  }
+
+  const op = { op: "move", target };
+  const key = destinations[0];
+  if (key === "index") {
+    const index = Number(values.index);
+    if (!Number.isInteger(index) || index < 0) {
+      out(`REFUSED  --index wants a number from 0 up, and got ${JSON.stringify(values.index)}.`);
+      return 1;
+    }
+    op.index = index;
+  } else {
+    op[key] = values[key];
+  }
+
+  const loaded = await readDesignFile(file);
+  const receipt = await applyAndWrite(loaded, [op], { values, verb: "move" });
+  if (receipt.refused) return 1;
+  reportWrite(receipt, values, file);
+  return EXIT_OK;
+}