@johnhenry/sitefile 0.0.0-stage → 0.0.0

package/lib/src/executor.js

@@ -0,0 +1,2193 @@
+import { chmod, mkdir, mkdtemp, readdir, readFile, realpath, rm, writeFile } from 'node:fs/promises';
+import { statSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { SitefileError } from './errors.js';
+import { sha256 } from './digest.js';
+import { FEED_ITEM } from './language/ast.js';
+import { fragmentText, parseProgram } from './language/validate.js';
+import { joinVirtual, basenameVirtual, normalizeVirtual } from './paths.js';
+import { importedStageRefs, plan, targetPlan } from './planner.js';
+import { checkWasmPlugin } from './plugins/wasm.js';
+import { DEFAULT_PLUGIN_POLICY, PluginHost, TRANSFORM_JOBS } from './plugins/host.js';
+import { cacheKey, digestFolder, TransformCache } from './plugins/cache.js';
+import { DEFAULT_TOOL_POLICY, resolveTool, runTool } from './plugins/exec.js';
+import { decodeUtf8, fileRefs, fragmentNotValue, parseRenderTemplate, renderTemplate, resolveJsonPath, walk } from './render.js';
+import { dataCollection, markdownCollection, sortDocuments } from './resources/documents.js';
+import { bytesToResource, verifyIntegrity } from './resources/convert.js';
+import { fetchRemote } from './resources/https.js';
+import { redactError, redactSecrets, secretHeaders } from './secrets.js';
+import { fetchGitCommit, pinnedGitUrl, selectGitPath } from './resources/git.js';
+import { extractArchive } from './resources/archive.js';
+import { writeTar } from './archive-writers.js';
+import { LocalContext } from './resources/local.js';
+import { Lockfile } from './resources/lockfile.js';
+import { findVendorDir, Vendor } from './resources/vendor.js';
+import { DEFAULT_ARCHIVE_LIMITS, DEFAULT_FETCH_POLICY } from './resources/types.js';
+import { makeFile, Tree } from './tree.js';
+import { IgnoreRules } from './resources/ignore.js';
+import { lint } from './lint.js';
+import { exportDirectory, exportFile, isExporterTempName } from './exporter.js';
+import { sourceDateEpoch } from './archive-writers.js';
+import { encodeTree, isArchiveFormat } from './export-formats.js';
+import { buildFacts, makeAttestations } from './attest.js';
+import { ANN, buildOciImage, imageMeta, layoutTree, ociArchive, parseConfig } from './oci.js';
+import { baseRef as parseBaseRef, readLayerBlobs, resolveBase, resolveFromImage } from './base-image.js';
+import { Store } from './store.js';
+import { begin, reserve } from './profile.js';
+import { BuildMemo, memoKey, valueKey } from './memo.js';
+import { checkSchema, compileSchema } from './schema.js';
+import { groupBy, paginate } from './pages.js';
+import { parseYaml } from './yaml.js';
+import { brokenLinks, reportBrokenLinks } from './checklinks.js';
+import { composeRenames, fingerprint } from './fingerprint.js';
+import { atomXml, headersFile, pageUrl, parseFeedDate, redirectsFile, sitemapXml } from './site.js';
+/** Read, parse and validate a Sitefile. */
+export async function loadProgram(options) {
+    const sitefilePath = path.resolve(options.sitefile ?? path.join(options.contextDir, 'Sitefile'));
+    let source;
+    try {
+        source = await readFile(sitefilePath, 'utf8');
+    }
+    catch (e) {
+        // A Git context names its Sitefile by the label (the checkout is a temporary directory).
+        throw new SitefileError('E_NOT_FOUND', `cannot read Sitefile '${options.label ?? sitefilePath}'`, undefined, { cause: e });
+    }
+    const label = options.label ?? (path.relative(process.cwd(), sitefilePath) || path.basename(sitefilePath));
+    return { program: parseProgram(source, label), sitefilePath, label, source };
+}
+/** Parse, validate and evaluate variables, without reading any sources. */
+export async function planBuild(options) {
+    const { program } = await loadProgram(options);
+    return planFor(program, options);
+}
+/** `validate`'s lint warnings (src/lint.ts) for the whole Sitefile (a `--target` does not narrow them). */
+export async function lintBuild(options, disabled = []) {
+    const { program, source } = await loadProgram(options);
+    return lint(program, plan(program, options.buildArgs ?? {}), source, disabled);
+}
+/** The plan of a program for these options (`target` applied). */
+function planFor(program, options) {
+    const p = plan(program, options.buildArgs ?? {});
+    return options.target === undefined ? p : targetPlan(p, options.target);
+}
+/** The lockfile a build would use: `Sitefile.lock` next to the Sitefile, unless disabled. */
+function lockPathFor(options, sitefilePath) {
+    return options.lockfile === false ? undefined : (options.lockfile ?? path.join(path.dirname(sitefilePath), 'Sitefile.lock'));
+}
+/** `validate --strict-pins`: check the pins of `p` against the lockfile without building or fetching. */
+export async function checkPlanPins(options, p) {
+    const sitefilePath = path.resolve(options.sitefile ?? path.join(options.contextDir, 'Sitefile'));
+    const lockPath = lockPathFor(options, sitefilePath);
+    const lock = lockPath ? await Lockfile.load(lockPath) : undefined;
+    void checkPins(p, lock, options.skipBase ? undefined : (options.baseImage ?? (p.exportFormat === 'oci' ? p.exportBase : undefined)));
+}
+/** Run a build in memory. */
+export async function build(options) {
+    // Build secrets never appear in a warning or an error, even when a server echoes one back.
+    if (options.secrets?.size) {
+        const secrets = options.secrets;
+        const onWarning = options.onWarning;
+        const redacted = { ...options, ...(onWarning ? { onWarning: (m) => onWarning(redactSecrets(m, secrets)) } : {}) };
+        try {
+            const r = await buildUnredacted(redacted);
+            return { ...r, warnings: r.warnings.map((w) => redactSecrets(w, secrets)) };
+        }
+        catch (e) {
+            throw redactError(e, secrets);
+        }
+    }
+    return buildUnredacted(options);
+}
+async function buildUnredacted(options) {
+    const memo = options.memo;
+    if (!memo)
+        return buildOnce(options);
+    memo.begin();
+    let ok = false;
+    try {
+        const r = await buildOnce(options);
+        ok = true;
+        return { ...r, memoStats: { ...memo.stats } };
+    }
+    finally {
+        memo.finish(ok);
+    }
+}
+async function buildOnce(options) {
+    // Git imports AS sitefile are checked out into temporary directories, removed when the build ends.
+    const tempDirs = [];
+    try {
+        return await buildWith(options, tempDirs);
+    }
+    finally {
+        await Promise.all(tempDirs.map((d) => rm(d, { recursive: true, force: true })));
+    }
+}
+async function buildWith(options, tempDirs) {
+    const prof = options.profiler;
+    const parseSpan = begin(prof, 'parse', 'build');
+    const { program, sitefilePath, label } = await loadProgram(options);
+    const full = plan(program, options.buildArgs ?? {});
+    const p = options.target === undefined ? full : targetPlan(full, options.target);
+    parseSpan.end({ imports: p.imports.length, stages: p.stages.length, ...(p.target !== undefined ? { target: p.target } : {}) });
+    const warnings = [];
+    const warn = (m) => {
+        warnings.push(m);
+        options.onWarning?.(m);
+    };
+    p.warnings.forEach(warn);
+    warnUnusedSecrets(p, options.secrets, warn);
+    const tools = await resolveTools(p, options, warn);
+    const pluginAllowed = checkPlugins(p, options, warn);
+    const contextReal = await realpath(options.contextDir).catch((e) => {
+        throw new SitefileError('E_NOT_FOUND', `build context '${options.contextDir}' does not exist`, undefined, { cause: e });
+    });
+    const ignore = ['.git'];
+    /** The same paths, absolute: an imported Sitefile's context inside this one skips them too. */
+    const skip = [];
+    if (options.outDir !== undefined) {
+        const outReal = await realpathLoose(path.resolve(options.outDir));
+        const rel = path.relative(contextReal, outReal);
+        if (rel !== '' && !rel.startsWith('..') && !path.isAbsolute(rel)) {
+            ignore.push(rel.split(path.sep).join('/'));
+            skip.push(outReal);
+            // Also skip temp/old siblings an interrupted export may have left behind.
+            const parent = path.dirname(outReal);
+            const siblings = await readdir(parent).catch(() => []);
+            for (const name of siblings) {
+                if (isExporterTempName(name, path.basename(outReal))) {
+                    ignore.push(path.relative(contextReal, path.join(parent, name)).split(path.sep).join('/'));
+                    skip.push(path.join(parent, name));
+                }
+            }
+        }
+    }
+    const vendorDir = await findVendorDir(contextReal, options.vendorDir);
+    if (vendorDir !== undefined) {
+        ignore.push(vendorDir);
+        skip.push(path.join(contextReal, ...vendorDir.split('/')));
+    }
+    for (const w of options.alsoWrites ?? []) {
+        const real = await realpathLoose(path.resolve(w));
+        const rel = path.relative(contextReal, real);
+        if (rel !== '' && !rel.startsWith('..') && !path.isAbsolute(rel)) {
+            ignore.push(rel.split(path.sep).join('/'));
+            skip.push(real);
+        }
+    }
+    const local = await LocalContext.open(contextReal, { ignore, allowHardlinks: options.allowHardlinks ?? false });
+    const vendor = vendorDir !== undefined ? await Vendor.open(local, vendorDir) : undefined;
+    const policy = { ...DEFAULT_FETCH_POLICY, ...options.fetchPolicy };
+    const archiveLimits = { ...DEFAULT_ARCHIVE_LIMITS, ...options.archiveLimits };
+    const lockPath = lockPathFor(options, sitefilePath);
+    const lock = lockPath ? await Lockfile.load(lockPath) : undefined;
+    // BASE: the image to build on (resolved after the files, below).
+    const baseRef = options.skipBase ? undefined : (options.baseImage ?? (p.exportFormat === 'oci' ? p.exportBase : undefined));
+    const pins = options.strictPins ? checkPins(p, lock, baseRef) : undefined;
+    // A --target build skips later stages; their FROM image lockfile entries are kept all the same.
+    for (const st of full.stages.slice(p.stages.length))
+        if (st.base.kind === 'image' && !st.base.local)
+            lock?.markImageUsed(imageLockKey(st.base));
+    const memo = options.memo;
+    const env = {
+        local,
+        policy,
+        archiveLimits,
+        lock,
+        label,
+        warn,
+        frozen: !!options.frozenLockfile,
+        update: !!options.updateLock,
+        vendor,
+        ...(options.secrets ? { secrets: options.secrets } : {}),
+        ...(memo ? { memo } : {}),
+    };
+    // Imports resolve concurrently: each gets its own trace thread, reserved in Sitefile order.
+    const importSpans = p.imports.map((spec, i) => {
+        prof?.nameThread(i + 2, `import ${spec.name}`);
+        return prof ? prof.reserve(`import ${spec.name}`, 'import', { uri: spec.uri, as: spec.as ?? 'file' }, i + 2) : undefined;
+    });
+    // Sitefile imports (AS sitefile) load after the others, one after the other, in Sitefile order.
+    const indexed = p.imports.map((spec, i) => [spec, i]);
+    const plainImports = indexed.filter(([s]) => s.as !== 'sitefile');
+    const plainResolved = await mapLimit(plainImports, options.concurrency ?? 4, async ([spec, i]) => {
+        importSpans[i]?.start();
+        const r = await resolveImport(spec, env);
+        importSpans[i]?.end({ kind: r.res.kind });
+        return r;
+    });
+    // DRAFTS false drops drafts; then SCHEMA checks run in Sitefile order, on the documents in path order; then SORT BY.
+    const resolved = new Map(plainImports.map(([s], j) => [s.name, { ...plainResolved[j], res: withoutDrafts(s, plainResolved[j].res) }]));
+    for (const spec of p.imports) {
+        const r = resolved.get(spec.name);
+        if (r && spec.schema)
+            await checkImportSchema(spec, r.res, local);
+    }
+    const images = [];
+    let imageStore;
+    const fromImage = async (b, unit) => {
+        imageStore ??= options.store ?? (await Store.open());
+        const r = await resolveFromImage(b.ref, b.at, b.local, {
+            store: imageStore,
+            platform: options.platform,
+            lock,
+            frozen: !!options.frozenLockfile,
+            update: !!options.updateLock,
+            vendor,
+            registry: {
+                ...options.registry,
+                allowPrivateNetwork: options.registry?.allowPrivateNetwork ?? policy.allowPrivateNetwork,
+            },
+            warn,
+            span: b.span,
+            lead: `${b.lead} image`,
+        });
+        images.push({ name: r.name, digest: r.digest, line: b.span.line, local: b.local, ...(unit !== undefined ? { import: unit } : {}) });
+        return r;
+    };
+    const plugins = new PluginHost({ ...DEFAULT_PLUGIN_POLICY, ...options.pluginPolicy }, warn);
+    const cache = options.cacheDir !== undefined ? new TransformCache(options.cacheDir, options.remoteCache) : undefined;
+    const stats = { hits: 0, misses: 0, writes: 0, corrupt: 0, pluginsSpawned: 0, pluginCalls: 0, toolRuns: 0 };
+    const toolPolicy = { ...DEFAULT_TOOL_POLICY, ...options.toolPolicy };
+    const unitsEnv = {
+        remote: env,
+        archiveLimits,
+        ...(memo ? { memo } : {}),
+        concurrency: options.concurrency ?? 4,
+        allowHardlinks: options.allowHardlinks ?? false,
+        strictPins: !!options.strictPins,
+        skip,
+        tempDirs,
+        recordSteps: !!options.recordSteps,
+        pins: {},
+        exec: { plugins, toolPolicy, stats, fetchPolicy: policy },
+        fromImage,
+    };
+    const root = {
+        name: undefined,
+        label,
+        local,
+        scope: rootScope(options, label),
+        chain: [{ id: options.sitefile === undefined ? contextReal : await realpathLoose(sitefilePath), label }],
+    };
+    const fullRefs = importedStageRefs(full.stages);
+    const resources = new Map();
+    // Incremental rebuilds: what each import is (its spec and the digest of what it read), and the build's ARG/LET values.
+    const resourceKeys = new Map();
+    const units = new Map();
+    for (const [spec, i] of indexed) {
+        const r = resolved.get(spec.name);
+        if (r) {
+            resources.set(spec.name, sorted(spec, r.res));
+            if (memo)
+                resourceKeys.set(spec.name, r.key);
+            continue;
+        }
+        importSpans[i]?.start();
+        const unit = await loadSitefileImport(spec, root, fullRefs, unitsEnv);
+        importSpans[i]?.end({ kind: 'tree' });
+        units.set(spec.name, unit);
+        resources.set(spec.name, unitResource(unit));
+        if (memo)
+            resourceKeys.set(spec.name, memoKey('sitefile', label, valueKey(spec), unit.digest));
+    }
+    if (pins)
+        Object.assign(pins.imports, unitsEnv.pins);
+    const envKey = memo ? memoKey('env', label, valueKey([...p.vars]), valueKey([...p.fragments.values()].map((f) => [f.name, f.text]))) : '';
+    const stageTrees = new Map();
+    const execEnv = {
+        local,
+        resources,
+        stages: stageTrees,
+        vars: p.vars,
+        fragments: p.fragments,
+        partials: new Map(),
+        label,
+        warn,
+        plugins,
+        tools: new Map(tools.map((t) => [t.name, t])),
+        toolPolicy,
+        pluginDigests: new Map(),
+        stats,
+        ...(cache ? { cache } : {}),
+        ...(prof ? { profiler: prof } : {}),
+        ...(memo ? { memo } : {}),
+        resourceKeys,
+        envKey,
+        stageKeys: new Map(),
+        fromImage,
+        fetchPolicy: policy,
+    };
+    let tree = Tree.empty;
+    const steps = options.recordSteps ? [] : undefined;
+    // FINGERPRINT renames: per operation (by line), and per stage (composed, inherited by FROM <stage>).
+    const renames = new Map();
+    const stageRenames = new Map();
+    let currentRenames = new Map();
+    try {
+        for (const spec of p.plugins) {
+            const s = begin(prof, `PLUGIN ${spec.name}`, 'plugin', { path: './' + spec.path });
+            await registerPlugin(spec, local, plugins, pluginAllowed);
+            s.end();
+        }
+        // The stages of imported Sitefiles this build reads (`FROM theme+assets`, `--from=theme+assets`).
+        await provideImportedStages(units, importedStageRefs(p.stages), stageTrees, execEnv.stageKeys, stageRenames, unitsEnv);
+        for (const [i, stage] of p.stages.entries()) {
+            const s = begin(prof, `stage ${stage.name ?? '#' + (i + 1)}`, 'stage', { from: stageFrom(stage) });
+            const start = await startStage(stage, execEnv);
+            tree = start.tree;
+            let key = start.key;
+            currentRenames = stage.base.kind === 'stage' ? (stageRenames.get(stage.base.name) ?? new Map()) : new Map();
+            const record = steps ? [tree] : undefined;
+            steps?.push(record);
+            for (const op of stage.operations) {
+                const o = begin(prof, `${label}:${op.span.line} ${op.kind}`, 'operation', { line: op.span.line });
+                const r = await executeOp(op, tree, key, currentRenames.size ? { ...execEnv, renames: currentRenames } : execEnv);
+                tree = r.tree;
+                key = r.key;
+                if (r.renames) {
+                    renames.set(op.span.line, r.renames);
+                    currentRenames = composeRenames(currentRenames, r.renames);
+                }
+                record?.push(tree);
+                o.end({ files: tree.size, ...(r.memo ? { memo: r.memo } : {}) });
+            }
+            if (stage.name !== undefined) {
+                stageRenames.set(stage.name, currentRenames);
+                stageTrees.set(stage.name, tree);
+                execEnv.stageKeys.set(stage.name, key);
+            }
+            s.end({ files: tree.size });
+        }
+    }
+    finally {
+        plugins.close();
+        stats.pluginsSpawned = plugins.stats.spawned;
+        stats.pluginCalls = plugins.stats.calls;
+        if (cache)
+            Object.assign(stats, cache.stats);
+    }
+    if (tree.isFile(p.exportPath)) {
+        throw new SitefileError('E_EXPORT', `EXPORT path '${p.exportPath}' is a file; export a directory`);
+    }
+    tree = withSiteRules(tree, p, label, currentRenames);
+    const output = tree.subtree(p.exportPath);
+    if (output.size === 0)
+        warn(p.target === undefined ? `EXPORT ${p.exportPath} contains no files` : `--target ${p.target}: stage '${p.target}' contains no files`);
+    // BASE: the image to build on. Resolved after the files so a failing build never pulls anything; its
+    // lockfile entry is saved together with the imports'.
+    const baseSpan = baseRef ? begin(prof, `BASE ${baseRef}`, 'import') : undefined;
+    const base = baseRef
+        ? await resolveBase(baseRef, {
+            store: options.store ?? (await Store.open()),
+            platform: options.platform,
+            lock,
+            frozen: !!options.frozenLockfile,
+            update: !!options.updateLock,
+            vendor,
+            registry: {
+                ...options.registry,
+                allowPrivateNetwork: options.registry?.allowPrivateNetwork ?? policy.allowPrivateNetwork,
+            },
+            warn,
+        })
+        : undefined;
+    baseSpan?.end();
+    const lockfileWritten = lock && !options.frozenLockfile ? await lock.save() : false;
+    return {
+        plan: p,
+        tree,
+        output,
+        // Imported Sitefiles' own imports follow, by qualified name (`theme+data`), for the provenance.
+        resources: units.size ? new Map([...resources, ...nestedResources(units)]) : resources,
+        warnings,
+        lockfileWritten,
+        tools,
+        transformStats: stats,
+        ...(base ? { base } : {}),
+        ...(images.length ? { images } : {}),
+        ...(steps ? { steps } : {}),
+        ...(pins ? { pins } : {}),
+        ...(units.size ? { imported: units } : {}),
+        ...(renames.size ? { renames } : {}),
+    };
+}
+/** The Sitefile.lock `images` key of a registry `FROM image` reference. */
+export function imageLockKey(b) {
+    return parseBaseRef(b.ref, b.span, `${b.lead} image`).lockKey;
+}
+/**
+ * `--strict-pins`: every remote input must be pinned, so the build is reproducible. A remote IMPORT
+ * needs INTEGRITY or a `Sitefile.lock` entry; a BASE image needs `@sha256:` or a lockfile `images`
+ * entry. `lock` is undefined with --no-lockfile (only the Sitefile's own pins count then). Checked in
+ * source order, before anything is fetched; the first unpinned input fails with E_UNPINNED.
+ */
+export function checkPins(p, lock, baseRef) {
+    const imports = {};
+    for (const spec of p.imports) {
+        if (spec.location.kind === 'git') {
+            if (spec.location.commit !== undefined)
+                imports[spec.name] = 'commit';
+            else if (lock?.getGit(spec.location.url))
+                imports[spec.name] = 'lockfile';
+            if (imports[spec.name])
+                continue;
+            throw new SitefileError('E_UNPINNED', `IMPORT ${spec.name}: '${spec.location.url}' is not pinned (--strict-pins); name a commit (#<40 hex>[:path]), or record it in Sitefile.lock with a build without --strict-pins`, spec.span);
+        }
+        if (spec.location.kind !== 'remote')
+            continue;
+        if (spec.integrity)
+            imports[spec.name] = 'integrity';
+        else if (lock?.get(spec.location.url))
+            imports[spec.name] = 'lockfile';
+        if (imports[spec.name])
+            continue;
+        throw new SitefileError('E_UNPINNED', `IMPORT ${spec.name}: '${spec.location.url}' is not pinned (--strict-pins); add INTEGRITY sha256:<hex>, or record it in Sitefile.lock with a build without --strict-pins`, spec.span);
+    }
+    const images = {};
+    for (const st of p.stages) {
+        if (st.base.kind !== 'image' || st.base.local)
+            continue;
+        const { ref, lockKey } = parseBaseRef(st.base.ref, st.base.span, `${st.base.lead} image`);
+        if (ref.digest !== undefined)
+            images[st.span.line] = 'digest';
+        else if (lock?.getImage(lockKey))
+            images[st.span.line] = 'lockfile';
+        else {
+            throw new SitefileError('E_UNPINNED', `${st.base.lead} image ${st.base.ref}: '${lockKey}' is not pinned (--strict-pins); pin it with @sha256:..., or record it in Sitefile.lock with a build without --strict-pins`, st.base.span);
+        }
+    }
+    const withImages = Object.keys(images).length ? { imports, images } : { imports };
+    if (baseRef === undefined)
+        return withImages;
+    const { ref, lockKey } = parseBaseRef(baseRef);
+    if (ref.digest !== undefined)
+        return { ...withImages, base: 'digest' };
+    if (lock?.getImage(lockKey))
+        return { ...withImages, base: 'lockfile' };
+    throw new SitefileError('E_UNPINNED', `BASE ${baseRef}: '${lockKey}' is not pinned (--strict-pins); pin it with @sha256:..., or record it in Sitefile.lock with a build without --strict-pins`);
+}
+/**
+ * Build, then write the exported tree to `outDir`: a directory for the
+ * `directory` format, a single file for zip, tar, tgz and wbn.
+ */
+export async function buildToDirectory(options) {
+    const result = await build(options);
+    const format = options.format ?? result.plan.exportFormat;
+    const span = begin(options.profiler, 'export', 'export', { format });
+    try {
+        return await exportBuild(result, format, options);
+    }
+    finally {
+        span.end();
+    }
+}
+async function exportBuild(result, format, options) {
+    const exportOptions = { contextDir: options.contextDir, ...(options.force ? { force: true } : {}) };
+    // Watch mode: a directory export writes only what changed since the session's last one.
+    const exportState = options.memo?.exportState;
+    if (format !== 'directory')
+        exportState?.clear();
+    if (format === 'oci') {
+        const img = buildOciImage(result.output, {
+            root: options.ociRoot ?? result.plan.exportRoot,
+            compression: options.ociCompression ?? result.plan.exportCompression,
+            platform: options.platform,
+            epoch: sourceDateEpoch(),
+            base: result.base,
+            ...(await imageMeta(options.contextDir, { git: !!options.gitLabels, ...(options.imageLabels ? { labels: options.imageLabels } : {}) })),
+        });
+        // An image built on a BASE carries the base's layers: copy them in so the export is self-contained.
+        const baseBlobs = result.base ? await readLayerBlobs(options.store ?? (await Store.open()), img.baseLayers) : undefined;
+        const referrers = options.attest ? await imageAttestations(result, img, options, options.attest) : [];
+        // A .tar destination gets an OCI archive; anything else a layout directory.
+        if (options.outDir.toLowerCase().endsWith('.tar')) {
+            const data = ociArchive(img, options.ociRefName, sourceDateEpoch(), baseBlobs, referrers);
+            const written = await exportFile(data, options.outDir, exportOptions);
+            return { ...result, format, outDir: written.outFile, bytes: written.bytes, fileDigest: sha256(data), manifestDigest: img.manifestDigest };
+        }
+        const written = await exportDirectory(layoutTree(img, options.ociRefName, baseBlobs, referrers), options.outDir, exportOptions);
+        return { ...result, format, outDir: written.outDir, manifestDigest: img.manifestDigest };
+    }
+    if (!isArchiveFormat(format)) {
+        const written = await exportDirectory(result.output, options.outDir, { ...exportOptions, ...(exportState ? { incremental: exportState } : {}) });
+        return { ...result, format, outDir: written.outDir, ...(written.incremental ? { incremental: written.incremental } : {}) };
+    }
+    const data = encodeTree(result.output, format, {
+        epoch: sourceDateEpoch(),
+        baseUrl: options.baseUrl ?? result.plan.exportBase,
+    });
+    const written = await exportFile(data, options.outDir, exportOptions);
+    return { ...result, format, outDir: written.outFile, bytes: written.bytes, fileDigest: sha256(data) };
+}
+/**
+ * The attestations (`--provenance`, `--sbom`) of an image built from `result`: in-toto statements
+ * whose subject is the image manifest. They never change the image itself.
+ */
+export async function imageAttestations(result, img, options, request) {
+    if (!request.provenance && !request.sbom)
+        return [];
+    const facts = await buildFacts(result, options);
+    const title = parseConfig(img.configBytes).labels[ANN.title];
+    return makeAttestations({ digest: img.manifestDigest, size: img.manifestBytes.byteLength, files: result.output, root: img.root, title }, facts, request, sourceDateEpoch());
+}
+/**
+ * Read an import. `key` identifies the result for incremental rebuilds: the import's spec
+ * (with its Sitefile position) and the digest of the bytes or tree it read. With a memo,
+ * conversions (parsing Markdown, data and archives) whose key is unchanged are reused.
+ */
+async function resolveImport(spec, env) {
+    // `AS sitefile` imports are loaded by loadSitefileImport, one after the other.
+    if (spec.as === 'sitefile')
+        throw new SitefileError('E_VALIDATION', `IMPORT ${spec.name}: a Sitefile import is not a resource`, spec.span);
+    const origin = `${env.label}:${spec.span.line} IMPORT ${spec.name}`;
+    const id = env.memo ? valueKey(spec) : '';
+    const keyOf = (raw) => (env.memo ? memoKey('import', env.label, id, raw) : '');
+    // A collection's documents are memoized one by one, as children of the import's entry.
+    const convert = (key, compute) => env.memo ? env.memo.memoize(key, (children) => compute(env.memo.documents(children))) : compute();
+    const convertBytes = async (key, compute) => {
+        const hit = env.memo?.get(key);
+        if (hit)
+            return hit;
+        const r = await compute();
+        env.memo?.set(key, r);
+        return r;
+    };
+    if (spec.location.kind === 'local') {
+        const rel = spec.location.path;
+        const kind = await env.local.stat(rel, spec.span);
+        if (kind === 'directory') {
+            if (spec.as === 'markdown') {
+                if (spec.integrity)
+                    throw new SitefileError('E_VALIDATION', `IMPORT ${spec.name}: INTEGRITY applies to files, not directories`, spec.span);
+                const tree = await env.local.readTree(rel, origin, spec.span);
+                const key = keyOf(tree.provenance.digest);
+                return {
+                    key,
+                    res: convert(key, (docs) => {
+                        const value = markdownCollection(tree.tree, spec.uri.replace(/\/+$/, ''), spec.span, docs);
+                        return { kind: 'value', format: 'markdown', value, provenance: tree.provenance };
+                    }),
+                };
+            }
+            if (spec.as === 'json' || spec.as === 'yaml') {
+                if (spec.integrity)
+                    throw new SitefileError('E_VALIDATION', `IMPORT ${spec.name}: INTEGRITY applies to files, not directories`, spec.span);
+                const format = spec.as;
+                const tree = await env.local.readTree(rel, origin, spec.span);
+                const key = keyOf(tree.provenance.digest);
+                return {
+                    key,
+                    res: convert(key, (docs) => {
+                        const value = dataCollection(tree.tree, format, spec.uri.replace(/\/+$/, ''), spec.span, docs);
+                        return { kind: 'value', format, value, provenance: tree.provenance };
+                    }),
+                };
+            }
+            if (spec.as && spec.as !== 'tree') {
+                throw new SitefileError('E_TYPE', `IMPORT ${spec.name}: '${spec.uri}' is a directory and cannot be imported AS ${spec.as}`, spec.span);
+            }
+            if (spec.integrity)
+                throw new SitefileError('E_VALIDATION', `IMPORT ${spec.name}: INTEGRITY applies to files, not directories`, spec.span);
+            const tree = await env.local.readTree(rel, origin, spec.span);
+            return { key: keyOf(tree.provenance.digest), res: tree };
+        }
+        const file = await env.local.readFile(rel, spec.span);
+        if (spec.integrity)
+            verifyIntegrity(file.bytes, spec.integrity, spec.uri, spec.span);
+        const key = keyOf(`${file.provenance.digest}\0${file.mode}\0${file.basename}`);
+        if (!spec.as || spec.as === 'file')
+            return { key, res: file };
+        const as = spec.as;
+        return { key, res: await convertBytes(key, () => bytesToResource(file.bytes, as, { uri: spec.uri, basename: file.basename, mode: file.mode }, spec.span, env.archiveLimits)) };
+    }
+    if (spec.location.kind === 'git') {
+        const loc = spec.location;
+        const { commit, selection } = await fetchGitImport(spec, loc, env);
+        const resolvedUrl = pinnedGitUrl(loc, commit);
+        if (selection.kind === 'file') {
+            const digest = sha256(selection.bytes);
+            const key = keyOf(`${commit}\0${digest}\0${selection.mode}`);
+            const as = spec.as ?? 'file';
+            const res = await convertBytes(key, () => bytesToResource(selection.bytes, as, { uri: spec.uri, resolvedUrl, basename: selection.basename, mode: selection.mode }, spec.span, env.archiveLimits));
+            return { key, res: { ...res, provenance: { ...res.provenance, gitCommit: commit } } };
+        }
+        const tree = Tree.fromFiles(selection.files.map(([p, f]) => [p, makeFile(f.bytes, origin, f.mode)]));
+        const provenance = { uri: spec.uri, resolvedUrl, digest: tree.digest(), gitCommit: commit };
+        const key = keyOf(`${commit}\0${provenance.digest}`);
+        const base = spec.uri.replace(/\/+$/, '');
+        if (spec.as === 'markdown') {
+            return { key, res: convert(key, (docs) => ({ kind: 'value', format: 'markdown', value: markdownCollection(tree, base, spec.span, docs), provenance })) };
+        }
+        if (spec.as === 'json' || spec.as === 'yaml') {
+            const format = spec.as;
+            return { key, res: convert(key, (docs) => ({ kind: 'value', format, value: dataCollection(tree, format, base, spec.span, docs), provenance })) };
+        }
+        if (spec.as && spec.as !== 'tree') {
+            throw new SitefileError('E_TYPE', `IMPORT ${spec.name}: '${spec.uri}' is a directory and cannot be imported AS ${spec.as}`, spec.span);
+        }
+        return { key, res: { kind: 'tree', tree, provenance } };
+    }
+    const url = spec.location.url;
+    const as = spec.as ?? 'file';
+    const { bytes, finalUrl } = await fetchRemoteImport(spec, url, env);
+    const basename = path.posix.basename(new URL(finalUrl).pathname) || spec.name;
+    const key = keyOf(`${sha256(bytes)}\0${finalUrl}`);
+    return { key, res: await convertBytes(key, () => bytesToResource(bytes, as, { uri: url, resolvedUrl: finalUrl, basename }, spec.span, env.archiveLimits)) };
+}
+/** `--secret` ids that no IMPORT … SECRET names (likely a typo). */
+export function warnUnusedSecrets(p, secrets, warn) {
+    if (!secrets)
+        return;
+    const used = new Set(p.imports.flatMap((s) => (s.secrets ?? []).map((x) => x.id)));
+    for (const id of [...secrets.keys()].sort())
+        if (!used.has(id))
+            warn(`--secret ${id} is not used by any IMPORT … SECRET`);
+}
+/**
+ * The bytes of a remote IMPORT, checked against its INTEGRITY and the lockfile (and recorded there):
+ * read from the vendor directory when it has the URL, otherwise fetched.
+ */
+export async function fetchRemoteImport(spec, url, env) {
+    const entry = env.lock?.get(url);
+    if (env.frozen && !entry) {
+        throw new SitefileError('E_LOCK_MISSING', `IMPORT ${spec.name}: '${url}' is not in the lockfile (--frozen-lockfile)`, spec.span);
+    }
+    const vendored = env.vendor?.resource(url);
+    if (env.vendor && !vendored) {
+        env.warn(`${env.label}:${spec.span.line}: IMPORT ${spec.name}: '${url}' is not vendored in ${env.vendor.dir}; fetching it (run 'sitefile vendor' to add it)`);
+    }
+    const fetchIt = () => {
+        const originHeaders = secretHeaders(spec, env.secrets);
+        return fetchRemote(url, env.policy, spec.span, originHeaders ? { originHeaders } : {});
+    };
+    const { bytes, finalUrl } = vendored && env.vendor ? await env.vendor.readResource(url, vendored, spec.span) : await fetchIt();
+    const digest = sha256(bytes);
+    if (spec.integrity) {
+        verifyIntegrity(bytes, spec.integrity, url, spec.span);
+    }
+    else if (entry && !env.update && entry.integrity !== digest) {
+        throw new SitefileError('E_LOCK_MISMATCH', `IMPORT ${spec.name}: '${url}' changed since it was locked (locked ${entry.integrity}, got ${digest}); rerun with --update-lock to accept it`, spec.span);
+    }
+    else if (!entry) {
+        env.warn(`${env.label}:${spec.span.line}: IMPORT ${spec.name} is not pinned; add INTEGRITY ${digest} for a reproducible build`);
+    }
+    if (env.frozen && entry && entry.integrity !== digest) {
+        throw new SitefileError('E_LOCK_MISMATCH', `IMPORT ${spec.name}: '${url}' does not match the lockfile (--frozen-lockfile)`, spec.span);
+    }
+    env.lock?.record(url, { integrity: digest, size: bytes.byteLength, resolved: finalUrl });
+    return { bytes, finalUrl };
+}
+/** The canonical bytes `sitefile vendor` stores for a Git selection: a file's bytes, or a tree as a deterministic tar. */
+export function gitSelectionBytes(selection) {
+    if (selection.kind === 'file')
+        return selection.bytes;
+    return writeTar(Tree.fromFiles(selection.files.map(([p, f]) => [p, makeFile(f.bytes, 'vendor', f.mode)])), { epoch: 0 });
+}
+/**
+ * The content of a Git IMPORT, checked against the lockfile (and recorded there). The commit is the
+ * one in the URL, else the locked one (unless --update-lock), else what the ref names now. A vendored
+ * copy of that commit is read instead of the network (a ref with no lockfile entry uses the vendored
+ * commit, as a BASE tag uses the vendored digest).
+ */
+export async function fetchGitImport(spec, loc, env) {
+    const url = loc.url;
+    const entry = env.lock?.getGit(url);
+    if (env.frozen && !entry) {
+        throw new SitefileError('E_LOCK_MISSING', `IMPORT ${spec.name}: '${url}' is not in the lockfile (--frozen-lockfile)`, spec.span);
+    }
+    if (entry && loc.commit !== undefined && entry.commit !== loc.commit) {
+        throw new SitefileError('E_LOCK_MISMATCH', `IMPORT ${spec.name}: '${url}' is locked to commit ${entry.commit}; rerun with --update-lock to accept ${loc.commit}`, spec.span);
+    }
+    let want = loc.commit ?? (entry && !env.update ? entry.commit : undefined);
+    const vendored = env.vendor?.git(url);
+    let selection;
+    if (vendored && env.vendor && (want === undefined ? !env.update : vendored.commit === want)) {
+        want = vendored.commit;
+        selection = await env.vendor.readGit(url, vendored, loc.path.slice(loc.path.lastIndexOf('/') + 1), env.archiveLimits ?? DEFAULT_ARCHIVE_LIMITS, spec.span);
+    }
+    else {
+        if (env.vendor) {
+            env.warn(`${env.label}:${spec.span.line}: IMPORT ${spec.name}: '${url}' is not vendored in ${env.vendor.dir}${vendored ? ` at commit ${want ?? 'the latest'}` : ''}; fetching it (run 'sitefile vendor' to add it)`);
+        }
+        const limits = env.archiveLimits ?? DEFAULT_ARCHIVE_LIMITS;
+        const originHeaders = secretHeaders(spec, env.secrets);
+        const objs = await fetchGitCommit(loc.repo, loc.ref, want, { policy: env.policy, span: spec.span, ...(originHeaders ? { originHeaders } : {}) }, limits);
+        want = objs.commit;
+        selection = selectGitPath(objs, loc, limits, spec.span);
+    }
+    if (loc.commit === undefined && !entry) {
+        env.warn(`${env.label}:${spec.span.line}: IMPORT ${spec.name} is not pinned; pin commit ${want} (#${want}${loc.path === '' ? '' : ':' + loc.path}) for a reproducible build`);
+    }
+    env.lock?.recordGit(url, { commit: want });
+    return { commit: want, selection };
+}
+// ---------------------------------------------------------------- Sitefile imports (IMPORT … AS sitefile)
+/** How deep Sitefile imports may nest (an imported Sitefile importing another counts one more level). */
+export const MAX_SITEFILE_IMPORT_DEPTH = 8;
+/** The label an imported Sitefile's messages and file origins use. */
+export function sitefileLabel(scope) {
+    return scope.prefix + path.posix.join(scope.dir, 'Sitefile');
+}
+/** The label scope of the build's own Sitefile. */
+function rootScope(options, label) {
+    if (options.sitefile === undefined)
+        return { prefix: '', dir: path.posix.dirname(label) };
+    return { prefix: '', dir: path.relative(process.cwd(), path.resolve(options.contextDir)).split(path.sep).join('/') || '.' };
+}
+/** The ARG values an `IMPORT … AS sitefile` passes, checked against the imported Sitefile's ARGs. */
+export function importedArgs(spec, program) {
+    const declared = new Map(program.instructions.flatMap((i) => (i.kind === 'ARG' ? [[i.name, i]] : [])));
+    const args = {};
+    for (const a of spec.args ?? []) {
+        if (!declared.has(a.name))
+            throw new SitefileError('E_UNDEFINED', `IMPORT ${spec.name}: ${program.file} has no ARG ${a.name}`, a.span);
+        args[a.name] = a.value;
+    }
+    for (const [name, ins] of declared) {
+        if (ins.defaultValue === undefined && !(name in args)) {
+            throw new SitefileError('E_MISSING_ARG', `IMPORT ${spec.name}: ARG ${name} of ${program.file} has no default; set it with ARG ${name}=<value>`, spec.span);
+        }
+    }
+    return args;
+}
+/**
+ * Parse, check and plan an imported Sitefile: no PLUGIN or TOOL, the IMPORT's ARG clauses, and the
+ * stages `refs` (references from the importing Sitefile) must exist.
+ */
+export function planImportedSitefile(spec, source, label, refs) {
+    const program = parseProgram(source, label);
+    for (const ins of program.instructions) {
+        if (ins.kind === 'PLUGIN' || ins.kind === 'TOOL') {
+            throw new SitefileError('E_UNSUPPORTED', `${ins.kind} ${ins.name}: a Sitefile imported AS sitefile cannot run plugins or tools`, ins.span);
+        }
+    }
+    const p = plan(program, importedArgs(spec, program), (n) => `IMPORT ${spec.name} ARG ${n}`);
+    const names = p.stages.flatMap((s) => (s.name === undefined ? [] : [s.name]));
+    for (const ref of refs) {
+        if (ref.import !== spec.name || names.includes(ref.stage))
+            continue;
+        throw new SitefileError('E_UNDEFINED', `${ref.name}: ${label} has no stage '${ref.stage}' (${names.length ? `stages: ${names.join(', ')}` : 'it has no named stages'})`, ref.span);
+    }
+    return { program, plan: p };
+}
+/** Write a tree to a new temporary directory (a Git import's checkout). */
+async function materializeTree(tree, env) {
+    const dir = await mkdtemp(path.join(os.tmpdir(), 'sitefile-import-'));
+    env.tempDirs.push(dir);
+    try {
+        for (const [p, n] of tree.entries()) {
+            const dest = path.join(dir, ...p.slice(1).split('/'));
+            await mkdir(path.dirname(dest), { recursive: true });
+            await writeFile(dest, n.bytes, { mode: n.mode });
+            await chmod(dest, n.mode);
+        }
+    }
+    catch (e) {
+        throw new SitefileError('E_EXPORT', `cannot write a Git checkout to a temporary directory: ${e.message}`, undefined, { cause: e });
+    }
+    return dir;
+}
+/**
+ * Load an `IMPORT name FROM <dir|git+https://…> AS sitefile`: find its context (a directory of the
+ * importer's context, or a Git tree written to a temporary directory), read and plan its Sitefile with the
+ * IMPORT's ARGs, check the stages `refs` name, and resolve its imports exactly as a build would.
+ */
+async function loadSitefileImport(spec, importer, refs, env) {
+    const qualified = importer.name === undefined ? spec.name : `${importer.name}+${spec.name}`;
+    const origin = `${importer.label}:${spec.span.line} IMPORT ${spec.name}`;
+    let hostDir;
+    let scope;
+    let id;
+    let display;
+    let provenance;
+    let gitTree;
+    if (spec.location.kind === 'git') {
+        const loc = spec.location;
+        const { commit, selection } = await fetchGitImport(spec, loc, { ...env.remote, label: importer.label });
+        display = `'${loc.url}'`;
+        if (selection.kind === 'file') {
+            throw new SitefileError('E_TYPE', `IMPORT ${spec.name}: ${display} is a file; AS sitefile needs the directory that holds the Sitefile`, spec.span);
+        }
+        gitTree = Tree.fromFiles(selection.files.map(([p, f]) => [p, makeFile(f.bytes, origin, f.mode)]));
+        scope = { prefix: `git+${loc.repo}#${commit}:`, dir: loc.path };
+        id = `${scope.prefix}${loc.path}`;
+        provenance = { uri: spec.uri, resolvedUrl: pinnedGitUrl(loc, commit), gitCommit: commit };
+        hostDir = await materializeTree(gitTree, env);
+    }
+    else if (spec.location.kind === 'local') {
+        const rel = spec.location.path;
+        display = rel === '' ? `'./'` : `'./${rel}'`;
+        if ((await importer.local.stat(rel, spec.span)) !== 'directory') {
+            throw new SitefileError('E_TYPE', `IMPORT ${spec.name}: ${display} is a file; AS sitefile needs the directory that holds the Sitefile`, spec.span);
+        }
+        hostDir = await importer.local.realPath(rel, spec.span);
+        scope = { prefix: importer.scope.prefix, dir: path.posix.join(importer.scope.dir, rel) };
+        id = hostDir;
+        provenance = { uri: spec.uri };
+    }
+    else {
+        throw new SitefileError('E_PROTOCOL', `IMPORT ${spec.name}: AS sitefile reads a context directory or a git+https:// repository, not a URL`, spec.span);
+    }
+    const label = sitefileLabel(scope);
+    const seen = importer.chain.findIndex((c) => c.id === id);
+    if (seen !== -1) {
+        const cycle = [...importer.chain.slice(seen).map((c) => c.label), label];
+        throw new SitefileError('E_VALIDATION', `IMPORT ${spec.name}: Sitefile import cycle: ${cycle.join(' -> ')}`, spec.span);
+    }
+    if (importer.chain.length > MAX_SITEFILE_IMPORT_DEPTH) {
+        throw new SitefileError('E_VALIDATION', `IMPORT ${spec.name}: Sitefile imports nest more than ${MAX_SITEFILE_IMPORT_DEPTH} levels deep`, spec.span);
+    }
+    // Its context: the directory, sandboxed (its own .sitefileignore applies; what the build writes is skipped).
+    const ignore = ['.git'];
+    for (const s of env.skip) {
+        const rel = path.relative(hostDir, s);
+        if (rel !== '' && !rel.startsWith('..') && !path.isAbsolute(rel))
+            ignore.push(rel.split(path.sep).join('/'));
+    }
+    const local = await LocalContext.open(hostDir, { ignore, allowHardlinks: env.allowHardlinks });
+    let sitefileBytes;
+    try {
+        sitefileBytes = (await local.readFile('Sitefile', spec.span)).bytes;
+    }
+    catch (e) {
+        if (e instanceof SitefileError && e.code === 'E_NOT_FOUND') {
+            throw new SitefileError('E_NOT_FOUND', `IMPORT ${spec.name}: ${display} has no Sitefile`, spec.span, { cause: e });
+        }
+        throw e;
+    }
+    const { plan: p } = planImportedSitefile(spec, new TextDecoder().decode(sitefileBytes), label, refs);
+    p.warnings.forEach(env.remote.warn);
+    const lock = env.remote.lock;
+    if (env.strictPins) {
+        const pins = checkPins(p, lock, undefined);
+        for (const [n, how] of Object.entries(pins.imports))
+            env.pins[`${qualified}+${n}`] = how;
+    }
+    // Its FROM image lockfile entries are kept even when its stages are not built.
+    for (const st of p.stages)
+        if (st.base.kind === 'image' && !st.base.local)
+            lock?.markImageUsed(imageLockKey(st.base));
+    // Its imports, as a build of it would resolve them (every one, as for a --target build).
+    const ienv = { ...env.remote, label, local, archiveLimits: env.archiveLimits, ...(env.memo ? { memo: env.memo } : {}) };
+    const plain = p.imports.filter((s) => s.as !== 'sitefile');
+    const resolved = await mapLimit(plain, env.concurrency, (s) => resolveImport(s, ienv));
+    const byName = new Map(plain.map((s, i) => [s.name, { ...resolved[i], res: withoutDrafts(s, resolved[i].res) }]));
+    // SCHEMA files are read from the imported Sitefile's own context.
+    for (const s of plain) {
+        const r = byName.get(s.name);
+        if (r && s.schema)
+            await checkImportSchema(s, r.res, local);
+    }
+    const resources = new Map();
+    const resourceKeys = new Map();
+    const imported = new Map();
+    const nestedRefs = importedStageRefs(p.stages);
+    const self = { name: qualified, label, local, scope, chain: [...importer.chain, { id, label }] };
+    for (const s of p.imports) {
+        const r = byName.get(s.name);
+        if (r) {
+            resources.set(s.name, sorted(s, r.res));
+            resourceKeys.set(s.name, r.key);
+            continue;
+        }
+        const unit = await loadSitefileImport(s, self, nestedRefs, env);
+        imported.set(s.name, unit);
+        resources.set(s.name, unitResource(unit));
+        resourceKeys.set(s.name, env.memo ? memoKey('sitefile', label, valueKey(s), unit.digest) : '');
+    }
+    const unit = {
+        name: qualified,
+        label,
+        plan: p,
+        digest: gitTree ? gitTree.digest() : sha256(sitefileBytes),
+        isDirectory: gitTree ? (rel) => rel === '' || gitTree.isDirectory('/' + rel) : (rel) => isHostDirectory(path.join(hostDir, ...rel.split('/'))),
+        sitefileBytes,
+        resources,
+        imported,
+        local,
+        scope,
+        resourceKeys,
+        envKey: env.memo ? memoKey('env', label, valueKey([...p.vars]), valueKey([...p.fragments.values()].map((f) => [f.name, f.text]))) : '',
+        stageTrees: new Map(),
+        stageKeys: new Map(),
+        renames: new Map(),
+        stageRenames: new Map(),
+        ...(env.recordSteps ? { steps: [] } : {}),
+        built: 0,
+        provenance,
+    };
+    return unit;
+}
+/** The resource an `AS sitefile` import stands for (provenance): its Sitefile, with the unit's digest. */
+function unitResource(unit) {
+    return { kind: 'file', bytes: unit.sitefileBytes, mode: 0o644, basename: 'Sitefile', provenance: { ...unit.provenance, digest: unit.digest } };
+}
+function isHostDirectory(p) {
+    try {
+        return statSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/** The source of the build's own Sitefile, for {@link readImportedSitefile}. */
+export async function rootSitefileSource(options, label, sitefilePath) {
+    const contextReal = await realpath(options.contextDir).catch((e) => {
+        throw new SitefileError('E_NOT_FOUND', `build context '${options.contextDir}' does not exist`, undefined, { cause: e });
+    });
+    const local = await LocalContext.open(contextReal, { ignore: ['.git'], allowHardlinks: options.allowHardlinks ?? false });
+    const id = options.sitefile === undefined ? contextReal : await realpathLoose(sitefilePath);
+    return { kind: 'local', local, scope: rootScope(options, label), label, chain: [{ id, label }] };
+}
+/**
+ * Read and plan the Sitefile an `IMPORT … AS sitefile` of `from` names, without building it (for `vendor`
+ * and `outdated`): the same location, cycle, depth and ARG rules as a build. A Git one is fetched with
+ * `fetchGit` (the commit a build would use). Returns its plan and the source its own imports read from.
+ */
+export async function readImportedSitefile(spec, from, refs, fetchGit) {
+    let scope;
+    let id;
+    let display;
+    let bytes;
+    let make;
+    if (spec.location.kind === 'git') {
+        const loc = spec.location;
+        const { commit, selection } = await fetchGit(spec, loc);
+        display = `'${loc.url}'`;
+        if (selection.kind === 'file') {
+            throw new SitefileError('E_TYPE', `IMPORT ${spec.name}: ${display} is a file; AS sitefile needs the directory that holds the Sitefile`, spec.span);
+        }
+        const tree = Tree.fromFiles(selection.files.map(([p, f]) => [p, makeFile(f.bytes, 'git', f.mode)]));
+        scope = { prefix: `git+${loc.repo}#${commit}:`, dir: loc.path };
+        id = `${scope.prefix}${loc.path}`;
+        bytes = tree.get('/Sitefile')?.bytes;
+        make = (label, chain) => ({ kind: 'tree', tree, dir: '', scope, label, chain });
+    }
+    else if (spec.location.kind === 'local') {
+        const rel = spec.location.path;
+        display = rel === '' ? `'./'` : `'./${rel}'`;
+        scope = { prefix: from.scope.prefix, dir: path.posix.join(from.scope.dir, rel) };
+        if (from.kind === 'local') {
+            if ((await from.local.stat(rel, spec.span)) !== 'directory') {
+                throw new SitefileError('E_TYPE', `IMPORT ${spec.name}: ${display} is a file; AS sitefile needs the directory that holds the Sitefile`, spec.span);
+            }
+            const real = await from.local.realPath(rel, spec.span);
+            id = real;
+            const local = await LocalContext.open(real, { ignore: ['.git'] });
+            bytes = await local.readFile('Sitefile', spec.span).then((f) => f.bytes, (e) => {
+                if (e instanceof SitefileError && e.code === 'E_NOT_FOUND')
+                    return undefined;
+                throw e;
+            });
+            make = (label, chain) => ({ kind: 'local', local, scope, label, chain });
+        }
+        else {
+            const dir = path.posix.join(from.dir, rel).replace(/^\.$/, '');
+            const at = dir === '' ? '/' : '/' + dir;
+            if (from.tree.isFile(at)) {
+                throw new SitefileError('E_TYPE', `IMPORT ${spec.name}: ${display} is a file; AS sitefile needs the directory that holds the Sitefile`, spec.span);
+            }
+            if (!from.tree.isDirectory(at))
+                throw new SitefileError('E_NOT_FOUND', `'${display.slice(1, -1)}' does not exist in the build context`, spec.span);
+            id = `${from.scope.prefix}${scope.dir}`;
+            bytes = from.tree.get(at === '/' ? '/Sitefile' : `${at}/Sitefile`)?.bytes;
+            const tree = from.tree;
+            make = (label, chain) => ({ kind: 'tree', tree, dir, scope, label, chain });
+        }
+    }
+    else {
+        throw new SitefileError('E_PROTOCOL', `IMPORT ${spec.name}: AS sitefile reads a context directory or a git+https:// repository, not a URL`, spec.span);
+    }
+    const label = sitefileLabel(scope);
+    const seen = from.chain.findIndex((c) => c.id === id);
+    if (seen !== -1) {
+        throw new SitefileError('E_VALIDATION', `IMPORT ${spec.name}: Sitefile import cycle: ${[...from.chain.slice(seen).map((c) => c.label), label].join(' -> ')}`, spec.span);
+    }
+    if (from.chain.length > MAX_SITEFILE_IMPORT_DEPTH) {
+        throw new SitefileError('E_VALIDATION', `IMPORT ${spec.name}: Sitefile imports nest more than ${MAX_SITEFILE_IMPORT_DEPTH} levels deep`, spec.span);
+    }
+    if (bytes === undefined)
+        throw new SitefileError('E_NOT_FOUND', `IMPORT ${spec.name}: ${display} has no Sitefile`, spec.span);
+    const { plan: p } = planImportedSitefile(spec, new TextDecoder().decode(bytes), label, refs);
+    return { plan: p, source: make(label, [...from.chain, { id, label }]) };
+}
+/** The resources of the Sitefiles a build imports, by qualified name (`theme+data`), depth first in IMPORT order. */
+function nestedResources(units, out = []) {
+    for (const unit of units.values()) {
+        for (const [name, res] of unit.resources)
+            out.push([`${unit.name}+${name}`, res]);
+        nestedResources(unit.imported, out);
+    }
+    return out;
+}
+/**
+ * Make the imported stages `refs` names available in `stages`/`keys` as `<import>+<stage>`: each imported
+ * Sitefile builds its stages up to the last one referenced (like a --target build).
+ */
+async function provideImportedStages(units, refs, stages, keys, renames, env) {
+    for (const [name, unit] of units) {
+        const wanted = refs.filter((r) => r.import === name);
+        if (!wanted.length)
+            continue;
+        const upto = Math.max(...wanted.map((r) => unit.plan.stages.findIndex((s) => s.name === r.stage)));
+        await buildUnitStages(unit, upto, env);
+        for (const st of unit.plan.stages.slice(0, unit.built)) {
+            if (st.name === undefined)
+                continue;
+            stages.set(`${name}+${st.name}`, unit.stageTrees.get(st.name));
+            keys.set(`${name}+${st.name}`, unit.stageKeys.get(st.name) ?? '');
+            renames.set(`${name}+${st.name}`, unit.stageRenames.get(st.name) ?? new Map());
+        }
+    }
+}
+/** Build an imported Sitefile's stages up to index `upto` (those already built are kept). */
+async function buildUnitStages(unit, upto, env) {
+    if (upto < unit.built)
+        return;
+    await provideImportedStages(unit.imported, importedStageRefs(unit.plan.stages.slice(0, upto + 1)), unit.stageTrees, unit.stageKeys, unit.stageRenames, env);
+    const execEnv = {
+        local: unit.local,
+        resources: unit.resources,
+        stages: unit.stageTrees,
+        vars: unit.plan.vars,
+        fragments: unit.plan.fragments,
+        partials: new Map(),
+        label: unit.label,
+        warn: env.remote.warn,
+        ...env.exec,
+        tools: new Map(),
+        pluginDigests: new Map(),
+        ...(env.memo ? { memo: env.memo } : {}),
+        resourceKeys: unit.resourceKeys,
+        envKey: unit.envKey,
+        stageKeys: unit.stageKeys,
+        fromImage: (b) => env.fromImage(b, unit.name),
+    };
+    for (let i = unit.built; i <= upto; i++) {
+        const stage = unit.plan.stages[i];
+        const start = await startStage(stage, execEnv);
+        let tree = start.tree;
+        let key = start.key;
+        let current = stage.base.kind === 'stage' ? (unit.stageRenames.get(stage.base.name) ?? new Map()) : new Map();
+        const record = unit.steps ? [tree] : undefined;
+        for (const op of stage.operations) {
+            const r = await executeOp(op, tree, key, current.size ? { ...execEnv, renames: current } : execEnv);
+            tree = r.tree;
+            key = r.key;
+            if (r.renames) {
+                unit.renames.set(op.span.line, r.renames);
+                current = composeRenames(current, r.renames);
+            }
+            record?.push(tree);
+        }
+        if (record)
+            unit.steps.push(record);
+        if (stage.name !== undefined) {
+            unit.stageRenames.set(stage.name, current);
+            unit.stageTrees.set(stage.name, tree);
+            unit.stageKeys.set(stage.name, key);
+        }
+        unit.built = i + 1;
+    }
+}
+/** The tree a stage starts from, and its key. */
+async function startStage(stage, env) {
+    const base = stage.base;
+    switch (base.kind) {
+        case 'scratch':
+            return { tree: Tree.empty, key: env.memo ? memoKey('scratch', env.envKey) : '' };
+        case 'stage':
+            return { tree: env.stages.get(base.name) ?? fail(base.name, stage.span), key: env.stageKeys.get(base.name) ?? '' };
+        case 'local': {
+            const display = base.path === '' ? './' : './' + base.path;
+            if ((await env.local.stat(base.path, stage.span)) !== 'directory') {
+                throw new SitefileError('E_TYPE', `FROM '${display}' is a file; FROM needs a directory`, stage.span);
+            }
+            const t = await env.local.readTree(base.path, `${env.label}:${stage.span.line} FROM`, stage.span);
+            return { tree: t.tree, key: env.memo ? memoKey('from', env.envKey, String(stage.span.line), base.path, t.provenance.digest) : '' };
+        }
+        case 'image': {
+            const img = await env.fromImage(base);
+            return { tree: img.tree, key: env.memo ? memoKey('image', env.envKey, String(stage.span.line), base.ref, base.at ?? '', img.digest) : '' };
+        }
+    }
+}
+/** What a stage starts from, for the trace. */
+function stageFrom(stage) {
+    const b = stage.base;
+    if (b.kind === 'image')
+        return `image ${b.ref}${b.at !== undefined ? ` AT ${b.at}` : ''}`;
+    return b.kind === 'scratch' ? 'scratch' : b.kind === 'stage' ? b.name : b.path === '' ? './' : './' + b.path;
+}
+function fail(name, span) {
+    throw new SitefileError('E_UNDEFINED', `unknown stage '${name}'`, span);
+}
+function recording(env) {
+    const warnings = [];
+    return {
+        ...env,
+        warnings,
+        unrecorded: env.warn,
+        warn: (m) => {
+            warnings.push(m);
+            env.warn(m);
+        },
+    };
+}
+/**
+ * Run `compute` unless `key` is memoized. A hit replays the warnings the step printed
+ * after those this run already printed before the lookup (the same code ran up to here,
+ * so they are a prefix). `store` says whether the result may be reused (a plugin can opt out).
+ */
+async function memoFiles(env, key, compute, store = () => true) {
+    if (!env.memo || key === undefined)
+        return { files: await compute([]) };
+    const hit = env.memo.get(key);
+    if (hit) {
+        for (const w of hit.warnings.slice(env.warnings.length))
+            env.warn(w);
+        return { files: hit.files, key, hit: true };
+    }
+    const children = [];
+    const files = await compute(children);
+    if (!store())
+        return { files };
+    env.memo.set(key, { files, warnings: [...env.warnings] }, children);
+    return { files, key };
+}
+/** What a source reference reads, for memo keys (the operation's own text covers inline bodies and paths). */
+function sourceKey(ref, src, env) {
+    switch (ref.kind) {
+        case 'inline':
+            return 'inline';
+        case 'local':
+            return `local\0${src?.digest ?? ''}`;
+        case 'stage':
+            return `stage\0${env.stageKeys.get(ref.name) ?? ''}`;
+        case 'import':
+            return `import\0${env.resourceKeys.get(ref.name) ?? ''}`;
+    }
+}
+/** Names an operand interpolates. */
+function operandNames(ops, out = new Set()) {
+    for (const op of ops)
+        for (const part of op?.parts ?? [])
+            if (part.kind !== 'text')
+                out.add(part.name);
+    return out;
+}
+/**
+ * The keys of the imports an operation may read, by name (ARG/LET values are in its opId).
+ * `except`: a loop variable, which hides an import of the same name.
+ */
+function namesKey(env, names, except) {
+    const list = [...new Set(names)].filter((n) => n !== except).sort();
+    return memoKey('names', ...list.flatMap((n) => [n, env.resourceKeys.get(n) ?? '']));
+}
+/** The html fragments a template context resolves (LETs from the plan, `AS html` imports parsed on first use). */
+function templateContext(env) {
+    const partial = (name) => {
+        const res = env.resources.get(name);
+        if (res?.kind !== 'value' || res.format !== 'html')
+            return undefined;
+        let nodes = env.partials.get(name);
+        if (!nodes) {
+            nodes = parseRenderTemplate(fragmentText(res.value), res.provenance.uri);
+            env.partials.set(name, nodes);
+        }
+        return nodes;
+    };
+    return {
+        isFragment: (name) => {
+            if (env.loop?.name === name)
+                return false;
+            if (env.fragments.has(name))
+                return true;
+            const res = env.resources.get(name);
+            return res?.kind === 'value' && res.format === 'html';
+        },
+        fragment: (name) => env.fragments.get(name)?.nodes ?? partial(name) ?? [],
+    };
+}
+/** Whether a template has a `${file …}` (it then reads the tree at its RENDER). */
+function usesFiles(nodes) {
+    return nodes.some((n) => n.kind === 'file' || (n.kind === 'each' && (usesFiles(n.body) || usesFiles(n.empty))) || (n.kind === 'if' && (usesFiles(n.then) || usesFiles(n.otherwise))));
+}
+/**
+ * The names a template reads, with those of the html fragments it uses (and theirs), for memo keys,
+ * and whether it or one of those fragments reads files. A fragment that does not parse adds nothing:
+ * rendering fails on it anyway.
+ */
+function renderDeps(nodes, env) {
+    const out = templateNames(nodes);
+    let files = usesFiles(nodes);
+    const ctx = templateContext(env);
+    const seen = new Set();
+    for (let grew = true; grew;) {
+        grew = false;
+        for (const name of [...out]) {
+            if (seen.has(name) || !ctx.isFragment(name))
+                continue;
+            seen.add(name);
+            try {
+                const before = out.size;
+                const f = ctx.fragment(name);
+                templateNames(f, out);
+                files ||= usesFiles(f);
+                grew ||= out.size > before;
+            }
+            catch {
+                // E_TEMPLATE in an imported partial: reported when the RENDER runs.
+            }
+        }
+    }
+    return { names: out, files };
+}
+/** Top-level names a template reads (variables, #each lists, #if conditions). */
+export function templateNames(nodes, out = new Set()) {
+    for (const n of nodes) {
+        if (n.kind === 'var')
+            out.add(n.name);
+        else if (n.kind === 'file')
+            for (const r of fileRefs(n))
+                out.add(r.name);
+        else if (n.kind === 'each') {
+            out.add(n.list.name);
+            templateNames(n.body, out);
+            templateNames(n.empty, out);
+        }
+        else if (n.kind === 'if') {
+            out.add(n.cond.name);
+            templateNames(n.then, out);
+            templateNames(n.otherwise, out);
+        }
+    }
+    return out;
+}
+/**
+ * Run one operation: produce its files, then add them to the tree. With a memo, a step whose
+ * key (the operation and everything it reads) is unchanged reuses its files, and one whose
+ * input tree is also unchanged reuses the resulting tree. The key of the result chains the
+ * input tree's key with the step's, like image layers.
+ */
+async function executeOp(op, tree, prevKey, env) {
+    const policy = 'overwrite' in op && op.overwrite ? 'overwrite' : 'error';
+    const memo = env.memo;
+    if (!memo) {
+        if (op.kind === 'SITEMAP')
+            return { tree: sitemap(op, tree, env), key: '' };
+        if (op.kind === 'FINGERPRINT')
+            return { ...fingerprintOp(op, tree, env), key: '' };
+        if (op.kind === 'CHECKLINKS') {
+            await checkLinks(op, tree, env, env.warn);
+            return { tree, key: '' };
+        }
+        return { tree: tree.withFiles((await produce(op, tree, recording(env), '', '')).files, policy, op.span), key: '' };
+    }
+    const opId = memoKey('op', env.envKey, valueKey(op));
+    if (op.kind === 'SITEMAP' || op.kind === 'FINGERPRINT' || op.kind === 'CHECKLINKS') {
+        // Reads the whole tree: only the chain key can say it is unchanged.
+        const key = memoKey('chain', prevKey, opId);
+        if (op.kind === 'CHECKLINKS') {
+            // The tree is unchanged; a hit skips the check (and its requests) and prints its warnings again.
+            const hit = memo.get(key);
+            if (hit) {
+                hit.warnings.forEach(env.warn);
+                return { tree, key, memo: 'hit' };
+            }
+            const warnings = [];
+            await checkLinks(op, tree, env, (m) => (warnings.push(m), env.warn(m)));
+            memo.set(key, { warnings });
+            return { tree, key, memo: 'miss' };
+        }
+        if (op.kind === 'FINGERPRINT') {
+            const hit = memo.get(key);
+            if (hit) {
+                hit.warnings.forEach(env.warn);
+                return { tree: hit.tree, renames: hit.renames, key, memo: 'hit' };
+            }
+            const warnings = [];
+            const out = fingerprintOp(op, tree, { ...env, warn: (m) => (warnings.push(m), env.warn(m)) });
+            memo.set(key, { ...out, warnings });
+            return { ...out, key, memo: 'miss' };
+        }
+        const hit = memo.get(key);
+        if (hit)
+            return { tree: hit, key, memo: 'hit' };
+        const out = sitemap(op, tree, env);
+        memo.set(key, out);
+        return { tree: out, key, memo: 'miss' };
+    }
+    const p = await produce(op, tree, recording(env), opId, prevKey);
+    // Not memoizable (e.g. a plugin that opted out of caching): chain on what it produced instead.
+    const stepKey = p.key ?? memoKey('files', ...p.files.flatMap(([f, n]) => [f, String(n.mode), n.digest, n.origin]));
+    const key = memoKey('chain', prevKey, stepKey);
+    const hit = memo.get(key);
+    if (hit)
+        return { tree: hit, key, memo: 'hit' };
+    const out = tree.withFiles(p.files, policy, op.span);
+    memo.set(key, out);
+    return { tree: out, key, memo: p.hit ? 'files' : 'miss' };
+}
+async function checkLinks(op, tree, env, warn) {
+    const broken = await brokenLinks(tree, op, env.fetchPolicy);
+    reportBrokenLinks(broken, op, `${env.label}:${op.span.line} CHECKLINKS`, warn);
+}
+function fingerprintOp(op, tree, env) {
+    return fingerprint(tree, op, `${env.label}:${op.span.line} FINGERPRINT`, env.warn);
+}
+function sitemap(op, tree, env) {
+    const origin = `${env.label}:${op.span.line} SITEMAP`;
+    return tree.withFiles([[op.dest, makeFile(new TextEncoder().encode(sitemapXml(tree, op.base)), origin)]], op.overwrite ? 'overwrite' : 'error', op.span);
+}
+/** Check a plugin file (sandbox, own folder, integrity) and start its process. */
+async function registerPlugin(spec, local, host, allowed) {
+    const { real, bytes } = await local.realFile(spec.path, spec.span);
+    if (spec.integrity)
+        verifyIntegrity(bytes, spec.integrity, `./${spec.path}`, spec.span);
+    if (real.endsWith('.wasm')) {
+        // A wasm plugin has no imports, so it reads nothing: no own-folder rule needed.
+        checkWasmPlugin(spec.name, bytes, spec.span);
+        host.register(spec.name, real, spec.span, bytes);
+        return;
+    }
+    // It runs as JavaScript (also a '.wasm' path that is a symlink to a JS file), so it needs the opt-in.
+    allowed(spec);
+    // A JS plugin may read its whole folder, so that folder must not be the context itself.
+    if (path.dirname(real) === local.root) {
+        throw new SitefileError('E_VALIDATION', `PLUGIN ${spec.name}: put the plugin in its own folder (e.g. ./plugins/${path.basename(real)}); a plugin can read every file next to it`, spec.span);
+    }
+    host.register(spec.name, real, spec.span);
+}
+/**
+ * Check every JavaScript PLUGIN against `--allow-plugin` / `--allow-plugins` before
+ * anything is read or started. A wasm plugin (a module that imports nothing) runs
+ * without permission. Returns the check, which registerPlugin repeats on the real path.
+ */
+function checkPlugins(p, options, warn) {
+    const names = new Set();
+    for (const name of options.allowPlugin ?? []) {
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name))
+            throw new SitefileError('E_USAGE', `--allow-plugin expects a PLUGIN name (an identifier), got '${name}'`);
+        names.add(name);
+    }
+    const all = options.allowAllPlugins ?? false;
+    const allowed = (spec) => {
+        if (all || names.has(spec.name))
+            return;
+        throw new SitefileError('E_UNSUPPORTED', `PLUGIN ${spec.name} runs JavaScript, which must be allowed explicitly: add --allow-plugin ${spec.name} (or --allow-plugins to allow every PLUGIN); WebAssembly plugins need no flag`, spec.span);
+    };
+    for (const spec of p.plugins)
+        if (!spec.path.endsWith('.wasm'))
+            allowed(spec);
+    for (const name of names)
+        if (!p.plugins.some((s) => s.name === name))
+            warn(`--allow-plugin ${name} does not match any PLUGIN and was ignored`);
+    return allowed;
+}
+/** Match each declared TOOL to a `--allow-exec` entry and resolve it to a real path. */
+async function resolveTools(p, options, warn) {
+    const allowed = new Map();
+    for (const spec of options.allowExec ?? []) {
+        const eq = spec.indexOf('=');
+        const name = eq < 0 ? spec : spec.slice(0, eq);
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name) || (eq >= 0 && eq === spec.length - 1)) {
+            throw new SitefileError('E_USAGE', `--allow-exec expects NAME or NAME=/absolute/path (NAME is an identifier), got '${spec}'`);
+        }
+        allowed.set(name, eq < 0 ? undefined : spec.slice(eq + 1));
+    }
+    const out = [];
+    for (const t of p.tools) {
+        if (!allowed.has(t.name)) {
+            throw new SitefileError('E_UNSUPPORTED', `TOOL ${t.name} runs an external program, which must be allowed explicitly: add --allow-exec ${t.name} (or --allow-exec ${t.name}=/absolute/path)`, t.span);
+        }
+        const tool = await resolveTool(t.name, allowed.get(t.name), process.env['PATH'], t.span);
+        options.onNotice?.(`tool ${t.name} -> ${tool.path}`);
+        out.push(tool);
+    }
+    for (const name of allowed.keys())
+        if (!p.tools.some((t) => t.name === name))
+            warn(`--allow-exec ${name} does not match any TOOL and was ignored`);
+    return out;
+}
+/** Interpolate an operand with ARG/LET values and, inside FOR, the loop element. */
+function interpolate(op, env) {
+    let out = '';
+    for (const part of op.parts) {
+        if (part.kind === 'text')
+            out += part.value;
+        else
+            out += String(lookup(part.name, part.path, part.span, env));
+    }
+    return out;
+}
+async function produceTransform(op, env, opId) {
+    const origin = `${env.label}:${op.span.line} TRANSFORM`;
+    let items = [undefined];
+    if (op.each) {
+        const list = valueOf(op.each.list, [], op.span, false, env);
+        if (!Array.isArray(list)) {
+            throw new SitefileError('E_TYPE', `FOR ${op.each.as} IN ${op.each.list}: '${op.each.list}' is not a list`, op.span);
+        }
+        if (list.length === 0)
+            env.warn(`${origin}: FOR ${op.each.as} IN ${op.each.list} produces nothing: the list is empty`);
+        items = list;
+    }
+    // The source is the same for every element; read it once.
+    let input;
+    let data;
+    let srcKey = '';
+    // A directory source: the plugin runs once per file (--include/--exclude pick them).
+    let dir;
+    const filtered = op.include !== undefined || op.exclude !== undefined;
+    if (op.source) {
+        const ref = op.source;
+        const res = ref.kind === 'import' ? env.resources.get(ref.name) : undefined;
+        if (ref.kind === 'import' && res?.kind === 'value') {
+            if (ref.path !== '/')
+                throw new SitefileError('E_PATH', `import '${ref.name}' is a value; use '${ref.name}:'`, ref.span);
+            if (filtered)
+                throw new SitefileError('E_TYPE', `--include and --exclude filter a directory, but '${ref.name}:' is a value import`, ref.span);
+            data = res.value;
+        }
+        else {
+            const src = await readSource(op.source, origin, env, op.exclude ? IgnoreRules.fromPatterns(op.exclude) : undefined);
+            if (src.kind !== 'file') {
+                if (op.each) {
+                    throw new SitefileError('E_TYPE', `TRANSFORM source '${src.label}' is a directory, which runs the plugin once per file and cannot be combined with FOR`, op.source.span);
+                }
+                dir = { tree: including(src.tree, op.include), label: src.label };
+            }
+            else {
+                if (filtered)
+                    throw new SitefileError('E_TYPE', `--include and --exclude filter a directory, but '${src.label}' is a file`, op.source.span);
+                input = { path: src.label, name: src.basename || src.label, bytes: src.bytes, ...textOf(src.bytes) };
+            }
+            if (env.memo)
+                srcKey = sourceKey(ref, src, env);
+        }
+    }
+    const tool = env.tools.get(op.plugin);
+    if (tool && !input && !dir && op.source) {
+        throw new SitefileError('E_TYPE', `TRANSFORM … WITH ${op.plugin}: a TOOL needs a file source, not a value import`, op.source.span);
+    }
+    const inputDigest = input ? sha256(input.bytes) : undefined;
+    let pluginDigest;
+    if ((env.cache || env.memo) && !tool) {
+        if (!env.pluginDigests.has(op.plugin)) {
+            // A wasm plugin is just its module; a JS plugin can read its whole folder.
+            const wasm = env.plugins.wasmBytes(op.plugin);
+            const dir = env.plugins.folderOf(op.plugin);
+            const digest = wasm ? sha256(wasm) : dir ? await digestFolder(dir) : undefined;
+            env.pluginDigests.set(op.plugin, digest);
+            if (digest === undefined && env.cache)
+                env.warn(`${origin}: PLUGIN ${op.plugin}'s folder is too large to hash; its results are not cached`);
+        }
+        pluginDigest = env.pluginDigests.get(op.plugin);
+    }
+    // Incremental rebuilds: the same code (plugin digest, or tool binary), source, data, list and interpolated names.
+    const code = tool ? `tool\0${tool.path}\0${tool.size}\0${tool.mtimeMs}` : pluginDigest !== undefined ? `plugin\0${pluginDigest}` : undefined;
+    const memo = env.memo && code !== undefined ? env.memo : undefined;
+    const operandRefs = operandNames([op.dest, ...op.options.map((o) => o.value), ...(op.args ?? [])], new Set(data !== undefined && op.source?.kind === 'import' ? [op.source.name] : []));
+    const key = memo ? memoKey('transform', opId, srcKey, code, namesKey(env, op.each ? new Set([...operandRefs, op.each.list]) : operandRefs)) : undefined;
+    const storable = () => tool !== undefined || env.plugins.cacheable(op.plugin);
+    if (dir) {
+        const files = { tree: dir.tree, label: dir.label, fileBase: memo ? memoKey('transform-file', opId, code, namesKey(env, operandRefs)) : undefined };
+        return memoFiles(env, key, (children) => transformFiles(op, env, files, { tool, pluginDigest, memo, children }), storable);
+    }
+    // One FOR element's files: the same request gives the same result (the list itself is not read).
+    const itemBase = memo && op.each ? memoKey('transform-item', opId, srcKey, code, namesKey(env, operandRefs, op.each.as)) : undefined;
+    return memoFiles(env, key, async (children) => {
+        const files = [];
+        for (const item of items) {
+            const itemKey = itemBase !== undefined ? memoKey(itemBase, valueKey(item)) : undefined;
+            const reused = itemKey !== undefined ? memo.get(itemKey, children) : undefined;
+            if (reused) {
+                files.push(...reused);
+                continue;
+            }
+            const itemFiles = [];
+            const itemEnv = op.each ? { ...env, loop: { name: op.each.as, value: item } } : env;
+            const rawDest = interpolate(op.dest, itemEnv);
+            if (starName(rawDest) !== undefined) {
+                throw new SitefileError('E_TYPE', `TRANSFORM destination '${rawDest}': a '*' name stands for each file of a directory source, and this TRANSFORM's source is not a directory`, op.dest.span);
+            }
+            const dest = normalizeVirtual(rawDest, op.dest.span, 'TRANSFORM destination');
+            const options = Object.create(null);
+            for (const o of op.options)
+                options[o.key] = interpolate(o.value, itemEnv);
+            const request = {
+                apiVersion: 1,
+                dest: dest.path,
+                options,
+                ...(input ? { input } : {}),
+                ...(data !== undefined ? { data } : {}),
+                ...(op.each ? { item } : {}),
+            };
+            let args;
+            if (tool) {
+                if (dest.trailingSlash)
+                    throw new SitefileError('E_PLUGIN', `TOOL ${op.plugin} writes one file, but '${rawDest}' is a directory destination`, op.dest.span);
+                args = (op.args ?? []).map((a) => interpolate(a, itemEnv));
+            }
+            // Everything the result can depend on: the code (plugin folder digest, or tool binary + argv) and the request.
+            const cacheable = env.cache !== undefined && (tool !== undefined || pluginDigest !== undefined);
+            const cached = cacheable
+                ? cacheKey({
+                    code: tool ? { tool: { path: tool.path, size: tool.size, mtimeMs: tool.mtimeMs }, args } : { plugin: pluginDigest },
+                    request: {
+                        dest: dest.path,
+                        options,
+                        input: input && { path: input.path, name: input.name, digest: inputDigest },
+                        data,
+                        item,
+                    },
+                })
+                : undefined;
+            const call = begin(env.profiler, `TRANSFORM ${op.plugin} ${dest.path}`, 'transform', { plugin: op.plugin, tool: tool !== undefined, dest: dest.path });
+            let result = cached ? await env.cache.get(cached) : undefined;
+            const cacheState = !cached ? 'off' : result ? 'hit' : 'miss';
+            if (!result) {
+                if (tool) {
+                    env.stats.toolRuns++;
+                    result = await runTool(tool, { args: args, dest: dest.path, options, ...(input ? { input: { name: input.name, bytes: input.bytes } } : {}) }, env.toolPolicy, 
+                    // The tool's stderr, like a TRANSFORM cache hit, is not replayed by a memo hit.
+                    (l) => env.unrecorded(l), op.span);
+                }
+                else {
+                    result = await env.plugins.call(op.plugin, request, op.span);
+                }
+                if (cached && (tool || env.plugins.cacheable(op.plugin)))
+                    await env.cache.put(cached, result);
+            }
+            call.end({ cache: cacheState });
+            if (result.kind === 'file') {
+                if (dest.trailingSlash) {
+                    throw new SitefileError('E_PLUGIN', `PLUGIN ${op.plugin} returned one file, but '${rawDest}' is a directory destination`, op.dest.span);
+                }
+                itemFiles.push([dest.path, makeFile(result.bytes, origin)]);
+            }
+            else {
+                // { files }: placed under the destination directory.
+                for (const [rel, bytes] of result.files) {
+                    const p = normalizeVirtual(`${dest.path === '/' ? '' : dest.path}/${rel}`, op.dest.span, `file '${rel}' returned by PLUGIN ${op.plugin}`).path;
+                    if (rel.includes('..') || rel.startsWith('/')) {
+                        throw new SitefileError('E_PLUGIN', `PLUGIN ${op.plugin} returned an unsafe path '${rel}'`, op.span);
+                    }
+                    itemFiles.push([p, makeFile(bytes, origin)]);
+                }
+            }
+            if (itemKey !== undefined && storable())
+                memo.set(itemKey, itemFiles);
+            files.push(...itemFiles);
+        }
+        return files;
+    }, 
+    // A plugin that answered `cache: false` is not reused either.
+    storable);
+}
+/** Decoded UTF-8 text for a plugin input, when the bytes are valid UTF-8. */
+function textOf(bytes) {
+    try {
+        return { text: new TextDecoder('utf-8', { fatal: true }).decode(bytes) };
+    }
+    catch {
+        return {};
+    }
+}
+/** A directory source with only the files an `--include` pattern matches (relative to its root). */
+function including(tree, include) {
+    if (!include)
+        return tree;
+    const rules = IgnoreRules.fromPatterns(include);
+    return Tree.fromFiles(tree.entries().filter(([p]) => rules.excludes(p.slice(1))));
+}
+/**
+ * The last segment of a TRANSFORM destination when it names each file of a directory source:
+ * `*` (the file's own name) or `*.ext` (its name with the extension replaced). Undefined otherwise.
+ */
+export function starName(dest) {
+    const last = dest.slice(dest.lastIndexOf('/') + 1);
+    return last === '*' || /^\*\.[^*]+$/.test(last) ? last : undefined;
+}
+/**
+ * Where one file of a directory TRANSFORM goes: `rel` is its path inside the source directory.
+ * `TO /out/*` keeps its relative path, `TO /out/*.ext` replaces its extension, and any other
+ * destination is the directory `<dest>/<relative dir>/` (the plugin names the files).
+ */
+export function fileDest(dest, rel) {
+    const base = dest.slice(0, dest.lastIndexOf('/') + 1);
+    const star = starName(dest);
+    const cut = rel.lastIndexOf('/');
+    const relDir = rel.slice(0, cut + 1);
+    const name = rel.slice(cut + 1);
+    if (star === '*')
+        return base + rel;
+    if (star !== undefined) {
+        const dot = name.lastIndexOf('.');
+        return base + relDir + (dot > 0 ? name.slice(0, dot) : name) + star.slice(1);
+    }
+    return (dest.endsWith('/') ? dest : dest + '/') + relDir;
+}
+/**
+ * Run `fn(0..n)` at most `limit` at a time, starting them in index order. After a failure no
+ * later index starts, so the lowest failing index is always among the results (and every index
+ * below it has run): callers report that one, whatever order the calls finished in.
+ */
+export async function runBounded(n, limit, fn) {
+    const out = new Array(n).fill(undefined);
+    let next = 0;
+    let failedAt = Infinity;
+    const lane = async () => {
+        for (;;) {
+            const i = next++;
+            if (i >= n || i > failedAt)
+                return;
+            try {
+                out[i] = { ok: true, value: await fn(i) };
+            }
+            catch (error) {
+                out[i] = { ok: false, error };
+                failedAt = Math.min(failedAt, i);
+            }
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(Math.max(1, limit), n) }, lane));
+    return out;
+}
+/** A failure for one file of a directory TRANSFORM: the same error, naming the file. */
+function namingFile(e, file) {
+    return e instanceof SitefileError ? new SitefileError(e.code, `${file}: ${e.detail}`, e.span) : e;
+}
+/**
+ * TRANSFORM over a directory: one plugin (or tool) call per file, in path order. Each call gets
+ * its own `input` and destination (see `fileDest`), is cached and memoized per file, and calls
+ * run up to TRANSFORM_JOBS at a time (a JavaScript plugin, one process, takes one at a time).
+ * Files, tool output, profile events and errors come in path order whatever order calls finish in.
+ */
+async function transformFiles(op, env, dir, ctx) {
+    const { tool, pluginDigest, memo, children } = ctx;
+    const line = `${env.label}:${op.span.line} TRANSFORM`;
+    const entries = dir.tree.entries();
+    if (entries.length === 0) {
+        env.warn(op.include || op.exclude
+            ? `${line}: --include/--exclude leave no files of '${dir.label}' to transform`
+            : `${line}: '${dir.label}' contains no files`);
+    }
+    const rawDest = interpolate(op.dest, env);
+    normalizeVirtual(rawDest, op.dest.span, 'TRANSFORM destination');
+    const dirDest = rawDest.endsWith('/') ? rawDest : rawDest + '/';
+    if (tool && starName(rawDest) === undefined) {
+        throw new SitefileError('E_PLUGIN', `TOOL ${op.plugin} writes one file per input, but '${rawDest}' is a directory destination: use '${dirDest}*' to keep each file's name, or '${dirDest}*.ext' to change its extension`, op.dest.span);
+    }
+    const options = Object.create(null);
+    for (const o of op.options)
+        options[o.key] = interpolate(o.value, env);
+    const args = tool ? (op.args ?? []).map((a) => interpolate(a, env)) : undefined;
+    const store = () => tool !== undefined || env.plugins.cacheable(op.plugin);
+    const done = [];
+    const jobs = [];
+    for (const [index, [p, node]] of entries.entries()) {
+        const rel = p.slice(1);
+        const label = (dir.label.endsWith('/') ? dir.label : dir.label + '/') + rel;
+        const fileKey = dir.fileBase !== undefined ? memoKey(dir.fileBase, rel, node.digest) : undefined;
+        const reused = fileKey !== undefined ? memo.get(fileKey, children) : undefined;
+        if (reused) {
+            done[index] = reused;
+            continue;
+        }
+        const perFile = fileDest(rawDest, rel);
+        const dest = normalizeVirtual(perFile, op.dest.span, 'TRANSFORM destination');
+        const input = { path: label, name: basenameVirtual(p), bytes: node.bytes, ...textOf(node.bytes) };
+        const cached = env.cache !== undefined && (tool !== undefined || pluginDigest !== undefined)
+            ? cacheKey({
+                code: tool ? { tool: { path: tool.path, size: tool.size, mtimeMs: tool.mtimeMs }, args } : { plugin: pluginDigest },
+                request: { dest: dest.path, options, input: { path: input.path, name: input.name, digest: sha256(input.bytes) }, data: undefined, item: undefined },
+            })
+            : undefined;
+        const span = reserve(env.profiler, `TRANSFORM ${op.plugin} ${dest.path}`, 'transform', { plugin: op.plugin, tool: tool !== undefined, dest: dest.path, input: label });
+        const job = {
+            index,
+            label,
+            origin: `${line} ${label}`,
+            rawDest: perFile,
+            dest,
+            input,
+            ...(cached !== undefined ? { cached } : {}),
+            ...(fileKey !== undefined ? { memoKey: fileKey } : {}),
+            span,
+            logs: [],
+            cache: cached !== undefined ? 'miss' : 'off',
+        };
+        if (cached !== undefined) {
+            const hit = await env.cache.get(cached);
+            if (hit) {
+                span.start();
+                span.end({ cache: 'hit' });
+                job.result = hit;
+                job.cache = 'hit';
+            }
+        }
+        jobs.push(job);
+    }
+    // The misses, a few at a time (a JavaScript plugin's one process takes one call at a time).
+    const misses = jobs.filter((j) => !j.result);
+    const limit = tool || env.plugins.isWasm(op.plugin) ? TRANSFORM_JOBS : 1;
+    const settled = await runBounded(misses.length, limit, async (i) => {
+        const job = misses[i];
+        job.span.start();
+        let result;
+        if (tool) {
+            env.stats.toolRuns++;
+            const call = { args: args, dest: job.dest.path, options, input: { name: job.input.name, bytes: job.input.bytes } };
+            result = await runTool(tool, call, env.toolPolicy, (l) => job.logs.push(l), op.span);
+        }
+        else {
+            result = await env.plugins.call(op.plugin, { apiVersion: 1, dest: job.dest.path, options, input: job.input }, op.span);
+        }
+        job.span.end({ cache: job.cache });
+        return result;
+    });
+    misses.forEach((job, i) => {
+        const r = settled[i];
+        if (r?.ok)
+            job.result = r.value;
+        else if (r)
+            job.error = { error: r.error };
+    });
+    // In path order: tool output, the first failure, cache writes and the files.
+    for (const job of jobs) {
+        // The tool's stderr, like a TRANSFORM cache hit, is not replayed by a memo hit.
+        for (const l of job.logs)
+            env.unrecorded(l);
+        if (job.error)
+            throw namingFile(job.error.error, job.label);
+        const result = job.result;
+        if (job.cache === 'miss' && store())
+            await env.cache.put(job.cached, result);
+        const files = [];
+        if (result.kind === 'file') {
+            if (job.dest.trailingSlash) {
+                throw new SitefileError('E_PLUGIN', `${job.label}: PLUGIN ${op.plugin} returned one file, but '${job.rawDest}' is a directory destination (use '${dirDest}*' or '${dirDest}*.ext' for one file per input)`, op.dest.span);
+            }
+            files.push([job.dest.path, makeFile(result.bytes, job.origin)]);
+        }
+        else {
+            for (const [rel, bytes] of result.files) {
+                const p = normalizeVirtual(`${job.dest.path === '/' ? '' : job.dest.path}/${rel}`, op.dest.span, `file '${rel}' returned by PLUGIN ${op.plugin}`).path;
+                if (rel.includes('..') || rel.startsWith('/')) {
+                    throw new SitefileError('E_PLUGIN', `${job.label}: PLUGIN ${op.plugin} returned an unsafe path '${rel}'`, op.span);
+                }
+                files.push([p, makeFile(bytes, job.origin)]);
+            }
+        }
+        if (job.memoKey !== undefined && store())
+            memo.set(job.memoKey, files);
+        done[job.index] = files;
+    }
+    // Two inputs may write the same path only with the same content.
+    const out = [];
+    const owner = new Map();
+    for (const files of done) {
+        for (const [p, node] of files ?? []) {
+            const prior = owner.get(p);
+            if (prior) {
+                if (prior.digest === node.digest)
+                    continue;
+                throw new SitefileError('E_CONFLICT', `'${p}' is written for two inputs with different content (${prior.origin} and ${node.origin}); rename one, or leave one out with --include/--exclude`, op.span);
+            }
+            owner.set(p, node);
+            out.push([p, node]);
+        }
+    }
+    return out;
+}
+/** REDIRECT and HEADER lines become `/_redirects` and `/_headers` at the root of the exported directory. */
+/**
+ * REDIRECT and HEADER lines become `/_redirects` and `/_headers` at the root of the exported directory.
+ * A HEADER pattern or REDIRECT target that is the URL of a file FINGERPRINT renamed in the exported stage
+ * names its new URL.
+ */
+function withSiteRules(tree, p, label, renames) {
+    const url = new Map();
+    for (const [from, to] of renames) {
+        const a = urlBelow(p.exportPath, from);
+        const b = urlBelow(p.exportPath, to);
+        if (a !== undefined && b !== undefined)
+            url.set(a, b);
+    }
+    const redirects = p.redirects.map((r) => ({ ...r, to: url.get(r.to) ?? r.to }));
+    const headers = p.headers.map((h) => ({ ...h, pattern: url.get(h.pattern) ?? h.pattern }));
+    const files = [
+        { name: '_redirects', text: redirectsFile(redirects), rules: redirects, kind: 'REDIRECT' },
+        { name: '_headers', text: headersFile(headers), rules: headers, kind: 'HEADER' },
+    ];
+    for (const f of files) {
+        const first = f.rules[0];
+        if (!first)
+            continue;
+        const policy = f.rules.some((r) => r.overwrite) ? 'overwrite' : 'error';
+        const node = makeFile(new TextEncoder().encode(f.text), `${label}:${first.span.line} ${f.kind}`);
+        tree = tree.withFiles([[joinVirtual(p.exportPath, f.name), node]], policy, first.span);
+    }
+    return tree;
+}
+/** The URL path of a tree path below the exported directory, or undefined outside it. */
+function urlBelow(dir, path) {
+    if (dir === '/')
+        return path;
+    return path.startsWith(dir + '/') ? path.slice(dir.length) : undefined;
+}
+function feedFiles(op, env) {
+    const origin = `${env.label}:${op.span.line} FEED`;
+    const list = valueOf(op.list, [], op.span, false, env);
+    if (!Array.isArray(list)) {
+        throw new SitefileError('E_TYPE', `FEED ${op.list}: '${op.list}' is not a list (import a directory AS markdown)`, op.span);
+    }
+    if (list.length === 0)
+        env.warn(`${origin}: '${op.list}' is empty, so the feed has no entries`);
+    const entries = [];
+    list.forEach((item, i) => {
+        if (item === null || typeof item !== 'object' || Array.isArray(item)) {
+            throw new SitefileError('E_TYPE', `FEED ${op.list}: element ${i + 1} is not a document (an object with title and date)`, op.span);
+        }
+        const doc = item;
+        const name = typeof doc['path'] === 'string' ? doc['path'] : `#${i + 1}`;
+        const text = (key) => {
+            const v = doc[key];
+            if (v === undefined || v === null)
+                return undefined;
+            if (typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean')
+                return String(v);
+            throw new SitefileError('E_TYPE', `FEED ${op.list}: '${key}' of document '${name}' is not text`, op.span);
+        };
+        const required = (key) => {
+            const v = text(key);
+            if (v === undefined)
+                throw new SitefileError('E_VALIDATION', `FEED ${op.list}: document '${name}' has no '${key}' (add it to its frontmatter)`, op.span);
+            return v;
+        };
+        const title = required('title');
+        const rawDate = required('date');
+        const date = parseFeedDate(rawDate);
+        if (!date) {
+            throw new SitefileError('E_VALIDATION', `FEED ${op.list}: document '${name}' has date '${rawDate}'; expected YYYY-MM-DD or an RFC 3339 date-time`, op.span);
+        }
+        const raw = interpolate(op.link, { ...env, loop: { name: FEED_ITEM, value: item } });
+        const link = normalizeVirtual(raw, op.link.span, 'FEED LINK');
+        const author = text('author');
+        const summary = text('excerpt');
+        const content = text('content');
+        entries.push({
+            title,
+            url: pageUrl(op.base, link.path === '/' || !link.trailingSlash ? link.path : link.path + '/'),
+            date,
+            ...(author !== undefined && author !== '' ? { author } : {}),
+            ...(summary !== undefined && summary !== '' ? { summary } : {}),
+            ...(content !== undefined ? { content } : {}),
+        });
+    });
+    const xml = atomXml({ title: op.title, siteUrl: op.base + '/', selfUrl: pageUrl(op.base, op.dest), entries });
+    return [[op.dest, makeFile(new TextEncoder().encode(xml), origin)]];
+}
+/**
+ * The files an operation (other than SITEMAP, FINGERPRINT and CHECKLINKS) adds; `opId` is its memo identity
+ * ('' without a memo), `treeKey` the key of the input tree (a RENDER with `${file …}` reads it).
+ */
+async function produce(op, tree, env, opId, treeKey) {
+    if (op.kind === 'TRANSFORM')
+        return produceTransform(op, env, opId);
+    // A feed reads its list and what its LINK names.
+    if (op.kind === 'FEED') {
+        const key = env.memo ? memoKey('feed', opId, namesKey(env, operandNames([op.link], new Set([op.list])))) : undefined;
+        return memoFiles(env, key, async () => feedFiles(op, env));
+    }
+    const origin = `${env.label}:${op.span.line} ${op.kind}`;
+    if (op.kind === 'COPY') {
+        const exclude = op.exclude ? IgnoreRules.fromPatterns(op.exclude) : undefined;
+        const src = await readSource(op.source, origin, env, exclude);
+        // --parents: the source's own path (inside the context, import or stage) is kept under the destination.
+        const kept = op.parents ? sourcePath(op.source) : '';
+        if (src.kind === 'file') {
+            if (exclude) {
+                throw new SitefileError('E_TYPE', `--exclude filters a directory, but '${src.label}' is a file`, op.source.span);
+            }
+            const intoDir = op.parents || op.destIsDir || tree.isDirectory(op.dest);
+            const key = env.memo ? memoKey('copy', opId, sourceKey(op.source, src, env), String(intoDir)) : undefined;
+            return memoFiles(env, key, async () => {
+                if (intoDir && src.inline) {
+                    throw new SitefileError('E_PATH', `'${op.dest}' is a directory; an inline ${src.label} body needs a file destination`, op.span);
+                }
+                const dest = intoDir ? joinVirtual(op.dest, kept || src.basename) : op.dest;
+                return [[dest, makeFile(src.bytes, origin, op.chmod ?? src.mode)]];
+            });
+        }
+        const key = env.memo ? memoKey('copy', opId, sourceKey(op.source, src, env), 'tree') : undefined;
+        return memoFiles(env, key, async () => {
+            if (src.tree.size === 0)
+                env.warn(exclude ? `${origin}: --exclude leaves no files of '${src.label}' to copy` : `${origin}: '${src.label}' contains no files`);
+            return src.tree.mountedAt(kept ? joinVirtual(op.dest, kept) : op.dest).map(([p, n]) => [p, { ...n, mode: op.chmod ?? n.mode, origin }]);
+        });
+    }
+    const src = await readSource(op.template, origin, env);
+    if (src.kind !== 'file') {
+        throw new SitefileError('E_TYPE', `RENDER template '${src.label}' is a directory, not a file`, op.template.span);
+    }
+    const text = decodeUtf8(src.bytes, `template '${src.label}'`, op.template.span);
+    const parts = src.inline
+        ? parseRenderTemplate(text, src.inline.file, src.inline.firstLine)
+        : parseRenderTemplate(text, src.label);
+    // A template with `${file …}` (itself or in a fragment) reads the tree, so the input tree is part of its key.
+    const deps = env.memo ? renderDeps(parts, env) : undefined;
+    const templateKey = env.memo ? memoKey('template', sourceKey(op.template, src, env), deps.files ? treeKey : '') : '';
+    // What the template names, the FOR list and the destination's variables (ARG/LET values are in opId).
+    const key = env.memo
+        ? memoKey('render', opId, templateKey, namesKey(env, op.each ? operandNames([op.each.dest], new Set(deps.names).add(op.each.list)) : deps.names))
+        : undefined;
+    const fileCtx = { tree: { get: (p) => tree.get(p)?.bytes, isDirectory: (p) => tree.isDirectory(p), renamed: (p) => env.renames?.get(p) }, inlineSvg: op.inlineSvg ?? false };
+    return memoFiles(env, key, async (children) => {
+        if (!op.each) {
+            const out = renderTemplate(parts, (name, p, span) => lookup(name, p, span, env), op.escape, (name, p, span, loose) => valueOf(name, p, span, loose, env), { ...templateContext(env), ...fileCtx });
+            return [[op.dest, makeFile(new TextEncoder().encode(out), origin)]];
+        }
+        // RENDER … FOR item IN list: one file per element, the destination interpolated per element.
+        const { as, list, dest } = op.each;
+        const items = valueOf(list, [], op.span, false, env);
+        if (!Array.isArray(items)) {
+            throw new SitefileError('E_TYPE', `FOR ${as} IN ${list}: '${list}' is not a list (import a directory AS markdown, or a JSON array)`, op.span);
+        }
+        // BY / PAGE: the loop runs over groups or pages instead of the elements.
+        const what = `FOR ${as} IN ${list}${op.each.by !== undefined ? ` BY ${op.each.by}` : ''}`;
+        const groups = op.each.by !== undefined ? groupBy(items, op.each.by, what, op.span) : undefined;
+        if (items.length === 0 && !(op.each.page && !groups))
+            env.warn(`${origin}: FOR ${as} IN ${list} renders nothing: '${list}' is empty`);
+        else if (groups?.length === 0)
+            env.warn(`${origin}: ${what} renders nothing: no element has '${op.each.by}'`);
+        const destOf = (item, op_) => {
+            let raw = '';
+            for (const part of op_.parts) {
+                if (part.kind === 'text')
+                    raw += part.value;
+                else
+                    raw += String(part.name === as ? resolveJsonPath(item, part.path, as, part.span) : lookup(part.name, part.path, part.span, env));
+            }
+            const target = normalizeVirtual(raw, op_.span, `RENDER destination for ${as}`);
+            if (target.trailingSlash) {
+                throw new SitefileError('E_PATH', `RENDER destination '${raw}' must be a file path, not a directory`, op_.span);
+            }
+            return target.path;
+        };
+        // Each element with its destination. Pages get `url`, `prev` and `next` once every page's destination is known.
+        const elements = [];
+        if (op.each.page) {
+            const { size, first } = op.each.page;
+            const runs = groups ? groups.map((g) => ({ key: g['key'], items: g['items'] })) : [{ items }];
+            for (const pages of paginate(runs, size)) {
+                const paths = pages.map((pg) => destOf(pg, pg['number'] === 1 && first ? first : dest));
+                const urls = paths.map((p) => pageUrl('', p));
+                pages.forEach((pg, i) => {
+                    elements.push({ item: { ...pg, url: urls[i], prev: urls[i - 1] ?? '', next: urls[i + 1] ?? '' }, path: paths[i] });
+                });
+            }
+        }
+        else {
+            for (const item of groups ?? items)
+                elements.push({ item, path: destOf(item, dest) });
+        }
+        // Incremental rebuilds: an element's page depends on the template, the element and the imports the
+        // template names (other than the loop variable), so editing one document re-renders one page.
+        const memo = env.memo;
+        const refsKey = memo ? namesKey(env, deps.names, as) : '';
+        const files = [];
+        for (const { item, path: targetPath } of elements) {
+            const itemEnv = { ...env, loop: { name: as, value: item } };
+            const target = { path: targetPath };
+            const page = () => {
+                const out = renderTemplate(parts, (name, p, span) => lookup(name, p, span, itemEnv), op.escape, (name, p, span, loose) => valueOf(name, p, span, loose, itemEnv), { ...templateContext(itemEnv), ...fileCtx });
+                return makeFile(new TextEncoder().encode(out), origin);
+            };
+            files.push([target.path, memo ? memo.memoize(memoKey('item', opId, templateKey, refsKey, valueKey(item)), page, children) : page()]);
+        }
+        return files;
+    });
+}
+/** `IMPORT … DRAFTS false`: leave out the elements whose `draft` is `true` (or the text `true`, as in a CSV cell). */
+function withoutDrafts(spec, res) {
+    if (spec.drafts === undefined || res.kind !== 'value')
+        return res;
+    if (!Array.isArray(res.value)) {
+        throw new SitefileError('E_TYPE', `IMPORT ${spec.name}: DRAFTS needs a list (a directory of documents, a CSV file or a JSON/YAML array), not a single value`, spec.span);
+    }
+    if (spec.drafts)
+        return res;
+    const isDraft = (d) => d !== null && typeof d === 'object' && !Array.isArray(d) && (d['draft'] === true || d['draft'] === 'true');
+    return { ...res, value: res.value.filter((d) => !isDraft(d)) };
+}
+/** `IMPORT … SCHEMA <path>`: read and compile the schema file, then check the import's documents. */
+async function checkImportSchema(spec, res, local) {
+    const schema = spec.schema;
+    const what = `IMPORT ${spec.name}`;
+    if (res.kind !== 'value') {
+        throw new SitefileError('E_TYPE', `${what}: SCHEMA checks documents, but the import is a ${res.kind}`, spec.span);
+    }
+    const file = await local.readFile(schema.path, schema.span);
+    const text = decodeUtf8(file.bytes, `schema '${schema.uri}'`, schema.span);
+    let value;
+    if (/\.json$/i.test(schema.path)) {
+        try {
+            value = JSON.parse(text);
+        }
+        catch (e) {
+            throw new SitefileError('E_SCHEMA', `${what}: schema '${schema.uri}' is not valid JSON: ${e.message}`, schema.span, { cause: e });
+        }
+    }
+    else
+        value = parseYaml(text, schema.uri);
+    checkSchema(res.value, compileSchema(value, schema.uri, what, schema.span), what, res.format === 'csv', spec.span);
+}
+/** Apply an import's SORT BY to a markdown collection. */
+function sorted(spec, res) {
+    if (!spec.sort || res.kind !== 'value')
+        return res;
+    if (!Array.isArray(res.value)) {
+        throw new SitefileError('E_TYPE', `IMPORT ${spec.name}: SORT BY needs a list (a directory of documents, a CSV file or a JSON/YAML array), not a single value`, spec.span);
+    }
+    if (!res.value.every((d) => d !== null && typeof d === 'object' && !Array.isArray(d))) {
+        throw new SitefileError('E_TYPE', `IMPORT ${spec.name}: SORT BY needs a list of objects with a '${spec.sort.key}' field`, spec.span);
+    }
+    return { ...res, value: sortDocuments(res.value, spec.sort.key, spec.sort.descending) };
+}
+/** The path `--parents` keeps: context-relative for a local source, inside the import or stage otherwise ('' for a root). */
+function sourcePath(ref) {
+    if (ref.kind === 'local')
+        return ref.path;
+    if (ref.kind === 'inline')
+        return '';
+    return ref.path.replace(/^\/+/, '');
+}
+/** A directory source without the files `exclude` (COPY --exclude) matches, relative to its root. */
+function excluding(tree, exclude) {
+    if (!exclude)
+        return tree;
+    return Tree.fromFiles(tree.entries().filter(([p]) => !exclude.excludes(p.slice(1))));
+}
+async function readSource(ref, origin, env, exclude) {
+    if (ref.kind === 'inline') {
+        const bytes = new TextEncoder().encode(ref.text);
+        const inline = { file: env.label, firstLine: ref.bodyLine };
+        return { kind: 'file', bytes, mode: 0o644, basename: '', label: `<<${ref.delimiter}`, inline };
+    }
+    if (ref.kind === 'local') {
+        const label = './' + ref.path;
+        if ((await env.local.stat(ref.path, ref.span)) === 'directory') {
+            const t = await env.local.readTree(ref.path, origin, ref.span, exclude);
+            return { kind: 'tree', tree: t.tree, label, digest: t.provenance.digest };
+        }
+        const f = await env.local.readFile(ref.path, ref.span);
+        return { kind: 'file', bytes: f.bytes, mode: f.mode, basename: f.basename, label, digest: `${f.provenance.digest}\0${f.mode}\0${f.basename}` };
+    }
+    if (ref.kind === 'stage') {
+        const tree = env.stages.get(ref.name) ?? fail(ref.name, ref.span);
+        const label = `--from=${ref.name} ${ref.path}`;
+        const node = tree.get(ref.path);
+        if (node)
+            return { kind: 'file', bytes: node.bytes, mode: node.mode, basename: basenameVirtual(ref.path), label };
+        if (tree.isDirectory(ref.path))
+            return { kind: 'tree', tree: excluding(tree.subtree(ref.path), exclude), label };
+        throw new SitefileError('E_NOT_FOUND', `'${ref.path}' does not exist in stage '${ref.name}'`, ref.span);
+    }
+    const label = ref.path === '/' ? `${ref.name}:` : `${ref.name}:${ref.path}`;
+    const res = env.resources.get(ref.name);
+    if (!res)
+        throw new SitefileError('E_UNDEFINED', `unknown import '${ref.name}'`, ref.span);
+    switch (res.kind) {
+        case 'value':
+            throw new SitefileError('E_TYPE', `import '${ref.name}' is a ${res.format} value: RENDER templates can read it, but it cannot be copied (import it AS file to copy it)`, ref.span);
+        case 'file':
+            if (ref.path !== '/')
+                throw new SitefileError('E_PATH', `import '${ref.name}' is a single file; use '${ref.name}:'`, ref.span);
+            return { kind: 'file', bytes: res.bytes, mode: res.mode, basename: res.basename, label };
+        case 'tree': {
+            const node = res.tree.get(ref.path);
+            if (node)
+                return { kind: 'file', bytes: node.bytes, mode: node.mode, basename: basenameVirtual(ref.path), label };
+            if (res.tree.isDirectory(ref.path))
+                return { kind: 'tree', tree: excluding(res.tree.subtree(ref.path), exclude), label };
+            throw new SitefileError('E_NOT_FOUND', `'${ref.path}' does not exist in import '${ref.name}'`, ref.span);
+        }
+    }
+}
+function lookup(name, p, span, env) {
+    if (env.loop && env.loop.name === name)
+        return resolveJsonPath(env.loop.value, p, name, span);
+    const v = env.vars.get(name);
+    if (v !== undefined) {
+        if (p.length)
+            throw new SitefileError('E_TYPE', `'${name}' is an ARG/LET value; dotted access only works on JSON imports`, span);
+        return v;
+    }
+    const res = env.resources.get(name);
+    if (!res)
+        throw new SitefileError('E_UNDEFINED', `'${name}' is not an ARG, LET or IMPORT`, span);
+    if (res.kind !== 'value') {
+        throw new SitefileError('E_TYPE', `import '${name}' is a ${res.kind}; templates can only read value imports (text, json, yaml, csv, markdown, wbn)`, span);
+    }
+    if (res.format === 'html')
+        throw fragmentNotValue(name, span);
+    if (res.format !== 'text')
+        return resolveJsonPath(res.value, p, name, span);
+    if (p.length)
+        throw new SitefileError('E_TYPE', `import '${name}' is text; dotted access only works on structured imports (json, yaml, csv, markdown, wbn)`, span);
+    return res.value;
+}
+/** Any value (lists, documents, scalars) for template blocks and FOR. `loose`: missing → undefined. */
+function valueOf(name, p, span, loose, env) {
+    if (env.loop && env.loop.name === name)
+        return walk(env.loop.value, p, name, span, loose);
+    const v = env.vars.get(name);
+    if (v !== undefined)
+        return walk(v, p, name, span, loose);
+    const res = env.resources.get(name);
+    if (!res) {
+        if (loose)
+            return undefined;
+        throw new SitefileError('E_UNDEFINED', `'${name}' is not an ARG, LET or IMPORT`, span);
+    }
+    if (res.kind !== 'value') {
+        throw new SitefileError('E_TYPE', `import '${name}' is a ${res.kind}; templates can only read value imports (text, json, yaml, csv, markdown, wbn)`, span);
+    }
+    return walk(res.value, p, name, span, loose);
+}
+// ---------------------------------------------------------------- helpers
+async function mapLimit(items, limit, fn) {
+    const out = new Array(items.length);
+    let next = 0;
+    const worker = async () => {
+        while (next < items.length) {
+            const i = next++;
+            out[i] = await fn(items[i], i);
+        }
+    };
+    await Promise.all(Array.from({ length: Math.max(1, Math.min(limit, items.length)) }, worker));
+    return out;
+}
+/** realpath of the nearest existing ancestor, with the missing tail re-joined. */
+async function realpathLoose(p) {
+    const tail = [];
+    let cur = p;
+    for (;;) {
+        try {
+            return path.join(await realpath(cur), ...tail.reverse());
+        }
+        catch {
+            const parent = path.dirname(cur);
+            if (parent === cur)
+                return p;
+            tail.push(path.basename(cur));
+            cur = parent;
+        }
+    }
+}
+//# sourceMappingURL=executor.js.map