prerender-crawler 0.1.0 → 0.2.0

package/README.md

@@ -2,7 +2,44 @@
 
 Framework-agnostic build-time prerendering. Point it at anything fetch-shaped — `Request` in, `Response` out — and it crawls the site into static files: seed pages, link discovery, header hints, redirects, retries, throttling, and an integration seam for capturing build-time data alongside the pages. No browser, no subprocess, no framework knowledge.
 
-Ships as an engine (`prerender-crawler`) and a Vite plugin built on it (`prerender-crawler/vite`).
+Ships as an engine (`prerender-crawler`), a Vite plugin built on it (`prerender-crawler/vite`), a CLI for everything else, and one tiny module for the app's own server (`prerender-crawler/announce`) so it can tell the crawl which pages it has.
+
+## CLI
+
+Prerender any running server, or any module exporting a request handler, with no framework integration at all:
+
+```sh
+# a running server — a framework's preview server, a container, a staging deploy
+npx prerender-crawler http://localhost:3000 --out dist
+
+# a built server module (handleRequest, fetch, or default.fetch), in-process
+npx prerender-crawler dist/server/server.js --out dist/client --redirects
+```
+
+```
+prerender-crawler <target> --out <dir> [options]
+  -o, --out <dir>          Output directory (required)
+  -p, --page <path>        Seed page; repeatable. Default: /
+  -m, --mode <mode>        static (default) or hybrid
+  -c, --concurrency <n>    Pages in flight at once. Default: 8
+  -i, --interval <ms>      Minimum ms between request starts. Default: 0
+  -r, --retries <n>        Re-fetch attempts for a failed page. Default: 2
+      --origin <url>       Origin requests are minted under (module targets)
+      --hint-header <name> Response header naming extra paths. Default: x-prerender
+      --redirects          Write redirects as _redirects rules instead of stubs
+      --redirects-file <f> Rules file name (implies --redirects). Default: _redirects
+      --sitemap <origin>   Write sitemap.xml with entries under this public origin
+      --sitemap-file <f>   Sitemap file name. Default: sitemap.xml
+      --report             Write a JSON report of the crawl (pages, timings, referrers, ...)
+      --report-file <f>    Report file name (implies --report). Default: prerender-report.json
+      --keep-query         Render /posts?page=2 apart from /posts (see Query strings)
+      --no-links           Do not follow links in rendered pages
+      --no-redirect-stubs  Write no meta-refresh stubs at redirected paths
+      --continue           Skip pages that fail instead of failing the run
+      --flat               Write /about as about.html instead of about/index.html
+```
+
+For an HTTP target the crawl origin is the target's, so absolute links in the rendered HTML count as same-origin.
 
 ## Vite plugin
 
@@ -19,22 +56,20 @@ export default defineConfig({
 });
 ```
 
-The plugin is build-only. It assumes three things about the app:
+The plugin is build-only. It assumes two things about the app:
 
 1. `vite build` produces a client output directory (the `client` environment's `outDir`, default `dist/client`).
 2. Some environment's output includes a module exporting a request handler — `handleRequest`, `fetch`, or `default.fetch`. Default: `server.js` in the `ssr` environment's `outDir`; override with `serverEntry`.
-3. Optionally, a [`filesystem-routing`](https://www.npmjs.com/package/filesystem-routing) route directory names the static pages.
 
-After the other environments build, it imports the server handler and crawls it in-process. Pages and integration-emitted files land in the client output.
+After the other environments build, it imports the server handler and crawls it in-process. Pages and integration-emitted files land in the client output. Which pages exist is the server's to say — see [Announcing pages](#announcing-pages).
 
 ### Options
 
 Everything from [`PrerenderOptions`](#engine-options) plus:
 
-| Option        | Default                  |                                                                                                                                                                                                                                                                                                                                                             |
-| ------------- | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `serverEntry` | `<ssr outDir>/server.js` | Built module exporting the handler.                                                                                                                                                                                                                                                                                                                         |
-| `fileRoutes`  | `true`                   | Seed the crawl with the static pages of the project's `filesystem-routing` directory. `true` applies when the package and `src/routes` exist and is skipped silently otherwise; pass `{ dir, extensions }` to mirror a customized `fileRoutes()` (then a missing package is an error); `false` disables. Dynamic routes are still found by following links. |
+| Option        | Default                  |                                     |
+| ------------- | ------------------------ | ----------------------------------- |
+| `serverEntry` | `<ssr outDir>/server.js` | Built module exporting the handler. |
 
 ### `import.meta.env.PRERENDER_MODE`
 
@@ -49,42 +84,115 @@ The one distinction every downstream policy keys on:
 
 ## Engine
 
-The plugin is a thin driver. The engine works with any transport:
+The plugin and CLI are thin drivers. The engine works with any transport — anything with a `fetch(request: Request): Promise<Response>`:
 
 ```ts
