@johnhenry/sitefile 0.0.0 → 0.0.1

package/CHANGELOG.md

@@ -1,5 +1,109 @@
 # Changelog
 
+## 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

package/README.md

@@ -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
@@ -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).
@@ -451,25 +457,57 @@ tools are code, and run only when you name them on the command line.
 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 } : {}),
         },
     };
 }

package/lib/src/cli/servers.js

@@ -33,12 +33,26 @@ export function parsePublish(spec) {
     return { host, port };
 }
 const isWildcard = (h) => h === '0.0.0.0' || h === '::';
+async function isFile(p) {
+    return fs.stat(p).then((s) => s.isFile(), () => false);
+}
+/** An archive file source: labelled by its absolute path, stored by its real path. */
+async function archiveSource(arg) {
+    const file = path.resolve(arg);
+    return { label: file, source: { kind: 'archive', path: await fs.realpath(file).catch(() => file) } };
+}
+/**
+ * A directory or archive file when `arg` looks like a path, else an image reference or ID, else an
+ * archive file by that name (`site.zip`). Whether a file is an archive is checked when it is loaded.
+ */
 async function resolveSource(store, arg) {
     if (/^(\.\.?|~.*|\.\.?\/.*|\/.*|.*\/)$/.test(arg)) {
         const dir = path.resolve(arg);
+        if (await isFile(dir))
+            return archiveSource(arg);
         const st = await fs.stat(dir).catch(() => undefined);
         if (!st?.isDirectory())
-            throw new SitefileError('E_NOT_FOUND', `'${arg}' is not a directory`);
+            throw new SitefileError('E_NOT_FOUND', `'${arg}' is not a directory or a file`);
         return { label: dir, source: { kind: 'dir', path: await fs.realpath(dir) } };
     }
     try {
@@ -48,6 +62,8 @@ async function resolveSource(store, arg) {
         if (e instanceof SitefileError && e.code === 'E_NOT_FOUND' && (await fs.stat(arg).then((s) => s.isDirectory(), () => false))) {
             throw new SitefileError('E_NOT_FOUND', `${e.message} (to serve the directory, write ./${arg})`);
         }
+        if (await isFile(arg))
+            return archiveSource(arg);
         throw e;
     }
 }
@@ -88,9 +104,9 @@ async function startDetached(reg, state) {
 }
 const run = {
     name: 'serve',
-    summary: 'serve an image or directory over HTTP',
-    usage: 'serve [--name n] [-p [host:]port] [-d] [--spa] <ref|id|./dir>  |  serve --watch [options] [context]',
-    description: 'Serve an image from the local store, or a directory (a snapshot read at start; paths starting with ./, ../ or /),\nover HTTP. GET and HEAD only; no directory listings. Binds 127.0.0.1 on a free port unless -p is given;\n0.0.0.0 is bound only when you pass it explicitly. Foreground by default (Ctrl-C stops it); -d detaches and\nrecords the server for servers, server stop, rm, logs and restart.\n\nWith --watch the argument is a build context (default .): its Sitefile is built in memory and served, rebuilt\nwhen the context, the Sitefile or a --build-arg-file changes, and open pages reload after each good rebuild\n(HTML responses get a small script listening on /__sitefile/reload). A failed rebuild keeps serving the last\ngood build. Nothing is written to the context except Sitefile.lock.',
+    summary: 'serve an image, directory or archive file over HTTP',
+    usage: 'serve [--name n] [-p [host:]port] [-d] [--spa] <ref|id|./dir|file>  |  serve --watch [options] [context]',
+    description: 'Serve an image from the local store, a directory (paths starting with ./, ../ or /), or an archive file over HTTP:\nzip, tar, tar.gz, wbn, or an OCI archive as build -o x.oci.tar and save write it (the format is read from the\nbytes). A directory or archive is a snapshot read at start. GET and HEAD only; no directory listings.\nBinds 127.0.0.1 on a free port unless -p is given;\n0.0.0.0 is bound only when you pass it explicitly. Foreground by default (Ctrl-C stops it); -d detaches and\nrecords the server for servers, server stop, rm, logs and restart.\n\nWith --watch the argument is a build context (default .): its Sitefile is built in memory and served, rebuilt\nwhen the context, the Sitefile or a --build-arg-file changes, and open pages reload after each good rebuild\n(HTML responses get a small script listening on /__sitefile/reload). A failed rebuild keeps serving the last\ngood build. Nothing is written to the context except Sitefile.lock.',
     flags: [
         '--name <n>        name for the server (-d only; default site-<6 hex>)',
         '-p, --publish <[host:]port>  address to bind (default 127.0.0.1, a free port)',
@@ -123,7 +139,7 @@ const run = {
         for (const f of WATCH_ONLY)
             if (v[f] !== undefined)
                 usage(`--${f} needs --watch`);
-        requireArgs(pos, 1, 1, 'an image reference or ./directory');
+        requireArgs(pos, 1, 1, 'an image reference, ./directory or archive file');
         const bind = parsePublish(str(v.publish));
         const name = str(v.name);
         if (name !== undefined && !v.detach)
@@ -141,7 +157,7 @@ const run = {
             await closeServer(server);
             return 0;
         }
-        await loadServedTree(store, source); // fail fast on a bad image or directory
+        await loadServedTree(store, source); // fail fast on a bad image, directory or archive
         const reg = await ServerRegistry.open(store);
         const { id, name: finalName } = await reg.allocate(name);
         const state = {
@@ -415,7 +431,7 @@ const restart = {
     name: 'restart',
     summary: 'restart a site server',
     usage: 'server restart [--time secs] <name|id>',
-    description: 'Stop the server if it is running, then start it again with the same name, image and bind address.\nImages are served by the same image ID; a directory is re-read.',
+    description: 'Stop the server if it is running, then start it again with the same name, image and bind address.\nImages are served by the same image ID; a directory or archive file is re-read.',
     flags: ['--time <secs>   grace period before SIGKILL (default 5)'],
     options: { time: { type: 'string' } },
     async run(v, pos) {