@daugasauron/dolly-build 0.0.0-stage → 0.1.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dolly contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,12 @@
-# Temporary Holding Version
+# @daugasauron/dolly-build
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A project with a Dolly image of your own: a Dollyfile `FROM` the installed
+`@daugasauron/dolly-image-pi-minimal` with the packages it INSTALLs (`@daugasauron/dolly-package-NAME`)
+and your files, built in a browser into a site that any static host serves as it lies.
+@daugasauron/dolly's README (`docs/embedding.md`) says how.
+
+```sh
+npx dolly-build init my-pi git
+npx dolly-build Dollyfile-my-pi my-pi
+python3 -m http.server -d my-pi -b 127.0.0.1 8080
+```

package/host/abi.mjs

@@ -0,0 +1,5 @@
+// Generated from abi/dolly-host-0.wat.
+export const DOLLY_HOST_RECORD_BYTES = 72;
+export const DOLLY_HOST_NAME_BYTES = 32;
+export const DOLLY_HOST_DIGEST_BYTES = 32;
+export const DOLLY_HOST_MAX_RECORDS = 64;

package/host/requirements.mjs

@@ -0,0 +1,62 @@
+import { DOLLY_HOST_RECORD_BYTES as recordBytes, DOLLY_HOST_NAME_BYTES as nameBytes,
+  DOLLY_HOST_DIGEST_BYTES as digestBytes, DOLLY_HOST_MAX_RECORDS as maxRecords } from "./abi.mjs";
+import { hex } from "../src/static-asset.mjs";
+
+const pattern = /^([a-z][a-z0-9-]{0,30})@(0|[1-9][0-9]{0,4})$/;
+
+export function hostRequirement(value) {
+  const match = typeof value === "string" && pattern.exec(value);
+  if (!match || Number(match[2]) > 65535) throw new TypeError(`invalid host requirement: ${value}`);
+  return { name: match[1], version: Number(match[2]) };
+}
+
+export function hostRequirements(values = []) {
+  if (!Array.isArray(values)) throw new TypeError("invalid host requirements");
+  const versions = new Map();
+  for (const value of values) {
+    const { name, version } = hostRequirement(value);
+    if (versions.has(name) && versions.get(name) !== version) throw new Error(`conflicting host ABI requirements for ${name}`);
+    versions.set(name, version);
+  }
+  if (versions.size > maxRecords) throw new TypeError("too many host requirements");
+  return [...versions].sort(([a], [b]) => a.localeCompare(b)).map(([name, version]) => `${name}@${version}`);
+}
+
+// The modules an executable's dolly.host records require: name@version -> ABI digest.
+export function executableHostRequirements(module) {
+  const required = new Map(), decoder = new TextDecoder("utf-8", { fatal: true });
+  let records = 0;
+  for (const { name, data } of module.customSectionData) {
+    if (name !== "dolly.host") continue;
+    records += data.length / recordBytes;
+    if (data.length === 0 || data.length % recordBytes || records > maxRecords) {
+      throw new Error("invalid dolly.host record count");
+    }
+    const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+    for (let offset = 0; offset < data.length; offset += recordBytes) {
+      const bytes = data.subarray(offset, offset + nameBytes), end = bytes.indexOf(0);
+      if (end < 1 || bytes.subarray(end).some(byte => byte !== 0) || view.getUint32(offset + nameBytes + 4, true) !== 0) {
+        throw new Error("invalid dolly.host record");
+      }
+      const requirement = `${decoder.decode(bytes.subarray(0, end))}@${view.getUint32(offset + nameBytes, true)}`;
+      const digest = hex(data.subarray(offset + recordBytes - digestBytes, offset + recordBytes));
+      if (required.has(requirement) && required.get(requirement) !== digest) {
+        throw new Error(`conflicting host ABI digests for ${requirement}`);
+      }
+      required.set(requirement, digest);
+    }
+  }
+  hostRequirements([...required.keys()]);
+  return required;
+}
+
+// available: name@version -> the ABI digest its provider implements. A session
+// with nena@0 can enable a module; any other has its image's list.
+export function checkHostAbi(required, available) {
+  for (const [requirement, digest] of required) {
+    if (!available.has(requirement)) throw new Error(available.has("nena@0")
+      ? `host module ${requirement} is not enabled: nena enable ${hostRequirement(requirement).name}`
+      : `host module ${requirement} is not declared by this image (REQUIRES HOST)`);
+    if (available.get(requirement) !== digest) throw new Error(`host module ${requirement} has a different layout than this program was built for`);
+  }
+}

