@johnhenry/sitefile 0.0.0 → 0.0.2

package/CHANGELOG.md

@@ -1,8 +1,122 @@
 # Changelog
 
+## 0.0.2 (2026-11-08)
+
+- **Plugin console output keeps its order** (johnhenry/sitefile#164): a
+  plugin's console lines are written before its result, in both the
+  TypeScript and Rust runners, so they always become build warnings (a race
+  dropped some). Fixed in 5689229 (#164).
+- **Docs: the tool is "sitefile".** The product name is lowercase where it
+  stands alone; "Sitefile" stays for the file (`Sitefile`, `Sitefile.lock`, "a
+  Sitefile") and the language. The desktop app is Sitefile Desktop.
+
+## 0.0.1 (2026-11-08)
+
+- **`serve` serves archive files** (johnhenry/sitefile#155): `sitefile serve
+  site.zip` (and `serve -d`) serves a zip, tar, tar.gz/tgz, Web Bundle or OCI
+  image archive (`build -o x.oci.tar`, `save`) the way it serves a directory.
+  The format comes from the bytes; a path-like argument that is a file is an
+  archive, and a bare name is an archive file when no image has that name.
+  Zip, tar and wbn are extracted with the default archive limits and served
+  without hidden files (as a directory is); an OCI archive serves its first
+  image as the store would, with every blob checked against its digest. The
+  file is read again on every start and `server restart`. Server records gain
+  `{"kind": "archive", "path": …}` (older records load unchanged); Rust adds
+  `ServerSource::Archive`, `servers::load_archive_tree` and
+  `load_archive_tree_with`, with every existing signature unchanged. A file
+  that is not an archive is `E_TYPE` naming it. docs/CLI.md, "Site servers".
+- **Explicit network settings: proxy, host rules, connect/read timeouts**
+  (johnhenry/sitefile#156), for networks that need a proxy and for sitefile
+  Desktop's Settings screen. `--proxy` / `SITEFILE_PROXY` (an `http://` proxy:
+  a CONNECT tunnel for https, absolute form for http; `HTTP(S)_PROXY` is still
+  never read), `--no-proxy` / `SITEFILE_NO_PROXY` (`NO_PROXY` syntax),
+  `--allow-hosts` / `SITEFILE_ALLOW_HOSTS` and `--deny-hosts` /
+  `SITEFILE_DENY_HOSTS` (checked on every hop, registries included; deny beats
+  allow; the new code `E_HOST_BLOCKED` names the rule), and `--connect-timeout`
+  / `--read-timeout` / `SITEFILE_FETCH_TIMEOUT`, on `build`, `validate`,
+  `inspect`, `graph`, `why`, `pull`, `push`, `vendor` and `outdated`. A proxy
+  never widens the fetch policy: the target is resolved and checked against
+  the private-address rule before the proxy is asked. Embedders pass the same
+  settings as `FetchPolicy.network` / `RegistryOptions.network`
+  (`NetworkSettings`, additive in both implementations). docs/CLI.md,
+  "Network"; `test/network.test.ts`, `rust/src/resources/network.rs`, and the
+  `net-proxy*`, `net-no-proxy`, `net-allow-hosts` and `net-deny-hosts`
+  conformance cases. Added in c131eb3 (#162).
+
+- **Library API for embedders** (johnhenry/sitefile#153), found by embedding
+  the crate in Sitefile Desktop. Rust: `servers::serve_detached`,
+  `restart_detached`, `start_detached`, `stop_server`, `resolve_source`,
+  `parse_publish` and `DetachedServe` (the CLI's `serve -d`, `server restart`
+  and `server stop` now call them); `executor::store_build_as_image` with
+  `ImageInfo` and `StoredImage` (what `build -t` calls);
+  `BuildOptions::store_home`, so `FROM <local image>`, `BASE` and the wasm
+  module cache use an embedder's store instead of `$SITEFILE_HOME`;
+  `BuildOptions::cancel` with `CancelToken`, checked between imports, stages,
+  operations and plugin or tool calls, failing with the new code
+  `E_CANCELLED`; detached workers are reaped on a background thread, so a
+  long-lived host can stop them without waiting out the grace period.
+  Both implementations: TRANSFORM cache entries record their PLUGIN or TOOL
+  (`"plugin"`, same bytes in both; older entries are still read, keys are
+  unchanged), with `usage_by_plugin`/`usageByPlugin`,
+  `prune_plugin`/`prunePlugin` and `sitefile cache prune --plugin <name>`; the
+  `E_UNSUPPORTED` error of a PLUGIN or TOOL that is not allowed carries
+  `needs` (kind, name, flag), with the message unchanged. CLI output is
+  otherwise unchanged. docs/RUST.md, "Embedding the crate";
+  `rust/tests/embed.rs`. Added in e0c555d (#154).
+
+- **`EXPORT … AS wbn COMPRESSION gzip`** (johnhenry/sitefile#143): a Web Bundle
+  export can now be gzip(`application/webbundle`), the `.wbn` archive format of
+  `@johnhenry/packfile` (`toArchive`/`fromArchive`) and `@johnhenry/fileable`
+  (`encode="wbn"`). `COMPRESSION` used to be `E_VALIDATION` on anything but
+  `oci`; it now applies to `oci` and `wbn`, and on `wbn` defaults to `none`, so
+  existing exports are byte-for-byte unchanged. The gzip layer only wraps the
+  finished bundle and uses the shared deterministic encoder (`src/deflate.ts`,
+  `rust/src/deflate.rs`), so both CLIs write identical bytes. On the CLI,
+  `-o site.wbn.gz` selects a gzipped wbn (also for `sitefile save`), the
+  default destination of such a Sitefile is `dist.wbn.gz`, and the new
+  `--compression gzip|none` overrides `EXPORT … COMPRESSION` for the export's
+  format (oci or wbn; any other format is a usage error); `--oci-compression`
+  stays as the oci-only spelling. A Sitefile's `COMPRESSION` belongs to its own
+  `AS` format: `--format wbn` on an `AS oci COMPRESSION …` Sitefile does not
+  inherit it. `test/packfile-interop.test.ts` now reads a gzip export built with
+  `BASE https://packfile.invalid/` through plain `fromArchive(buffer)`; new
+  conformance cases compare the bytes of both implementations. Added in
+  3c537de (#149).
+
+- **Example: a fileable plugin for TRANSFORM** (`examples/fileable/`,
+  johnhenry/sitefile#145). A JavaScript plugin renders a `@johnhenry/fileable`
+  tree into the build with fileable's in-memory `toFiles()` and returns
+  `{ files }`, so a JSX file tree needs no directory or zip on disk in
+  between. fileable stays out of sitefile's dependencies: it is a
+  devDependency, and `examples/fileable/vendor.mjs` copies the files its
+  browser entry point loads into the plugin folder (gitignored; nothing
+  generated is committed), the only folder a plugin can read. Its `cmd`
+  attribute and other features that need files, processes or the environment
+  fail with a clear `E_PLUGIN`. Checked by `npm run examples` and by
+  conformance (both CLIs). docs/PLUGINS.md, "Example: rendering a fileable
+  tree". Added in 0b5c4b3 (#147).
+
+- **`EXPORT … AS wbn` bakes HEADER and exact REDIRECT rules into the bundle's
+  responses** (johnhenry/sitefile#144, #150). Each response gets the headers of the
+  `/_headers` blocks matching its URL, with `sitefile serve`'s matching
+  (`serve-rules.ts`; a directory URL like `<base>docs/` matches with its
+  slash and gets its own response when its headers differ). Exact-path
+  `/_redirects` rules with a 3xx status become responses with that status, a
+  `location` and an empty body, in `serve`'s order (a forced `301!` replaces
+  the file; other rules apply only where `serve` would find nothing). Splats,
+  `200` rewrites and `404` rules stay in `/_redirects`, which, like
+  `/_headers`, is still in the bundle. Bundles of trees without those files
+  are byte-identical to before. packfile's `createWebBundleRouter()` now
+  answers with the HEADER values and redirects (`test/packfile-interop.test.ts`);
+  conformance cases `ok-wbn-rules` and `ok-wbn-rules-files` compare both
+  implementations' bytes. The TypeScript `headersFor` no longer drops a
+  header named `__proto__` (the Rust port never did); this also
+  changes the TypeScript `sitefile serve`, which now sends such a header as
+  the Rust binary does. Added in 429ab24 (#150).
+
 ## 0.0.0 — first npm release (2026-11-06)
 
-`@johnhenry/sitefile` is a new package: Sitefile was never published to npm
+`@johnhenry/sitefile` is a new package: sitefile was never published to npm
 under any name, and `0.0.0` is its first version. It joins the @johnhenry
 family as its static build orchestrator, next to `@johnhenry/fileable` (file
 trees in JSX) and `@johnhenry/packfile` (the Web Bundle reader and server).

package/README.md

@@ -1,4 +1,4 @@
-# Sitefile
+# sitefile
 
 [![npm version](https://img.shields.io/npm/v/%40johnhenry%2Fsitefile.svg)](https://www.npmjs.com/package/@johnhenry/sitefile)
 [![CI](https://github.com/johnhenry/sitefile/actions/workflows/ci.yml/badge.svg)](https://github.com/johnhenry/sitefile/actions/workflows/ci.yml)
@@ -84,10 +84,10 @@ no runtime dependencies.
 | `TOOL name` + `TRANSFORM … WITH name TO <dest> [OPTIONS …] [FOR …] ARGS …` | yes; run an external program (e.g. `ffmpeg`) you allow with `--allow-exec name`: argv only, no shell, temp files, scrubbed environment (see [docs/PLUGINS.md](docs/PLUGINS.md)) |
 | `SITEMAP BASE <url> [TO <dest>]` | yes; a sitemaps.org `/sitemap.xml` of the `.html` pages so far |
 | `FEED <import> BASE <url> LINK <path> [TO <dest>] [TITLE <text>]` | yes; an Atom `/feed.xml` from Markdown posts (`title` and `date` required) |
-| `REDIRECT <from> <to> [STATUS 301\|302\|303\|307\|308]`, `HEADER <pattern> <Name>: <value>` | yes; `/_redirects` and `/_headers` for Netlify / Cloudflare Pages (and `sitefile serve`) |
+| `REDIRECT <from> <to> [STATUS 301\|302\|303\|307\|308]`, `HEADER <pattern> <Name>: <value>` | yes; `/_redirects` and `/_headers` for Netlify / Cloudflare Pages (and `sitefile serve`); a `wbn` export also bakes HEADER values into each response and exact-path REDIRECTs into 3xx responses (splats stay in `/_redirects`) |
 | `CHECKLINKS [--warn] [--external]` | yes; fails (or warns) on links to files that do not exist, with file and line; `--external` requests http(s) links under the network policy |
 | `FINGERPRINT [--overwrite] <pattern>… [MANIFEST <dest>]` | yes; renames assets to `name.<hash>.ext` and rewrites the HTML and CSS that reference them, plus a JSON manifest |
-| `EXPORT <path> [AS directory\|zip\|tar\|tgz\|wbn\|oci] [BASE <https-url>] [AT <root>]` | yes; archives are deterministic, `wbn` is an unsigned Web Bundle (needs `BASE` or `--base-url`), `oci` is a single-layer OCI image of the files (under `AT`, default `/srv/www`) |
+| `EXPORT <path> [AS directory\|zip\|tar\|tgz\|wbn\|oci] [BASE <https-url>] [AT <root>] [COMPRESSION gzip\|none]` | yes; archives are deterministic, `wbn` is an unsigned Web Bundle (needs `BASE` or `--base-url`; `COMPRESSION gzip` gzips it, default `none`), `oci` is a single-layer OCI image of the files (under `AT`, default `/srv/www`; `COMPRESSION` sets its layer, default `gzip`) |
 
 Templates can also live in the Sitefile itself (see `examples/inline/`):
 
@@ -163,7 +163,7 @@ build used, `--cache-from <ref>` reuses them (see [docs/CLI.md](docs/CLI.md#regi
 ## CLI
 
 ```
-sitefile build [context] [-o dist] [--format directory|zip|tar|tgz|wbn] [--base-url URL]
+sitefile build [context] [-o dist] [--format directory|zip|tar|tgz|wbn] [--base-url URL] [--compression gzip|none]
                [--build-arg K=V | --build-arg K] [--build-arg-file vars.json|.yaml|.env] [--force]
                [--frozen-lockfile | --update-lock] [--strict-pins] [--allow-http] [--allow-private-network]
                [--allow-hardlinks] [--allow-exec name[=/abs/path]]... [--allow-plugin name]... [--allow-plugins]
@@ -181,7 +181,7 @@ sitefile build [context] -t name[:tag]        # also store the build as an image
 sitefile images | image inspect|diff|prune | tag | rmi | save
 sitefile cache info | cache prune [--older-than days]   # TRANSFORM result cache
 sitefile cache du                                       # cache sizes; SITEFILE_CACHE_MAX bounds them (default 1G)
-sitefile serve [-d] [--name n] [-p [host:]port] [--spa] <image|./dir>
+sitefile serve [-d] [--name n] [-p [host:]port] [--spa] <image|./dir|site.zip>
 sitefile serve --watch [-p [host:]port] [--spa] [context]   # build in memory, serve, live reload
 sitefile servers [-a] | server stop|rm [-f]|restart|logs [-f] <name>
 ```
@@ -273,6 +273,7 @@ CycloneDX file list to the image as OCI 1.1 referrers (deterministic, pushed wit
 sitefile build examples/hello --format zip     # examples/hello/dist.zip
 sitefile build examples/hello -o hello.tar.gz      # format from the extension
 sitefile build examples/hello --format wbn --base-url https://example.com/
+sitefile build examples/hello -o hello.wbn.gz --base-url https://example.com/   # gzip(Web Bundle)
 ```
 
 Archives are reproducible: sorted entries, fixed timestamps (or `SOURCE_DATE_EPOCH`),
@@ -324,6 +325,7 @@ stopgap in VS Code.
 - [docs/RUST.md](docs/RUST.md) — the Rust port: layout, parity checks, known differences
 - [docs/LSP.md](docs/LSP.md) — the language server for editors (`sitefile lsp`, Rust binary)
 - [docs/PLUGINS.md](docs/PLUGINS.md) — writing renderer plugins, and the sandbox
+- [docs/DOCKER.md](docs/DOCKER.md) — sitefile next to Docker: site images Docker runs, Dockerfile stages, shared registries
 - [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) — invariants and module layout
 - [docs/MILESTONES.md](docs/MILESTONES.md), [docs/TASKS.md](docs/TASKS.md)
 - [AGENTS.md](AGENTS.md) — the verification loop and rules for anyone (human or agent) changing this repo
@@ -378,7 +380,7 @@ stage), so building one is treated as running untrusted input. Templates,
 imports and WebAssembly plugins are data; JavaScript plugins and external
 tools are code, and run only when you name them on the command line.
 
-**What Sitefile guarantees:**
+**What sitefile guarantees:**
 
 - **Local reads stay inside the build context.** No `..`, absolute paths or
   symlinks out; hard-linked files are refused (`E_HARDLINK`) unless
@@ -388,7 +390,11 @@ tools are code, and run only when you name them on the command line.
 - **Remote imports are `https:` only, to public addresses only** — checked at
   connect time and on every redirect (SSRF), size- and time-limited, never
   decompressed or executed. `--allow-http` and `--allow-private-network` are the
-  only ways to widen this.
+  only ways to widen this. An explicit proxy (`--proxy` / `$SITEFILE_PROXY`;
+  `HTTP(S)_PROXY` is never read) does not widen it either: sitefile resolves and
+  checks the target itself before handing it to the proxy. `--allow-hosts` and
+  `--deny-hosts` narrow it further, on every hop
+  ([docs/CLI.md](docs/CLI.md#network-proxy-host-rules-and-timeouts)).
 - **Pins are enforced.** Unpinned URLs are recorded in `Sitefile.lock` and must
   match on later builds; `--strict-pins` refuses any remote import or BASE image
   that is not pinned (`INTEGRITY`, `@sha256:` or a lockfile entry).
@@ -441,35 +447,67 @@ tools are code, and run only when you name them on the command line.
   `INTEGRITY`, `@sha256:` and `--strict-pins` for builds that must be
   reproducible.
 - **Web Bundles are unsigned.** `EXPORT … AS wbn` writes an unsigned b2 bundle;
-  signing (for example for an Isolated Web App) happens outside Sitefile.
+  signing (for example for an Isolated Web App) happens outside sitefile.
 - **Widening flags are yours to justify.** `--allow-http`,
   `--allow-private-network`, `--allow-hardlinks`, `--force` and `serve -p
   0.0.0.0:…` each turn off one of the guarantees above for that build.
 
 ## Family
 
-Sitefile is the build orchestrator of the @johnhenry family's static tools. It
+sitefile is the build orchestrator of the @johnhenry family's static tools. It
 runs the pipeline (pinned imports, stages, templates, sandboxed plugins, checks,
 exports); its siblings write file trees in code and serve the result. It has no
-runtime dependency on either: they meet at file formats, a directory or a `.wbn`
-Web Bundle.
+runtime dependency on either: they meet at file formats, a directory, a zip or
+a `.wbn` Web Bundle.
 
 - **[`@johnhenry/fileable`](https://github.com/johnhenry/fileable)** -- writes
   file trees in JSX (`Dir`, `File`, `Rm`), for scaffolding and codegen. A
-  fileable build's output directory, or its `encode="zip"` archive, is an
-  ordinary Sitefile input: `COPY ./generated/ /`, or `IMPORT gen FROM
-  ./site.zip AS tree` and `COPY gen:/ /` (both give the same output). Its
-  `encode="wbn"` archive is gzip around a Web Bundle, which `AS tree` does not
-  read yet (johnhenry/sitefile#141). Neither package depends on the other.
+  fileable build's output is an ordinary sitefile input. Neither package
+  depends on the other.
 - **[`@johnhenry/packfile`](https://github.com/johnhenry/packfile)** -- the
-  family's Web Bundle reader and in-memory server. `EXPORT / AS wbn BASE <url>`
-  writes a plain b2 Web Bundle that packfile's `fromWebBundle(buffer, { baseURL })`
-  reads back into exactly the exported files, and `createRouter()` serves as a
-  `(Request) => Response` handler. packfile's own archive format
-  (`fromArchive()`) is gzip around the same bundle under
-  `https://packfile.invalid/`: gzip a Sitefile bundle exported with that BASE and
-  `fromArchive()` reads it as is. `test/packfile-interop.test.ts` checks all
-  three; `@johnhenry/packfile` is a devDependency for that test only.
+  family's Web Bundle reader and in-memory server. It reads what `EXPORT … AS
+  wbn` writes and serves it as a `(Request) => Response` handler.
+  `@johnhenry/packfile` is a devDependency here for
+  `test/packfile-interop.test.ts` only.
+
+### Working together: what works today
+
+Checked on 2026-11-07 against the npm releases (`@johnhenry/sitefile` 0.0.0,
+`@johnhenry/fileable` 0.1.1, `@johnhenry/packfile` 0.2.0) and each
+repository's `main`. "Fixed on main, in the next release" means merged but
+not published: the npm versions still behave as the rest of that row says.
+
+| From | To | How | Status |
+| --- | --- | --- | --- |
+| fileable, loose output | sitefile | `COPY ./generated/ /` | Works |
+| fileable, `encode="zip"` | sitefile | `IMPORT gen FROM ./site.zip AS tree`, then `COPY gen:/ /` | Works (same output as loose) |
+| fileable, `encode="wbn"` | sitefile | `IMPORT … AS tree` | **Not yet:** it's gzip around a Web Bundle, and `AS tree` reads only plain bundles ([#141](https://github.com/johnhenry/sitefile/issues/141)) |
+| fileable tree, rendered during a build | Sitefile | a JavaScript `TRANSFORM` plugin calling fileable's in-memory `toFiles()` | An example on main, not part of the npm package: [`examples/fileable/`](examples/fileable/) ([#145](https://github.com/johnhenry/sitefile/issues/145)). fileable is vendored into the plugin folder; `cmd`, local `src=` and `env://` fail with `E_PLUGIN` |
+| sitefile, `EXPORT / AS wbn BASE <url>` | packfile | `fromWebBundle(buffer, { baseURL })` from `@johnhenry/packfile/web-bundle`, then `createRouter(files)` | Works; tested here (`test/packfile-interop.test.ts`), and packfile's own tests read a bundle written by sitefile 0.0.0 |
+| sitefile `.wbn` | packfile `fromArchive()` | with 0.0.0 / 0.2.0: gzip it, and export with `BASE https://packfile.invalid/` | Works with that workaround. **Fixed on main, in the next release:** `EXPORT … AS wbn COMPRESSION gzip` (or `-o site.wbn.gz`) writes the gzip ([#143](https://github.com/johnhenry/sitefile/issues/143)), and `fromArchive()` takes a `baseURL` or the origin of the bundle's primary URL, so any `BASE` reads back ([packfile#18](https://github.com/johnhenry/packfile/issues/18)) |
+| sitefile `HEADER` / `REDIRECT` | packfile `createWebBundleRouter()` | -- | **Not applied in 0.0.0:** only the `/_headers` and `/_redirects` files are in the bundle. **Fixed on main, in the next release:** each response carries its HEADER values, and exact-path 301/302/303/307/308 REDIRECTs are 3xx responses with `location` ([#144](https://github.com/johnhenry/sitefile/issues/144)). Splats, `200` rewrites and `404` rules stay in `/_redirects` only |
+| packfile `toArchive()` | sitefile | `IMPORT … AS tree` | **Not yet** (same as fileable's `.wbn`, [#141](https://github.com/johnhenry/sitefile/issues/141)) |
+
+Gotchas when serving a Sitefile bundle with packfile:
+
+- **Pass `createRouter()` a path string for non-ASCII paths.** A `Request`
+  for `/docs/ünï/page.html` returns 404 because the pathname isn't
+  percent-decoded; the string `"/docs/ünï/page.html"` works
+  ([packfile#20](https://github.com/johnhenry/packfile/issues/20)).
+- **`fromWebBundle` skips the bundle's entry at the bare base URL.** sitefile
+  stores the index page there as well as at `/index.html`; you get it from
+  `index.html`.
+- **The `baseURL` you pass to `fromWebBundle` must be the `BASE` you exported
+  with.** Entries under any other origin are skipped, so the wrong base reads
+  back as an empty map, without an error. packfile's `fromArchive()` on its
+  main branch (next release) defaults to the origin of the primary URL, which
+  sitefile writes only when the site has `/index.html`; with a `BASE` that has
+  a path (`https://site.example/blog/`), the keys start with `blog/` unless you
+  pass that `baseURL`.
+- **HEADER and REDIRECT need `createWebBundleRouter()`** (on main, next
+  release): `createWebBundleRouter(new wbn.Bundle(bytes), { baseURL })` serves
+  each exchange's own status and headers. `createRouter()` serves a files map,
+  so it answers with the files only.
 
 ## License
 

package/lib/src/checklinks.js

@@ -44,6 +44,8 @@ function externalReason(e, url, policy) {
             return /^http:/i.test(url) && !policy.allowHttp ? 'plain http is checked only with --allow-http' : 'not allowed by the network policy';
         case 'E_SSRF_BLOCKED':
             return 'a non-public address (checked only with --allow-private-network)';
+        case 'E_HOST_BLOCKED':
+            return 'refused by the allow-hosts/deny-hosts rules';
         case 'E_REDIRECT':
             return 'too many or invalid redirects';
         default:

package/lib/src/cli/build-image.js

@@ -1,6 +1,6 @@
 import { sourceDateEpoch } from '../archive-writers.js';
 import { SitefileError } from '../errors.js';
-import { imageAttestations } from '../executor.js';
+import { imageAttestations, sitefileCompression } from '../executor.js';
 import { imageMeta } from '../oci.js';
 import { parseLocalRef } from '../ref.js';
 import { shortId, Store } from '../store.js';
@@ -20,7 +20,7 @@ export async function storeBuildAsImage(result, tags, info) {
     const store = await Store.open();
     const { id } = await store.addImage(result.output, {
         root: info.ociRoot ?? result.plan.exportRoot,
-        compression: info.ociCompression ?? result.plan.exportCompression,
+        compression: info.ociCompression ?? sitefileCompression(result.plan, 'oci'),
         platform: info.platform,
         epoch: sourceDateEpoch(),
         base: result.base,

package/lib/src/cli/cache.js

@@ -24,17 +24,24 @@ const info = {
 const prune = {
     name: 'cache prune',
     summary: 'delete cached TRANSFORM results',
-    usage: 'cache prune [--older-than <days> | --max-size <size>]',
-    description: 'Delete every cached TRANSFORM result, or only entries not used for the given number of days, and the blobs no\nentry still uses. With --max-size, instead apply the automatic size limit now with that size: least recently\nused evictable data (TRANSFORM results, compiled wasm modules, untagged images and unused blobs) is deleted\nuntil the rest fits. Tagged images are never touched.',
-    flags: ['    --older-than <days>   keep entries used within this many days', '    --max-size <size>     shrink evictable data to this size (e.g. 500M, 2G)'],
-    options: { 'older-than': { type: 'string' }, 'max-size': { type: 'string' } },
+    usage: 'cache prune [--older-than <days>] [--plugin <name>] | --max-size <size>',
+    description: 'Delete every cached TRANSFORM result, or only entries not used for the given number of days, and the blobs no\nentry still uses. With --plugin, only the results of that PLUGIN or TOOL (entries written before results\nrecorded their plugin are kept). With --max-size, instead apply the automatic size limit now with that size:\nleast recently used evictable data (TRANSFORM results, compiled wasm modules, untagged images and unused\nblobs) is deleted until the rest fits. Tagged images are never touched.',
+    flags: [
+        '    --older-than <days>   keep entries used within this many days',
+        '    --plugin <name>       only the results of this PLUGIN or TOOL',
+        '    --max-size <size>     shrink evictable data to this size (e.g. 500M, 2G)',
+    ],
+    options: { 'older-than': { type: 'string' }, plugin: { type: 'string' }, 'max-size': { type: 'string' } },
     async run(v, pos) {
         requireArgs(pos, 0, 0, 'no arguments');
         const raw = v['older-than'];
         const max = str(v['max-size']);
+        const plugin = str(v['plugin']);
         if (max !== undefined) {
             if (raw !== undefined)
                 usage('--older-than and --max-size conflict');
+            if (plugin !== undefined)
+                usage('--plugin and --max-size conflict');
             const n = parseSize(max);
             if (n === undefined || n === 0)
                 usage('--max-size expects a size greater than 0, such as 500M or 2G');
@@ -49,7 +56,10 @@ const prune = {
                 usage('--older-than expects a positive number of days');
             ms = days * 86_400_000;
         }
-        const r = await new TransformCache(transformCacheDir()).prune(ms);
+        if (plugin !== undefined && !/^[A-Za-z_][A-Za-z0-9_]*$/.test(plugin))
+            usage(`--plugin expects a PLUGIN or TOOL name (an identifier), got '${plugin}'`);
+        const cache = new TransformCache(transformCacheDir());
+        const r = plugin === undefined ? await cache.prune(ms) : await cache.prunePlugin(plugin, ms);
         process.stdout.write(`Deleted ${r.entries} entr${r.entries === 1 ? 'y' : 'ies'} and ${r.blobs} blob${r.blobs === 1 ? '' : 's'}\nTotal reclaimed space: ${humanSize(r.bytes)}\n`);
         return 0;
     },

package/lib/src/cli/images.js

@@ -4,7 +4,7 @@ import path from 'node:path';
 import { sourceDateEpoch, writeTar } from '../archive-writers.js';
 import { SitefileError } from '../errors.js';
 import { exportDirectory, exportFile } from '../exporter.js';
-import { encodeTree, formatFromExtension, isArchiveFormat } from '../export-formats.js';
+import { compressionFromExtension, encodeTree, formatFromExtension, isArchiveFormat } from '../export-formats.js';
 import { EXPORT_FORMATS, parseExportFormat } from '../language/ast.js';
 import { MEDIA, siteLayerIndex } from '../oci.js';
 import { looksLikeImageId, parseLocalRef, refKey } from '../ref.js';
@@ -175,7 +175,7 @@ const save = {
     name: 'save',
     summary: 'export an image to a directory or archive',
     usage: 'save <ref|id> -o <out> [--format fmt] [--base-url url] [--force]',
-    description: 'Write an image\'s files to a directory, or to a zip, tar, tar.gz (tgz) or wbn archive, or the image itself as\nan OCI archive (-o x.oci.tar) or OCI layout directory (--format oci). The format is chosen like "build -o":\nfrom --format, else the extension (.zip .tar .tar.gz .tgz .wbn .oci.tar), else a directory.\nArchives are deterministic (set SOURCE_DATE_EPOCH to stamp them). A non-empty destination needs --force.',
+    description: 'Write an image\'s files to a directory, or to a zip, tar, tar.gz (tgz) or wbn archive, or the image itself as\nan OCI archive (-o x.oci.tar) or OCI layout directory (--format oci). The format is chosen like "build -o":\nfrom --format, else the extension (.zip .tar .tar.gz .tgz .wbn .wbn.gz .oci.tar), else a directory; a wbn\nwritten to *.wbn.gz is gzipped.\nArchives are deterministic (set SOURCE_DATE_EPOCH to stamp them). A non-empty destination needs --force.',
     flags: [
         '-o, --out <path>     destination (required)',
         `    --format <fmt>   ${EXPORT_FORMATS.join(' | ')} (alias tar.gz)`,
@@ -223,7 +223,7 @@ const save = {
                 process.stdout.write(`Saved ${shortId(id)} (${tree.size} files) to ${shown(w.outDir)}\n`);
             }
             else {
-                const data = encodeTree(tree, format, { epoch: sourceDateEpoch(), baseUrl: str(v['base-url']) });
+                const data = encodeTree(tree, format, { epoch: sourceDateEpoch(), baseUrl: str(v['base-url']), compression: compressionFromExtension(out, format) });
                 const w = await exportFile(data, out, opts);
                 process.stdout.write(`Saved ${shortId(id)} (${tree.size} files) to ${shown(w.outFile)} (${format === 'tgz' ? 'tar.gz' : format}, ${w.bytes} bytes)\n`);
             }

package/lib/src/cli/index.d.ts

@@ -5,6 +5,6 @@ export declare const EXTRA_COMMANDS: readonly string[];
  * an editor tool. Here `sitefile lsp` is a usage error that points there.
  */
 export declare const LSP_UNAVAILABLE = "'sitefile lsp' (the language server) is provided by the Rust implementation: build it with 'cd rust && cargo build --release' and run 'rust/target/release/sitefile lsp' (see docs/LSP.md)";
-export declare const EXTRA_HELP = "\nImages (local store: $SITEFILE_HOME or ~/.sitefile):\n  sitefile build [context] -t name[:tag]           also store the result as an image (repeatable -t)\n  sitefile images [--json] [--digests] [-q]        list images (alias: image ls)\n  sitefile image inspect <ref> [--json]            show an image manifest\n  sitefile image prune                             delete unreferenced manifests and blobs\n  sitefile image diff <a> <b>                      added/removed/changed paths\n  sitefile tag <src> <dst>                         add a name:tag\n  sitefile rmi [-f] <ref|id>...                    remove tags / images\n  sitefile save <ref> -o out[.zip|.tar|.tar.gz|.wbn]   export an image\n  sitefile push <registry/name[:tag]>              push a (tagged) image to an OCI registry\n  sitefile pull <[registry/]name[:tag][@digest]>   pull an image (a bare name means Docker Hub)\n\nVariants:\n  sitefile bake [targets...] [-f file] [--print]   build several targets (matrix, groups) from\n                                                   sitefile.bake.yaml; --print shows the plan\n\nOffline builds:\n  sitefile vendor [context] [--vendor-dir dir]     download remote imports and the BASE image into\n                                                   vendor/sitefile; builds then read them from there\n\nPins:\n  sitefile outdated [context] [--json]             compare remote imports and the BASE image with\n                                                   their pins (never changes anything)\n\nBuild cache (TRANSFORM results: $SITEFILE_HOME/cache/transform):\n  sitefile cache info [--json]                     location, entries, size\n  sitefile cache prune [--older-than <days>]       delete cached results\n  sitefile cache prune --max-size <size>           shrink evictable data (LRU) to <size>\n  sitefile cache du [--json]                       size of every cache and the store (alias: cache ls)\n  Evictable data over $SITEFILE_CACHE_MAX (default 1GiB, 0 = no limit) is deleted after each build.\n\nServing sites (detached servers are tracked by name):\n  sitefile serve [--name n] [-p [host:]port] [-d] [--spa] <ref|./dir>\n  sitefile serve --watch [-p [host:]port] [ctx]    build in memory, serve, rebuild + live reload\n  sitefile servers [-a] [--json]                   list servers (alias: server ls)\n  sitefile server stop|rm [-f]|restart|logs [-f] <name|id>\n\nEditor support:\n  sitefile lsp [--stdio]                           language server over stdio (Rust build only; docs/LSP.md)\n\nRun 'sitefile <command> --help' for the options of a command.\n";
+export declare const EXTRA_HELP = "\nImages (local store: $SITEFILE_HOME or ~/.sitefile):\n  sitefile build [context] -t name[:tag]           also store the result as an image (repeatable -t)\n  sitefile images [--json] [--digests] [-q]        list images (alias: image ls)\n  sitefile image inspect <ref> [--json]            show an image manifest\n  sitefile image prune                             delete unreferenced manifests and blobs\n  sitefile image diff <a> <b>                      added/removed/changed paths\n  sitefile tag <src> <dst>                         add a name:tag\n  sitefile rmi [-f] <ref|id>...                    remove tags / images\n  sitefile save <ref> -o out[.zip|.tar|.tar.gz|.wbn]   export an image\n  sitefile push <registry/name[:tag]>              push a (tagged) image to an OCI registry\n  sitefile pull <[registry/]name[:tag][@digest]>   pull an image (a bare name means Docker Hub)\n\nVariants:\n  sitefile bake [targets...] [-f file] [--print]   build several targets (matrix, groups) from\n                                                   sitefile.bake.yaml; --print shows the plan\n\nOffline builds:\n  sitefile vendor [context] [--vendor-dir dir]     download remote imports and the BASE image into\n                                                   vendor/sitefile; builds then read them from there\n\nPins:\n  sitefile outdated [context] [--json]             compare remote imports and the BASE image with\n                                                   their pins (never changes anything)\n\nBuild cache (TRANSFORM results: $SITEFILE_HOME/cache/transform):\n  sitefile cache info [--json]                     location, entries, size\n  sitefile cache prune [--older-than <days>]       delete cached results\n  sitefile cache prune --max-size <size>           shrink evictable data (LRU) to <size>\n  sitefile cache du [--json]                       size of every cache and the store (alias: cache ls)\n  Evictable data over $SITEFILE_CACHE_MAX (default 1GiB, 0 = no limit) is deleted after each build.\n\nServing sites (detached servers are tracked by name):\n  sitefile serve [--name n] [-p [host:]port] [-d] [--spa] <ref|./dir|file>\n  sitefile serve --watch [-p [host:]port] [ctx]    build in memory, serve, rebuild + live reload\n  sitefile servers [-a] [--json]                   list servers (alias: server ls)\n  sitefile server stop|rm [-f]|restart|logs [-f] <name|id>\n\nEditor support:\n  sitefile lsp [--stdio]                           language server over stdio (Rust build only; docs/LSP.md)\n\nRun 'sitefile <command> --help' for the options of a command.\n";
 export declare function isExtraCommand(name: string | undefined): boolean;
 export declare function runExtraCommand(argv: readonly string[]): Promise<number>;

package/lib/src/cli/index.js

@@ -51,7 +51,7 @@ Build cache (TRANSFORM results: $SITEFILE_HOME/cache/transform):
   Evictable data over $SITEFILE_CACHE_MAX (default 1GiB, 0 = no limit) is deleted after each build.
 
 Serving sites (detached servers are tracked by name):
-  sitefile serve [--name n] [-p [host:]port] [-d] [--spa] <ref|./dir>
+  sitefile serve [--name n] [-p [host:]port] [-d] [--spa] <ref|./dir|file>
   sitefile serve --watch [-p [host:]port] [ctx]    build in memory, serve, rebuild + live reload
   sitefile servers [-a] [--json]                   list servers (alias: server ls)
   sitefile server stop|rm [-f]|restart|logs [-f] <name|id>

package/lib/src/cli/network.d.ts

@@ -0,0 +1,34 @@
+import { type NetworkSettings } from '../resources/network.js';
+/** parseArgs options for the network flags (build, validate, inspect, graph, why, pull, push, vendor, outdated). */
+export declare const NETWORK_OPTIONS: {
+    readonly proxy: {
+        readonly type: 'string';
+    };
+    readonly 'no-proxy': {
+        readonly type: 'string';
+        readonly multiple: true;
+    };
+    readonly 'allow-hosts': {
+        readonly type: 'string';
+        readonly multiple: true;
+    };
+    readonly 'deny-hosts': {
+        readonly type: 'string';
+        readonly multiple: true;
+    };
+    readonly 'connect-timeout': {
+        readonly type: 'string';
+    };
+    readonly 'read-timeout': {
+        readonly type: 'string';
+    };
+};
+/** Help lines for {@link NETWORK_OPTIONS}, at the given flag-column width. */
+export declare function networkHelp(width: number): string[];
+type Values = Record<string, string | boolean | Array<string | boolean> | undefined>;
+/**
+ * The network settings for a command: the SITEFILE_* environment, then the flags on top (flags replace
+ * the proxy and timeouts and add to the host lists). Throws E_USAGE for a bad value.
+ */
+export declare function networkOption(v: Values, env?: NodeJS.ProcessEnv): NetworkSettings | undefined;
+export {};

package/lib/src/cli/network.js

@@ -0,0 +1,56 @@
+import { SitefileError } from '../errors.js';
+import { mergeNetwork, networkFromEnv, networkProblem, splitList } from '../resources/network.js';
+/** parseArgs options for the network flags (build, validate, inspect, graph, why, pull, push, vendor, outdated). */
+export const NETWORK_OPTIONS = {
+    proxy: { type: 'string' },
+    'no-proxy': { type: 'string', multiple: true },
+    'allow-hosts': { type: 'string', multiple: true },
+    'deny-hosts': { type: 'string', multiple: true },
+    'connect-timeout': { type: 'string' },
+    'read-timeout': { type: 'string' },
+};
+/** Help lines for {@link NETWORK_OPTIONS}, at the given flag-column width. */
+export function networkHelp(width) {
+    const rows = [
+        ['--proxy <url>', ['send requests through this HTTP proxy: http://[user:password@]host[:port]', '(also $SITEFILE_PROXY; HTTP(S)_PROXY are never read)']],
+        ['--no-proxy <hosts>', ['hosts reached directly, not through the proxy (NO_PROXY syntax; repeatable,', 'comma-separated; also $SITEFILE_NO_PROXY)']],
+        ['--allow-hosts <hosts>', ['contact only hosts matching these patterns (repeatable, comma-separated;', 'also $SITEFILE_ALLOW_HOSTS)']],
+        ['--deny-hosts <hosts>', ['never contact hosts matching these patterns; beats --allow-hosts', '(repeatable, comma-separated; also $SITEFILE_DENY_HOSTS)']],
+        ['--connect-timeout <ms>', ['time limit for opening each connection (also $SITEFILE_FETCH_TIMEOUT)']],
+        ['--read-timeout <ms>', ['longest wait for data on a connection (also $SITEFILE_FETCH_TIMEOUT)']],
+    ];
+    const out = [];
+    for (const [flag, lines] of rows) {
+        lines.forEach((l, i) => out.push(`${(i === 0 ? flag : '').padEnd(width)}${l}`));
+    }
+    return out;
+}
+function ms(raw, flag) {
+    if (raw === undefined)
+        return undefined;
+    const n = Number(raw);
+    if (!/^\d+$/.test(raw) || !Number.isSafeInteger(n) || n <= 0)
+        throw new SitefileError('E_USAGE', `${flag} expects a positive integer`);
+    return n;
+}
+const strings = (v) => (Array.isArray(v) ? v.filter((x) => typeof x === 'string') : []);
+/**
+ * The network settings for a command: the SITEFILE_* environment, then the flags on top (flags replace
+ * the proxy and timeouts and add to the host lists). Throws E_USAGE for a bad value.
+ */
+export function networkOption(v, env = process.env) {
+    const flags = {
+        ...(typeof v.proxy === 'string' ? { proxy: v.proxy } : {}),
+        noProxy: strings(v['no-proxy']).flatMap(splitList),
+        allowHosts: strings(v['allow-hosts']).flatMap(splitList),
+        denyHosts: strings(v['deny-hosts']).flatMap(splitList),
+        connectTimeoutMs: ms(typeof v['connect-timeout'] === 'string' ? v['connect-timeout'] : undefined, '--connect-timeout'),
+        readTimeoutMs: ms(typeof v['read-timeout'] === 'string' ? v['read-timeout'] : undefined, '--read-timeout'),
+    };
+    const merged = mergeNetwork(networkFromEnv(env), flags);
+    const problem = networkProblem(merged);
+    if (problem)
+        throw new SitefileError('E_USAGE', problem);
+    return Object.keys(merged).length ? merged : undefined;
+}
+//# sourceMappingURL=network.js.map

package/lib/src/cli/outdated.js

@@ -1,3 +1,4 @@
+import { NETWORK_OPTIONS, networkHelp, networkOption } from './network.js';
 import { insecureRegistriesFromEnv } from '../base-image.js';
 import { collectBuildArgs } from '../build-args.js';
 import { outdated } from '../outdated.js';
@@ -47,10 +48,12 @@ const outdatedCommand = {
         '--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>                check this BASE image (overrides EXPORT ... AS oci BASE)',
         '--insecure-registry <h>       allow plain http to registry host[:port] (repeatable)',
     ],
     options: {
+        ...NETWORK_OPTIONS,
         file: { type: 'string', short: 'f' },
         json: { type: 'boolean' },
         'build-arg': { type: 'string', multiple: true },
@@ -68,6 +71,7 @@ const outdatedCommand = {
         requireArgs(pos, 0, 1, 'a context directory');
         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 base = str(v.base);
         const r = await outdated({
@@ -80,6 +84,7 @@ const outdatedCommand = {
                 allowPrivateNetwork: !!v['allow-private-network'],
                 ...(maxBytes ? { maxBytes } : {}),
                 ...(timeoutMs ? { timeoutMs } : {}),
+                ...(network ? { network } : {}),
             },
             ...(v['no-lockfile'] ? { lockfile: false } : {}),
             ...(base !== undefined ? { baseImage: base } : {}),

package/lib/src/cli/registry.js

@@ -1,3 +1,4 @@
+import { NETWORK_OPTIONS, networkHelp, networkOption } from './network.js';
 import { insecureRegistriesFromEnv, makeClient } from '../base-image.js';
 import { SitefileError } from '../errors.js';
 import { parseRef, refKey, withDefaultRegistry, canonicalRef } from '../ref.js';
@@ -30,9 +31,11 @@ const COMMON_FLAGS = [
     '                                    $SITEFILE_REGISTRY_AUTH or ~/.docker/config.json (auths, credHelpers, credsStore)',
     '--password-stdin                    read the password from stdin',
     '--allow-private-network             let redirects/token servers on other hosts resolve to private addresses',
-    '--timeout <ms>                      per-request idle timeout (default 30000)',
+    '--timeout <ms>                      per-request idle timeout (default 30000; --read-timeout wins)',
+    ...networkHelp(36),
 ];
 const COMMON_OPTIONS = {
+    ...NETWORK_OPTIONS,
     'insecure-registry': { type: 'string', multiple: true },
     username: { type: 'string' },
     'password-stdin': { type: 'boolean' },
@@ -52,12 +55,14 @@ async function clientOptions(v) {
     }
     const timeoutMs = positive(str(v.timeout), '--timeout');
     const maxBlob = positive(str(v['max-download-bytes']), '--max-download-bytes');
+    const network = networkOption(v);
     return {
         explicit,
         options: {
             insecureRegistries: insecureRegistriesFromEnv(strs(v['insecure-registry'])),
             allowPrivateNetwork: !!v['allow-private-network'],
             limits: { ...(timeoutMs ? { timeoutMs } : {}), ...(maxBlob ? { maxBlobBytes: maxBlob } : {}) },
+            ...(network ? { network } : {}),
         },
     };
 }