create-pathfinder 4.2.0 → 4.3.0

package/skills/render-artifact/engine/bin/render.mjs

@@ -0,0 +1,225 @@
+#!/usr/bin/env node
+/**
+ * `render-artifact` — validate a specification, or deliver it as an artifact.
+ *
+ *   node bin/render.mjs validate <spec.json> [--repo <dir>] [--json]
+ *   node bin/render.mjs deliver  <spec.json> <out.html> [--repo <dir>] [--json]
+ *   node bin/render.mjs doctor   [--json]
+ *
+ * Exit codes are the contract, and a non-zero exit is never reported as
+ * success:
+ *
+ *   0  every layer that ran passed, and the artifact was committed
+ *   1  a validation or delivery layer failed; nothing was committed
+ *   2  the command line was wrong
+ *
+ * `--repo` names the repository whose history evidence resolves in. It defaults
+ * to the specification's own directory, which is right for a specification that
+ * lives in the repository it cites, and is exactly what needs overriding when
+ * it does not.
+ */
+
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+
+import { RENDERER_VERSION } from "../version.mjs";
+import { validateSpecification, formatReport } from "../validate/index.mjs";
+import { deliver } from "../deliver.mjs";
+import { doctor } from "../doctor.mjs";
+
+const USAGE = `render-artifact ${RENDERER_VERSION}
+
+  validate <spec.json> [--repo <dir>] [--json]
+      Run the structural, composition and evidence layers. Writes nothing.
+
+  deliver <spec.json> <out.html> [--repo <dir>] [--json]
+      Validate, then render and commit the artifact atomically. Prints a
+      receipt naming the renderer version and the digests it produced.
+
+  doctor [--json]
+      Report whether this machine can render at all. Does not validate any
+      particular specification.
+`;
+
+function main(argv) {
+  const flags = { json: false, repo: null };
+  const positional = [];
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const argument = argv[i];
+    if (argument === "--json") { flags.json = true; continue; }
+    if (argument === "--repo") {
+      i += 1;
+      if (i >= argv.length) return usageError("--repo needs a directory");
+      flags.repo = argv[i];
+      continue;
+    }
+    if (argument === "--help" || argument === "-h") { process.stdout.write(USAGE); return 0; }
+    if (argument.startsWith("-")) return usageError(`unknown option \`${argument}\``);
+    positional.push(argument);
+  }
+
+  const [command, ...rest] = positional;
+  if (command === undefined) return usageError("no command given");
+  if (command === "doctor") return runDoctor(flags);
+  if (command === "validate") return runValidate(rest, flags);
+  if (command === "deliver") return runDeliver(rest, flags);
+  return usageError(`unknown command \`${command}\``);
+}
+
+function runDoctor(flags) {
+  const result = doctor();
+  if (flags.json) {
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  } else {
+    process.stdout.write(`render-artifact ${RENDERER_VERSION} — capability check\n\n`);
+    for (const check of result.checks) {
+      process.stdout.write(`  ${check.ok ? "ok  " : "FAIL"} ${check.name}: ${check.detail}\n`);
+    }
+    process.stdout.write(
+      "\n  This reports whether the engine can render here. It does not " +
+      "validate\n  any specification, and the determinism check compares two " +
+      "renders in\n  one process — cross-environment determinism is checked by " +
+      "rendering the\n  same specification in different environments and " +
+      "comparing digests.\n");
+  }
+  return result.ok ? 0 : 1;
+}
+
+function runValidate([specPath], flags) {
+  if (!specPath) return usageError("validate needs a specification path");
+
+  const loaded = loadSpec(specPath, flags);
+  if (loaded.exitCode !== undefined) return loaded.exitCode;
+
+  const result = validateSpecification(loaded.spec, { repoDir: repoDirFor(specPath, flags) });
+
+  if (flags.json) {
+    // `not_run` is reported here for the same reason it is in the human-readable
+    // report: a caller that saw `ok: true` beside two layers, with nothing
+    // saying why the third is missing, would have to infer the difference
+    // between "everything passed" and "one layer did not apply" — and the point
+    // of keeping the layers apart is that nobody has to infer it.
+    process.stdout.write(`${JSON.stringify({
+      ok: result.ok,
+      renderer_version: RENDERER_VERSION,
+      ran: result.ran,
+      skipped: result.skipped,
+      not_run: result.notRun,
+      resolved_citations: result.resolvedCitations,
+      diagnostics: result.diagnostics,
+    }, null, 2)}\n`);
+    return result.ok ? 0 : 1;
+  }
+
+  process.stdout.write(`validating ${specPath}\n${formatReport(result)}\n`);
+  process.stdout.write(result.ok
+    ? "\nvalid. Nothing was written: `validate` never delivers.\n"
+    : "\ninvalid. Nothing was written.\n");
+  return result.ok ? 0 : 1;
+}
+
+function runDeliver([specPath, outPath], flags) {
+  if (!specPath || !outPath) return usageError("deliver needs a specification path and an output path");
+
+  // Read the bytes and hand only the bytes on. `deliver` parses, validates,
+  // renders and digests from that one source, so the receipt cannot end up
+  // describing a specification other than the one that was rendered.
+  let specBytes;
+  try {
+    specBytes = readFileSync(specPath);
+  } catch (error) {
+    return reportLoadFailure(flags, "specification_unreadable", specPath, error.message);
+  }
+
+  const result = deliver(specBytes, specPath, outPath, { repoDir: repoDirFor(specPath, flags) });
+
+  if (!result.ok) {
+    if (flags.json) {
+      process.stdout.write(`${JSON.stringify({
+        ok: false,
+        renderer_version: RENDERER_VERSION,
+        delivered: false,
+        diagnostics: result.diagnostics,
+      }, null, 2)}\n`);
+    } else if (result.validation) {
+      process.stderr.write(`validating ${specPath}\n${formatReport(result.validation)}\n`);
+      process.stderr.write(
+        `\ninvalid. Nothing was delivered, and any artifact already at ` +
+        `${outPath} is untouched.\n`);
+    } else {
+      for (const d of result.diagnostics) {
+        process.stderr.write(`  FAIL delivery: [${d.code}] ${d.message}\n`);
+      }
+    }
+    return 1;
+  }
+
+  if (flags.json) {
+    process.stdout.write(`${JSON.stringify({
+      ok: true, delivered: true, ...result.receipt,
+    }, null, 2)}\n`);
+    return 0;
+  }
+
+  const { receipt } = result;
+  process.stdout.write([
+    `validating ${specPath}`,
+    formatReport(result.validation),
+    "  ok delivery: rendered, digested, and committed atomically",
+    "",
+    "receipt",
+    `  renderer version   ${receipt.renderer_version}`,
+    `  specification      ${receipt.specification.path}`,
+    `    sha256           ${receipt.specification.sha256}`,
+    `    bytes            ${receipt.specification.bytes}`,
+    `  artifact           ${receipt.artifact.path}`,
+    `    sha256           ${receipt.artifact.sha256}`,
+    `    bytes            ${receipt.artifact.bytes}`,
+    "",
+    "  Delivered. This says the artifact was validated and written, not that it",
+    "  looks right — open it in a browser to know that.",
+    "",
+  ].join("\n"));
+  return 0;
+}
+
+/** Where evidence resolves: `--repo` if given, otherwise the spec's directory. */
+function repoDirFor(specPath, flags) {
+  return resolve(flags.repo ?? dirname(resolve(specPath)));
+}
+
+function loadSpec(specPath, flags) {
+  let bytes;
+  try {
+    bytes = readFileSync(specPath);
+  } catch (error) {
+    return { exitCode: reportLoadFailure(flags, "specification_unreadable", specPath, error.message) };
+  }
+
+  let spec;
+  try {
+    spec = JSON.parse(bytes.toString("utf8"));
+  } catch (error) {
+    return { exitCode: reportLoadFailure(flags, "specification_not_json", specPath, error.message) };
+  }
+
+  return { spec, bytes };
+}
+
+function reportLoadFailure(flags, code, path, message) {
+  const d = { layer: "structural", code, path, message };
+  if (flags.json) {
+    process.stdout.write(`${JSON.stringify({ ok: false, diagnostics: [d] }, null, 2)}\n`);
+  } else {
+    process.stderr.write(`  FAIL structural: [${code}] ${path}\n       ${message}\n`);
+  }
+  return 1;
+}
+
+function usageError(message) {
+  process.stderr.write(`render-artifact: ${message}\n\n${USAGE}`);
+  return 2;
+}
+
+process.exitCode = main(process.argv.slice(2));

