@pieceful/ravel-host-node 0.2.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pieceful/ravel-host-node",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "type": "module",
   "description": "Node host capabilities for Ravel.",
   "license": "MIT",
@@ -36,15 +36,16 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@pieceful/ravel-asciidoc": "0.2.0",
-    "@pieceful/ravel-core": "0.2.0",
-    "@pieceful/ravel-html": "0.2.0",
-    "@pieceful/ravel-markdown": "0.2.0",
-    "@pieceful/ravel-markdown-litpro": "0.2.0",
-    "@pieceful/ravel-map": "0.2.0",
-    "@pieceful/ravel-myst": "0.2.0",
-    "@pieceful/ravel-noweb": "0.2.0",
-    "@pieceful/ravel-org": "0.2.0",
-    "smol-toml": "^1.7.0"
+    "@pieceful/ravel-asciidoc": "0.3.0",
+    "@pieceful/ravel-core": "0.3.0",
+    "@pieceful/ravel-html": "0.3.0",
+    "@pieceful/ravel-map": "0.3.0",
+    "@pieceful/ravel-markdown": "0.3.0",
+    "@pieceful/ravel-markdown-litpro": "0.3.0",
+    "@pieceful/ravel-myst": "0.3.0",
+    "@pieceful/ravel-noweb": "0.3.0",
+    "@pieceful/ravel-org": "0.3.0",
+    "@pieceful/ravel-transforms": "0.3.0",
+    "smol-toml": "^1.9.1"
   }
 }

package/src/index.js

@@ -1,5 +1,6 @@
 import { lstat, readFile, readdir, mkdir, rename, unlink, writeFile } from "node:fs/promises";
 import { createHash, randomUUID } from "node:crypto";