package/package.json

@@ -1,6 +1,18 @@
 {
+  "version": "0.1.5",
+  "type": "module",
   "name": "@daugasauron/dolly-build",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "license": "MIT",
+  "bin": {
+    "dolly-build": "scripts/dolly-build.mjs"
+  },
+  "dependencies": {
+    "@daugasauron/dolly": "0.1.5",
+    "playwright-core": "1.63.0"
+  },
+  "description": "Build a Dolly image of your own, FROM an installed image package, in a browser, into a static site.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/daugasauron/dolly.git"
+  }
+}

package/scripts/dolly-build-init/Dollyfile

@@ -0,0 +1,54 @@
+# Pi reads its instructions, skills, extensions and themes from /home/dolly/.pi/agent/
+# (Pi's docs/configuration.md, in the image under /usr/lib/node_modules/@earendil-works/pi-coding-agent/docs/).
+# A FILE row writes its body, each line indented four spaces, into the image.
+
+FILE /home/dolly/.pi/agent/AGENTS.md
+    You are the coding agent of this project. Keep answers short, and run the
+    project's tests after a change.
+
+FILE /home/dolly/.pi/agent/skills/changelog/SKILL.md
+    ---
+    name: changelog
+    description: Keeps /workspace/CHANGELOG.md. Use when asked to record a change.
+    ---
+    Add the change under "## Unreleased", one line each, newest first.
+
+FILE /home/dolly/.pi/agent/extensions/hello.js
+    export default function (pi) {
+      pi.registerCommand("hello", {
+        description: "Say hello",
+        handler: async (name, ctx) => ctx.ui.notify(`Hello, ${name || "world"}, from __NAME__!`, "info"),
+      });
+    }
+
+# A tool of your own, on the agent's PATH with EXPORTS TOOL: a script
+# (#!/bin/slop, or #!/usr/bin/janis for JavaScript); with the cc package, a C
+# program (FILE /tmp/NAME.c with its body, then SLOP cc /tmp/NAME.c -o /usr/bin/NAME);
+# a file of an npm package, pinned by its SHA-256 (SOURCE https://unpkg.com/PACKAGE@VERSION/FILE
+# SHA256 /usr/lib/FILE, then FILE /usr/lib/FILE to keep it; a script imports it by that path).
+FILE /usr/bin/todo
+    #!/bin/slop
+    # todo [DIR]: lists the TODO and FIXME notes under DIR (default .).
+    rg -n 'TODO|FIXME' "${1:-.}"
+EXPORTS TOOL todo
+
+# Pi's colours are public/theme.json, which the page writes at boot.
+
+# Pi sends OpenRouter's Claude models through Anthropic's Messages API, whose
+# browser header OpenRouter's CORS refuses: this entry sends them through Chat
+# Completions. An endpoint of your own that speaks OpenAI's API is such an entry
+# too (docs/agent-frontend.md).
+FILE /home/dolly/.pi/agent/models.json
+    { "providers": { "openrouter": { "baseUrl": "https://openrouter.ai/api/v1", "api": "openai-completions",
+      "apiKey": "$OPENROUTER_API_KEY", "models": [{ "id": "anthropic/claude-sonnet-5.5" }] } } }
+
+# How Pi starts: the key at a prompt that does not show it, the provider and the
+# model (Pi's docs/providers.md). Another provider is this line and the page's
+# policy rule: Anthropic's API with your own key is the second line. /model in Pi
+# changes the model for a session; --offline keeps Pi from requests the policy
+# refuses. Ctrl+D leaves Pi for a shell.
+FILE /etc/dolly/init.slop
+    pi-key OPENROUTER_API_KEY --offline --provider openrouter --model anthropic/claude-sonnet-5.5
+    # pi-key ANTHROPIC_API_KEY --offline --provider anthropic --model claude-sonnet-5-5
+    printf '\nPi exited; this is a Slop shell.\n'
+    /bin/foreground -i /bin/slop

package/scripts/dolly-build-init/public/index.html