package/skills/render-artifact/engine/deliver.mjs

@@ -0,0 +1,197 @@
+/**
+ * Layer 4 — delivery. Parse, validate, render, digest, and commit atomically.
+ *
+ * Four properties this file exists to guarantee:
+ *
+ * 1. **One source of truth: the bytes.** `deliver` takes the specification as
+ *    bytes and nothing else. It copies them, parses that copy, validates the
+ *    parsed value, renders that same value, and reports the digest of those
+ *    same bytes. There is deliberately no parameter through which a caller
+ *    could supply an object alongside unrelated bytes — the receipt would then
+ *    describe a specification that was never rendered, and nothing downstream
+ *    could tell. The absent parameter is the guarantee; a check would only be
+ *    a second thing to get wrong.
+ * 2. **Verification is earned.** Delivery runs validation itself and mints its
+ *    attestation from that result. The renderer emits a verification claim only
+ *    against one, so an artifact that says its evidence was checked is an
+ *    artifact whose evidence this process checked, moments earlier, from these
+ *    bytes.
+ * 3. **Atomic commit.** The artifact is written to a temporary file beside the
+ *    destination and renamed over it. A rename within a directory is atomic, so
+ *    a reader never sees a half-written page, and a failure at any earlier step
+ *    leaves the previously delivered artifact exactly as it was.
+ * 4. **A receipt that says what it checked.** Renderer version, and SHA-256 and
+ *    byte count for both the specification and the artifact. The renderer
+ *    version is in there because it is part of the deterministic input: the
+ *    invariant is *same specification bytes and same renderer version*, so a
+ *    receipt naming only the digests would describe half the compiler.
+ */
+
+import { createHash } from "node:crypto";
+import { closeSync, fsyncSync, openSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, basename, join } from "node:path";
+
+import { RENDERER_VERSION } from "./version.mjs";
+import { render } from "./render/index.mjs";
+import { diagnostic } from "./validate/diagnostics.mjs";
+import { validateSpecification } from "./validate/index.mjs";
+import { attest } from "./verification.mjs";
+
+/**
+ * @typedef {object} Receipt
+ * @property {string} renderer_version
+ * @property {{ path: string, sha256: string, bytes: number }} specification
+ * @property {{ path: string, sha256: string, bytes: number }} artifact
+ */
+
+/**
+ * Validate, render, and commit the specification held in `specBytes`.
+ *
+ * @param {Buffer} specBytes  the specification exactly as it was read
+ * @param {string} specPath   where it was read from, for the receipt
+ * @param {string} outPath    where the artifact is committed
+ * @param {{ repoDir: string }} options  where evidence resolves
+ * @returns {{ ok: true, receipt: Receipt, validation: object }
+ *          | { ok: false, diagnostics: object[], validation?: object }}
+ */
+export function deliver(specBytes, specPath, outPath, { repoDir }) {
+  // Copy first. Everything below — the parse, the render, the digest — reads
+  // this copy, so a caller mutating its own buffer afterwards cannot leave the
+  // receipt describing bytes that were never rendered.
+  const frozenBytes = Buffer.from(specBytes);
+
+  let spec;
+  try {
+    spec = JSON.parse(frozenBytes.toString("utf8"));
+  } catch (error) {
+    return fail("specification_not_json", specPath,
+      `the specification could not be parsed, and nothing was written: ${error.message}`);
+  }
+
+  const validation = validateSpecification(spec, { repoDir });
+  if (!validation.ok) {
+    return { ok: false, validation, diagnostics: validation.diagnostics };
+  }
+
+  let html;
+  try {
+    // The attestation is minted here, from the validation just performed on
+    // this parse of these bytes. It is the only thing that lets the artifact
+    // say its evidence was checked.
+    html = render(deepFreeze(structuredClone(spec)), attest(validation));
+  } catch (error) {
+    return fail("render_failed", outPath,
+      `rendering threw and nothing was written: ${error.message}`);
+  }
+
+  // The invariant is about bytes, so check the bytes rather than trusting that
+  // no template ever grew a `\r` or that no environment introduced a BOM.
+  if (html.includes("\r")) {
+    return fail("carriage_return_in_output", outPath,
+      "rendered HTML contains a carriage return; artifacts use \\n only, on " +
+      "every platform");
+  }
+  if (html.charCodeAt(0) === 0xFEFF) {
+    return fail("byte_order_mark_in_output", outPath,
+      "rendered HTML begins with a byte-order mark; artifacts are UTF-8 " +
+      "without one");
+  }
+
+  const artifactBytes = Buffer.from(html, "utf8");
+
+  try {
+    commitAtomically(outPath, artifactBytes);
+  } catch (error) {
+    return fail("commit_failed", outPath,
+      `the artifact could not be committed, and any previously delivered ` +
+      `artifact is untouched: ${error.message}`);
+  }
+
+  return {
+    ok: true,
+    validation,
+    receipt: {
+      renderer_version: RENDERER_VERSION,
+      specification: {
+        path: specPath,
+        sha256: sha256(frozenBytes),
+        bytes: frozenBytes.byteLength,
+      },
+      artifact: {
+        path: outPath,
+        sha256: sha256(artifactBytes),
+        bytes: artifactBytes.byteLength,
+      },
+    },
+  };
+}
+
+/**
+ * Render without writing anything and without validating anything.
+ *
+ * No attestation is minted, so the artifact makes no claim to have been
+ * checked. Used by `doctor`, which is asking whether rendering works at all,
+ * and by anyone comparing two renders rather than keeping either.
+ */
+export function renderOnly(spec) {
+  const html = render(deepFreeze(structuredClone(spec)));
+  const bytes = Buffer.from(html, "utf8");
+  return { html, sha256: sha256(bytes), bytes: bytes.byteLength };
+}
+
+export function sha256(bytes) {
+  return createHash("sha256").update(bytes).digest("hex");
+}
+
+function fail(code, path, message) {
+  return { ok: false, diagnostics: [diagnostic("delivery", code, path, message)] };
+}
+
+/**
+ * Write beside the destination, flush to disk, then rename over it.
+ *
+ * The `fsync` matters as much as the rename: without it the rename can be
+ * durable while the content behind it is not, which is how a crash leaves a
+ * correctly named, empty artifact. The temporary name is derived from the
+ * destination and the process id so two concurrent deliveries to one path do
+ * not stage over each other.
+ */
+function commitAtomically(outPath, bytes) {
+  const directory = dirname(outPath);
+  const temporary = join(directory, `.${basename(outPath)}.${process.pid}.tmp`);
+
+  let handle;
+  try {
+    writeFileSync(temporary, bytes, { encoding: null, mode: 0o644 });
+    handle = openSync(temporary, "r+");
+    fsyncSync(handle);
+  } catch (error) {
+    safeUnlink(temporary);
+    throw error;
+  } finally {
+    if (handle !== undefined) closeSync(handle);
+  }
+
+  try {
+    renameSync(temporary, outPath);
+  } catch (error) {
+    safeUnlink(temporary);
+    throw error;
+  }
+}
+
+function safeUnlink(path) {
+  try {
+    unlinkSync(path);
+  } catch {
+    /* Nothing to clean up, or nothing we can do about it. */
+  }
+}
+
+/** Freeze an object graph in place, so rendering cannot mutate its own input. */
+function deepFreeze(value) {
+  if (value === null || typeof value !== "object" || Object.isFrozen(value)) return value;
+  Object.freeze(value);
+  for (const key of Object.keys(value)) deepFreeze(value[key]);
+  return value;
+}