-import { runPrerender } from "prerender-crawler";
+import { runPrerender, httpTransport, moduleTransport } from "prerender-crawler";
 
 const result = await runPrerender({
-  transport: { fetch: request => app.handle(request) },
+  transport: { fetch: request => app.handle(request) }, // or:
+  // transport: httpTransport("http://localhost:3000"),   a running server
+  // transport: await moduleTransport("dist/server.js"),  a handler module
   outDir: "dist",
   pages: ["/", "/about", { path: "/404", filename: "404.html" }],
   mode: "static"
 });
 
-result.pages; // RenderedPage[] — path, referrers, filename, emitted, html
-result.files; // EmittedFile[]  — what integrations emitted
-result.skipped; // SkippedPage[]  — failures left out (failOnError: false)
+result.pages; // RenderedPage[]   — path, referrers, filename, emitted, response, duration, html, redirect?
+result.redirects; // RedirectRecord[] — { from, to, status }, one per redirected path
+result.files; // EmittedFile[]    — what integrations emitted
+result.skipped; // SkippedPage[]    — failures left out (failOnError: false)
+```
+
+`httpTransport` sends the crawl's requests to the target's origin (path and query kept) and hands redirects back as the 3xx responses the server sent. Pass `{ headers }` for an auth token or `{ fetch }` for a custom implementation. `moduleTransport` imports a module exporting `handleRequest`, `fetch`, or `default.fetch` and calls it directly.
+
+### Announcing pages
+
+The crawl finds pages by following links and by reading the hint header (`x-prerender`, comma-separated paths) off responses. A page nothing links to is invisible to the first; the second is how a server that knows its routes declares them — and the thing that knows the routes is the router the app built for the request. The crawler knows no router; it only defines the wire. `prerender-crawler/announce` is that wire, free of Node imports so application server code can use it:
+
+```ts
+import { announcePages } from "prerender-crawler/announce";
+
+// in the request handler, with whatever the router exposes — e.g. TanStack Router:
+const pages = Object.entries(router.routesByPath)
+  .filter(
+    ([path, route]) => !path.includes("$") && (route.fullPath.endsWith("/") || !route.children)
+  )
+  .map(([path]) => path);
+announcePages(request, response.headers, pages);
+```
+
+`announcePages` writes the header only when the request is the crawler's (it carries the hint header) — a visitor's response is untouched. What to announce: the paths that address a static page — no parameters or splats (only a render knows their values; the crawl finds those pages by their links), leaves and indexes (a layout with children but no index has no page of its own). The Vite plugin, the CLI against a module, and the CLI against a running server all send the hint header, so one line in the app seeds all three.
+
+Enumerating a specific router's static pages is the framework integration's job, not this package's: [`@solidjs/prerender`](../solid) ships `solidRouterPages`, `tanstackRouterPages`, and `announceRoutes(router)` (which also reads the request from the ambient request event) for the routers Solid apps use.
+
+### Redirects
+
+A path that answers 3xx is recorded (`result.redirects`, one record per hop — `/a → /b → /c` is two records, the way host rules spell it) and its same-origin target is crawled as a page in its own right, so the destination renders once at its own URL. The redirected path itself gets a **meta-refresh stub** pointing at the chain's final destination, so the old URL keeps working on hosts with no redirect support. A redirect to another spelling of the same page (`/posts → /posts/`) is followed in place, not recorded.
+
+Hosts with real redirect rules do better than stubs:
+
+```ts
+import { redirects } from "prerender-crawler";
+
+runPrerender({ integrations: [redirects()] }); // or prerender({ integrations: [redirects()] })
+```
+
+`redirects()` emits a `_redirects` file (`/from /to 301`, the format Netlify and Cloudflare Pages share) and declares `handlesRedirects`, which stops the engine writing stubs — necessary on Netlify, where an existing file shadows the rule. Options: `filename`, `force` (Netlify's `301!`), and `format(records)` for another host's syntax.
+
+### Sitemap
+
+```ts
+import { sitemap } from "prerender-crawler";
+
+runPrerender({ integrations: [sitemap({ hostname: "https://example.com" })] });
+```
+
+Every rendered page becomes a `<url>` entry — the crawl knows the one thing a route manifest cannot, which pages actually exist with dynamic segments expanded. Redirect stubs, non-HTML responses, query spellings, and pages marked `noindex` (`<meta name="robots">` in the head or an `X-Robots-Tag` header) are left out, the same signals a search engine honors on the live site. Options: `filename`, `trailingSlash`, `filter(page)` for further exclusions, and `entry(page)` returning `lastmod` / `changefreq` / `priority` per page. `indexable(page)` and `formatSitemap(entries)` are exported for tooling that formats its own.
+
+### Report
+
+```ts
+import { report } from "prerender-crawler";
+
+runPrerender({ integrations: [report({ filename: "../prerender-report.json" })] });
+```
+
+Writes what the crawl did as JSON: every page with its status, content type, duration, output file, whether it was written and which pages linked to it; every redirect; every skipped page with its error and referrers; every file other integrations emitted; and totals. It answers "why was this page crawled", "which pages are slow" and "what did the build produce" after the process is gone. The default filename lands in the output directory and deploys with the site — `../` keeps it a build artifact.
+
+### Query strings
+
+By default the query is stripped from every URL the crawl sees: `/posts`, `/posts?page=2` and `/posts?utm=x` are one page, rendered once. That is what a static host can serve — a file at a path, the same for every query.
+
+`keepQuery: true` makes each query spelling a page of its own (parameters sorted, so `?a=1&b=2` and `?b=2&a=1` meet). Each renders separately — its links are followed, its data captured — but is **written only when its seed entry names a `filename`**, because `posts/index.html` is already `/posts`. It exists for hybrid builds baking per-query data, and for sites that map queries onto files themselves:
+
+```ts
+runPrerender({
+  keepQuery: true,
+  pages: [{ path: "/posts?page=2", filename: "posts/page/2/index.html" }]
+});
 ```
 
 ### Engine options
 
-| Option                   | Default                        |                                                                                                                                                                                         |
-| ------------------------ | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `mode`                   | `"static"`                     | See [Modes](#modes). Decides the `emitPages` default.                                                                                                                                   |
-| `pages`                  | `["/"]`                        | Seeds: strings, `{ path, filename?, emit? }` entries, or a (async) function returning them. Duplicates collapse to one render.                                                          |
-| `crawlLinks`             | `true`                         | Follow same-origin links in rendered HTML. The only way dynamic routes are discovered without explicit seeding.                                                                         |
-| `hintHeader`             | `"x-prerender"`                | Response header naming additional paths (comma-separated) — the route the data lives on announces the routes built from it.                                                             |
-| `filter`                 |                                | `(path) => boolean`; drops a discovered path before it's fetched.                                                                                                                       |
-| `concurrency`            | `8`                            | Pages in flight at once.                                                                                                                                                                |
-| `interval`               | `0`                            | Minimum ms between the starts of consecutive requests across all workers — a throttle for renders hitting rate-limited APIs.                                                            |
-| `retries` / `retryDelay` | `2` / `500`                    | Re-fetch attempts for a failed page, and the wait between them.                                                                                                                         |
-| `failOnError`            | `true`                         | Whether a page that still fails after retries fails the run. Otherwise it's reported in `skipped`, with the pages that linked to it.                                                    |
-| `maxRedirects`           | `5`                            | Internal redirect hops followed for one page.                                                                                                                                           |
-| `emitPages`              | `true` static / `false` hybrid | Whether rendered pages are written: a boolean, or a per-path predicate. Per-entry `emit` overrides. Unemitted pages still render fully — links are still followed, data still captured. |
-| `autoSubfolderIndex`     | `true`                         | `/about` → `about/index.html` (true) or `about.html` (false).                                                                                                                           |
-| `origin`                 | `"http://localhost"`           | Origin requests are minted under.                                                                                                                                                       |
-| `onRendered`             |                                | Observes every rendered page — the seam for sitemaps and post-processing.                                                                                                               |
-| `integrations`           | `[]`                           | See below.                                                                                                                                                                              |
+| Option                   | Default                                         |                                                                                                                                                                                         |
+| ------------------------ | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `mode`                   | `"static"`                                      | See [Modes](#modes). Decides the `emitPages` default.                                                                                                                                   |
+| `pages`                  | `["/"]`                                         | Seeds: strings, `{ path, filename?, emit? }` entries, or a (async) function returning them. Duplicates collapse to one render.                                                          |
+| `crawlLinks`             | `true`                                          | Follow same-origin links in rendered HTML. The only way dynamic routes are discovered without explicit seeding.                                                                         |
+| `hintHeader`             | `"x-prerender"`                                 | Response header naming additional paths (comma-separated). See [Announcing pages](#announcing-pages).                                                                                   |
+| `filter`                 |                                                 | `(path) => boolean`; drops a discovered path before it's fetched.                                                                                                                       |
+| `keepQuery`              | `false`                                         | Render query spellings as distinct pages. See [Query strings](#query-strings).                                                                                                          |
+| `concurrency`            | `8`                                             | Pages in flight at once.                                                                                                                                                                |
+| `interval`               | `0`                                             | Minimum ms between the starts of consecutive requests across all workers — a throttle for renders hitting rate-limited APIs.                                                            |
+| `retries` / `retryDelay` | `2` / `500`                                     | Re-fetch attempts for a failed page, and the wait between them.                                                                                                                         |
+| `failOnError`            | `true`                                          | Whether a page that still fails after retries fails the run. Otherwise it's reported in `skipped`, with the pages that linked to it.                                                    |
+| `redirectStubs`          | `true` unless an integration `handlesRedirects` | Whether redirected paths get a meta-refresh stub file pointing at the chain's end. See [Redirects](#redirects).                                                                         |
+| `emitPages`              | `true` static / `false` hybrid                  | Whether rendered pages are written: a boolean, or a per-path predicate. Per-entry `emit` overrides. Unemitted pages still render fully — links are still followed, data still captured. |
+| `autoSubfolderIndex`     | `true`                                          | `/about` → `about/index.html` (true) or `about.html` (false).                                                                                                                           |
+| `origin`                 | `"http://localhost"`                            | Origin requests are minted under.                                                                                                                                                       |
+| `onRendered`             |                                                 | Observes every rendered page as it lands — for post-processing. Integrations see the same pages on `context.pages`.                                                                     |
+| `integrations`           | `[]`                                            | See below.                                                                                                                                                                              |
 
 ### Integrations
 
@@ -95,6 +203,7 @@ interface PrerenderIntegration {
   name: string;
   setup?(context: PrerenderContext): void | Promise<void>; // before the first render
   teardown?(context: PrerenderContext): void | Promise<void>; // after the last render, before writes
+  handlesRedirects?: boolean; // "I write host redirect rules" — the engine skips its stubs
   client?: string; // module a bundler plugin imports into the client build (reserved)
 }
 
@@ -102,20 +211,28 @@ interface PrerenderContext {
   mode: PrerenderMode;
   origin: string;
   outDir: string;
+  pages: readonly RenderedPage[]; // complete by teardown
+  redirects: readonly RedirectRecord[]; // complete by teardown
+  skipped: readonly SkippedPage[]; // complete by teardown
+  files: readonly EmittedFile[]; // what earlier integrations emitted
   emitFile(file: { filename: string; contents: string | Uint8Array }): void;
 }
 ```
 
