@johnhenry/sitefile 0.0.0 → 0.0.1

package/lib/src/cli/vendor.js

@@ -1,3 +1,4 @@
+import { NETWORK_OPTIONS, networkHelp, networkOption } from './network.js';
 import path from 'node:path';
 import { insecureRegistriesFromEnv } from '../base-image.js';
 import { collectBuildArgs } from '../build-args.js';
@@ -31,11 +32,13 @@ const vendorCommand = {
         '--allow-private-network       permit loopback/private network addresses',
         `--max-download-bytes <n>      per-resource size limit (default ${DEFAULT_FETCH_POLICY.maxBytes})`,
         `--timeout <ms>                per-resource fetch timeout (default ${DEFAULT_FETCH_POLICY.timeoutMs})`,
+        ...networkHelp(30),
         '--base <image>                vendor this BASE image (overrides EXPORT ... AS oci BASE)',
         '--platform <os/arch>          BASE platform to vendor (default linux/amd64)',
         '--insecure-registry <h>       allow plain http to registry host[:port] (repeatable)',
     ],
     options: {
+        ...NETWORK_OPTIONS,
         file: { type: 'string', short: 'f' },
         'vendor-dir': { type: 'string' },
         'build-arg': { type: 'string', multiple: true },
@@ -58,6 +61,7 @@ const vendorCommand = {
         const context = pos[0] ?? '.';
         const maxBytes = positive(str(v['max-download-bytes']), '--max-download-bytes');
         const timeoutMs = positive(str(v.timeout), '--timeout');
+        const network = networkOption(v);
         const file = str(v.file);
         const vendorDir = str(v['vendor-dir']);
         const base = str(v.base);
@@ -72,6 +76,7 @@ const vendorCommand = {
                 allowPrivateNetwork: !!v['allow-private-network'],
                 ...(maxBytes ? { maxBytes } : {}),
                 ...(timeoutMs ? { timeoutMs } : {}),
+                ...(network ? { network } : {}),
             },
             ...(vendorDir !== undefined ? { vendorDir } : {}),
             ...(base !== undefined ? { baseImage: base } : {}),

package/lib/src/cli.js

@@ -2,9 +2,9 @@
 import { parseArgs } from 'node:util';
 import path from 'node:path';
 import { SitefileError, isSitefileError } from './errors.js';
-import { build, buildToDirectory, checkPlanPins, lintBuild, planBuild } from './executor.js';
+import { build, buildToDirectory, checkPlanPins, lintBuild, planBuild, sitefileCompression } from './executor.js';
 import { LINT_RULES } from './lint.js';
-import { defaultOutName, formatFromExtension } from './export-formats.js';
+import { compressionFromExtension, defaultOutName, formatFromExtension } from './export-formats.js';
 import { collectBuildArgs } from './build-args.js';
 import { insecureRegistriesFromEnv, makeClient } from './base-image.js';
 import { cacheLimitFromEnv } from './cache-limit.js';
@@ -24,6 +24,7 @@ import { promises as fs } from 'node:fs';
 import { graphDot, graphText, planGraph, why, whyText } from './explain.js';
 import { isGitContext, materializeGitContext } from './cli/git-context.js';
 import { loadSecrets } from './secrets.js';
+import { NETWORK_OPTIONS, networkHelp, networkOption } from './cli/network.js';
 const VERSION = SITEFILE_VERSION;
 const HELP = `sitefile ${VERSION} — Docker-inspired static artifact builder
 
@@ -43,16 +44,19 @@ Options:
       --target <stage>         stop after the named stage and export its whole tree instead of
                                the EXPORT path (EXPORT's format still applies; no _redirects/_headers)
   -o, --out <path>             export destination (build only): a directory for 'directory',
-                               a file for zip, tar, tgz, wbn
+                               a file for zip, tar, tgz, wbn (*.wbn.gz: a gzipped bundle)
   -t, --tag <name[:tag]>       also store the build as a local image (build only, repeatable);
                                with -t and no -o nothing is written to the context
       --format <fmt>           directory | zip | tar | tgz (alias tar.gz) | wbn | oci (build only).
                                oci writes an OCI archive for -o *.tar (e.g. site.oci.tar), else an
                                OCI image layout directory.
-                               Default: the --out extension (.zip .tar .tar.gz .tgz .wbn .oci.tar),
+                               Default: the --out extension (.zip .tar .tar.gz .tgz .wbn .wbn.gz .oci.tar),
                                else the Sitefile's EXPORT ... AS <fmt>
       --oci-root <path>        directory inside an oci image layer (default /srv/www; overrides EXPORT ... AT)
-      --oci-compression <c>    oci site layer: gzip (default) or none (plain tar; overrides EXPORT ... COMPRESSION)
+      --compression <c>        gzip or none (build only; overrides EXPORT ... COMPRESSION): the oci site layer
+                               (default gzip; none: plain tar), or the whole wbn (default none; gzip:
+                               gzip(application/webbundle), also chosen by -o *.wbn.gz)
+      --oci-compression <c>    the same as --compression, for oci only
       --label <key=value>      add an OCI image config label (repeatable)
       --git-labels             add org.opencontainers.image.source/revision from the git checkout
                                (off by default: they change the image ID on every commit)
@@ -98,6 +102,7 @@ Options:
       --allow-hardlinks        permit hard-linked files in the context (you assert they are safe)
       --max-download-bytes <n> per-resource size limit (default ${DEFAULT_FETCH_POLICY.maxBytes})
       --timeout <ms>           per-resource fetch timeout (default ${DEFAULT_FETCH_POLICY.timeoutMs})
+${networkHelp(25).map((l) => `      ${l}`).join('\n')}
       --json                   machine-readable output (validate, inspect, graph, why)
       --dot                    Graphviz DOT output (graph only)
       --watch                  build, then rebuild when the context, the Sitefile or a
@@ -121,6 +126,7 @@ export async function main(argv, run = {}) {
             args: [...argv],
             allowPositionals: true,
             options: {
+                ...NETWORK_OPTIONS,
                 file: { type: 'string', short: 'f' },
                 target: { type: 'string' },
                 out: { type: 'string', short: 'o' },
@@ -129,6 +135,7 @@ export async function main(argv, run = {}) {
                 'base-url': { type: 'string' },
                 'oci-root': { type: 'string' },
                 'oci-compression': { type: 'string' },
+                compression: { type: 'string' },
                 label: { type: 'string', multiple: true },
                 'git-labels': { type: 'boolean' },
                 provenance: { type: 'boolean' },
@@ -255,11 +262,13 @@ export async function main(argv, run = {}) {
     let failed = false;
     let fetched;
     try {
+        const network = networkOption(o);
         const fetchPolicy = {
             allowHttp: !!o['allow-http'],
             allowPrivateNetwork: !!o['allow-private-network'],
             ...(o['max-download-bytes'] ? { maxBytes: positiveInt(o['max-download-bytes'], '--max-download-bytes') } : {}),
             ...(o.timeout ? { timeoutMs: positiveInt(o.timeout, '--timeout') } : {}),
+            ...(network ? { network } : {}),
         };
         if (gitContext) {
             // A Git URL context: fetched into a temporary directory, built from there, then removed.
@@ -272,7 +281,7 @@ export async function main(argv, run = {}) {
             ? new RegistryCache({
                 from: cacheFrom.map((r) => parseCacheRef('--cache-from', r)),
                 to: cacheTo[0] !== undefined ? parseCacheRef('--cache-to', cacheTo[0]) : undefined,
-                client: (registry) => makeClient(registry, { insecureRegistries: insecureRegistriesFromEnv(o['insecure-registry'] ?? []), allowPrivateNetwork: !!o['allow-private-network'] }),
+                client: (registry) => makeClient(registry, { insecureRegistries: insecureRegistriesFromEnv(o['insecure-registry'] ?? []), allowPrivateNetwork: !!o['allow-private-network'], network }),
                 limit: cacheLimitFromEnv(),
                 warn: (m) => process.stderr.write(`warning: ${m}\n`),
                 notice: (m) => process.stderr.write(`${m}\n`),
@@ -293,14 +302,26 @@ export async function main(argv, run = {}) {
             if (!ociCompression)
                 return usageError(`--oci-compression expects gzip or none, got '${o['oci-compression']}'`);
         }
+        let compression;
+        if (o.compression !== undefined) {
+            compression = parseOciCompression(o.compression);
+            if (!compression)
+                return usageError(`--compression expects gzip or none, got '${o.compression}'`);
+            if (ociCompression !== undefined)
+                return usageError('--compression and --oci-compression set the same thing; give one');
+        }
         // No --format: an archive extension on --out picks the format, so `-o site.zip`
         // writes a zip instead of a directory named site.zip.
         if (!formatOverride && o.out)
             formatOverride = formatFromExtension(o.out);
         // The default destination depends on the format, which the Sitefile may set.
-        const sitefileFormat = command === 'build' && !o.out && !formatOverride ? (await planBuild({ contextDir: context, ...(file ? { sitefile: file } : {}), buildArgs })).exportFormat : undefined;
+        // (A wbn's default name also depends on its COMPRESSION: dist.wbn or dist.wbn.gz.)
+        const sitefilePlan = command === 'build' && !o.out && (!formatOverride || formatOverride === 'wbn') ? await planBuild({ contextDir: context, ...(file ? { sitefile: file } : {}), buildArgs }) : undefined;
+        const sitefileFormat = formatOverride ? undefined : sitefilePlan?.exportFormat;
+        const defaultFormat = formatOverride ?? sitefileFormat ?? 'directory';
+        const defaultCompression = defaultFormat === 'wbn' ? (compression ?? (sitefilePlan ? sitefileCompression(sitefilePlan, 'wbn') : undefined)) : undefined;
         // A Git context's default destination is in the current directory, not the temporary checkout.
-        const out = o.out ?? path.join(fetched ? '.' : context, defaultOutName(formatOverride ?? sitefileFormat ?? 'directory'));
+        const out = o.out ?? path.join(fetched ? '.' : context, defaultOutName(defaultFormat, defaultCompression));
         run.wrote?.push(out);
         const options = {
             contextDir: context,
@@ -335,6 +356,20 @@ export async function main(argv, run = {}) {
             ...(profiler ? { profiler, alsoWrites: [o.profile] } : {}),
             ...(run.memo ? { memo: run.memo } : {}),
         };
+        // --compression belongs to the export's own format, oci or wbn (-t without -o stores an oci image);
+        // a *.wbn.gz destination means a gzipped bundle.
+        let wbnCompression;
+        if (command === 'build' && compression !== undefined) {
+            const fmt = (o.tag ?? []).length && !o.out ? 'oci' : (formatOverride ?? sitefileFormat ?? (await planBuild(options)).exportFormat);
+            if (fmt === 'oci')
+                ociCompression = compression;
+            else if (fmt === 'wbn')
+                wbnCompression = compression;
+            else
+                return usageError(`--compression applies only to oci and wbn exports, not ${fmt}`);
+        }
+        if (formatOverride === 'wbn' && o.out)
+            wbnCompression ??= compressionFromExtension(o.out, 'wbn');
         switch (command) {
             case 'build': {
                 const tags = o.tag ?? [];
@@ -369,6 +404,7 @@ export async function main(argv, run = {}) {
                     ...(o['base-url'] !== undefined ? { baseUrl: o['base-url'] } : {}),
                     ...(o['oci-root'] !== undefined ? { ociRoot: o['oci-root'] } : {}),
                     ...(ociCompression !== undefined ? { ociCompression } : {}),
+                    ...(wbnCompression !== undefined ? { wbnCompression } : {}),
                     ...(o.platform !== undefined ? { platform: o.platform } : {}),
                     imageLabels: labels,
                     gitLabels: !!o['git-labels'],

package/lib/src/errors.d.ts

@@ -10,7 +10,7 @@ export interface SourceSpan {
  */
 export type ErrorCode = 'E_SYNTAX' | 'E_UNKNOWN_INSTRUCTION' | 'E_UNSUPPORTED' | 'E_VALIDATION' | 'E_UNDEFINED' | 'E_DUPLICATE' | 'E_MISSING_ARG' | 'E_TYPE' | 'E_PATH' | 'E_PATH_ESCAPE' | 'E_NOT_FOUND' | 'E_UNSUPPORTED_FILE' | 'E_HARDLINK'
 /** Two paths equal under Unicode simple case folding, or two context names equal after NFC. */
- | 'E_PATH_COLLISION' | 'E_CONFLICT' | 'E_PROTOCOL' | 'E_SSRF_BLOCKED' | 'E_FETCH' | 'E_FETCH_STATUS' | 'E_FETCH_TIMEOUT' | 'E_TOO_LARGE' | 'E_REDIRECT' | 'E_INTEGRITY' | 'E_LOCK_MISMATCH' | 'E_LOCK_MISSING'
+ | 'E_PATH_COLLISION' | 'E_CONFLICT' | 'E_PROTOCOL' | 'E_SSRF_BLOCKED' | 'E_HOST_BLOCKED' | 'E_FETCH' | 'E_FETCH_STATUS' | 'E_FETCH_TIMEOUT' | 'E_TOO_LARGE' | 'E_REDIRECT' | 'E_INTEGRITY' | 'E_LOCK_MISMATCH' | 'E_LOCK_MISSING'
 /** A remote input (IMPORT URL or BASE image) has no pin, under --strict-pins. */
  | 'E_UNPINNED'
 /** A malformed or unsupported Git smart HTTP response or packfile (git+https IMPORT, Git URL contexts). */
@@ -22,13 +22,35 @@ export type ErrorCode = 'E_SYNTAX' | 'E_UNKNOWN_INSTRUCTION' | 'E_UNSUPPORTED' |
 /** CHECKLINKS found references to files that do not exist (or, with --external, URLs that do not answer). */
  | 'E_BROKEN_LINK' | 'E_EXPORT' | 'E_EXPORT_UNSAFE' | 'E_STORE' | 'E_SERVER' | 'E_REGISTRY' | 'E_AUTH'
 /** One or more `sitefile bake` targets failed. */
- | 'E_BAKE' | 'E_USAGE';
+ | 'E_BAKE' | 'E_USAGE'
+/** The build was stopped by its embedder (the Rust library's `CancelToken`; see docs/RUST.md). */
+ | 'E_CANCELLED';
+/**
+ * The permission a build needs: carried by the `E_UNSUPPORTED` error of a JavaScript PLUGIN
+ * (`--allow-plugin <name>`) or a TOOL (`--allow-exec <name>`) that was not allowed, so callers
+ * need not parse the message.
+ */
+export interface Needs {
+    readonly kind: 'plugin' | 'tool';
+    /** The declared PLUGIN or TOOL name. */
+    readonly name: string;
+    /** The flag that grants it. */
+    readonly flag: '--allow-plugin' | '--allow-exec';
+}
+export declare function needsPlugin(name: string): Needs;
+export declare function needsTool(name: string): Needs;
+export interface SitefileErrorOptions extends ErrorOptions {
+    /** What must be allowed (permission errors only). */
+    readonly needs?: Needs;
+}
 export declare class SitefileError extends Error {
     readonly code: ErrorCode;
     readonly span: SourceSpan | undefined;
     /** The message without the location prefix. */
     readonly detail: string;
-    constructor(code: ErrorCode, detail: string, span?: SourceSpan, options?: ErrorOptions);
+    /** For a permission error (`E_UNSUPPORTED` at a PLUGIN or TOOL line): what must be allowed. Not part of the message. */
+    readonly needs: Needs | undefined;
+    constructor(code: ErrorCode, detail: string, span?: SourceSpan, options?: SitefileErrorOptions);
 }
 export declare function formatSpan(span: SourceSpan): string;
 export declare function isSitefileError(e: unknown, code?: ErrorCode): e is SitefileError;

package/lib/src/errors.js

@@ -1,14 +1,23 @@
+export function needsPlugin(name) {
+    return { kind: 'plugin', name, flag: '--allow-plugin' };
+}
+export function needsTool(name) {
+    return { kind: 'tool', name, flag: '--allow-exec' };
+}
 export class SitefileError extends Error {
     code;
     span;
     /** The message without the location prefix. */
     detail;
+    /** For a permission error (`E_UNSUPPORTED` at a PLUGIN or TOOL line): what must be allowed. Not part of the message. */
+    needs;
     constructor(code, detail, span, options) {
         super(span ? `${formatSpan(span)}: ${detail}` : detail, options);
         this.name = 'SitefileError';
         this.code = code;
         this.span = span;
         this.detail = detail;
+        this.needs = options?.needs;
     }
 }
 export function formatSpan(span) {

package/lib/src/executor.d.ts

@@ -198,6 +198,8 @@ export interface ExportTarget {
     readonly ociRoot?: string;
     /** oci: site layer encoding (overrides EXPORT ... COMPRESSION; default gzip). */
     readonly ociCompression?: OciCompression;
+    /** wbn: `gzip` wraps the bundle in gzip (overrides EXPORT ... COMPRESSION; default none). */
+    readonly wbnCompression?: OciCompression;
     /** Extra OCI config labels. */
     readonly imageLabels?: Readonly<Record<string, string>>;
     /** Add org.opencontainers.image.source/revision from the git checkout (opt-in). */
@@ -231,6 +233,11 @@ export declare function buildToDirectory(options: BuildOptions & ExportTarget &
     readonly outDir: string;
     readonly force?: boolean;
 }): Promise<ExportedBuild>;
+/**
+ * The Sitefile's `EXPORT ... COMPRESSION` for an export in `format`: it belongs to the EXPORT's own format,
+ * so a `--format` override to another format does not inherit it (undefined: that format's default).
+ */
+export declare function sitefileCompression(plan: Pick<Plan, 'exportFormat' | 'exportCompression'>, format: ExportFormat): OciCompression | undefined;
 /**
  * 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.

package/lib/src/executor.js

@@ -2,7 +2,7 @@ import { chmod, mkdir, mkdtemp, readdir, readFile, realpath, rm, writeFile } fro
 import { statSync } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { SitefileError } from './errors.js';
+import { needsPlugin, needsTool, SitefileError } from './errors.js';
 import { sha256 } from './digest.js';
 import { FEED_ITEM } from './language/ast.js';
 import { fragmentText, parseProgram } from './language/validate.js';
@@ -237,7 +237,7 @@ async function buildWith(options, tempDirs) {
             vendor,
             registry: {
                 ...options.registry,
-                allowPrivateNetwork: options.registry?.allowPrivateNetwork ?? policy.allowPrivateNetwork,
+                allowPrivateNetwork: options.registry?.allowPrivateNetwork ?? policy.allowPrivateNetwork, network: options.registry?.network ?? policy.network,
             },
             warn,
             span: b.span,
@@ -388,7 +388,7 @@ async function buildWith(options, tempDirs) {
             vendor,
             registry: {
                 ...options.registry,
-                allowPrivateNetwork: options.registry?.allowPrivateNetwork ?? policy.allowPrivateNetwork,
+                allowPrivateNetwork: options.registry?.allowPrivateNetwork ?? policy.allowPrivateNetwork, network: options.registry?.network ?? policy.network,
             },
             warn,
         })
@@ -492,7 +492,7 @@ async function exportBuild(result, format, options) {
     if (format === 'oci') {
         const img = buildOciImage(result.output, {
             root: options.ociRoot ?? result.plan.exportRoot,
-            compression: options.ociCompression ?? result.plan.exportCompression,
+            compression: options.ociCompression ?? sitefileCompression(result.plan, 'oci'),
             platform: options.platform,
             epoch: sourceDateEpoch(),
             base: result.base,
@@ -517,10 +517,18 @@ async function exportBuild(result, format, options) {
     const data = encodeTree(result.output, format, {
         epoch: sourceDateEpoch(),
         baseUrl: options.baseUrl ?? result.plan.exportBase,
+        ...(format === 'wbn' ? { compression: options.wbnCompression ?? sitefileCompression(result.plan, 'wbn') } : {}),
     });
     const written = await exportFile(data, options.outDir, exportOptions);
     return { ...result, format, outDir: written.outFile, bytes: written.bytes, fileDigest: sha256(data) };
 }
+/**
+ * The Sitefile's `EXPORT ... COMPRESSION` for an export in `format`: it belongs to the EXPORT's own format,
+ * so a `--format` override to another format does not inherit it (undefined: that format's default).
+ */
+export function sitefileCompression(plan, format) {
+    return plan.exportFormat === format ? plan.exportCompression : undefined;
+}
 /**
  * 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.
@@ -1377,7 +1385,7 @@ function checkPlugins(p, options, warn) {
     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);
+        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, { needs: needsPlugin(spec.name) });
     };
     for (const spec of p.plugins)
         if (!spec.path.endsWith('.wasm'))
@@ -1401,7 +1409,7 @@ async function resolveTools(p, options, warn) {
     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);
+            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, { needs: needsTool(t.name) });
         }
         const tool = await resolveTool(t.name, allowed.get(t.name), process.env['PATH'], t.span);
         options.onNotice?.(`tool ${t.name} -> ${tool.path}`);
@@ -1547,7 +1555,7 @@ async function produceTransform(op, env, opId) {
                 })
                 : 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;
+            let result = cached ? await env.cache.get(cached, op.plugin) : undefined;
             const cacheState = !cached ? 'off' : result ? 'hit' : 'miss';
             if (!result) {
                 if (tool) {
@@ -1560,7 +1568,7 @@ async function produceTransform(op, env, opId) {
                     result = await env.plugins.call(op.plugin, request, op.span);
                 }
                 if (cached && (tool || env.plugins.cacheable(op.plugin)))
-                    await env.cache.put(cached, result);
+                    await env.cache.put(cached, result, op.plugin);
             }
             call.end({ cache: cacheState });
             if (result.kind === 'file') {
@@ -1722,7 +1730,7 @@ async function transformFiles(op, env, dir, ctx) {
             cache: cached !== undefined ? 'miss' : 'off',
         };
         if (cached !== undefined) {
-            const hit = await env.cache.get(cached);
+            const hit = await env.cache.get(cached, op.plugin);
             if (hit) {
                 span.start();
                 span.end({ cache: 'hit' });
@@ -1766,7 +1774,7 @@ async function transformFiles(op, env, dir, ctx) {
             throw namingFile(job.error.error, job.label);
         const result = job.result;
         if (job.cache === 'miss' && store())
-            await env.cache.put(job.cached, result);
+            await env.cache.put(job.cached, result, op.plugin);
         const files = [];
         if (result.kind === 'file') {
             if (job.dest.trailingSlash) {

package/lib/src/export-formats.d.ts

@@ -1,16 +1,23 @@
 import { type WriterOptions } from './archive-writers.js';
-import type { ExportFormat } from './language/ast.js';
+import type { ExportFormat, OciCompression } from './language/ast.js';
 import type { Tree } from './tree.js';
 export type ArchiveFormat = Exclude<ExportFormat, 'directory' | 'oci'>;
 /** Single-file formats encoded by {@link encodeTree}. `oci` is handled separately (layout directory or OCI archive). */
 export declare function isArchiveFormat(f: ExportFormat): f is ArchiveFormat;
-/** Default output path relative to the context: `dist`, `dist.zip`, `dist.tar`, `dist.tar.gz`, `dist.wbn`. */
-export declare function defaultOutName(format: ExportFormat): string;
+/**
+ * Default output path relative to the context: `dist`, `dist.zip`, `dist.tar`, `dist.tar.gz`, `dist.wbn`
+ * (`dist.wbn.gz` for a gzipped bundle), `dist.oci.tar`.
+ */
+export declare function defaultOutName(format: ExportFormat, compression?: OciCompression): string;
 export interface EncodeOptions extends WriterOptions {
     /** Required for `wbn`: absolute https URL ending in `/`. */
     readonly baseUrl?: string | undefined;
+    /** `wbn`: `gzip` wraps the finished bundle in gzip (the shared deterministic encoder); default none. */
+    readonly compression?: OciCompression | undefined;
 }
 /** Serialize a tree in an archive format. Deterministic: see archive-writers.ts and wbn.ts. */
 export declare function encodeTree(tree: Tree, format: ArchiveFormat, options?: EncodeOptions): Uint8Array;
 /** The export format implied by an output file name, if it has an archive extension. */
 export declare function formatFromExtension(out: string): ExportFormat | undefined;
+/** The compression implied by an output file name for `format`: `gzip` for a wbn written to `*.wbn.gz`. */
+export declare function compressionFromExtension(out: string, format: ExportFormat): OciCompression | undefined;

package/lib/src/export-formats.js

@@ -1,11 +1,15 @@
 import { writeTar, writeTgz, writeZip } from './archive-writers.js';
+import { gzip } from './deflate.js';
 import { writeWebBundle } from './wbn.js';
 /** Single-file formats encoded by {@link encodeTree}. `oci` is handled separately (layout directory or OCI archive). */
 export function isArchiveFormat(f) {
     return f !== 'directory' && f !== 'oci';
 }
-/** Default output path relative to the context: `dist`, `dist.zip`, `dist.tar`, `dist.tar.gz`, `dist.wbn`. */
-export function defaultOutName(format) {
+/**
+ * Default output path relative to the context: `dist`, `dist.zip`, `dist.tar`, `dist.tar.gz`, `dist.wbn`
+ * (`dist.wbn.gz` for a gzipped bundle), `dist.oci.tar`.
+ */
+export function defaultOutName(format, compression) {
     switch (format) {
         case 'directory':
             return 'dist';
@@ -16,7 +20,7 @@ export function defaultOutName(format) {
         case 'tgz':
             return 'dist.tar.gz';
         case 'wbn':
-            return 'dist.wbn';
+            return compression === 'gzip' ? 'dist.wbn.gz' : 'dist.wbn';
         case 'oci':
             return 'dist.oci.tar';
     }
@@ -30,8 +34,11 @@ export function encodeTree(tree, format, options = {}) {
             return writeTar(tree, options);
         case 'tgz':
             return writeTgz(tree, options);
-        case 'wbn':
-            return writeWebBundle(tree, options.baseUrl);
+        case 'wbn': {
+            // The bundle is written first, unchanged; gzip only wraps its bytes (header mtime 0, see deflate.ts).
+            const bundle = writeWebBundle(tree, options.baseUrl);
+            return options.compression === 'gzip' ? gzip(bundle) : bundle;
+        }
     }
 }
 /** The export format implied by an output file name, if it has an archive extension. */
@@ -45,8 +52,12 @@ export function formatFromExtension(out) {
         return 'tar';
     if (name.endsWith('.zip'))
         return 'zip';
-    if (name.endsWith('.wbn'))
+    if (name.endsWith('.wbn') || name.endsWith('.wbn.gz'))
         return 'wbn';
     return undefined;
 }
+/** The compression implied by an output file name for `format`: `gzip` for a wbn written to `*.wbn.gz`. */
+export function compressionFromExtension(out, format) {
+    return format === 'wbn' && out.toLowerCase().endsWith('.wbn.gz') ? 'gzip' : undefined;
+}
 //# sourceMappingURL=export-formats.js.map

package/lib/src/index.d.ts

@@ -1,4 +1,4 @@
-export { SitefileError, isSitefileError, formatSpan, type ErrorCode, type SourceSpan } from './errors.js';
+export { SitefileError, isSitefileError, formatSpan, needsPlugin, needsTool, type ErrorCode, type Needs, type SourceSpan } from './errors.js';
 export type * from './language/ast.js';
 export { parseSitefile } from './language/parser.js';
 export { validate, parseProgram } from './language/validate.js';
@@ -9,4 +9,5 @@ export { BuildMemo, type MemoStats } from './memo.js';
 export { Profiler } from './profile.js';
 export { Tree, makeFile, type FileNode, type ConflictPolicy } from './tree.js';
 export { DEFAULT_ARCHIVE_LIMITS, DEFAULT_FETCH_POLICY, type ArchiveLimits, type FetchPolicy, type Resource } from './resources/types.js';
+export { networkFromEnv, mergeNetwork, networkProblem, hostMatches, type NetworkSettings } from './resources/network.js';
 export { extractArchive } from './resources/archive.js';

package/lib/src/index.js

@@ -1,4 +1,4 @@
-export { SitefileError, isSitefileError, formatSpan } from './errors.js';
+export { SitefileError, isSitefileError, formatSpan, needsPlugin, needsTool } from './errors.js';
 export { parseSitefile } from './language/parser.js';
 export { validate, parseProgram } from './language/validate.js';
 export { plan } from './planner.js';
@@ -8,5 +8,6 @@ export { BuildMemo } from './memo.js';
 export { Profiler } from './profile.js';
 export { Tree, makeFile } from './tree.js';
 export { DEFAULT_ARCHIVE_LIMITS, DEFAULT_FETCH_POLICY } from './resources/types.js';
+export { networkFromEnv, mergeNetwork, networkProblem, hostMatches } from './resources/network.js';
 export { extractArchive } from './resources/archive.js';
 //# sourceMappingURL=index.js.map

package/lib/src/language/ast.d.ts

@@ -201,13 +201,20 @@ export interface ExportInstruction {
     readonly base?: Operand;
     /** `AT </srv/www>`: where the files live inside the layer (`oci` only). */
     readonly at?: Operand;
-    /** `COMPRESSION gzip|none`: how the site layer is stored (`oci` only; default gzip). */
+    /**
+     * `COMPRESSION gzip|none` (`oci` and `wbn` only): how the oci site layer is stored (default gzip),
+     * or whether the whole Web Bundle is gzipped (default none).
+     */
     readonly compression?: {
         readonly value: OciCompression;
         readonly span: SourceSpan;
     };
 }
-/** OCI site layer encoding: `gzip` (tar+gzip, the default) or `none` (plain tar). */
+/**
+ * `EXPORT ... COMPRESSION`: for `oci`, the site layer encoding, `gzip` (tar+gzip, the default) or `none`
+ * (plain tar); for `wbn`, `gzip` wraps the bundle in gzip (the family's `.wbn.gz`) and `none` (the default)
+ * writes the plain bundle.
+ */
 export type OciCompression = 'gzip' | 'none';
 export declare const OCI_COMPRESSIONS: readonly OciCompression[];
 /** Parse a compression name (case-insensitive); undefined if unknown. */

package/lib/src/outdated.js

@@ -160,7 +160,7 @@ export async function outdated(options) {
                 return entry({ kind, name, source, pin, pinnedBy, latest: null, status: 'digest-only', newerTag: null, error: null });
             }
             const tag = ref.tag ?? 'latest';
-            const client = makeClient(registry, { ...options.registry, allowPrivateNetwork: options.registry?.allowPrivateNetwork ?? policy.allowPrivateNetwork });
+            const client = makeClient(registry, { ...options.registry, allowPrivateNetwork: options.registry?.allowPrivateNetwork ?? policy.allowPrivateNetwork, network: options.registry?.network ?? policy.network });
             const latest = (await client.getManifest(ref.name, tag)).digest;
             let newerTag = null;
             if (versionTag(tag)) {

package/lib/src/planner.d.ts

@@ -259,7 +259,7 @@ export interface Plan {
     readonly exportBase: string | undefined;
     /** Evaluated `AT` clause of EXPORT ... AS oci: the root directory inside the image layer. */
     readonly exportRoot: string | undefined;
-    /** `COMPRESSION` clause of EXPORT ... AS oci (undefined: gzip). */
+    /** `COMPRESSION` clause of EXPORT ... AS oci or wbn (undefined: gzip for oci, none for wbn). */
     readonly exportCompression: OciCompression | undefined;
     /** REDIRECT lines in source order (any stage); EXPORT writes them to `/_redirects`. */
     readonly redirects: readonly RedirectSpec[];

package/lib/src/planner.js

@@ -240,8 +240,8 @@ export function plan(program, buildArgs = {}, argSource = (n) => `--build-arg ${
                 if (ins.at && ins.format !== 'oci')
                     throw new SitefileError('E_VALIDATION', 'EXPORT ... AT applies only to AS oci', ins.at.span);
                 exportRoot = ins.at ? normalizeVirtual(evaluateOperand(ins.at, vars), ins.at.span, 'EXPORT AT path').path : undefined;
-                if (ins.compression && ins.format !== 'oci')
-                    throw new SitefileError('E_VALIDATION', 'EXPORT ... COMPRESSION applies only to AS oci', ins.compression.span);
+                if (ins.compression && ins.format !== 'oci' && ins.format !== 'wbn')
+                    throw new SitefileError('E_VALIDATION', 'EXPORT ... COMPRESSION applies only to AS oci and AS wbn', ins.compression.span);
                 exportCompression = ins.compression?.value;
                 break;
         }

package/lib/src/plugins/cache.d.ts

@@ -2,15 +2,27 @@ import type { PluginResult } from './host.js';
 /**
  * Content-addressed cache of TRANSFORM results (see docs/PLUGINS.md, "Caching").
  *
- *   <dir>/entries/<key>.json   manifest: which blobs make up the result
+ *   <dir>/entries/<key>.json   manifest: which blobs make up the result, and the
+ *                              PLUGIN or TOOL that produced it ("plugin")
  *   <dir>/blobs/<hex>          result bytes, named by their SHA-256
  *
  * The key is the SHA-256 of a canonical JSON document describing everything the
  * result can depend on. Reads verify every blob's digest and size; a damaged
  * entry is removed and counts as a miss, so the next put rewrites it.
+ * "plugin" is optional (entries written before it was recorded have none and are
+ * still read) and not part of the key.
  */
 /** Bump to invalidate every existing entry when the key or entry format changes. */
 export declare const CACHE_VERSION = 1;
+/** What one plugin's entries hold (`TransformCache.usageByPlugin`). */
+export interface PluginCacheUsage {
+    /** The PLUGIN or TOOL name; undefined for entries that record none. */
+    readonly plugin: string | undefined;
+    readonly entries: number;
+    /** Distinct blobs these entries reference (a blob shared with another plugin's entry counts for both). */
+    readonly blobs: number;
+    readonly bytes: number;
+}
 /** What an entry records: the result kind and `[path, blob hex, size]` per file (a `file` result has one, with path ''). */
 export interface CacheEntry {
     readonly kind: 'file' | 'files';
@@ -48,9 +60,11 @@ export declare class TransformCache {
     constructor(dir: string, remote?: RemoteCache | undefined);
     private entryPath;
     private blobPath;
-    get(key: string): Promise<PluginResult | undefined>;
+    /** `plugin`: the TRANSFORM's PLUGIN or TOOL, recorded on an entry fetched from the remote cache. */
+    get(key: string, plugin?: string): Promise<PluginResult | undefined>;
     private load;
-    put(key: string, result: PluginResult): Promise<void>;
+    /** `plugin`: the PLUGIN or TOOL that produced the result (see `usageByPlugin`, `prunePlugin`). */
+    put(key: string, result: PluginResult, plugin?: string): Promise<void>;
     private writeAtomic;
     info(): Promise<CacheInfo>;
     /**
@@ -62,6 +76,18 @@ export declare class TransformCache {
         blobs: number;
         bytes: number;
     }>;
+    /**
+     * Remove the entries `plugin` (a PLUGIN or TOOL name) wrote that were not used for `olderThanMs`
+     * (0: all of them), then the blobs they used that no remaining entry references. Entries of other
+     * plugins, entries that record no plugin, and blobs no entry references yet are kept.
+     */
+    prunePlugin(plugin: string, olderThanMs?: number, now?: number): Promise<{
+        entries: number;
+        blobs: number;
+        bytes: number;
+    }>;
+    /** Entries, blobs and bytes per plugin, sorted by name (entries that record none first). Reads no blob. */
+    usageByPlugin(): Promise<PluginCacheUsage[]>;
 }
 /** Digest of every regular file under `dir` (a plugin can read all of them, so any may change its output). */
 export declare function digestFolder(dir: string, limits?: {