package/skills/render-artifact/engine/doctor.mjs

@@ -0,0 +1,96 @@
+/**
+ * `doctor` — can this machine render at all?
+ *
+ * Deliberately not "does the shipped example validate here". Those are
+ * different questions and conflating them would make the answer useless. The
+ * example under `examples/` cites the Pathfinder source repository at a fixed
+ * commit; in an installed destination project that commit does not exist, and
+ * validating it there correctly fails. A `doctor` that reported that as a
+ * broken installation would be wrong about the only thing it is for.
+ *
+ * So: `doctor` checks capability — the runtime, the schemas, the kind registry,
+ * and that rendering is reproducible in this process. Whether a particular
+ * specimen validates is what `validate` is for.
+ */
+
+import { RENDERER_VERSION, SCHEMA_VERSION } from "./version.mjs";
+import { KINDS, schemaRegistry, validateStructure } from "./validate/structural.mjs";
+import { validateComposition } from "./validate/composition.mjs";
+import { renderOnly } from "./deliver.mjs";
+import { RENDERERS } from "./render/index.mjs";
+
+/** The Node the kit already requires. Nothing else is needed. */
+const MINIMUM_NODE_MAJOR = 18;
+
+/**
+ * A specimen that exercises the whole path without needing a repository: no
+ * citations, so no Git, so the check means the same thing on every machine.
+ */
+const SELF_CHECK = Object.freeze({
+  schema_version: SCHEMA_VERSION,
+  kind: "lesson",
+  artifact: { title: "Renderer self-check" },
+  source: { repo: "pathfinder", commit: "0000000" },
+  lesson: {
+    modules: [{
+      id: "self-check",
+      title: "Self-check",
+      sections: [{ type: "prose", id: "self-check-prose", body: ["Rendered locally."] }],
+    }],
+  },
+});
+
+/**
+ * @returns {{ ok: boolean, checks: {name: string, ok: boolean, detail: string}[] }}
+ */
+export function doctor() {
+  const checks = [];
+  const add = (name, ok, detail) => checks.push({ name, ok, detail });
+
+  const major = Number.parseInt(process.versions.node.split(".")[0], 10);
+  add("node", major >= MINIMUM_NODE_MAJOR,
+    `Node ${process.versions.node} (needs >= ${MINIMUM_NODE_MAJOR})`);
+
+  add("dependencies", true,
+    "zero runtime dependencies; the engine imports only node: builtins");
+
+  try {
+    const registry = schemaRegistry();
+    add("schemas", registry.byId.size >= 2,
+      `${[...registry.byId.keys()].sort().join(", ")} loaded`);
+  } catch (error) {
+    add("schemas", false, `schemas could not be loaded: ${error.message}`);
+  }
+
+  const kinds = Object.keys(KINDS).sort();
+  const rendered = Object.keys(RENDERERS).sort();
+  add("kinds", kinds.join(",") === rendered.join(","),
+    `schema kinds [${kinds.join(", ")}] and renderers [${rendered.join(", ")}] agree`);
+
+  try {
+    const structural = validateStructure(SELF_CHECK);
+    const composition = structural.length === 0 ? validateComposition(SELF_CHECK) : [];
+    add("validation", structural.length === 0 && composition.length === 0,
+      structural.length === 0 && composition.length === 0
+        ? "structural and composition layers ran on an internal specimen"
+        : "the internal specimen did not validate, which means the engine is broken");
+  } catch (error) {
+    add("validation", false, `validation threw: ${error.message}`);
+  }
+
+  try {
+    const first = renderOnly(SELF_CHECK);
+    const second = renderOnly(SELF_CHECK);
+    add("determinism", first.sha256 === second.sha256,
+      first.sha256 === second.sha256
+        ? `two renders of one specimen agreed (${first.sha256.slice(0, 12)}…, ` +
+          `${first.bytes} bytes)`
+        : `two renders of one specimen disagreed: ${first.sha256} vs ${second.sha256}`);
+  } catch (error) {
+    add("determinism", false, `rendering threw: ${error.message}`);
+  }
+
+  add("renderer", true, `render-artifact ${RENDERER_VERSION}, schema_version ${SCHEMA_VERSION}`);
+
+  return { ok: checks.every((check) => check.ok), checks };
+}