@@ -0,0 +1,61 @@
+<!doctype html>
+<meta charset="utf-8">
+<title>__NAME__</title>
+<link rel="icon" href="data:,">
+<style>
+  /* The font of the popups of Pi's ask_user and show_html, and the scheme of their
+     form controls. Their colours and the terminal's are theme.json's. */
+  #dolly { --dolly-html-font: ui-monospace, monospace; --dolly-html-color-scheme: dark; }
+</style>
+<main id="dolly" style="position:fixed;inset:0"></main>
+<script type="module">
+  // Dolly needs cross-origin isolation. Where the host sends no COOP and COEP
+  // headers, coi-serviceworker.js adds them: the page registers it and loads again
+  // under it, once; boot() says so if that did not isolate it.
+  if (!crossOriginIsolated && navigator.serviceWorker && !sessionStorage.getItem("dolly-isolation-retry")) {
+    sessionStorage.setItem("dolly-isolation-retry", "1");
+    await navigator.serviceWorker.register("./coi-serviceworker.js");
+    await navigator.serviceWorker.ready;
+    location.reload();
+    await new Promise(() => {});
+  }
+  sessionStorage.removeItem("dolly-isolation-retry");
+  const { boot } = await import("./dolly/src/browser.mjs");
+  const { images, image, modules } = await import("./image/index.mjs");
+
+  // The hosts the agent may reach, and nothing else: the model's provider here,
+  // one rule per host the agent needs (api.github.com, pypi.org). A rule names an
+  // origin, its paths and methods, and the header that carries the key (docs/http.md
+  // in @daugasauron/dolly). Hosts without CORS headers go through a relay of your
+  // own (docs/agent-frontend.md).
+  const policy = { rules: [
+    { origin: "https://openrouter.ai", pathPrefix: "/api/v1/", methods: ["GET", "POST"], credentialHeaders: ["authorization"] },
+    // { origin: "https://api.anthropic.com", pathPrefix: "/v1/", methods: ["POST"], credentialHeaders: ["x-api-key"] },
+  ] };
+
+  // The project: workspace/ is written into /workspace at each boot. dolly-build
+  // lists its files in workspace.json beside this page. Pi's tools can read these
+  // files; they are not for secrets.
+  const listing = await fetch("./workspace.json");
+  if (!listing.ok) throw new Error("workspace.json must list the files under workspace/, as dolly-build writes it");
+  const files = {};
+  await Promise.all((await listing.json()).map(async path => {
+    const url = `./workspace/${path.split("/").map(encodeURIComponent).join("/")}`;
+    files[`/workspace/${path}`] = new Uint8Array(await (await fetch(url)).arrayBuffer());
+  }));
+  // The sandbox's colours, all in theme.json: Pi's theme (Pi's docs/themes.md), written
+  // over the image's, whose background, text, accent and muted the terminal and the
+  // popups take too (docs/embedding.md in @daugasauron/dolly).
+  const theme = await (await fetch("./theme.json")).text();
+  files["/home/dolly/.pi/agent/themes/dolly.json"] = theme;
+  const { vars } = JSON.parse(theme), look = document.querySelector("#dolly").style;
+  look.setProperty("--dolly-background", vars.background);
+  look.setProperty("--dolly-color", vars.text);
+  look.setProperty("--dolly-accent", vars.accent);
+  look.setProperty("--dolly-display-palette-8", vars.muted);
+
+  // Save (Ctrl+Shift+S) keeps the sandbox's state in this browser and names it in the
+  // address, ?session=NAME: the page then opens that save, as it was, in place of a fresh start.
+  const session = new URLSearchParams(location.search).get("session") ?? undefined;
+  await boot(document.querySelector("#dolly"), { images, image, modules, http: { policy }, files, session });
+</script>

package/scripts/dolly-build-init/public/theme.json