-`emitFile` is the channel for artifacts produced during the crawl — captured server-function results, extracted payloads, sitemaps. Throwing from `teardown` fails the run: the place to verify the crawl produced everything the runtime half will need. [`@solidjs/prerender`](../solid) is the reference integration.
+`emitFile` is the channel for artifacts produced during the crawl — captured server-function results, extracted payloads, sitemaps. Filenames resolve against the output directory; `../` or an absolute path lands outside it. Throwing from `teardown` fails the run: the place to verify the crawl produced everything the runtime half will need. `redirects()`, `sitemap()` and `report()` above are the shipped examples, each a formatter over the context; [`@solidjs/prerender`](../solid) is the reference integration with a runtime half.
 
 ### Utilities
 
-- `fileRoutePages({ root, dir, extensions })` / `staticRoutePaths(entries)` — the static page paths of a `filesystem-routing` manifest, as a `pages` source.
-- `extractLinks(html)`, `normalizeLink(href, from)`, `normalizePath(path)`, `outputFilename(path, autoSubfolderIndex)` — the crawl's own primitives.
+- `httpTransport(target, { headers?, fetch? })`, `moduleTransport(entry)`, `loadHandler(entry)` — the shipped transports.
+- `redirects(options?)`, `formatRedirectsFile(records, force?)` — the redirects integration and its `_redirects` formatter.
+- `sitemap(options)`, `indexable(page)`, `formatSitemap(entries)` — the sitemap integration and its parts.
+- `report(options?)` — the crawl report integration.
+- `prerender-crawler/announce`: `announcePages(request, headers, paths, { header? })`, `HINT_HEADER` — the wire, for application server code.
+- `extractLinks(html, pageUrl, { keepQuery? })`, `normalizeLink(href, base, origin)`, `normalizeRoute(url)`, `normalizePath(pathname)`, `splitRoute(route)`, `outputFilename(path, autoSubfolderIndex)` — the crawl's own primitives.
 
 ## Requirements
 
