book-kit 0.0.0-stage → 0.6.0

package/commands/conventions.js

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+
+// book-kit conventions
+//
+// Print the book's writing conventions as Markdown, from its resolved config:
+// the callouts and how to write them, the structure the validators expect,
+// which checks run, and each preset's CONVENTIONS.md. The Claude agents in
+// claude-plugin/ read this instead of hardcoding one house style.
+
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { loadConfig } from '../lib/config.js';
+import { enabledRules } from '../lib/lint.js';
+import { BUILTIN_VALIDATORS } from '../validators/index.js';
+
+const config = loadConfig();
+const { callouts = [], structure, validators, paths } = config;
+const code = (s) => `\`${s}\``;
+const lines = [];
+const say = (...more) => lines.push(...more);
+
+say(
+  `# Writing conventions: ${config.metadata.title}`,
+  '',
+  `Generated by ${code('book-kit conventions')} from book.config.yml${config.presets.length ? ` and ${config.presets.map((p) => code(p.name)).join(', ')}` : ''}. The book's CLAUDE.md and style guide win where they differ.`,
+  '',
+  '## Structure',
+  '',
+  `- Chapters are Markdown files in ${code(`${paths.src}/`)}, built in the order ${code(paths.index)} lists them. Add a new chapter to ${code(paths.index)} in the same change.`,
+  '- Each chapter opens with an H2 title. Use H3 and H4 below it, and never skip a level.',
+);
+if (structure.required_callout) {
+  say(`- Every chapter opens with a ${code(`.${structure.required_callout}`)} callout, right after the title.`);
+}
+if (callouts.some((c) => c.class === 'takeaways')) {
+  say(`- Files ending in ${code(`${structure.takeaways_suffix}.md`)} are generated from the TL;DRs by ${code('just key-takeaways')}; never edit them by hand.`);
+}
+say(
+  `- Not narrative chapters (skipped by the prose checks): ${structure.structural_slugs.map(code).join(', ')}, and drafts ending in ${code(`${structure.draft_suffix}.md`)}.`,
+  '',
+  '## Callouts',
+  '',
+  callouts.length
+    ? 'Write a callout as a fenced div whose class and custom-style match. The build adds the label, so never type it; a typed one renders twice.'
+    : 'This book defines no callouts.',
+  '',
+);
+if (callouts.length) {
+  const first = callouts[0].class;
+  say('```markdown', `::: {.${first} custom-style="${first}"}`, 'Text.', ':::', '```', '');
+  for (const c of callouts) {
+    const label = c.label ? ` (label "${c.label}")` : '';
+    const pair = c.pair_with ? `; a chapter with one should also have ${code(`.${c.pair_with}`)}` : '';
+    say(`- ${code(`.${c.class}`)}${label}${c.aria ? `: ${c.aria}` : ''}${pair}`);
+  }
+  say('');
+}
+
+const on = BUILTIN_VALIDATORS.map((v) => v.name).filter((name) => validators.severity?.[name] !== 'off');
+const rules = enabledRules(config).map((r) => r.name);
+say(
+  '## Checks',
+  '',
+  `Run ${code('just check-all')} before handing work back: ${code('book-kit validate')}, markdownlint, and textlint.`,
+  '',
+  `- Validators that run: ${on.map(code).join(', ')}.${(validators.plugins ?? []).length ? ` Plus the book's own: ${validators.plugins.map(code).join(', ')}.` : ''}`,
+  `- The kit's prose rules that run: ${rules.length ? rules.map(code).join(', ') : 'none'}.`,
+  '',
+);
+
+for (const { name, dir } of config.presets) {
+  const file = join(dir, 'CONVENTIONS.md');
+  if (existsSync(file)) say(`<!-- from preset ${name} -->`, '', readFileSync(file, 'utf8').trim(), '');
+}
+
+process.stdout.write(`${lines.join('\n').trimEnd()}\n`);

package/commands/convert-pdfx.sh