@@ -0,0 +1,67 @@
+{
+  "name": "dolly",
+  "vars": {
+    "accent": "#f2d45c",
+    "text": "#e8e3d7",
+    "muted": "#77736c",
+    "background": "#262626",
+    "panel": "#30302e"
+  },
+  "colors": {
+    "accent": "accent",
+    "border": "muted",
+    "borderAccent": "accent",
+    "borderMuted": "muted",
+    "success": "accent",
+    "error": "accent",
+    "warning": "accent",
+    "muted": "muted",
+    "dim": "muted",
+    "text": "text",
+    "thinkingText": "muted",
+    "selectedBg": "panel",
+    "scrollbarThumb": "muted",
+    "searchMatchBg": "panel",
+    "searchMatchText": "accent",
+    "userMessageBg": "panel",
+    "userMessageText": "text",
+    "customMessageBg": "panel",
+    "customMessageText": "text",
+    "customMessageLabel": "accent",
+    "toolPendingBg": "background",
+    "toolSuccessBg": "background",
+    "toolErrorBg": "background",
+    "toolTitle": "accent",
+    "toolOutput": "text",
+    "mdHeading": "accent",
+    "mdLink": "accent",
+    "mdLinkUrl": "muted",
+    "mdCode": "accent",
+    "mdCodeBlock": "text",
+    "mdCodeBlockBorder": "muted",
+    "mdQuote": "muted",
+    "mdQuoteBorder": "muted",
+    "mdHr": "muted",
+    "mdListBullet": "accent",
+    "toolDiffAdded": "accent",
+    "toolDiffRemoved": "accent",
+    "toolDiffContext": "muted",
+    "syntaxComment": "muted",
+    "syntaxKeyword": "accent",
+    "syntaxFunction": "text",
+    "syntaxVariable": "text",
+    "syntaxString": "accent",
+    "syntaxNumber": "accent",
+    "syntaxType": "accent",
+    "syntaxOperator": "accent",
+    "syntaxPunctuation": "muted",
+    "thinkingOff": "muted",
+    "thinkingMinimal": "accent",
+    "thinkingLow": "accent",
+    "thinkingMedium": "accent",
+    "thinkingHigh": "accent",
+    "thinkingXhigh": "accent",
+    "thinkingMax": "accent",
+    "bashMode": "accent"
+  }
+}

package/scripts/dolly-build-init/public/workspace/README.md

@@ -0,0 +1,5 @@
+# Workspace
+
+The agent's project. The page writes this directory into `/workspace` at each
+boot, so an edit here is a build that keeps the image, then a reload; what the
+agent changes stays in the browser tab. Replace this file with your project.

package/scripts/dolly-build.mjs