+import { deflateRawSync } from "node:zlib";
 import { basename, dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { parse as parseToml } from "smol-toml";
 import {
@@ -10,14 +11,17 @@ import {
 } from "@pieceful/ravel-core";
 import { asciidocToMap } from "@pieceful/ravel-asciidoc";
 import { htmlToMap } from "@pieceful/ravel-html";
-import { markdownToMap } from "@pieceful/ravel-markdown";
+import { markdownToMap, parseFrontMatter } from "@pieceful/ravel-markdown";
 import { isLitproMarkdown, litproMarkdownToMap } from "@pieceful/ravel-markdown-litpro";
 import { assertRavelMap } from "@pieceful/ravel-map";
 import { mystToMap } from "@pieceful/ravel-myst";
 import { nowebToMap } from "@pieceful/ravel-noweb";
 import { orgToMap } from "@pieceful/ravel-org";
+import { builtinTransforms } from "@pieceful/ravel-transforms";
+import { pathToFileURL } from "node:url";
 
 const missing = (error) => error?.code === "ENOENT";
+const componentPattern = /^[a-z][a-z0-9-]*$/;
 
 const throwIfAborted = (signal) => {
   if (!signal?.aborted) return;
@@ -298,6 +302,7 @@ const collectPretransformMaps = async (
   const activeScope = scope ?? await createInputScope(dirname(resolve(entryPath)));
   const visited = new Set();
   const maps = [];
+  const mapPaths = [];
   const diagnostics = [];
   const authoredSourcePaths = new Set();
   const authoredSourceTexts = new Map();
@@ -390,12 +395,14 @@ const collectPretransformMaps = async (
       });
     }
     maps.push(map);
+    mapPaths.push(absolutePath);
   };
 
   await visit(entryPath, entryOptions);
   throwIfAborted(signal);
   return {
     maps,
+    mapPaths,
     diagnostics,
     rootDirectory: activeScope.root,
     authoredSourcePaths: [...authoredSourcePaths].sort(),
@@ -455,6 +462,252 @@ const reportUnknownKeys = (value, allowed, description, configPath) => {
   }
 };
 
+// Names core evaluates itself; a project transform cannot replace them.
+const coreTransformNames = new Set([
+  "concat", "trim", "normalize-eol", "indent", "dedent", "replace", "quote-reference",
+  "jsontext", "emit", "text", "ch", "delay"
+]);
+
+/**
+ * Load `[[transforms]]` entries: project-local ES modules whose export is a
+ * `(value, context) => string` function. These run as ordinary Node code with
+ * the host's privileges, so they are configured only in the TOML file, never by
+ * a document. Ravel's built-in transforms are always available and a project
+ * module may replace one of them (for example to use another Markdown engine).
+ */
+const loadProjectTransforms = async (entries, scope, absoluteConfig) => {
+  const transforms = { ...builtinTransforms };
+  if (entries === undefined) return transforms;
+  if (!Array.isArray(entries)) throw inputError("RC102", "transforms must contain [[transforms]] entries.", absoluteConfig);
+  const seen = new Set();
+  for (const [index, entry] of entries.entries()) {
+    const path = "transforms[" + index + "]";
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) throw inputError("RC102", path + " must be a table.", absoluteConfig);
+    reportUnknownKeys(entry, new Set(["name", "module", "export"]), path, absoluteConfig);
+    const name = requireConfigString(entry.name, path + ".name", absoluteConfig);
+    if (!/^[a-z][a-z0-9-]*$/.test(name)) throw inputError("RC102", path + ".name must be a lowercase transform name such as \"markdown-it\".", absoluteConfig);
+    if (coreTransformNames.has(name)) throw inputError("RC102", path + ".name " + JSON.stringify(name) + " is a core command and cannot be replaced.", absoluteConfig);
+    if (seen.has(name)) throw inputError("RC102", path + ".name " + JSON.stringify(name) + " is defined more than once.", absoluteConfig);
+    seen.add(name);
+    const modulePath = await scope.path(requireConfigString(entry.module, path + ".module", absoluteConfig), path + ".module");
+    const exportName = entry.export === undefined ? "default" : requireConfigString(entry.export, path + ".export", absoluteConfig);
+    let namespace;
+    try {
+      // The content hash keeps a long-lived host (an editor) from reusing a
+      // stale module after the file changes.
+      const url = pathToFileURL(modulePath);
+      url.search = "ravel=" + contentHash(await readFile(modulePath, "utf8")).slice(0, 16);
+      namespace = await import(url.href);
+    } catch (error) {
+      throw inputError("RC103", path + " could not load " + modulePath + ": " + (error?.message ?? String(error)), absoluteConfig);
+    }
+    const transform = namespace[exportName];
+    if (typeof transform !== "function") {
+      throw inputError("RC103", path + " module " + modulePath + " has no function export " + JSON.stringify(exportName) + ".", absoluteConfig);
+    }
+    transforms[name] = transform;
+  }
+  return transforms;
+};
+
+const escapeRegExp = (value) => value.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+
+/** Translate a `/`-separated glob (`*`, `**`, `?`) into an anchored RegExp. */
+const globPattern = (glob) => {
+  let pattern = "";
+  for (let index = 0; index < glob.length; index += 1) {
+    const character = glob[index];
+    if (character === "*" && glob[index + 1] === "*") {
+      const slash = glob[index + 2] === "/";
+      pattern += slash ? "(?:[^/]+/)*" : ".*";
+      index += slash ? 2 : 1;
+    } else if (character === "*") pattern += "[^/]*";
+    else if (character === "?") pattern += "[^/]";
+    else pattern += escapeRegExp(character);
+  }
+  return new RegExp("^" + pattern + "$");
+};
+
+/**
+ * List files under `root` matching `glob`, in a deterministic code-point
+ * order. Dot-files and dot-directories are skipped; a symbolic link anywhere
+ * in the walk is an error, as everywhere else in the Node host.
+ */
+const globFiles = async (root, glob, description) => {
+  if (isAbsolute(glob) || glob.split("/").includes("..")) {
+    throw new Error(description + " must be a relative glob inside the Ravel root: " + glob);
+  }
+  const segments = glob.split("/");
+  const firstWild = segments.findIndex((segment) => /[*?]/.test(segment));
+  const base = firstWild === -1 ? segments.slice(0, -1) : segments.slice(0, firstWild);
+  const start = join(root, ...base);
+  const matcher = globPattern(glob);
+  const matches = [];
+  const walk = async (directory) => {
+    let entries;
+    try {
+      entries = await readdir(directory, { withFileTypes: true });
+    } catch (error) {
+      if (missing(error)) return;
+      throw error;
+    }
+    for (const entry of entries) {
+      if (entry.name.startsWith(".")) continue;
+      const path = join(directory, entry.name);
+      if (entry.isSymbolicLink()) throw new Error(description + " must not traverse a symbolic link: " + path);
+      if (entry.isDirectory()) await walk(path);
+      else if (entry.isFile() && matcher.test(portableRelative(root, path))) matches.push(path);
+    }
+  };
+  await assertNoSymlinks(root, start, description);
+  await walk(start);
+  return matches.sort((left, right) => {
+    const a = portableRelative(root, left);
+    const b = portableRelative(root, right);
+    return a < b ? -1 : a > b ? 1 : 0;
+  });
+};
+
+const positionAt = (text, offset) => {
+  let line = 0;
+  let lineStart = 0;
+  for (let index = text.indexOf("\n"); index !== -1 && index < offset; index = text.indexOf("\n", index + 1)) {
+    line += 1;
+    lineStart = index + 1;
+  }
+  return { line, column: offset - lineStart, offset };
+};
+
+const slugify = (value) => String(value).toLowerCase().normalize("NFKD")
+  .replace(/[\u0300-\u036f]/g, "").replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+
+const fillPattern = (pattern, values, description, configPath) => pattern.replace(/\{([a-z][a-z0-9_-]*)\}/gi, (match, key) => {
+  const value = values[key];
+  if (value === undefined || value === null || typeof value === "object") {
+    throw inputError("RC104", description + " uses {" + key + "}, which is not a text value for this item.", configPath);
+  }
+  return String(value);
+});
+
+/**
+ * Expand `[[collections]]`: every file matching `glob` becomes an item
+ * document with a `body` chunk (the text after any front matter, mapped to its
+ * exact source range), a `data.json` chunk (front matter plus slug, name, path,
+ * and output), and a `page` chunk that pipes the body through `pipe` and, when
+ * `layout` names a chunk, fills that layout with `template`. Each item gets one
+ * `out` directive from the `out` pattern. A `<name>::index.json` chunk lists
+ * every item's data, in order, for index pages.
+ */
+const loadCollections = async (entries, scope, absoluteConfig, overlays) => {
+  const empty = { maps: [], inputPaths: [], texts: new Map() };
+  if (entries === undefined) return empty;
+  if (!Array.isArray(entries)) throw inputError("RC102", "collections must contain [[collections]] entries.", absoluteConfig);
+  const maps = [];
+  const inputPaths = [];
+  const texts = new Map();
+  const names = new Set();
+  const configUri = portableRelative(scope.root, absoluteConfig);
+  for (const [index, entry] of entries.entries()) {
+    const path = "collections[" + index + "]";
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) throw inputError("RC102", path + " must be a table.", absoluteConfig);
+    reportUnknownKeys(entry, new Set(["name", "glob", "out", "layout", "pipe", "references"]), path, absoluteConfig);
+    const name = requireConfigString(entry.name, path + ".name", absoluteConfig);
+    if (!componentPattern.test(name)) throw inputError("RC102", path + ".name must be a lowercase identifier such as \"pages\".", absoluteConfig);
+    if (names.has(name)) throw inputError("RC102", path + ".name " + JSON.stringify(name) + " is used by more than one collection.", absoluteConfig);
+    names.add(name);
+    const glob = requireConfigString(entry.glob, path + ".glob", absoluteConfig);
+    const outPattern = requireConfigString(entry.out, path + ".out", absoluteConfig);
+    const layout = entry.layout === undefined ? null : requireConfigString(entry.layout, path + ".layout", absoluteConfig);
+    const pipe = entry.pipe === undefined ? "markdown" : entry.pipe;
+    if (typeof pipe !== "string") throw inputError("RC102", path + ".pipe must be a pipeline string such as \"markdown\" or \"\".", absoluteConfig);
+    if (entry.references !== undefined && typeof entry.references !== "boolean") {
+      throw inputError("RC102", path + ".references must be true or false.", absoluteConfig);
+    }
+    for (const [field, value] of [["layout", layout ?? ""], ["pipe", pipe]]) {
+      if (value.includes("`")) throw inputError("RC102", path + "." + field + " must not contain a backtick.", absoluteConfig);
+    }
+    let files;
+    try {
+      files = await globFiles(scope.root, glob, path + ".glob");
+    } catch (error) {
+      throw inputError("RC104", error.message, absoluteConfig);
+    }
+    const items = [];
+    const slugs = new Map();
+    for (const file of files) {
+      const uri = portableRelative(scope.root, file);
+      const text = await readInputText(file, "collection item", "RC101", overlays);
+      let front;
+      try {
+        front = parseFrontMatter(text);
+      } catch (error) {
+        throw inputError("RC104", "Invalid front matter in " + uri + ": " + (error?.message ?? String(error)), file);
+      }
+      const data = front.data ?? {};
+      if (typeof data !== "object" || Array.isArray(data)) throw inputError("RC104", "Front matter in " + uri + " must be a mapping.", file);
+      const stem = basename(uri, extname(uri));
+      const slug = slugify(typeof data.slug === "string" ? data.slug : stem);
+      if (!slug) throw inputError("RC104", "Could not derive a slug for " + uri + "; add a `slug` to its front matter.", file);
+      if (slugs.has(slug)) throw inputError("RC104", uri + " and " + slugs.get(slug) + " both produce the slug " + JSON.stringify(slug) + " in collection " + name + ".", file);
+      slugs.set(slug, uri);
+      const dir = dirname(uri) === "." ? "" : dirname(uri);
+      const values = { ...data, slug, name: stem, dir, path: uri.slice(0, uri.length - extname(uri).length) };
+      const output = fillPattern(outPattern, values, path + ".out", absoluteConfig);
+      items.push({ file, uri, text, front, data: { ...data, slug, name: stem, dir, path: uri, out: output, collection: name }, output });
+    }
+    const sourceAt = (uri, text, start, end) => ({ uri, range: { start: positionAt(text, start), end: positionAt(text, end) } });
+    const literalSyntax = (enabled) => ({ data: { ravel: { referenceSyntax: { underscore: enabled } } } });
+    for (const item of items) {
+      const document = name + "-" + item.data.slug;
+      if (!componentPattern.test(document)) throw inputError("RC104", "Collection item " + item.uri + " produces the invalid document id " + document + ".", item.file);
+      const chunk = (chunkName, type, body, source, metadata) => ({
+        id: document + "::" + chunkName + (type ? "." + type : ""),
+        identity: { document, chunk: chunkName, minor: null, type },
+        name: chunkName,
+        body,
+        definitionPipeline: [],
+        metadata,
+        source
+      });
+      const bodySource = sourceAt(item.uri, item.text, item.front.bodyStart, item.text.length);
+      const frontSource = sourceAt(item.uri, item.text, 0, item.front.end);
+      const content = "ch('" + document + "::body" + (pipe.trim() ? " | " + pipe.trim() : "") + "')";
+      const page = layout
+        ? "_`" + layout + " | template(ch('" + document + "::data.json'), 'content', " + content + ")`"
+        : "_`" + document + "::body" + (pipe.trim() ? " | " + pipe.trim() : "") + "`";
+      maps.push({
+        version: 1,
+        document: { id: document, uri: item.uri, format: "ravel-collection-item-v1" },
+        chunks: [
+          chunk("body", null, item.text.slice(item.front.bodyStart), bodySource, { language: "markdown", tags: ["collection"], ...literalSyntax(entry.references === true) }),
+          chunk("data", "json", JSON.stringify(item.data, null, 2) + "\n", frontSource, { language: "json", tags: ["collection"], ...literalSyntax(false) })
+        ],
+        directives: [
+          { kind: "create", document, name: "page", body: page, source: configSource(absoluteConfig) },
+          { kind: "out", name: item.output, from: document + "::page", source: configSource(absoluteConfig) }
+        ]
+      });
+      inputPaths.push(item.file);
+      texts.set(item.file, item.text);
+    }
+    maps.push({
+      version: 1,
+      document: { id: name, uri: configUri, format: "ravel-collection-index-v1" },
+      chunks: [{
+        id: name + "::index.json",
+        identity: { document: name, chunk: "index", minor: null, type: "json" },
+        name: "index",
+        body: JSON.stringify(items.map((item) => item.data), null, 2) + "\n",
+        definitionPipeline: [],
+        metadata: { language: "json", tags: ["collection"], ...literalSyntax(false) },
+        source: configSource(absoluteConfig)
+      }],
+      directives: []
+    });
+  }
+  return { maps, inputPaths, texts };
+};
+
 const loadLiveConfiguration = async (
   live,
   scope,
@@ -544,10 +797,13 @@ export const loadTomlBuild = async (configPath, options = {}) => {
     if (Array.isArray(error?.diagnostics)) throw error;
     throw inputError("RC101", "Invalid Ravel TOML config: " + (error?.message ?? String(error)), absoluteConfig);
   }
-  reportUnknownKeys(config, new Set(["version", "files", "build", "outputs", "live"]), "config", absoluteConfig);
+  reportUnknownKeys(config, new Set(["version", "files", "collections", "build", "outputs", "live", "transforms"]), "config", absoluteConfig);
   if (config.version !== 1) throw inputError("RC102", "version must be 1.", absoluteConfig);
-  if (!Array.isArray(config.files) || config.files.length === 0) {
-    throw inputError("RC102", "files must contain one or more [[files]] entries.", absoluteConfig);
+  if (config.files !== undefined && !Array.isArray(config.files)) {
+    throw inputError("RC102", "files must contain [[files]] entries.", absoluteConfig);
+  }
+  if (!config.files?.length && !config.collections?.length) {
+    throw inputError("RC102", "files must contain one or more [[files]] entries, or the config must define [[collections]].", absoluteConfig);
   }
   if (config.build !== undefined && (!config.build || typeof config.build !== "object" || Array.isArray(config.build))) {
     throw inputError("RC102", "build must be a [build] table.", absoluteConfig);
@@ -576,7 +832,7 @@ export const loadTomlBuild = async (configPath, options = {}) => {
     options.overlays,
     { readResources: options.readLiveResources !== false }
   );
-  const results = await Promise.all(config.files.map(async (file, index) => {
+  const results = await Promise.all((config.files ?? []).map(async (file, index) => {
     if (!file || typeof file !== "object") throw inputError("RC102", "files[" + index + "] must be a table.", absoluteConfig);
     reportUnknownKeys(file, new Set([
       "path", "document", "mode", "profile", "adapter", "dialect",
@@ -662,7 +918,16 @@ export const loadTomlBuild = async (configPath, options = {}) => {
     }, scope, options.overlays);
   }));
   throwIfAborted(options.signal);
-  const pretransform = combineMaps(results.flatMap((result) => result.maps));
+  // Several [[files]] may import the same document; load it once, keeping the
+  // first occurrence in configuration order.
+  const seenMapPaths = new Set();
+  const collections = await loadCollections(config.collections, scope, absoluteConfig, options.overlays);
+  const pretransform = combineMaps([...results.flatMap((result) => result.maps.filter((_, index) => {
+    const path = result.mapPaths[index];
+    if (seenMapPaths.has(path)) return false;
+    seenMapPaths.add(path);
+    return true;
+  })), ...collections.maps]);
   pretransform.diagnostics.push(...results.flatMap((result) => result.diagnostics));
   for (const output of config.outputs ?? []) {
     if (!output || typeof output !== "object") throw inputError("RC102", "Each [[outputs]] entry must be a table.", absoluteConfig);
@@ -676,11 +941,17 @@ export const loadTomlBuild = async (configPath, options = {}) => {
   }
   return {
     pretransform: relativizeSourceUris(pretransform, scope.root),
-    authoredSourceUris: [...new Set(results.flatMap(authoredSourceUris))].sort(),
-    authoredSourceTexts: Object.assign({}, ...results.map(authoredSourceTexts)),
+    authoredSourceUris: [...new Set([
+      ...results.flatMap(authoredSourceUris),
+      ...collections.inputPaths.map((path) => portableRelative(scope.root, path))
+    ])].sort(),
+    authoredSourceTexts: Object.assign({}, ...results.map(authoredSourceTexts), Object.fromEntries(
+      [...collections.texts.entries()].map(([path, text]) => [portableRelative(scope.root, path), text])
+    )),
     loadedInputUris: [...new Set([
       relative(scope.root, absoluteConfig).split(sep).join("/"),
-      ...results.flatMap(loadedInputUris)
+      ...results.flatMap(loadedInputUris),
+      ...collections.inputPaths.map((path) => portableRelative(scope.root, path))
     ])].sort(),
     sourceEditsAllowed: results.every((result) => !result.containsJsonMaps),
     ...(outDirectory === undefined ? {} : { outputDirectory: await scope.path(outDirectory, "build.out_dir") }),
@@ -689,6 +960,7 @@ export const loadTomlBuild = async (configPath, options = {}) => {
       clean: build.clean === true,
       backup: build.backup ?? false
     },
+    transforms: await loadProjectTransforms(config.transforms, scope, absoluteConfig),
     ...(live ? { live } : {})
   };
 };
@@ -716,7 +988,8 @@ export const loadBuildInput = async (inputPath, options = {}) => {
       authoredSourceUris: authoredSourceUris(collected),
       authoredSourceTexts: authoredSourceTexts(collected),
       loadedInputUris: loadedInputUris(collected),
-      sourceEditsAllowed: !collected.containsJsonMaps
+      sourceEditsAllowed: !collected.containsJsonMaps,
+      transforms: { ...builtinTransforms }
     };
   }
   throw inputError("RH101", "Ravel input must be a .json map, supported markup document, or .toml build config.", inputPath);
@@ -748,19 +1021,21 @@ const sidecarName = (name) => name + ".ravelmap";
 /** Build a deterministic, non-writing description of artifact output. */
 export const planDeliverables = (program, outputDirectory) => {
   const root = resolve(outputDirectory);
-  const destinations = new Set();
+  // Compare case-insensitively so a plan is portable to macOS and Windows,
+  // where `README.md` and `readme.md` name the same file.
+  const destinations = new Set([manifestName, textManifestName].map((name) => safeDestination(root, name).toLowerCase()));
+  const claim = (destination, message) => {
+    const key = destination.toLowerCase();
+    if (destinations.has(key)) throw new Error(message);
+    destinations.add(key);
+  };
   const deliverables = orderedDeliverables(program).map((deliverable) => {
     const destination = safeDestination(root, deliverable.name);
-    if (destinations.has(destination)) throw new Error("Multiple deliverables resolve to the same destination: " + deliverable.name);
-    destinations.add(destination);
+    claim(destination, "Deliverable collides with another output or Ravel's manifest (names are compared case-insensitively): " + deliverable.name);
     const hasProvenance = Array.isArray(deliverable.segments);
     const ravelmap = hasProvenance ? sidecarName(deliverable.name) : null;
     if (ravelmap) {
-      const mapDestination = safeDestination(root, ravelmap);
-      if (destinations.has(mapDestination)) {
-        throw new Error("A deliverable provenance map collides with another output: " + ravelmap);
-      }
-      destinations.add(mapDestination);
+      claim(safeDestination(root, ravelmap), "A deliverable provenance map collides with another output: " + ravelmap);
     }
     return {
       name: deliverable.name,
@@ -772,10 +1047,7 @@ export const planDeliverables = (program, outputDirectory) => {
     };
   });
   if (deliverables.some((deliverable) => deliverable.ravelmap)) {
-    const aggregateDestination = safeDestination(root, aggregateProvenanceName);
-    if (destinations.has(aggregateDestination)) {
-      throw new Error("The aggregate provenance map collides with another output: " + aggregateProvenanceName);
-    }
+    claim(safeDestination(root, aggregateProvenanceName), "The aggregate provenance map collides with another output: " + aggregateProvenanceName);
   }
   return {
     version: 1,
@@ -887,8 +1159,9 @@ const writeFilesAtomically = async (scope, entries, description) => {
       const token = randomUUID();
       const temporary = join(dirname(entry.destination), "." + basename(entry.destination) + ".ravel-stage-" + token);
       const backup = join(dirname(entry.destination), "." + basename(entry.destination) + ".ravel-backup-" + token);
-      await writeFile(temporary, entry.value, "utf8");
+      // Record the entry before writing so a failed write still removes its temporary file.
       staged.push({ ...entry, exists, temporary, backup, committed: false, backedUp: false });
+      await writeFile(temporary, entry.value, "utf8");
     }
 
     for (const entry of staged) {
@@ -911,16 +1184,25 @@ const writeFilesAtomically = async (scope, entries, description) => {
       }
     }
   } catch (error) {
+    // Restore every entry even if one restoration fails, then report the
+    // original failure with any rollback problems attached.
+    const rollbackErrors = [];
     for (const entry of staged.slice().reverse()) {
-      if (entry.committed) await removeIfPresent(entry.destination);
-      if (entry.backedUp) {
+      for (const step of [
+        () => entry.committed && removeIfPresent(entry.destination),
+        () => entry.backedUp && rename(entry.backup, entry.destination),
+        () => removeIfPresent(entry.temporary)
+      ]) {
         try {
-          await rename(entry.backup, entry.destination);
+          await step();
         } catch (rollbackError) {
-          if (!missing(rollbackError)) throw rollbackError;
+          if (!missing(rollbackError)) rollbackErrors.push(rollbackError);
         }
       }
-      await removeIfPresent(entry.temporary);
+    }
+    if (rollbackErrors.length) {
+      error.message += " (rollback incomplete: " + rollbackErrors.map((entry) => entry.message).join("; ") + ")";
+      error.rollbackErrors = rollbackErrors;
     }
     throw error;
   }
@@ -1011,10 +1293,14 @@ export const writeBuildManifest = async (program, outputDirectory, {
 export const writeBuildArtifacts = async (program, outputDirectory, {
   rootDirectory = outputDirectory,
   stale = [],
+  clean = false,
   generatedAt = new Date().toISOString()
 } = {}) => {
   const scope = await createOutputScope(outputDirectory, rootDirectory);
   const plan = planDeliverables(program, scope.root);
+  // With `clean`, previously managed files are removed only after the new
+  // build has committed, so a failed write keeps the last good output.
+  const previous = clean ? await readManifest(scope.root, rootDirectory) : null;
   const manifest = createBuildManifest(program, scope.root, { stale, builtAt: generatedAt });
   const deliverableEntries = plan.deliverables.map((deliverable) => ({
     destination: safeDestination(scope.root, deliverable.name),
@@ -1043,8 +1329,27 @@ export const writeBuildArtifacts = async (program, outputDirectory, {
     { destination: manifestDestination, value: JSON.stringify(manifest, null, 2) + "\n" },
     { destination: textManifestDestination, value: formatTextManifest(manifest, generatedAt) }
   ], "Build artifact path");
+  // Remove previously managed deliverables (and their sidecars) that this
+  // build no longer produces; files it rewrote were already replaced.
+  const active = new Set(plan.deliverables.map((deliverable) => deliverable.name));
+  const supersededDeliverables = previous
+    ? managedDeliverables(previous.manifest).filter((deliverable) => !active.has(deliverable.name))
+    : [];
+  const superseded = supersededDeliverables.flatMap((deliverable) => [
+    safeDestination(scope.root, deliverable.name),
+    ...(deliverable.ravelmap ? [safeDestination(scope.root, deliverable.ravelmap)] : [])
+  ]);
+  if (previous?.manifest.provenance?.aggregate && !aggregateEntry.length) {
+    superseded.push(safeDestination(scope.root, previous.manifest.provenance.aggregate));
+  }
+  await removeManagedTargets(scope, superseded);
   return {
     written: deliverableEntries.map((entry) => entry.destination),
+    removed: supersededDeliverables.map((deliverable) => ({
+      name: deliverable.name,
+      path: portableRelative(scope.root, safeDestination(scope.root, deliverable.name)),
+      from: deliverable.from ?? null
+    })).sort((left, right) => left.name.localeCompare(right.name)),
     provenance: {
       sidecars: provenanceEntries.map((entry) => entry.destination),
       aggregate: aggregateEntry[0]?.destination ?? null
@@ -1076,6 +1381,23 @@ const planManagedRemoval = async (outputDirectory, rootDirectory, staleOnly) =>
   };
 };
 
+/** Delete managed files only after every path component passes the symlink policy. */
+const removeManagedTargets = async (scope, targets) => {
+  for (const target of targets) {
+    await assertNoSymlinks(scope.root, target, "Managed output path");
+    await existingFile(target, "Managed output path");
+  }
+  for (const target of targets) await removeIfPresent(target);
+};
+
+const managedTargets = (root, manifest) => [
+  ...managedDeliverables(manifest).flatMap((deliverable) => [
+    safeDestination(root, deliverable.name),
+    ...(deliverable.ravelmap ? [safeDestination(root, deliverable.ravelmap)] : [])
+  ]),
+  ...(manifest.provenance?.aggregate ? [safeDestination(root, manifest.provenance.aggregate)] : [])
+];
+
 const removeManagedFiles = async (plan, rootDirectory, dryRun, removeManifest) => {
   if (!plan.manifest || dryRun) return { removed: plan.deliverables, manifestRemoved: false };
   const scope = await createOutputScope(plan.outputDirectory, rootDirectory);
@@ -1087,8 +1409,7 @@ const removeManagedFiles = async (plan, rootDirectory, dryRun, removeManifest) =
     ...(plan.aggregate ? [safeDestination(scope.root, plan.aggregate)] : []),
     ...(removeManifest ? [safeDestination(scope.root, manifestName), safeDestination(scope.root, textManifestName)] : [])
   ];
-  for (const target of targets) await existingFile(target, "Managed output path");
-  for (const target of targets) await removeIfPresent(target);
+  await removeManagedTargets(scope, targets);
   return { removed: plan.deliverables, manifestRemoved: removeManifest };
 };
 
@@ -1154,30 +1475,34 @@ const zipArchive = (files) => {
     }
     const { date, time } = zipDateTime(file.mtime);
     const crc = crc32(file.value);
+    // Deflate when it helps; tiny or incompressible files stay stored.
+    const deflated = deflateRawSync(file.value);
+    const method = deflated.length < size ? 8 : 0;
+    const data = method === 8 ? deflated : file.value;
     const local = Buffer.alloc(30);
     local.writeUInt32LE(0x04034b50, 0);
     local.writeUInt16LE(20, 4);
     local.writeUInt16LE(0x0800, 6);
-    local.writeUInt16LE(0, 8);
+    local.writeUInt16LE(method, 8);
     local.writeUInt16LE(time, 10);
     local.writeUInt16LE(date, 12);
     local.writeUInt32LE(crc, 14);
-    local.writeUInt32LE(size, 18);
+    local.writeUInt32LE(data.length, 18);
     local.writeUInt32LE(size, 22);
     local.writeUInt16LE(name.length, 26);
     local.writeUInt16LE(0, 28);
-    locals.push(local, name, file.value);
+    locals.push(local, name, data);
 
     const directory = Buffer.alloc(46);
     directory.writeUInt32LE(0x02014b50, 0);
     directory.writeUInt16LE(20, 4);
     directory.writeUInt16LE(20, 6);
     directory.writeUInt16LE(0x0800, 8);
-    directory.writeUInt16LE(0, 10);
+    directory.writeUInt16LE(method, 10);
     directory.writeUInt16LE(time, 12);
     directory.writeUInt16LE(date, 14);
     directory.writeUInt32LE(crc, 16);
-    directory.writeUInt32LE(size, 20);
+    directory.writeUInt32LE(data.length, 20);
     directory.writeUInt32LE(size, 24);
     directory.writeUInt16LE(name.length, 28);
     directory.writeUInt16LE(0, 30);
@@ -1187,7 +1512,7 @@ const zipArchive = (files) => {
     directory.writeUInt32LE(0, 38);
     directory.writeUInt32LE(offset, 42);
     central.push(directory, name);
-    offset += local.length + name.length + size;
+    offset += local.length + name.length + data.length;
   }
   const centralSize = central.reduce((size, value) => size + value.length, 0);
   if (offset + centralSize > 0xffffffff) throw new Error("Backup archive is too large for ZIP without ZIP64 support.");
@@ -1203,20 +1528,25 @@ const zipArchive = (files) => {
   return Buffer.concat([...locals, ...central, end]);
 };
 
-const collectBackupFiles = async (root, directory = root) => {
+/** Read the files named by the previous manifest; unmanaged neighbors are never archived. */
+const collectBackupFiles = async (root, manifest) => {
+  const targets = [
+    ...managedTargets(root, manifest),
+    safeDestination(root, manifestName),
+    safeDestination(root, textManifestName)
+  ];
   const files = [];
-  const entries = await readdir(directory, { withFileTypes: true });
-  for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
-    const path = join(directory, entry.name);
-    const stat = await lstat(path);
-    if (stat.isSymbolicLink()) throw new Error("Backup output must not traverse a symbolic link: " + path);
-    if (stat.isDirectory()) files.push(...await collectBackupFiles(root, path));
-    else if (stat.isFile()) files.push({
-      name: relative(root, path).split(sep).join("/"),
-      value: await readFile(path),
-      mtime: stat.mtime
-    });
-    else throw new Error("Backup output must contain only files and directories: " + path);
+  for (const path of [...new Set(targets)].sort()) {
+    await assertNoSymlinks(root, path, "Backup output");
+    let stat;
+    try {
+      stat = await lstat(path);
+    } catch (error) {
+      if (missing(error)) continue;
+      throw error;
+    }
+    if (!stat.isFile()) throw new Error("Backup output must be a file: " + path);
+    files.push({ name: portableRelative(root, path), value: await readFile(path), mtime: stat.mtime });
   }
   return files;
 };
@@ -1225,33 +1555,47 @@ const collectBackupFiles = async (root, directory = root) => {
 export const planOutputBackup = async (outputDirectory, {
   outputRootDirectory = outputDirectory,
   backupRootDirectory = outputRootDirectory,
-  backupPath
+  backupPath,
+  timestampName = false
 } = {}) => {
   const output = resolve(outputDirectory);
   const previous = await readManifest(output, outputRootDirectory);
-  if (!previous) throw new Error("Cannot create a backup without an existing Ravel build manifest: " + output);
+  // A first build has nothing to protect, so there is nothing to archive.
+  if (!previous) return { outputDirectory: output, path: null, skipped: "no previous Ravel build" };
   const builtAt = previous.manifest.builtAt;
   const timestamp = Date.parse(builtAt);
   if (!Number.isFinite(timestamp)) throw new Error("Build manifest has no valid build timestamp for backup: " + previous.path);
   const backupRoot = resolve(backupRootDirectory);
   await assertDirectory(backupRoot, "Backup root");
-  const path = backupPath === undefined
-    ? join(backupRoot, "backups", basename(output) + "-" + Math.floor(timestamp / 1000) + ".zip")
-    : await scopedPath(backupRoot, backupPath, "Backup path");
-  if (extname(path).toLowerCase() !== ".zip") throw new Error("Backup file must have a .zip extension: " + path);
-  if (!containedIn(backupRoot, path)) throw new Error("Backup path escapes the Ravel root: " + path);
-  await assertNoSymlinks(backupRoot, path, "Backup path");
-  if (await existingFile(path, "Backup file")) throw new Error("Backup file already exists: " + path);
+  const seconds = Math.floor(timestamp / 1000);
+  const named = backupPath === undefined ? null : await scopedPath(backupRoot, backupPath, "Backup path");
+  if (named && extname(named).toLowerCase() !== ".zip") throw new Error("Backup file must have a .zip extension: " + named);
+  // A derived name is reused by every build, so it never blocks one: when the
+  // name is taken (two builds in one second, or a retry after a failed write),
+  // a numeric suffix keeps every archive. An explicit name must be new.
+  const derived = named === null || timestampName;
+  const base = named === null
+    ? join(backupRoot, "backups", basename(output) + "-" + seconds)
+    : timestampName ? named.slice(0, -extname(named).length) + "-" + seconds : named.slice(0, -extname(named).length);
+  let path = base + ".zip";
+  for (let attempt = 2; ; attempt += 1) {
+    if (!containedIn(backupRoot, path)) throw new Error("Backup path escapes the Ravel root: " + path);
+    await assertNoSymlinks(backupRoot, path, "Backup path");
+    if (!await existingFile(path, "Backup file")) break;
+    if (!derived) throw new Error("Backup file already exists: " + path);
+    path = base + "-" + attempt + ".zip";
+  }
   return { outputDirectory: output, path, manifest: previous, builtAt };
 };
 
 /** Archive the complete current output tree before it is cleaned or replaced. */
 export const createOutputBackup = async (outputDirectory, options = {}) => {
   const plan = await planOutputBackup(outputDirectory, options);
+  if (!plan.path) return { path: null, files: [], skipped: plan.skipped };
   const backupRoot = resolve(options.backupRootDirectory ?? options.outputRootDirectory ?? outputDirectory);
   await ensureDirectoryTree(backupRoot, dirname(plan.path), "Backup path");
   if (await existingFile(plan.path, "Backup file")) throw new Error("Backup file already exists: " + plan.path);
-  const files = await collectBackupFiles(plan.outputDirectory);
+  const files = await collectBackupFiles(plan.outputDirectory, plan.manifest.manifest);
   const temporary = join(dirname(plan.path), "." + basename(plan.path) + ".ravel-stage-" + randomUUID());
   try {
     await writeFile(temporary, zipArchive(files));