@jimhoyd/urlcode 0.4.2 → 0.4.7

package/docs/FUNCTION-SECURITY.md

@@ -1,251 +0,0 @@
-# Function execution: trusted by default, sandboxed opt-in
-
-`function` and `middleware` routes run **trusted and unsandboxed by default**:
-in the host process, with full Node, filesystem and network access, exactly
-like any other project code (docs/SPIKE-DEFAULT-TRUST-MODEL.md). This is a
-deliberate, maintainer-decided reversal of alpha.2's blanket sandbox — see
-that spike document for the full rationale. It is a call the project makes,
-not a property the runtime can verify: URLCode cannot know whether your code
-is safe to trust, only whether you asked for isolation.
-
-Declare `sandbox: true` on a route when its code specifically warrants
-isolation: it processes input from a source the project doesn't fully trust
-(a third-party webhook payload, for example), it is a contribution nobody on
-the team has reviewed, or it handles a secret sensitive enough that a bug in
-that one route should not be able to reach the rest of the process or the
-filesystem. A sandboxed route runs in QuickJS inside WebAssembly, in a
-separate worker thread, with none of the host access described below — its
-guarantees are unchanged from every earlier release and are described in
-full in the rest of this document. Absence of `sandbox` (or `sandbox: false`)
-means trusted; there is no separate `unsafe`/`trusted` field to opt back into
-the old sandboxed-by-default behavior — set `sandbox: true` per route instead.
-
-**Either way, binding grants are unaffected.** Trusting a route's code by
-default does not grant it any `env`/`secrets` it was not explicitly declared
-in YAML and approved by an operator policy pinned to the project revision
-(see "Granting selected bindings" below). A trusted function only *can* do
-more with Node once it runs — it does not receive anything more than a
-sandboxed one would.
-
-This is a claim about `context`/`context.secrets` injection, not an
-access-control guarantee on trusted code. The binding grant governs only what
-URLCode hands a route through `context`; it does not restrict what trusted
-(non-`sandbox`) code can independently do, because that code has full Node
-access by design. A trusted function can read `process.env`, open files or
-make network calls on its own regardless of what its route was or was not
-granted — withholding a binding grant limits what URLCode gives the code
-through `context`, not what the code itself, running with full Node access,
-can go and get. A sandboxed route has no such independent access: the guest
-API is all it has, so its binding grant *is* effectively its whole reach into
-the environment. Trusted code's reach is not bounded that way; treat the
-grant as scoping `context`, not as scoping the process.
-
-## Migrating to the trusted default
-
-If you are upgrading a project from a release before this change shipped:
-**every existing `function` and `middleware` route silently changes execution
-mode**, from sandboxed to trusted, unless it already has (or you add)
-`sandbox: true`. This is a real behavior change on upgrade, not a
-documentation update — a route that used to run with no filesystem or network
-access will, after the upgrade, run with full Node access unless you opt it
-back into the sandbox.
-
-Before upgrading:
-
-- List every `function` and `middleware` route in the project.
-- For each one, decide whether you fully trust that code to run in-process
-  with full Node/filesystem/network access — the same trust you would extend
-  to any other code you deploy to that server.
-- Add `sandbox: true` explicitly to any route whose code you do not fully
-  trust, that processes input from a source you don't control, or that handles
-  a secret binding you want isolated — before you upgrade, not after.
-- Routes you do want running trusted need no change; that is now the default.
-
-The change moves the sandbox from an unconditional guarantee to an explicit,
-per-route choice, mainly for performance: the previous blanket sandbox capped
-concurrency at two workers with no queue shared across every function route on
-the server, which does not scale to real concurrent traffic. It also brings
-first-party code in line with how the rest of the Node ecosystem treats
-deployed application code. The sandbox itself is unchanged for routes that opt
-into it; only the default for routes that declare neither option has changed.
-
-## What "sandboxed" (`sandbox: true`) still guarantees
-
-- Function sources are parsed/snapshotted without importing them into Node.
-- Code runs in QuickJS inside WebAssembly, with no host JS functions/objects
-  exposed to the guest. Request/response/context use a JSON/string boundary.
-- No `process`, `require`, Node built-ins, filesystem, shell, sockets, fetch,
-  WebSocket, workers, native extensions or ambient environment is available.
-- Module resolution is restricted to the route's declared middleware and function relative JavaScript
-  dependency graphs inside the project. Symlink escapes, remote/bare imports and
-  dynamic imports in source fail. Runtime-created imports cannot broaden access.
-- A fresh guest heap/module state per invocation prevents state crossing requests.
-- 32 MiB guest heap, 512 KiB stack, source/input/output/header limits, bounded
-  concurrency, guest interruption and an independent worker termination deadline.
-- External bindings are denied by default. Project YAML cannot self-authorize.
-  Operator grants are exact-name, route-scoped and pinned to configuration/source.
-
-The guest API is intentionally narrower than Node or full Fetch; see the
-[implemented contract](SPECIFICATION.md). A function moving from trusted to
-`sandbox: true` that uses Node/network or binary/stream APIs must be rewritten
-for the supported guest profile, or stay trusted. Redirects need none of this
-machinery either way.
-
-This engine — worker spawning, the module-allowlist walk, the two-layer
-deadline, `maxBytes` and response-shape validation — is one implementation
-shared by route dispatch and by `@jimhoyd/urlcode/sandbox`'s `SandboxPool`.
-That public HTTP-shaped primitive remains available to extension authors, but
-project extension hooks use arbitrary typed values and contract v1 runs them
-trusted in-process; it rejects `sandbox: true` rather than claiming HTTP sandbox
-semantics apply to them. See [extensions](EXTENSIONS.md#project-level-lifecycle-hooks).
-
-## What the trusted default can and can't do
-
-A trusted route (no `sandbox`, or `sandbox: false`) has none of the guest
-restrictions above:
-
-- Full Node built-ins, `process`, the filesystem, `fetch`, sockets, workers
-  and npm packages are available, exactly as in any other Node module.
-- Module resolution is ordinary Node ESM resolution: bare specifiers, dynamic
-  `import()` and node_modules all work. There is no dependency-graph allowlist
-  and no per-module/total source-size budget (function-sources.ts's
-  `MODULE_LIMIT`/`MODULE_BYTE_LIMIT`/`TOTAL_BYTE_LIMIT` apply only to what a
-  sandboxed snapshot bundles).
-- Node's own module cache is shared across invocations and across the whole
-  process; there is no fresh heap per call. Module-level state persists
-  between requests exactly like an ordinary long-running Node server, so a
-  trusted function that mutates shared/global state affects later requests
-  the way hand-written server code would.
-- There is no worker-thread deadline that force-terminates a stuck call. A
-  trusted invocation races a configurable timeout, but that race can only
-  reject the *call*; it cannot preempt code that blocks the event loop
-  synchronously. See [capacity](CAPACITY.md) for what this means for one slow
-  or hung trusted route's effect on the rest of the process.
-- A snapshot reload re-imports a trusted route's own entry file fresh (each
-  reload gets its own cache-busted module registration), so editing the
-  `source` file a route declares and reloading picks up the change, the same
-  as the sandboxed pool rebuilding from scratch. A file that entry file
-  merely *imports* is not similarly busted: Node's own module cache is
-  keyed by the resolved URL of that import statement, which this runtime
-  does not rewrite, so an edited dependency two files deep from the route
-  keeps serving its old content until the process restarts. Restructure a
-  route so the code you expect to hot-reload is the declared entry file
-  itself, or restart rather than reload after editing a trusted route's
-  dependencies. A `sandbox: true` route has no such gap: reload always
-  rebuilds its whole snapshot, dependencies included.
-
-What does **not** change with trust: `args` are still exactly the validated
-values the route declares (never raw request input), and `env`/`secrets` are
-still exactly what the route's YAML requests and an operator policy grants,
-pinned to the project revision — trust changes where code runs, not what
-it is handed *through `context`*. It does not change what the code can go get
-on its own once it is running; see "binding grants are unaffected" above for
-that distinction.
-
-## Trusted code, not trusted requests
-
-"Trusted" describes the code's authorship — first-party project code you
-reviewed and deployed — not the requests it handles. Every request, in either
-mode, still carries client-controlled path, query, header and body data that is
-exactly as adversarial as it always was. Running trusted means that code
-executes with full Node access if it mishandles that input; it does not mean
-the input itself became safe to trust. Declare `parameters` and `request.body`
-validation in YAML, check `args` and any other request data again inside
-function/middleware code, and implement your own authentication and
-authorization — no route, sandboxed or trusted, adds automatic auth.
-`sandbox: true` narrows what a bug or an unreviewed dependency in the *code*
-can do with that same request data; it is not a substitute for validating or
-authenticating the request itself.
-
-## Granting selected bindings
-
-An application may request a named binding in YAML, but only an operator can
-approve it. Inspect what the app requests without executing any module:
-
-```sh
-urlcode permissions --project /srv/my-links
-```
-
-This prints a proposed JSON shape with `version: 1`, `projectSha256` and `routes`.
-It grants nothing. Review the code/configuration and keep only necessary bindings.
-Save the policy **outside the application checkout**, in an operator-controlled
-file; never let application authors or deployment artifacts overwrite it.
-
-```json
-{
-  "version": 1,
-  "projectSha256": "REPLACE_WITH_THE_REVIEWED_PROJECT_DIGEST",
-  "routes": {
-    "/customer/{id}": {
-      "env": ["API_MODE"],
-      "secrets": ["customer_api_key"]
-    }
-  }
-}
-```
-
-The placeholder deliberately does not validate. Use the actual digest produced
-by inspection. Then, with values securely injected into the process:
-
-```sh
-urlcode validate --project /srv/my-links --policy /etc/urlcode/my-links-policy.json
-urlcode serve --project /srv/my-links --policy /etc/urlcode/my-links-policy.json
-```
-
-`dev`, `test` and `validate --local` use the same policy rules even for `.env.local`.
-The JavaScript API accepts an equivalent operator-supplied `permissions` object.
-Every config change invalidates the grant, and so does a module change within
-what the approval digest actually hashes: for a sandboxed route, its
-middleware/function sources and their full dependency graph; for a trusted
-route, only its own entry-file source (see the next paragraph — a trusted
-route's transitive dependencies are explicitly **not** part of that digest).
-Inspect/review the new revision before updating the operator file. Policies
-are read at startup, not hot-reloaded. A failed development candidate leaves
-the previous approved snapshot running.
-
-Granting a secret deliberately makes it available to every middleware and function
-in that route, trusted or sandboxed alike. A sandboxed route's middleware
-sources and their full dependency graph are included in the approval digest,
-as before; a trusted route's own entry-file source is included too, so
-changing that file's content invalidates the grant, but a change to a helper
-module it merely imports does not by itself (see function-sources.ts's
-`collectTrustedSources`) — a known, documented gap versus the sandboxed path's
-full dependency-graph hashing: a trusted route's grant scope is entry-file-only,
-not transitive. Either way, code can include any granted data
-in its HTTP response: neither the sandbox nor the trusted default promises
-secrecy from code that was explicitly authorized to read a value. Minimize
-grants, use scoped/short-lived credentials and revoke/restart when needed.
-Other routes get none of that context.
-
-## Next capability work
-
-Outbound requests need a host-owned broker with explicit destination/method
-allowlists, private/metadata/loopback-address restrictions, DNS/rebinding defenses,
-redirect revalidation, deadlines and byte/concurrency limits. Application YAML
-must not grant those permissions. Persistent state needs similarly scoped access.
-Until such brokers are implemented and tested, these capabilities are unavailable
-to a *sandboxed* route. Provider adapters must preserve a `sandbox: true`
-route's isolation or reject deployment; they cannot silently downgrade a
-route that explicitly asked for the sandbox into unrestricted Node execution.
-(A trusted route, by contrast, already has unrestricted Node execution by
-design on the self-hosted target — see "What the trusted default can and
-can't do" above; non-Node targets refuse `function`/`middleware` entirely,
-trusted or sandboxed, since neither execution mode exists there.)
-
-## Verification and remaining risk
-
-Tests attempt constructor/eval escapes, Node/filesystem/shell/network imports,
-runtime-created imports, cross-request prototype/state pollution, oversized
-allocations, loops, unauthorized secret requests and stale/repo-local policies.
-These are regression tests, not a proof of complete security.
-
-The URLCode host, parser, QuickJS/WASM engine, native runtime and dependencies
-remain trusted computing components that need patching and review. Guest heap
-limits do not cap all host/WASM RSS; use OS/container memory/CPU/PID limits as an
-additional layer. Native engine bugs or resource exhaustion remain residual risks.
-For a public arbitrary-code/multi-tenant service, require independent security
-review plus process/VM-level isolation and operational controls before launch.
-Do not advertise this release as an audited hostile multi-tenant hosting platform.
-
-Implementation references: [QuickJS/WASM project](https://github.com/justjake/quickjs-emscripten)
-and its [runtime isolation/limits API](https://github.com/justjake/quickjs-emscripten/blob/main/doc/quickjs-emscripten/classes/QuickJSRuntime.md).

package/docs/HTTP.md

@@ -1,129 +0,0 @@
-# HTTP request and response configuration
-
-Implemented in alpha.4. This is a documented HTTP subset, not a promise that every
-HTTP feature is configurable. It builds on [RFC 9110](https://www.rfc-editor.org/rfc/rfc9110.html).
-
-```yaml
-version: "1"
-routes:
-  /echo:
-    methods: [POST]
-    request:
-      body:
-        required: true
-        maxBytes: 16384
-        contentTypes: [application/json]
-        format: json
-    function:
-      source: functions/echo.mjs
-    response:
-      headers:
-        Cache-Control: no-store
-        X-App: my-links
-  /go:
-    redirect:
-      url: https://example.com
-      status: 302
-    response:
-      headers:
-        Cache-Control: public, max-age=60
-  /status:
-    respond:
-      status: 200
-      json: {ok: true}
-```
-
-`functions/echo.mjs`:
-
-```js
-export default async function echo(request) {
-  return Response.json(await request.json());
-}
-```
-
-## Requests
-
-Keep ordinary routes short: omit `methods` to accept GET and HEAD. Set
-`methods: [POST]` for a POST-only handler, or `methods: [GET, HEAD, POST]` for all
-three. Use uppercase method names. Explicit lists replace the defaults; GET does
-not implicitly add HEAD when a list is supplied. The schema advertises the same
-default as the runtime. No declaration is needed for the default 302 redirect
-status or default `Cache-Control: no-store` on functions/redirects.
-
-
-| Field | Behavior |
-|---|---|
-| `methods` | Allowed methods, default GET/HEAD; exact lists, 405 plus Allow on mismatch |
-| `parameters` | Required/defaulted/typed path, query and header inputs; see the specification |
-| `request.body.required` | Reject an empty body with 400; default false |
-| `request.body.maxBytes` | 0–1048576; tighter per-route budget, enforced while reading fixed/chunked bodies; 413 on overflow |
-| `request.body.contentTypes` | Exact lowercase MIME essences for nonempty bodies; parameters ignored; mismatch/missing type returns 415 |
-| `request.body.format` | `text`: validate UTF-8; `json`: validate UTF-8, JSON media type and JSON syntax; malformed input returns 400 |
-
-The operator request limit remains an upper bound; YAML cannot raise it. A route
-without body policy keeps the existing server limit. A configured body policy
-rejects nonidentity Content-Encoding for nonempty bodies; no automatic decompression.
-Empty optional bodies skip media/format checks. Inputs are validated before the
-handler; the original body remains available through function `request.text()` or
-`request.json()`. No YAML body interpolation or automatic argument binding.
-Request header inputs use `parameters` with `in: header`; this is validation,
-not arbitrary modification or forwarding of the incoming request.
-
-## Responses
-
-`response.headers` maps HTTP names to literal strings. Names are case insensitive;
-duplicate spellings and invalid names/control characters fail activation. YAML
-values replace the same handler headers, including all prior Set-Cookie values.
-Only `Set-Cookie` accepts a list, producing separate header lines:
-
-```yaml
-response:
-  headers:
-    Cache-Control: no-store
-    Set-Cookie:
-      - "theme=light; Path=/; SameSite=Lax; Secure"
-      - "notice=seen; Path=/; HttpOnly; SameSite=Lax; Secure"
-```
-
-Use functions for dynamic cookies; never commit session credentials or secret
-values into header literals. Header configuration applies to handler responses,
-including declared error statuses, but not runtime validation/errors (400, 404,
-405, 413, 415, 500, etc.). Defaults remain `no-store`, `nosniff` and a request ID.
-Header policy is bounded to 64 keys/16 KiB; merged function headers remain bounded.
-
-Framing, hop-by-hop headers, Location, Allow, range/cache validators,
-Content-Encoding, X-Request-ID and X-Content-Type-Options are reserved to the
-runtime/handler. Configure redirect URLs/status on `redirect`; asset content type,
-cache and disposition on its own handler. Asset metadata cannot be overridden by
-`response.headers`. On functions/declared responses, Content-Type may be configured;
-JSON declarations require a JSON type. No response header secret interpolation.
-
-`respond` is an additional native handler (exactly one handler per route):
-
-- `status`: 200–599, default 200; 206 and 304 are reserved for native asset semantics.
-- `text`: literal UTF-8 body, default content type text/plain.
-- `json`: any JSON-compatible YAML value, serialized with application/json.
-- Omit both for an empty body; declaring both fails. Body limit is 1 MiB.
-- Status 204/205 cannot declare a nonempty body. HEAD always suppresses the body.
-
-Functions still return their own Response/status/body. YAML header policy does
-not replace function status/body. Asset handlers retain conditional/HEAD/range
-behavior described in [assets](ASSETS.md). Use OPTIONS explicitly if you need a
-declared response; merely adding a header does not implement CORS preflight.
-
-## Still outside this contract
-
-Automatic CORS/preflight policy, cookie parsing/signing, authentication, body JSON
-Schema validation, multipart/file uploads, streaming, content negotiation,
-WebSocket upgrades and proxies are not implemented. Do not advertise these as
-supported just because raw headers can be declared. Compression negotiation,
-security-header profiles, per-client throttling, User-Agent policy and HTTP
-caching strategies exist only as optional, off-by-default
-[policies](POLICIES.md); a project that declares none keeps the identity-only
-behavior described here, and YAML `response.headers` beat any header a policy
-would add. Future features need their own portable semantics and tests; unknown
-YAML fields fail.
-
-Middleware runs after route/method/input/body validation and before YAML response
-header overrides. See [middleware](MIDDLEWARE.md) for ordering and native body
-preservation rules.

package/docs/INSTALL.md

@@ -1,128 +0,0 @@
-# Installing URLCode
-
-URLCode is a Node CLI. Every channel below installs the same published tarball;
-pick whichever fits how you already manage tools. All of them require
-**Node.js 22.13 or newer**. The tarball ships plain JavaScript built from the
-TypeScript source (`dist/`, with declarations; see [TypeScript](TYPESCRIPT.md)),
-so the installed `urlcode` command runs `dist/cli.js` and needs no build tool.
-
-## npm
-
-The stable release target is `0.4.1`. Use these commands after publication;
-`npm run release:status` in a checkout reports live registry availability. An
-unversioned npm install selects the current `latest` channel, while `@alpha`
-explicitly selects the separate prerelease channel.
-
-```sh
-npm install --global @jimhoyd/urlcode@0.4.1
-urlcode --help
-```
-
-Project-local, which is what an application repository should normally pin.
-Which dependency list it belongs in depends on how the project uses URLCode:
-
-```sh
-# Using URLCode as a tool: validate, test and build in CI, never imported by
-# the code that serves requests.
-npm install --save-dev --save-exact @jimhoyd/urlcode@0.4.1
-npx urlcode validate
-
-# Embedding the runtime (see TYPESCRIPT.md): the application imports
-# @jimhoyd/urlcode at startup, so it must survive `npm ci --omit=dev`.
-npm install --save --save-exact @jimhoyd/urlcode@0.4.1
-```
-
-A devDependency is absent from a production install, so an application that
-imports `createRuntime`, `startServer`, `prerenderPages` or any other
-[embedding entry point](TYPESCRIPT.md) fails at startup on a missing module if it
-is installed with `--save-dev`. An application should also pin an **exact**
-version rather than a range: the compiled Cloudflare artifact format is tied to
-the runtime version that reads it.
-
-## Homebrew
-
-```sh
-brew tap jimhoyd-com/urlcode
-brew trust jimhoyd-com/urlcode
-brew install urlcode
-```
-
-Homebrew refuses to load a formula from a third-party tap until you trust it,
-so without the middle line the install stops with `Refusing to load formula …
-from untrusted tap`. Trusting a tap means agreeing to run code from this
-repository, the same as with the install script; `brew trust --formula
-jimhoyd-com/urlcode/urlcode` limits it to this one formula.
-
-The tap's formula is generated from the published tarball for each release and
-attached to the GitHub release as `urlcode.rb`. Homebrew verifies the tarball's
-SHA-256 against the formula before installing.
-
-Verified on macOS (arm64) against the 0.3.0 tap: fetch verified, installed into
-`/opt/homebrew/Cellar/urlcode/0.3.0`.
-
-## Install script
-
-```sh
-curl -fsSL https://raw.githubusercontent.com/jimhoyd-com/urlcode/main/install.sh | sh
-```
-
-It downloads the release tarball, verifies its SHA-256 against the release's
-`SHA256SUMS`, and installs with npm. Options:
-
-```sh
-curl -fsSL .../install.sh | sh -s -- --version 0.4.1 --prefix "$HOME/.local"
-```
-
-`--prefix` avoids needing privileges for a global npm directory; add
-`$PREFIX/bin` to `PATH`. Piping a script into a shell means trusting the source
-for that moment: to inspect first, download it, read it, then run it.
-
-## Container
-
-No image is published yet: the release job's GHCR step is gated behind the
-`PUBLISH_CONTAINER` repository variable and has not run, so there is nothing at
-`ghcr.io/jimhoyd-com/urlcode` to pull. After the release tag exists, build it from that checkout:
-
-```sh
-git clone --branch v0.4.1 https://github.com/jimhoyd-com/urlcode.git
-docker build -t urlcode:0.4.1 urlcode
-docker run --rm -p 127.0.0.1:3000:3000 -v "$PWD:/project:ro" urlcode:0.4.1 \
-  serve --project /project --host 0.0.0.0
-```
-
-The image runs the same built runtime, `node /opt/urlcode/dist/cli.js`, as its
-entry point. Pin the digest rather than a tag for a deployment, and give the
-container its own resource limits. See [operations](OPERATIONS.md).
-
-## From source
-
-```sh
-git clone https://github.com/jimhoyd-com/urlcode.git
-cd urlcode
-make dev
-```
-
-A clone runs the TypeScript source directly (`node src/cli.ts`, Node 22.18+),
-with no build step; see [local development](LOCAL-DEVELOPMENT.md).
-
-Three Node versions appear around the project, and they are not a contradiction:
-the installed package runs on Node 22.13 or newer (`engines`), running the
-TypeScript source from a clone needs 22.18 or newer because it relies on Node's
-built-in type stripping, the release workflow's npm trusted publishing needs
-22.14 or newer, and the container image pins Node 26. Only the first number
-constrains a deployment of the published tarball.
-
-## Verify what you installed
-
-Releases carry Sigstore provenance signed by the release workflow. Before
-trusting a downloaded artifact:
-
-```sh
-gh attestation verify jimhoyd-urlcode-0.3.0.tgz --repo jimhoyd-com/urlcode \
-  --signer-workflow jimhoyd-com/urlcode/.github/workflows/release.yml
-```
-
-A signature establishes where an artifact came from. It is not a statement that
-the release is safe for your workload, and it is not a production-readiness
-claim; see [release readiness](RELEASE-READINESS.md) and
-[release security](RELEASE-SECURITY.md).

package/docs/INTERCHANGE.md

@@ -1,134 +0,0 @@
-# Redirect interchange and bulk authoring
-
-`importRoutes` and `exportRoutes` return a conversion report without writing files,
-activating a runtime, reading bindings, loading function sources or running code.
-The CLI can preview the report before creating a new output file. Failed reports
-never contain a partial document or output; duplicate paths never overwrite a row.
-
-```js
-import { importRoutes, exportRoutes } from '@jimhoyd/urlcode';
-const report = await importRoutes({
-  format: 'csv', source: 'migration.csv',
-  text: 'path,url,status\n/old,https://example.test/new,301\n'
-});
-if (!report.ok) throw new Error(JSON.stringify(report.diagnostics));
-// report.output is URLCode project YAML; report.document is the validated project.
-const csv = await exportRoutes({ format: 'csv', document: report.document });
-```
-
-Each report has `ok`, `lossless`, `routeCount` and `diagnostics`. Diagnostics name
-an input source, physical CSV/text row or JSON/YAML array index where available,
-a path where appropriate, a code, severity and explanation. Destinations and
-credentials are not echoed in validation errors. Output is sorted by literal
-path, independent of input order. Import does not merge an existing project;
-normal project loading rejects collisions across includes when output is added.
-
-## CLI usage
-
-```sh
-# Bulk row formats can be inferred from the input extension or named explicitly.
-urlcode import csv migration.csv --out routes.yaml --dry-run
-urlcode import csv migration.csv --out routes.yaml
-urlcode import migration.json --report json --dry-run
-
-# Provider migrations require explicit acknowledgment of the reported differences.
-urlcode import netlify _redirects --out imported.yaml --dry-run
-urlcode import netlify _redirects --out imported.yaml --accept-provider-differences
-urlcode export --target netlify --project ./project --out _redirects --accept-provider-differences
-urlcode export --target cloudflare --project ./project --dry-run
-urlcode export --target vercel --project ./project --dry-run
-urlcode export --target netlify-toml --project ./project --dry-run
-```
-
-General import syntax is `urlcode import [format] FILE`; `--format` explicitly
-overrides the positional format or extension. Exports use `--target` for a
-provider format, or `--format csv|json|yaml` for row data. `--out FILE` creates a
-new file with mode 0600 and never overwrites one. `--dry-run` validates and
-returns a report without creating the requested output. `--report json` always
-emits the report. Failures exit nonzero and leave no converted output.
-
-Reports include source/row diagnostics and the successful candidate output.
-Acknowledged provider conversions always emit a report with their warnings,
-even when `--out` is provided; raw provider output is never silently printed as
-if it were lossless. Project export flattens validated includes, but refuses
-other unsupported project behavior instead of dropping it. For a large input
-that needs a complete sharded project, use [bulk import](BULK.md).
-
-## Supported forms
-
-| Format | Input/output subset |
-| --- | --- |
-| `csv` | Header exactly `path,url,status`; optional empty status defaults to 302; quoted fields and escaped quotes |
-| `json` | Array of `{path,url,status?}`; status must be a number |
-| `yaml` | The same row array in strict URLCode YAML syntax; not a full project file |
-| `netlify` | `_redirects`: literal source, absolute HTTP(S) destination, optional status (default 301) |
-| `cloudflare` | Pages `_redirects`: same columns, default 302; 2,000 static rules, 1,000 characters per rule |
-| `vercel` | `vercel.json` containing only `redirects`; literal `source`, absolute `destination`, and either boolean `permanent` (308/307) or `statusCode` |
-| `netlify-toml` | Only `[[redirects]]` blocks with `from`, `to`, optional numeric `status` (default 301); unescaped double-quoted strings |
-
-All statuses are restricted to 301, 302, 303, 307 and 308. Literal ASCII paths
-and absolute HTTP(S) destinations are required. The existing schema and semantic
-compiler validate resulting routes. No provider pattern compiler is introduced.
-
-The TOML subset deliberately rejects general TOML constructs, build settings,
-escapes, inline comments, nested conditions, force flags and other tables. A full
-`netlify.toml` must be separated into a redirects-only input by the operator. This
-avoids silently discarding build settings or reinterpreting unsupported syntax.
-
-Functions, assets, middleware, conditions, parameters, query maps/allowlists,
-headers, policies, includes and any other extra route/project fields cannot be
-exported by this subset. Relative destinations, wildcards, provider placeholder
-syntax, rewrites and duplicate paths fail. Use a runtime adapter for richer
-behavior. CSV/JSON/YAML round-trips are lossless within the declared simple subset.
-
-## Provider semantics require explicit acknowledgment
-
-Provider conversions fail by default. `acceptProviderDifferences: true` (CLI
-`--accept-provider-differences`) permits a **non-lossless migration candidate**;
-it does not suppress invalid rules, discard unsupported fields or claim exact
-behavior. Every such successful report retains a warning and `lossless: false`.
-
-URLCode drops incoming query parameters and defaults to GET/HEAD. Native
-redirect systems can apply to other methods and have different normalization
-and request-query behavior. Netlify automatically forwards queries for common
-redirect statuses and can give existing files precedence. Cloudflare Pages
-redirects override assets, but Pages Functions can bypass `_redirects`.
-Review behavior for requests with queries, non-GET methods, slash/URL normalization
-and conflicting assets/functions before deploying. The acknowledged subset is
-literal GET/HEAD requests without these conflicts. No provider deployment was
-performed as part of interchange unit tests.
-
-Provider references checked 2026-09-17:
-
-- [Netlify redirect options](https://docs.netlify.com/manage/routing/redirects/redirect-options/)
-- [Netlify TOML configuration](https://docs.netlify.com/build/configure-builds/file-based-configuration/)
-- [Cloudflare Pages redirects](https://developers.cloudflare.com/pages/configuration/redirects/)
-- [Vercel redirect configuration](https://vercel.com/docs/project-configuration/vercel-json)
-
-## Resource limits
-
-Imports reject more than 32 MiB of input or 100,000 rows. Diagnostic collection
-stops after 100 invalid rows; normal route compilation retains its deadline and
-validation rules. Large output can still exceed the runtime YAML worker's heap
-or deadline: conversion success does not promise activation of a single 100k
-route YAML file. Split large migration inputs into independently reviewed files
-and use explicit `includes`; aggregate project limits continue to apply.
-
-Reports also expose bounded classification counts:
-
-- `convertedRoutes`: routes actually returned in successful output; zero when
-  any error prevents output.
-- `nativeEquivalentRoutes`: returned routes with no conversion warnings; always
-  zero for acknowledged provider conversions.
-- `runtimeRequiredRoutes`: route diagnostics identifying behavior outside the
-  simple export subset.
-- `unsupportedRows`: known invalid/duplicate input-row diagnostics.
-- `providerDifferenceRoutes`: candidate routes subject to the provider semantic
-  warning; these overlap converted routes after acknowledgment.
-- `fullyScanned`: false on parser/global failures or truncated diagnostics. Counts
-  then describe only examined input, never an inferred total.
-
-These counts are not a partition of arbitrary malformed input. `routeCount`
-retains its original meaning: routes in the candidate table, or rows
-parsed before an early global failure. A failed report contains no candidate
-output even if some rows were convertible.