@@ -0,0 +1,278 @@
+#!/usr/bin/env node
+// An npm user's image: builds a Dollyfile FROM an installed image package, with
+// the packages it INSTALLs from their packages, in a browser with that browser's
+// Dolly runtime, into a site a static host serves as it lies (docs/embedding.md,
+// "Your own image").
+//   npx dolly-build init NAME [PACKAGE…]   writes Dollyfile-NAME FROM pi-minimal and public/ (the page)
+//   npx dolly-build Dollyfile-NAME OUT [--browser chrome|chromium|firefox]
+// OUT is the files of public/, workspace.json listing public/workspace/, the runtime
+// (dolly/), the host modules the image declares (dolly-host-NAME/),
+// coi-serviceworker.js for hosts without isolation headers, and image/, the image's
+// directory as an image package lays it out (catalog, metadata, packs, recipes,
+// amy-index.txt, index.mjs). It runs in the directory whose node_modules/@daugasauron/
+// holds the runtime, the image and package directories and the host module packages
+// (pnpm links there what it keeps elsewhere); the runtime runs only in the browser.
+import { cp, mkdir, mkdtemp, readdir, readFile, realpath, rename, rm, writeFile } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { existsSync } from "node:fs";
+import { createServer } from "node:http";
+import { basename, dirname, extname, join, relative, resolve, sep } from "node:path";
+import { pathToFileURL } from "node:url";
+import { parseArgs } from "node:util";
+import { chromium, firefox } from "playwright-core";
+import { amyIndex, catalogJson, catalogRecord, heldPackages, indexDescriptions, indexSource, metadataJson, snapshotMetadata } from "./image-directory.mjs";
+import { buildImageInPage, savePageSnapshot } from "./page-image-build.mjs";
+import { isolationHeaders, mimeTypes } from "./serve.mjs";
+import { ensureSnapshotPacks } from "./share-pages-snapshots.mjs";
+import { verifySnapshotIdentity } from "./snapshot-identity.mjs";
+import { decodeSystemSnapshot } from "./system-snapshot-format.mjs";
+import { readWasmInterface } from "./wasm-interface.mjs";
+import { loadRecipeGraph } from "../src/dollyfile-graph.mjs";
+import { imageFileName, inspectDollyfile } from "../src/dollyfile-view.mjs";
+import { imageInputs } from "../src/image-inputs.mjs";
+import { validName } from "../src/image-names.mjs";
+import { siteReference, sitePath } from "../src/static-asset.mjs";
+
+function fail(message) {
+  console.error(`dolly-build: ${message}`);
+  process.exit(1);
+}
+const scope = resolve("node_modules/@daugasauron");
+if (!existsSync(join(scope, "dolly"))) fail("run it where node_modules/@daugasauron/dolly is installed");
+const load = path => import(pathToFileURL(path).href);
+const { positionals, values: { browser: browserName } } = parseArgs({ allowPositionals: true,
+  options: { browser: { type: "string", default: "chrome" } } });
+// Firefox's system add-on updater resolves its host even behind a proxy.
+const browsers = {
+  chrome: options => chromium.launch({ channel: "chrome", headless: true, ...options }),
+  chromium: options => chromium.launch({ headless: true, ...options }),
+  firefox: options => firefox.launch({ headless: true, firefoxUserPrefs: { "extensions.systemAddon.update.enabled": false }, ...options }),
+};
+const usage = "usage: dolly-build init NAME [PACKAGE...] | Dollyfile-NAME OUT [--browser chrome|chromium|firefox]";
+const init = positionals[0] === "init";
+if (!browsers[browserName] || (init ? positionals.length < 2 : positionals.length !== 2)) fail(usage);
+
+// The installed image and package directories (dolly-image-NAME, dolly-package-NAME):
+// each holds its own image's packs, and the catalog and metadata of that image's
+// closure. npm installs the packages a package installs beside it, pnpm beside its
+// real path.
+const directories = [];
+for (const pending = [scope]; pending.length;) {
+  const parent = pending.pop();
+  for (const name of (await readdir(parent)).filter(name => /^dolly-(image|package)-/.test(name))) {
+    const directory = await realpath(join(parent, name));
+    if (directories.some(found => found.directory === directory)) continue;
+    directories.push({ directory, package: `@daugasauron/${name}`, image: name.replace(/^dolly-(image|package)-/, ""),
+      catalog: JSON.parse(await readFile(join(directory, "dist/dolly-images.json"), "utf8")) });
+    pending.push(dirname(directory));
+  }
+}
+const definitionOf = ({ catalog, image }) => catalog.images.find(candidate => candidate.image === image);
+const installed = (image, kind) => directories.find(candidate => candidate.image === image)
+  ?? fail(`${image} is not installed: npm install @daugasauron/dolly-${kind}-${image}`);
+// The directory whose own image a row names, at the row's pin.
+const holder = reference => directories.find(candidate => {
+  const definition = definitionOf(candidate);
+  return siteReference(definition.dollyfile) === reference.location && definition.sha256 === reference.sha256;
+});
+// The host module packages: the runtime's own and one package each.
+const modules = new Map();
+for (const name of await readdir(join(scope, "dolly/host"))) {
+  if (existsSync(join(scope, "dolly/host", name, "module.json"))) modules.set(name, `dolly/host/${name}/module.json`);
+}
+for (const name of (await readdir(scope)).filter(name => name.startsWith("dolly-host-"))) {
+  modules.set(JSON.parse(await readFile(join(scope, name, "module.json"), "utf8")).name, `${name}/module.json`);
+}
+const hostPackage = name => `@daugasauron/dolly-host-${name === "download" ? "save" : name}`;
+
+try {
+  if (init) await scaffold(positionals[1], positionals.slice(2));
+  else await build(...positionals.map(path => resolve(path)));
+} catch (error) {
+  fail(error.message);
+}
+
+// A project: the recipe (FROM pi-minimal at its pin, INSTALL of each PACKAGE,
+// the template's rows, the base's ENTRY) and public/, the page's files: the page,
+// its theme and the workspace.
+async function scaffold(name, packages) {
+  if (!validName(name)) fail(`${name}: a name is lowercase letters, digits and dashes, at most 32 bytes`);
+  const base = definitionOf(installed("pi-minimal", "image"));
+  const installs = packages.map(image => definitionOf(installed(image, "package")));
+  // snapshot@0 is the page's Save: a save is kept in the browser, and the page opens it again.
+  const hosts = [...new Set([base, ...installs].flatMap(definition => definition.hostRequirements).concat("snapshot@0"))].sort();
+  const row = (operation, definition) => `${operation} ${siteReference(definition.dollyfile)} ${definition.sha256}\n`;
+  const template = async file => (await readFile(join(import.meta.dirname, "dolly-build-init", file), "utf8")).replaceAll("__NAME__", name);
+  const files = {
+    [`Dollyfile-${name}`]: `DOLLY 7\nAPPLICATION ${name}\n${hosts.map(host => `REQUIRES HOST ${host}\n`).join("")}\n` +
+      row("FROM", base) + installs.map(definition => row("INSTALL", definition)).join("") + "\n" + await template("Dollyfile") +
+      `\nENTRY ${base.entry.join(" ")}\n`,
+    "public/index.html": await template("public/index.html"),
+    "public/theme.json": await template("public/theme.json"),
+    "public/workspace/README.md": await template("public/workspace/README.md"),
+  };
+  const present = Object.keys(files).filter(file => existsSync(file));
+  if (present.length) fail(`${present.join(", ")}: already here`);
+  await mkdir("public/workspace", { recursive: true });
+  for (const [file, text] of Object.entries(files)) await writeFile(file, text);
+  // The site and node_modules are built, not kept: a .gitignore, unless the project has one.
+  if (!existsSync(".gitignore")) await writeFile(".gitignore", `node_modules/\n${name}/\n`);
+  const missing = hosts.map(host => host.split("@")[0]).filter(name => !modules.has(name));
+  console.log(`dolly-build: wrote ${Object.keys(files).join(", ")}\n` +
+    (missing.length ? `  npm install ${missing.map(hostPackage).join(" ")}   the recipe declares ${missing.join(", ")}\n` : "") +
+    `  npx dolly-build Dollyfile-${name} ${name}   builds the image and the site, ${name}/ (again after a change)\n` +
+    `  python3 -m http.server -d ${name} -b 127.0.0.1 8080   serves it, as any static host does`);
+}
+
+async function build(recipePath, outArgument) {
+  const filename = basename(recipePath), source = await readFile(recipePath, "utf8");
+  const parsed = inspectDollyfile(source, filename), image = parsed.image;
+  if (imageFileName(filename) !== image) fail(`${filename}: name it Dollyfile-${image}`);
+  if (!parsed.from) fail(`${filename}: FROM an installed image`);
+  if (!existsSync("public/index.html")) fail("public/index.html: the page of the site (dolly-build init writes one)");
+  // A rebuild replaces the site it wrote before, and nothing else.
+  const previous = join(outArgument, "image");
+  if (existsSync(outArgument) && !existsSync(join(previous, "dist/dolly-images.json"))) {
+    fail(`${outArgument} exists and is not a site dolly-build wrote: remove it, or name another`);
+  }
+  // Every row that names an image names one of the installed directories at its pin.
+  const holders = parsed.artifacts.map(reference => holder(reference) ?? fail(`${filename}:${reference.line}: no installed ` +
+    `package holds ${reference.location} at that pin (dolly-build init writes the rows of the installed ones)`));
+  // One catalog of their closures: the same image at the same pin in each.
+  const records = new Map(), staticSources = new Map(), first = new Map();
+  for (const directory of holders) {
+    for (const record of directory.catalog.images) {
+      if (records.has(record.image) && records.get(record.image).sha256 !== record.sha256) {
+        fail(`${directory.package} holds ${record.image} at another pin than ${first.get(record.image)}: install packages of one version`);
+      }
+      records.set(record.image, record);
+      first.set(record.image, first.get(record.image) ?? directory.package);
+    }
+    for (const entry of directory.catalog.staticSources) staticSources.set(entry.path, entry);
+  }
+  if (records.has(image)) fail(`${image} is already an image of ${first.get(image)}`);
+  const declared = parsed.hostRequirements.map(requirement => requirement.split("@")[0]);
+  const missing = declared.filter(name => !modules.has(name));
+  if (missing.length) fail(`${image} declares ${missing.join(", ")}: install ${missing.map(hostPackage).join(", ")}`);
+  const runtime = join(scope, "dolly/dist");
+  const identities = { buildId: (await load(join(runtime, "dolly-build-id.mjs"))).DOLLY_BUILD_ID,
+    imageBuildId: (await load(join(runtime, "dolly-image-build-id.mjs"))).DOLLY_IMAGE_BUILD_ID };
+
+  const staging = await mkdtemp(join(dirname(outArgument), ".dolly-build-"));
+  try {
+    // The page's files and the listing of its workspace, the runtime and the host
+    // modules the image declares, as their packages hold them, and the worker
+    // that isolates the page where the host sends no headers.
+    await cp("public", staging, { recursive: true });
+    const workspace = join(staging, "workspace");
+    if (existsSync(workspace)) {
+      const files = (await readdir(workspace, { recursive: true, withFileTypes: true })).filter(entry => entry.isFile())
+        .map(entry => relative(workspace, join(entry.parentPath, entry.name)).split(sep).join("/")).sort();
+      await writeFile(join(staging, "workspace.json"), `${JSON.stringify(files)}\n`);
+    }
+    for (const name of new Set(["dolly", ...declared.map(module => modules.get(module).split("/")[0])])) {
+      await cp(join(scope, name), join(staging, name), { recursive: true, dereference: true });
+    }
+    await cp(join(scope, "dolly/coi-serviceworker.js"), join(staging, "coi-serviceworker.js"));
+    // The image a build of this recipe on this runtime wrote before is kept.
+    if (await built(previous, image, source, identities)) await rename(previous, join(staging, "image"));
+    else await buildImage(join(staging, "image"), { filename, source, image, parsed, holders, records, staticSources, declared, identities });
+    await rm(outArgument, { recursive: true, force: true });
+    await rename(staging, outArgument);
+  } catch (error) {
+    await rm(staging, { recursive: true, force: true });
+    throw error;
+  }
+  console.log(`dolly-build: ${relative(process.cwd(), outArgument) || "."} is the site of ${image}: a static host serves it as it lies`);
+}
+
+// Whether DIRECTORY holds IMAGE built from SOURCE by the runtime of these IDENTITIES.
+async function built(directory, image, source, identities) {
+  const read = async file => JSON.parse(await readFile(join(directory, "dist", file), "utf8").catch(() => "null"));
+  const [catalog, metadata] = await Promise.all([read("dolly-images.json"), read(`dolly-${image}-system-snapshot.json`)]);
+  return catalog?.images.find(record => record.image === image)?.sha256 === createHash("sha256").update(source).digest("hex") &&
+    metadata?.buildId === identities.imageBuildId && metadata?.runtimeBuildId === identities.buildId;
+}
+
+// The image directory, laid out as an image package: the closures' metadata and
+// recipes, this recipe beside them, the image's metadata and packs, its package
+// index and its index.mjs. Every installed directory's packs are served for the
+// build alone: a package's directory holds its own, and npm installs the packages
+// it installs beside it.
+async function buildImage(directory, { filename, source, image, parsed, holders, records, staticSources, declared, identities }) {
+  await mkdir(directory);
+  for (const holding of new Set(holders)) {
+    await cp(holding.directory, directory, { recursive: true, filter: path => ![
+      join(holding.directory, "dist/packs"), join(holding.directory, "dist/dolly-images.json"), join(holding.directory, "index.mjs"),
+      join(holding.directory, "amy-index.txt"), join(holding.directory, "package.json"), join(holding.directory, "README.md")].includes(path) });
+  }
+  await writeFile(join(directory, filename), source);
+  const graph = await loadRecipeGraph(reference => readFile(join(directory, sitePath(reference).slice(1))), siteReference(filename));
+  const catalog = [...records.values(), catalogRecord({ image, filename, source, parsed }, graph)];
+  await writeFile(join(directory, "dist/dolly-images.json"), catalogJson(catalog, [...staticSources.values()]));
+
+  const page = "<!doctype html><title>dolly-build</title>";
+  // The packages at their names (the runtime at /dolly/, the host modules beside it).
+  const roots = [["/", scope], ["/image/", directory],
+    ...directories.map(installed => ["/image/dist/packs/", join(installed.directory, "dist/packs")])];
+  const server = createServer(async (request, response) => {
+    const path = decodeURIComponent(new URL(request.url, "http://127.0.0.1").pathname);
+    if (path === "/") return response.writeHead(200, { ...isolationHeaders, "content-type": "text/html" }).end(page);
+    for (const [prefix, root] of roots.toReversed().filter(([prefix]) => path.startsWith(prefix))) {
+      const file = resolve(root, path.slice(prefix.length));
+      if (!file.startsWith(root + sep)) break;
+      const body = await readFile(file).catch(() => null);
+      if (body) return response.writeHead(200, { ...isolationHeaders,
+        "content-type": mimeTypes.get(extname(file)) ?? "application/octet-stream" }).end(body);
+    }
+    response.writeHead(404).end();
+  });
+  // The browser's own requests (its vendor's updates, clock, autofill) go to a proxy that
+  // refuses them: it reaches this server and the recipes' sources alone.
+  const refusal = createServer((request, response) => response.writeHead(403).end()).on("connect", (request, socket) => socket.destroy());
+  await Promise.all([server, refusal].map(listener => new Promise(listening => listener.listen(0, "127.0.0.1", listening))));
+  const origin = `http://127.0.0.1:${server.address().port}`;
+  // The recipes' own upstream URLs are the only network the build may use.
+  const rules = graph.records.flatMap(record => record.sources.filter(entry => sitePath(entry.location) === null))
+    .map(entry => ({ origin: new URL(entry.location).origin, path: new URL(entry.location).pathname, methods: ["GET"] }));
+  const browser = await browsers[browserName]({ proxy: { server: `http://127.0.0.1:${refusal.address().port}`,
+    bypass: [...new Set(["127.0.0.1", ...rules.map(rule => new URL(rule.origin).hostname)])].join(",") } });
+  let inputs;
+  try {
+    const tab = await browser.newPage();
+    tab.setDefaultTimeout(0);
+    await tab.exposeFunction("dollyBuildLog", text => void process.stderr.write(text));
+    await tab.addInitScript(rules => { globalThis.DOLLY_HTTP_POLICY = { maxRequests: 256, rules }; }, rules);
+    await tab.goto(`${origin}/`);
+    ({ inputs } = await tab.evaluate(`(${buildImageInPage})(${JSON.stringify(`${origin}/dolly/`)}, ` +
+      `${JSON.stringify(`${origin}/image/`)}, ${JSON.stringify(image)}, undefined, ` +
+      `${JSON.stringify([...modules.values()].map(path => `${origin}/${path}`))})`));
+    await savePageSnapshot(tab, join(directory, `dist/dolly-${image}-system.snapshot`));
+  } finally {
+    await browser.close();
+    server.close();
+    refusal.close();
+  }
+
+  // Checked and described as the catalog's images are, by the runtime it runs on.
+  const runtime = join(scope, "dolly/dist");
+  const snapshotPath = join(directory, `dist/dolly-${image}-system.snapshot`), snapshot = await readFile(snapshotPath);
+  const decoded = decodeSystemSnapshot(snapshot);
+  const entry = verifySnapshotIdentity({ image, source, parsed }, graph, decoded,
+    await readWasmInterface(join(runtime, "dolly-process-0.wasm")),
+    (await load(join(runtime, "dolly-process-abi.mjs"))).DOLLY_PROCESS_ABI_DIGEST);
+  const packed = await ensureSnapshotPacks(join(directory, "dist"),
+    snapshotMetadata(image, graph, imageInputs(inputs), snapshot, decoded, entry, identities));
+  await writeFile(join(directory, `dist/dolly-${image}-system-snapshot.json`), metadataJson(packed));
+  await rm(snapshotPath);
+
+  // The packages it holds, described as the installed directories' indexes describe them.
+  const descriptions = new Map();
+  for (const installed of directories) {
+    const text = await readFile(join(installed.directory, "amy-index.txt"), "utf8").catch(() => "");
+    for (const [name, description] of indexDescriptions(text)) descriptions.set(name, description);
+  }
+  const held = heldPackages(catalog, image);
+  await writeFile(join(directory, "amy-index.txt"), amyIndex(catalog.filter(record => held.includes(record.image)), descriptions));
+  await writeFile(join(directory, "index.mjs"), indexSource(image, declared.map(name => `../${modules.get(name)}`)));
+}