-Node 20+. Vite 7 or 8 for the plugin (optional peer). `filesystem-routing` ≥ 0.2 for route seeding (optional peer).
+Node 20+. Vite 7 or 8 for the plugin (optional peer).
 
 ## License
 

package/dist/announce.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The announce protocol: how a server tells a crawl which pages it has.
+ *
+ * The crawl finds pages by following links and by reading the hint header
+ * (`x-prerender`, comma-separated paths) off responses. A route nothing
+ * links to is invisible to the first; the second is how a server that
+ * KNOWS its routes declares them — and the thing that knows the routes is
+ * the router the app built for the request. Which routes count is the
+ * router's business, so the enumeration lives with the framework
+ * integration (`@solidjs/prerender` ships Solid Router's and TanStack
+ * Router's); this module is only the wire: put the paths on the header
+ * when the request is the crawler's. Every crawl — the Vite plugin, the
+ * CLI against a built module, the CLI against a running server — sends
+ * the hint request header and seeds from the answer.
+ *
+ * What to announce: paths that address a static page. No parameters or
+ * splats (only a render knows their values; the crawl finds them by their
+ * links), leaves and indexes (a layout with children but no index has no
+ * page of its own). One spelling per page — the engine normalizes trailing
+ * slashes, so either is fine.
+ *
+ * Imported by application SERVER code: no Node imports here.
+ */
+/** The hint header the engine reads, and the request header it sends. */
+export declare const HINT_HEADER = "x-prerender";
+export interface AnnounceOptions {
+    /** The header name, if the crawl was configured with a custom `hintHeader`. @default "x-prerender" */
+    header?: string;
+}
+/**
+ * Puts `paths` on the response's hint header — when the request is the
+ * crawler's (it carries the hint header). Returns whether it did. A
+ * regular visitor's response is left untouched.
+ *
+ * ```ts
+ * announcePages(event.request, event.response.headers, staticPaths);
+ * ```
+ */
+export declare function announcePages(request: Request, headers: Headers, paths: readonly string[], options?: AnnounceOptions): boolean;

package/dist/announce.js

@@ -0,0 +1,41 @@
+/**
+ * The announce protocol: how a server tells a crawl which pages it has.
+ *
+ * The crawl finds pages by following links and by reading the hint header
+ * (`x-prerender`, comma-separated paths) off responses. A route nothing
+ * links to is invisible to the first; the second is how a server that
+ * KNOWS its routes declares them — and the thing that knows the routes is
+ * the router the app built for the request. Which routes count is the
+ * router's business, so the enumeration lives with the framework
+ * integration (`@solidjs/prerender` ships Solid Router's and TanStack
+ * Router's); this module is only the wire: put the paths on the header
+ * when the request is the crawler's. Every crawl — the Vite plugin, the
+ * CLI against a built module, the CLI against a running server — sends
+ * the hint request header and seeds from the answer.
+ *
+ * What to announce: paths that address a static page. No parameters or
+ * splats (only a render knows their values; the crawl finds them by their
+ * links), leaves and indexes (a layout with children but no index has no
+ * page of its own). One spelling per page — the engine normalizes trailing
+ * slashes, so either is fine.
+ *
+ * Imported by application SERVER code: no Node imports here.
+ */
+/** The hint header the engine reads, and the request header it sends. */
+export const HINT_HEADER = "x-prerender";
+/**
+ * Puts `paths` on the response's hint header — when the request is the
+ * crawler's (it carries the hint header). Returns whether it did. A
+ * regular visitor's response is left untouched.
+ *
+ * ```ts
+ * announcePages(event.request, event.response.headers, staticPaths);
+ * ```
+ */
+export function announcePages(request, headers, paths, options = {}) {
+    const { header = HINT_HEADER } = options;
+    if (!request.headers.has(header) || paths.length === 0)
+        return false;
+    headers.set(header, paths.join(","));
+    return true;
+}

package/dist/cli-main.d.ts

@@ -0,0 +1,7 @@
+export declare const USAGE = "Usage: prerender-crawler <target> --out <dir> [options]\n\nPrerenders a site into static files by crawling it.\n\n  <target>                 An http(s) origin of a running server, or the path of a\n                           module exporting a Request -> Response handler\n                           (handleRequest, fetch, or default.fetch).\n\nOptions:\n  -o, --out <dir>          Output directory (required)\n  -p, --page <path>        Seed page; repeatable. Default: /\n  -m, --mode <mode>        static (default) or hybrid \u2014 see docs for what each writes\n  -c, --concurrency <n>    Pages in flight at once. Default: 8\n  -i, --interval <ms>      Minimum ms between request starts. Default: 0\n  -r, --retries <n>        Re-fetch attempts for a failed page. Default: 2\n      --origin <url>       Origin requests are minted under (module targets).\n                           Default: http://localhost\n      --hint-header <name> Response header naming extra paths. Default: x-prerender\n      --redirects          Write the redirects as host rules (_redirects format,\n                           Netlify / Cloudflare Pages) instead of meta-refresh stubs\n      --redirects-file <f> Rules file name (implies --redirects). Default: _redirects\n      --sitemap <origin>   Write sitemap.xml with entries under this public origin\n                           (https://example.com)\n      --sitemap-file <f>   Sitemap file name. Default: sitemap.xml\n      --report             Write a JSON report of the crawl (pages, timings, referrers,\n                           redirects, skips)\n      --report-file <f>    Report file name (implies --report). Resolved against the\n                           output dir; ../ keeps it out of the deploy.\n                           Default: prerender-report.json\n      --keep-query         Render /posts?page=2 apart from /posts (not written unless\n                           the app maps queries to files \u2014 see docs)\n      --no-links           Do not follow links in rendered pages\n      --no-redirect-stubs  Write no meta-refresh stubs at redirected paths\n      --continue           Skip pages that fail instead of failing the run\n      --flat               Write /about as about.html instead of about/index.html\n  -h, --help               Show this help\n";
+export interface CliIO {
+    stdout(line: string): void;
+    stderr(line: string): void;
+}
+/** Runs the CLI for `argv` (without the node and script entries). Returns the exit code. */
+export declare function main(argv: string[], io: CliIO): Promise<number>;

package/dist/cli-main.js

@@ -0,0 +1,181 @@
+// The CLI's logic, separated from the executable entry (./cli.ts) so tests
+// can drive it with an argv and capture its output.
+import path from "node:path";
+import { parseArgs } from "node:util";
+import { runPrerender } from "./crawl.js";
+import { redirects } from "./redirects.js";
+import { report } from "./report.js";
+import { sitemap } from "./sitemap.js";
+import { httpTransport, moduleTransport } from "./transports.js";
+export const USAGE = `Usage: prerender-crawler <target> --out <dir> [options]
+
+Prerenders a site into static files by crawling it.
+
+  <target>                 An http(s) origin of a running server, or the path of a
+                           module exporting a Request -> Response handler
+                           (handleRequest, fetch, or default.fetch).
+
+Options:
+  -o, --out <dir>          Output directory (required)
+  -p, --page <path>        Seed page; repeatable. Default: /
+  -m, --mode <mode>        static (default) or hybrid — see docs for what each writes
+  -c, --concurrency <n>    Pages in flight at once. Default: 8
+  -i, --interval <ms>      Minimum ms between request starts. Default: 0
+  -r, --retries <n>        Re-fetch attempts for a failed page. Default: 2
+      --origin <url>       Origin requests are minted under (module targets).
+                           Default: http://localhost
+      --hint-header <name> Response header naming extra paths. Default: x-prerender
+      --redirects          Write the redirects as host rules (_redirects format,
+                           Netlify / Cloudflare Pages) instead of meta-refresh stubs
+      --redirects-file <f> Rules file name (implies --redirects). Default: _redirects
+      --sitemap <origin>   Write sitemap.xml with entries under this public origin
+                           (https://example.com)
+      --sitemap-file <f>   Sitemap file name. Default: sitemap.xml
+      --report             Write a JSON report of the crawl (pages, timings, referrers,
+                           redirects, skips)
+      --report-file <f>    Report file name (implies --report). Resolved against the
+                           output dir; ../ keeps it out of the deploy.
+                           Default: prerender-report.json
+      --keep-query         Render /posts?page=2 apart from /posts (not written unless
+                           the app maps queries to files — see docs)
+      --no-links           Do not follow links in rendered pages
+      --no-redirect-stubs  Write no meta-refresh stubs at redirected paths
+      --continue           Skip pages that fail instead of failing the run
+      --flat               Write /about as about.html instead of about/index.html
+  -h, --help               Show this help
+`;
+/** Runs the CLI for `argv` (without the node and script entries). Returns the exit code. */
+export async function main(argv, io) {
+    const parsed = parse(argv);
+    if ("error" in parsed) {
+        io.stderr(`${parsed.error}\n\n${USAGE}`);
+        return 2;
+    }
+    const { values, positionals } = parsed;
+    if (values.help) {
+        io.stdout(USAGE);
+        return 0;
+    }
+    const target = positionals[0];
+    if (!target || positionals.length > 1 || !values.out) {
+        io.stderr(!target
+            ? "Missing <target>."
+            : !values.out
+                ? "Missing --out <dir>."
+                : `Unexpected argument: ${positionals[1]}.`);
+        io.stderr(`\n${USAGE}`);
+        return 2;
+    }
+    const mode = values.mode ?? "static";
+    if (mode !== "static" && mode !== "hybrid") {
+        io.stderr(`--mode must be static or hybrid, got ${mode}.`);
+        return 2;
+    }
+    let transport;
+    let origin = values.origin;
+    try {
+        if (/^https?:\/\//.test(target)) {
+            transport = httpTransport(target);
+            origin ??= new URL(target).origin;
+        }
+        else {
+            transport = await moduleTransport(path.resolve(target));
+        }
+    }
+    catch (error) {
+        io.stderr(describe(error));
+        return 1;
+    }
+    const integrations = [];
+    if (values.redirects || values["redirects-file"] !== undefined) {
+        integrations.push(redirects({ filename: values["redirects-file"] }));
+    }
+    if (values.sitemap !== undefined || values["sitemap-file"] !== undefined) {
+        if (!values.sitemap || !/^https?:\/\//.test(values.sitemap)) {
+            io.stderr(`--sitemap needs the site's public origin (https://example.com).`);
+            return 2;
+        }
+        integrations.push(sitemap({ hostname: values.sitemap, filename: values["sitemap-file"] }));
+    }
+    if (values.report || values["report-file"] !== undefined) {
+        integrations.push(report({ filename: values["report-file"] }));
+    }
+    const outDir = path.resolve(values.out);
+    try {
+        const result = await runPrerender({
+            transport,
+            outDir,
+            mode: mode,
+            origin,
+            pages: values.page?.length ? values.page : undefined,
+            concurrency: values.concurrency !== undefined ? integer(values.concurrency) : undefined,
+            interval: values.interval !== undefined ? integer(values.interval) : undefined,
+            retries: values.retries !== undefined ? integer(values.retries) : undefined,
+            hintHeader: values["hint-header"],
+            crawlLinks: !values["no-links"],
+            keepQuery: values["keep-query"],
+            redirectStubs: values["no-redirect-stubs"] ? false : undefined,
+            failOnError: !values.continue,
+            autoSubfolderIndex: !values.flat,
+            integrations
+        });
+        const written = result.pages.filter(page => page.emitted).length;
+        const parts = [`rendered ${result.pages.length} page(s) (${written} written)`];
+        if (result.redirects.length)
+            parts.push(`${result.redirects.length} redirect(s)`);
+        if (result.files.length)
+            parts.push(`${result.files.length} file(s) emitted`);
+        const relative = path.relative(process.cwd(), outDir);
+        const shown = relative === "" ? "." : relative.startsWith("..") ? outDir : relative;
+        io.stdout(`[prerender] ${parts.join(", ")} -> ${shown}`);
+        for (const miss of result.skipped) {
+            io.stderr(`[prerender] skipped ${miss.path}: ${describe(miss.error)}`);
+        }
+        return 0;
+    }
+    catch (error) {
+        io.stderr(`[prerender] ${describe(error)}`);
+        return 1;
+    }
+}
+const spec = {
+    allowPositionals: true,
+    options: {
+        out: { type: "string", short: "o" },
+        page: { type: "string", short: "p", multiple: true },
+        mode: { type: "string", short: "m" },
+        concurrency: { type: "string", short: "c" },
+        interval: { type: "string", short: "i" },
+        retries: { type: "string", short: "r" },
+        origin: { type: "string" },
+        "hint-header": { type: "string" },
+        redirects: { type: "boolean" },
+        "redirects-file": { type: "string" },
+        sitemap: { type: "string" },
+        "sitemap-file": { type: "string" },
+        report: { type: "boolean" },
+        "report-file": { type: "string" },
+        "keep-query": { type: "boolean" },
+        "no-links": { type: "boolean" },
+        "no-redirect-stubs": { type: "boolean" },
+        continue: { type: "boolean" },
+        flat: { type: "boolean" },
+        help: { type: "boolean", short: "h" }
+    }
+};
+function parse(argv) {
+    try {
+        return parseArgs({ args: argv, ...spec });
+    }
+    catch (error) {
+        return { error: describe(error) };
+    }
+}
+function integer(value) {
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed < 0) {
+        throw new Error(`Expected a non-negative integer, got ${JSON.stringify(value)}.`);
+    }
+    return parsed;
+}
+const describe = (error) => (error instanceof Error ? error.message : String(error));

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import { main } from "./cli-main.js";
+process.exitCode = await main(process.argv.slice(2), {
+    stdout: line => console.log(line),
+    stderr: line => console.error(line)
+});