@@ -0,0 +1,194 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Converts a PDF to PDF/X-1a:2001 (CMYK, no transparency, embedded fonts)
+# for print distribution via IngramSpark or similar POD services.
+#
+# Usage:
+#   book-kit convert-pdfx [input.pdf output.pdf [title]]
+#
+# With no arguments, converts the book's print PDF (dist/<basename>.pdf) to
+# dist/<basename><output.pdfx_suffix>.pdf, titled print.pdfx_title: what
+# `just pdfx` does, without rebuilding the PDF (e.g. in a CI job that
+# downloaded it from another).
+#
+# Requirements:
+#   - Ghostscript (gs) installed
+#   - USWebCoatedSWOP.icc: $BOOK_KIT_ICC_PROFILE if set, else the book's
+#     profiles/USWebCoatedSWOP.icc if present, else downloaded (sha256-pinned)
+#     into the user cache by download-icc-profile.sh
+#
+# Runs from the book root (book-kit sets the working directory and
+# BOOK_KIT_ROOT).
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+KIT_ROOT="${BOOK_KIT_ROOT:-$(cd "$SCRIPT_DIR/.." && pwd)}"
+
+if [ $# -eq 0 ]; then
+  bk() { node "$SCRIPT_DIR/../bin/book-kit.js" config "$1"; }
+  dist="$(bk paths.dist)"
+  name="$(bk output.basename)"
+  set -- "$dist/$name.pdf" "$dist/$name$(bk output.pdfx_suffix).pdf" "$(bk print.pdfx_title)"
+elif [ $# -lt 2 ]; then
+  echo "Usage: book-kit convert-pdfx [input.pdf output.pdf [title]]" >&2
+  exit 2
+fi
+INPUT="$1"
+OUTPUT="$2"
+TITLE="${3:-}"
+
+ICC_PROFILE="$(bash "$SCRIPT_DIR/download-icc-profile.sh" --print-path)"
+PDFX_DEF="$KIT_ROOT/profiles/pdfx-def.ps"
+
+# ---------------------------------------------------------------------------
+# Preflight checks
+# ---------------------------------------------------------------------------
+
+# Check for Ghostscript
+if ! command -v gs &>/dev/null; then
+  echo "✗ Error: Ghostscript (gs) is not installed." >&2
+  echo "" >&2
+  echo "  Install it with:" >&2
+  echo "    macOS:  brew install ghostscript" >&2
+  echo "    Ubuntu: sudo apt-get install ghostscript" >&2
+  echo "    Fedora: sudo dnf install ghostscript" >&2
+  exit 1
+fi
+
+# Fetch (or locate) the ICC profile; download-icc-profile.sh verifies its sha256.
+bash "$SCRIPT_DIR/download-icc-profile.sh" >/dev/null
+
+# Check for input PDF
+if [ ! -f "$INPUT" ]; then
+  echo "✗ Error: Input PDF not found: $INPUT" >&2
+  echo "  Build it first with: just pdf" >&2
+  exit 1
+fi
+
+# Check for PDF/X definition file
+if [ ! -f "$PDFX_DEF" ]; then
+  echo "✗ Error: PDF/X definition file not found: $PDFX_DEF" >&2
+  exit 1
+fi
+
+# Ensure output directory exists
+mkdir -p "$(dirname "$OUTPUT")"
+
+# ---------------------------------------------------------------------------
+# Build a temporary pdfx-def.ps with the absolute ICC profile path
+# ---------------------------------------------------------------------------
+
+# Ghostscript needs an absolute path to the ICC profile in the PostScript
+# definition file. We substitute the placeholder at runtime so the committed
+# .ps file stays portable.
+PDFX_DEF_TMP="$(mktemp "${TMPDIR:-/tmp}/pdfx-def.XXXXXX.ps")"
+trap 'rm -f "$PDFX_DEF_TMP"' EXIT
+
+# PostScript string escaping for the title: \, (, ) must be backslash-escaped.
+PS_TITLE="$(printf '%s' "$TITLE" | sed -e 's/\\/\\\\/g' -e 's/(/\\(/g' -e 's/)/\\)/g')"
+ICC_PROFILE="$ICC_PROFILE" PS_TITLE="$PS_TITLE" python3 -c '
+import os, sys
+src = open(sys.argv[1]).read()
+src = src.replace("__ICC_PROFILE_PATH__", os.environ["ICC_PROFILE"]).replace("__TITLE__", os.environ["PS_TITLE"])
+open(sys.argv[2], "w").write(src)
+' "$PDFX_DEF" "$PDFX_DEF_TMP"
+
+# ---------------------------------------------------------------------------
+# Strip annotations (PDF/X-1a does not permit non-TrapNet/PrinterMark annots)
+# ---------------------------------------------------------------------------
+# WeasyPrint embeds hyperlink annotations that cause Ghostscript to revert the
+# entire output to normal PDF when -dPDFX is set. Strip them first.
+
+STRIPPED_TMP="$(mktemp "${TMPDIR:-/tmp}/book-kit-stripped.XXXXXX.pdf")"
+trap 'rm -f "$PDFX_DEF_TMP" "$STRIPPED_TMP"' EXIT
+
+python3 - "$INPUT" "$STRIPPED_TMP" <<'PYEOF'
+import sys
+import pikepdf
+
+src, dst = sys.argv[1], sys.argv[2]
+with pikepdf.open(src) as pdf:
+    for page in pdf.pages:
+        if "/Annots" in page:
+            del page["/Annots"]
+    pdf.save(dst)
+PYEOF
+
+# ---------------------------------------------------------------------------
+# Convert to PDF/X-1a:2001
+# ---------------------------------------------------------------------------
+
+echo "Converting to PDF/X-1a:2001..."
+echo "  Input:  $INPUT"
+echo "  Output: $OUTPUT"
+echo "  ICC:    $ICC_PROFILE"
+echo ""
+
+gs \
+  -dBATCH \
+  -dNOPAUSE \
+  -dNOOUTERSAVE \
+  -dNOSAFER \
+  -dQUIET \
+  -dPDFX \
+  -dCompatibilityLevel=1.3 \
+  -sDEVICE=pdfwrite \
+  -sColorConversionStrategy=CMYK \
+  -sProcessColorModel=DeviceCMYK \
+  -dNOTRANSPARENCY \
+  -dEmbedAllFonts=true \
+  -dSubsetFonts=true \
+  -dCompressFonts=true \
+  -dCompressPages=true \
+  -r300 \
+  -dAutoRotatePages=/None \
+  -dPDFSETTINGS=/prepress \
+  -sOutputFile="$OUTPUT" \
+  "$PDFX_DEF_TMP" \
+  -f "$STRIPPED_TMP"
+
+# ---------------------------------------------------------------------------
+# Report results
+# ---------------------------------------------------------------------------
+
+if [ -f "$OUTPUT" ]; then
+  input_size=$(wc -c < "$INPUT")
+  output_size=$(wc -c < "$OUTPUT")
+
+  # Format file sizes for human readability (pure bash, no bc dependency)
+  format_size() {
+    local bytes=$1
+    if [ "$bytes" -ge 1048576 ]; then
+      local mb=$((bytes / 1048576))
+      local remainder=$(( (bytes % 1048576) * 10 / 1048576 ))
+      echo "${mb}.${remainder} MB"
+    elif [ "$bytes" -ge 1024 ]; then
+      local kb=$((bytes / 1024))
+      local remainder=$(( (bytes % 1024) * 10 / 1024 ))
+      echo "${kb}.${remainder} KB"
+    else
+      echo "$bytes bytes"
+    fi
+  }
+
+  echo ""
+  echo "✓ PDF/X-1a:2001 conversion complete"
+  echo "  Input:  $(format_size "$input_size") ($INPUT)"
+  echo "  Output: $(format_size "$output_size") ($OUTPUT)"
+
+  # Quick check: output should be non-trivially sized
+  if [ "$output_size" -lt 1024 ]; then
+    echo "" >&2
+    echo "⚠ Warning: Output file is suspiciously small ($output_size bytes)." >&2
+    echo "  The conversion may not have worked correctly." >&2
+    exit 1
+  fi
+
+  echo ""
+  echo "  Next steps:"
+  echo "    - Validate with: gs -o /dev/null -sDEVICE=nullpage \"$OUTPUT\""
+  echo "    - Upload to IngramSpark for print distribution"
+else
+  echo "✗ Error: Conversion failed. Output file was not created." >&2
+  exit 1
+fi

package/commands/download-icc-profile.sh

@@ -0,0 +1,105 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Locates or downloads the USWebCoatedSWOP.icc CMYK profile (the standard
+# profile for U.S. web offset printing) for PDF/X-1a conversion.
+#
+# The kit doesn't ship the profile. In order of preference it uses:
+#   1. $BOOK_KIT_ICC_PROFILE
+#   2. profiles/USWebCoatedSWOP.icc in the book (a book may vendor it)
+#   3. the user cache ($XDG_CACHE_HOME or ~/.cache)/book-kit/, downloading it
+#
+# --print-path prints the resolved path and exits without downloading.
+#
+# Whatever the source, the exact bytes are pinned by sha256: the mirrors below
+# are untrusted, and a silently-changed CMYK profile would corrupt print color
+# without any build error.
+
+if [ -n "${BOOK_KIT_ICC_PROFILE:-}" ]; then
+  ICC_FILE="$BOOK_KIT_ICC_PROFILE"
+elif [ -f "${BOOK_ROOT:-.}/profiles/USWebCoatedSWOP.icc" ]; then
+  ICC_FILE="${BOOK_ROOT:-.}/profiles/USWebCoatedSWOP.icc"
+else
+  ICC_FILE="${XDG_CACHE_HOME:-$HOME/.cache}/book-kit/USWebCoatedSWOP.icc"
+fi
+PROFILES_DIR="$(dirname "$ICC_FILE")"
+
+if [ "${1:-}" = "--print-path" ]; then
+  echo "$ICC_FILE"
+  exit 0
+fi
+EXPECTED_SHA256="35f401731df11a4eba3502af632e51d68bc394bcb7d34632a331c1ba3f4a0bf6"
+
+# Verify a file matches the pinned sha256. Uses sha256sum (Linux) or shasum
+# (macOS), whichever is available.
+verify_sha256() {
+  local file="$1" actual
+  if command -v sha256sum >/dev/null 2>&1; then
+    actual="$(sha256sum "$file" | awk '{print $1}')"
+  elif command -v shasum >/dev/null 2>&1; then
+    actual="$(shasum -a 256 "$file" | awk '{print $1}')"
+  else
+    # Fail closed: an unverifiable profile could silently corrupt print color.
+    echo "✗ Error: no sha256 tool (sha256sum or shasum) found; can't verify $file." >&2
+    return 1
+  fi
+  [ "$actual" = "$EXPECTED_SHA256" ]
+}
+
+# Known public sources for USWebCoatedSWOP.icc (tried in order)
+URLS=(
+  "https://github.com/theeluwin/CMYK2RGB/raw/master/USWebCoatedSWOP.icc"
+  "https://github.com/livgilbert/tiffr/raw/main/USWebCoatedSWOP.icc"
+)
+
+if [ -f "$ICC_FILE" ]; then
+  if verify_sha256 "$ICC_FILE"; then
+    echo "✓ ICC profile already exists and matches pinned sha256: $ICC_FILE"
+    echo "  Size: $(wc -c < "$ICC_FILE") bytes"
+    exit 0
+  fi
+  echo "✗ Error: $ICC_FILE exists but its sha256 does not match the pinned value." >&2
+  echo "  Expected: $EXPECTED_SHA256" >&2
+  echo "  Refusing to use it. Delete it to re-fetch, or restore the vendored copy." >&2
+  exit 1
+fi
+
+mkdir -p "$PROFILES_DIR"
+
+echo "Downloading USWebCoatedSWOP.icc CMYK ICC profile..."
+
+for url in "${URLS[@]}"; do
+  echo "  Trying: $url"
+  if curl -fsSL --retry 3 --retry-delay 2 -o "$ICC_FILE" "$url"; then
+    # Verify the file is non-empty and looks like an ICC profile
+    # ICC profiles start with a 4-byte size field followed by "acsp" at offset 36
+    file_size=$(wc -c < "$ICC_FILE")
+    if [ "$file_size" -lt 100 ]; then
+      echo "  ✗ Downloaded file too small ($file_size bytes), trying next source..."
+      rm -f "$ICC_FILE"
+      continue
+    fi
+
+    if ! verify_sha256 "$ICC_FILE"; then
+      echo "  ✗ Downloaded file failed sha256 check (mirror may have changed), trying next source..."
+      rm -f "$ICC_FILE"
+      continue
+    fi
+
+    echo "✓ Downloaded ICC profile: $ICC_FILE ($file_size bytes), sha256 verified"
+    exit 0
+  else
+    echo "  ✗ Failed to download from this source, trying next..."
+    rm -f "$ICC_FILE"
+  fi
+done
+
+echo "✗ Error: Could not download ICC profile from any known source." >&2
+echo "" >&2
+echo "  You can manually download USWebCoatedSWOP.icc and place it at:" >&2
+echo "    $ICC_FILE" >&2
+echo "" >&2
+echo "  Sources:" >&2
+echo "    - Adobe ICC profiles: https://www.adobe.com/support/downloads/iccprofiles/iccprofiles_win.html" >&2
+echo "    - color.org: https://www.color.org/registry/index.xalter" >&2
+exit 1

package/commands/fonts.py

@@ -0,0 +1,212 @@
+#!/usr/bin/env python3
+"""Build the theme's fonts from the upstream releases, and print where they are.
+
+    book-kit fonts               build (or reuse) the fonts; print their directory
+    book-kit fonts --link PATH   also point the book's fonts directory at them
+
+The kit doesn't ship the Latin subsets and Kindle static instances its theme
+loads. Adobe's Source fonts are OFL-licensed with the Reserved Font Name
+"Source", which bars redistributing modified versions under that name; a
+subset made for your own build, embedded in your book, is fine. So this
+downloads the unmodified upstream files pinned in toolchain.json `fonts`
+(checked against their SHA-256), applies fonts/recipe.json, and caches the result.
+
+The cache lives in $BOOK_KIT_CACHE, else $XDG_CACHE_HOME/book-kit, else
+~/.cache/book-kit, keyed by the recipe, the pinned releases, and the fontTools
+and brotli versions, so a build is a no-op once the fonts exist. The same
+inputs give byte-identical files: nothing is timestamped with the build time.
+"""
+
+import hashlib
+import io
+import json
+import os
+import shutil
+import sys
+import tempfile
+import urllib.request
+import zipfile
+
+# Don't leave a __pycache__ in commands/ (it would ship in the npm package).
+sys.dont_write_bytecode = True
+
+
+def require_font_tools():
+    """Import fontTools and brotli, which only building the fonts needs.
+
+    Imported here rather than at the top so a book that brings its own fonts
+    directory doesn't need either package installed.
+    """
+    global brotli, fontTools, subset, TTFont, instancer
+    try:
+        import brotli
+        import fontTools
+        from fontTools import subset
+        from fontTools.ttLib import TTFont
+        from fontTools.varLib import instancer
+    except ImportError as e:
+        print(
+            f"book-kit fonts: {e.name} is required. Install the kit's Python packages: "
+            "python3 -m pip install -r node_modules/book-kit/requirements.txt",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+
+KIT = os.environ.get("BOOK_KIT_ROOT") or os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+
+
+def log(msg):
+    print(f"book-kit fonts: {msg}", file=sys.stderr)
+
+
+def cache_root():
+    if os.environ.get("BOOK_KIT_CACHE"):
+        return os.environ["BOOK_KIT_CACHE"]
+    base = os.environ.get("XDG_CACHE_HOME") or os.path.join(os.path.expanduser("~"), ".cache")
+    return os.path.join(base, "book-kit")
+
+
+def fetch(source, downloads):
+    """A pinned file's bytes, downloaded once and checked against its SHA-256."""
+    path = os.path.join(downloads, source["sha256"])
+    if not os.path.exists(path):
+        log(f"downloading {source['url']}")
+        with urllib.request.urlopen(source["url"], timeout=120) as r:
+            data = r.read()
+        digest = hashlib.sha256(data).hexdigest()
+        if digest != source["sha256"]:
+            sys.exit(f"book-kit fonts: {source['url']} has SHA-256 {digest}, expected {source['sha256']}")
+        os.makedirs(downloads, exist_ok=True)
+        tmp = f"{path}.{os.getpid()}"
+        with open(tmp, "wb") as f:
+            f.write(data)
+        os.replace(tmp, path)
+    with open(path, "rb") as f:
+        return f.read()
+
+
+def load(data):
+    # recalcTimestamp=False keeps upstream's head.modified, so output doesn't
+    # depend on when it was built.
+    return TTFont(io.BytesIO(data), recalcTimestamp=False)
+
+
+def save(font, path):
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    font.flavor = "woff2"
+    font.save(path)
+
+
+def set_name(font, name_id, value):
+    """Overwrite every record of name_id (adding a Windows English one if none)."""
+    table = font["name"]
+    records = [r for r in table.names if r.nameID == name_id]
+    for r in records:
+        r.string = value
+    if not records:
+        table.setName(value, name_id, 3, 1, 0x409)
+
+
+def build(recipe, sources, downloads, out):
+    zips = {}
+    built = {}
+    for job in recipe["subsets"]:
+        src = job["source"]
+        if "member" in job:
+            if src not in zips:
+                zips[src] = zipfile.ZipFile(io.BytesIO(fetch(sources[src], downloads)))
+            font = load(zips[src].read(job["member"]))
+        else:
+            font = load(fetch(sources[src], downloads))
+        options = subset.Options()
+        options.layout_features = recipe["features"][job["features"]]
+        options.drop_tables += job.get("drop_tables", [])
+        subsetter = subset.Subsetter(options)
+        subsetter.populate(unicodes=subset.parse_unicodes(recipe["unicodes"][job["unicodes"]]))
+        subsetter.subset(font)
+        for name_id, value in job.get("names", {}).items():
+            set_name(font, int(name_id), value)
+        path = os.path.join(out, job["out"])
+        save(font, path)
+        with open(path, "rb") as f:
+            built[job["out"]] = f.read()
+
+    for job in recipe["instances"]:
+        font = load(built[job["from"]])
+        axes = {a.axisTag: a.defaultValue for a in font["fvar"].axes}
+        axes.update(job["axes"])
+        static = instancer.instantiateVariableFont(font, axes)
+        save(static, os.path.join(out, job["out"]))
+
+
+def kit_link(path, root):
+    """Is path a symlink book-kit made: into the font cache, or to this kit's
+    fonts/ (where the kit bundled its fonts before building them)?"""
+    if not os.path.islink(path):
+        return False
+    target = os.path.realpath(os.path.join(os.path.dirname(path), os.readlink(path)))
+    cache = os.path.realpath(os.path.join(root, "fonts"))
+    return target.startswith(cache + os.sep) or target == os.path.realpath(os.path.join(KIT, "fonts"))
+
+
+def link(path, out, root):
+    """Point the book's fonts directory at out, unless the book brought its own:
+    a real directory, or a symlink book-kit didn't make, is left alone."""
+    if os.path.islink(path) and os.readlink(path) == out:
+        return
+    os.symlink(out, f"{path}.{os.getpid()}")
+    os.replace(f"{path}.{os.getpid()}", path)
+    log(f"linked {path} -> {out} (add {path} to .gitignore)")
+
+
+def main():
+    args = sys.argv[1:]
+    link_path = None
+    if args[:1] == ["--link"] and len(args) == 2:
+        link_path = args[1]
+    elif args:
+        sys.exit("usage: book-kit fonts [--link PATH]")
+    root = cache_root()
+    if link_path and (os.path.lexists(link_path) and not kit_link(link_path, root)):
+        return  # The book's own fonts: don't build or touch anything.
+    require_font_tools()
+
+    with open(os.path.join(KIT, "fonts", "recipe.json"), "rb") as f:
+        recipe_bytes = f.read()
+    with open(os.path.join(KIT, "toolchain.json")) as f:
+        sources = json.load(f)["fonts"]
+    recipe = json.loads(recipe_bytes)
+
+    key = hashlib.sha256(
+        recipe_bytes
+        + json.dumps(sources, sort_keys=True).encode()
+        + f"fonttools {fontTools.version} brotli {brotli.__version__}".encode()
+    ).hexdigest()[:16]
+    out = os.path.join(root, "fonts", key)
+
+    if not os.path.exists(os.path.join(out, ".complete")):
+        os.makedirs(os.path.join(root, "fonts"), exist_ok=True)
+        # Build beside the final directory and rename it into place, so an
+        # interrupted or concurrent build never leaves a half-written set.
+        tmp = tempfile.mkdtemp(prefix=f"{key}.", dir=os.path.join(root, "fonts"))
+        try:
+            build(recipe, sources, os.path.join(root, "downloads"), tmp)
+            open(os.path.join(tmp, ".complete"), "w").close()
+            try:
+                os.rename(tmp, out)
+            except OSError:
+                if not os.path.exists(os.path.join(out, ".complete")):
+                    raise
+        finally:
+            shutil.rmtree(tmp, ignore_errors=True)
+        log(f"built {len(recipe['subsets']) + len(recipe['instances'])} fonts in {out}")
+
+    if link_path:
+        link(link_path, out, root)
+    else:
+        print(out)
+
+
+if __name__ == "__main__":
+    main()