package/scripts/dollyfile-graph.mjs

@@ -0,0 +1,41 @@
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { loadRecipeGraph } from "../src/dollyfile-graph.mjs";
+import { recipeFileName } from "../src/dollyfile-view.mjs";
+import { recipeFiles } from "./recipe-files.mjs";
+import { siteReference } from "../src/static-asset.mjs";
+
+// Loads catalog recipe graphs from a project directory, sharing parsed recipes.
+export function createDollyfileGraphLoader(projectDir) {
+  const recipes = new Map();
+  let files;
+  async function read(reference) {
+    files ??= recipeFiles(projectDir);
+    const path = (await files).get(reference);
+    if (!path) throw new Error(`${reference}: no such recipe`);
+    return readFile(resolve(projectDir, path));
+  }
+  return (rootFilename = "Dollyfile") => loadRecipeGraph(read, siteReference(rootFilename), recipes);
+}
+
+export function loadDollyfileGraph(projectDir, rootFilename = "Dollyfile") {
+  return createDollyfileGraphLoader(projectDir)(rootFilename);
+}
+
+// The recipe provenance /bin/dollyfile records, in its order.
+export function recipeRecords(graph) {
+  const records = [], seen = new Set();
+  function visit(record) {
+    if (seen.has(record.location)) return;
+    seen.add(record.location);
+    for (const { target } of record.artifactTargets) visit(target);
+    records.push({
+      name: record.name, locator: record.location,
+      sourcePath: record.location,
+      retainedPath: `/etc/dolly/recipes/${recipeFileName(record.location)}`,
+      sha256: record.sha256, byteLength: Buffer.byteLength(record.source),
+    });
+  }
+  visit(graph.root);
+  return records;
+}