@jimhoyd/urlcode 0.4.1 → 0.4.6

package/docs/TOOLING.md

@@ -1,298 +0,0 @@
-# Tooling SDK and local MCP
-
-The tooling API consolidates authoring operations without starting a runtime:
-
-- `inspectProject(project, {origin?, target?, offset?, limit?})` loads and
-  semantically compiles the project and returns route metadata, revision hash and
-  target compatibility. Route pages default to 100 entries, maximum 1,000.
-  Compatibility contains global `compatible`, `requirementCount` and `issueCount`
-  plus a separate `issues` page. Both arrays use the same zero-based `offset`
-  and `limit`, independently: an issue page is indexed over all compatibility
-  issues, not filtered to the route page. Compatibility includes `hasMore` for
-  its issue page. Empty pages never imply compatibility; the verdict and counts
-  always cover the entire project. Full requirement arrays are omitted because
-  route entries already contain their capability names.
-- `validateProject(project, options)` returns the same compilation verdict and
-  compatibility verdict and global counts without route or issue pages.
-  `firstIssue` is the first issue across the whole project, or null; supplied
-  pagination settings do not change it. The low-level
-  `analyzeCompiledCapabilities` API still returns the complete report.
-  For unusually long route paths, request smaller pages to fit the MCP output
-  byte limit; page entry bounds do not override that transport limit.
-- `explainRoute(project, path, options)` selects the route for a path and
-  describes its effective behavior from the compiled IR: methods, handler (with
-  its destination, module and export, file, extension or link collection),
-  the middleware chain in order, validated inputs (parameters and the request
-  body policy), the policies in effect with each compiled policy's inventory,
-  extension requirements, the cache outcome (the policy strategy, an explicit
-  header, an asset declaration, or the `no-store` the runtime forces on
-  extension, proxy and conditional routes), binding names (never values),
-  egress origins, response headers, capabilities and per-target support. A miss
-  returns `matched: false` with the nearest route patterns. With `extensions`
-  (a host file's registrations) each extension requirement also reports whether
-  a provider is registered, whether its revision pin matches and whether the
-  requirement satisfies the provider's policy schema; nothing is activated.
-  `explainProject(project, options)` returns every route the same way.
-- `buildManifest(project, options)` returns the generated semantic manifest
-  described under [`urlcode manifest`](#explain-and-manifest).
-- `getCapabilities(target?)` describes local implementation support and separate
-  deployment evidence.
-- `getCapability(name)` returns one catalog entry: kind, summary, resolved schema
-  fragments, constraints, required operator grants, per-target support, refused
-  targets and the bundled recipes and cookbook routes that use it. Unknown names
-  throw a `ConfigError` listing the valid names.
-- `getSchemaFragment(path)` returns only the fragment of
-  `schemas/urlcode.schema.json` for a dotted path (`route`, `redirect`,
-  `policies.cache`, `site.sitemap`) with local `$ref`s inlined; `schemaPathNames()`
-  lists the accepted top-level names. Both read bundled package data only.
-- `previewImport(options)` and `previewExport(project, format, acknowledgment?)`
-  return conversion reports and candidate text, never writing files. Provider
-  semantic differences require the existing explicit acknowledgment and remain
-  non-lossless.
-- `listRecipes()` and `showRecipe(name)` expose the fixed bundled recipe catalog.
-- `inspectExtensions({project, hostFile?})` reports each operator-registered
-  extension's name, contract version, targets, credential headers, configuration
-  and policy JSON Schemas, whether the project declares it, whether its revision
-  pin matches and where routes mount or require it, plus the project's declared
-  names. With `hostFile` it executes that trusted operator module under the
-  `--host-file` rules (absolute path, outside the project) and releases it
-  afterwards; without one it lists declarations only. `describeExtensions(project,
-  registrations?)` produces the same report from registrations already in hand.
-  Neither activates an extension. See [EXTENSIONS.md](EXTENSIONS.md).
-- `buildContext(project, {target?, hostFile?, budget?})` returns the compact
-  project context an authoring agent needs before it writes anything (see
-  below); `renderContext` produces the YAML rendering and `estimateTokens`
-  the characters-per-token estimate the budget uses.
-
-## Project context
-
-`urlcode context [--project DIR] [--target T] [--host-file F] [--budget N]
-[--json] [--stats]` emits one deterministic YAML document (JSON with
-`--json`) derived only from the compiled project and the capability catalog,
-never from prose. It uses the same loader and semantic compiler as
-`inspectProject`: no binding values, guest execution, environment reads or
-network. Keys always appear in this order:
-
-- `urlcode` (package version) and `schema` (`"1"`).
-- `project`: entry file, route count, handlers used with counts, extensions
-  declared, policies in effect at the top level and the number of routes each
-  policy applies to, requested env and secret binding names,
-  `site` keys, and `files` (include, function and middleware paths). With
-  `--host-file`, `host` counts the operator module's extensions and plugins
-  without activating them.
-- `routes`: path, methods and handler per route, sorted by path.
-- `constraints`: a fixed list that holds for every project (network and Node
-  built-ins available to trusted code and withdrawn by `sandbox: true`, no
-  regex routes, one handler per route, exact or `{param}` path segments,
-  subtree mounts only for static and extension routes, no YAML interpolation,
-  injected `env`/`secrets` by operator grant only), each with a value and a
-  note spelling out how it differs between the two trust modes.
-- `targets`: for each capability target (or the one `--target`), which of this
-  project's used features are supported, conditional, refused or unknown.
-- `commands`: the exact `validate`, `test`, `audit --expect-routes N` (N is
-  the compiled route count), `routes` and `capabilities` invocations.
-
-`--budget N` drops sections in a fixed order until the YAML rendering fits
-the estimate: per-route detail, then `targets`, then the constraint notes
-(keys and values stay), then `project.files`, then `commands`. The dropped
-sections are listed under `omitted`. The estimate is `ceil(characters / 4)`;
-there is no tokenizer dependency, so treat both numbers as approximate. A
-budget the smallest rendering cannot meet is an error rather than an
-overrun. `--stats` writes a JSON line to stderr comparing the estimated size
-of the shipped documentation (`docs/*.md` and `llms.txt`) with the emitted
-context, labeled `estimate: characters/4`. The MCP tool `get_context` takes
-`target` and `budget` and returns the same object with `--project .` in the
-commands; it never takes a host file or any other path.
-
-Inspection reads declared configuration and function source graphs to validate
-references and compute revision hashes. It compiles route and policy semantics
-using dummy binding values. It never reads environment or dotenv credentials,
-starts guest execution, follows network destinations, or opens operator link
-stores. The result contains no raw compiled route, binding values or source text.
-Inspection is not deployment readiness: missing operator grants, live service
-availability, asset snapshot activation and provider behavior require their own
-checks. Build output remains an explicit separate build API/CLI operation.
-
-The package root also exports existing operator-invoked workflow APIs:
-`buildCloudflare(project, options)` compiles and writes a Cloudflare artifact;
-`buildStatic(project, options)` compiles redirects and static files into plain
-objects and redirect metadata for S3 + CloudFront (see [static
-hosting](STATIC.md)); `runProjectTests(project, options)` starts the local
-runtime, executes request fixtures and closes it; `scaffoldProject(project,
-{dryRun})` creates missing placeholders while preserving existing files;
-`initProject(destination)` creates the standard starter; and
-`addRedirect(project, destination, alias?)` updates project YAML under the
-authoring lock. `CloudflareBuildOptions`, `CloudflareBuildReport`,
-`StaticBuildOptions`, `StaticBuildReport`, `ProjectTestOptions`,
-`ProjectTestResult`, `ScaffoldReport` and `ScaffoldUnresolved` describe these
-existing operations.
-
-These SDK functions have explicit write or execution effects and are available
-to trusted callers only. Project tests use normal runtime activation, grants and
-sandboxing; granted proxy/signal fixtures can perform real outbound operations.
-Compilation and authoring write caller-selected destinations under each existing
-helper's documented rules. They are **not** MCP tools. MCP remains limited to
-the read-only operations below; adding a package-root export does not grant an
-assistant file-write, guest-execution, deployment or network authority.
-
-## Explain and manifest
-
-`urlcode explain [/route] [--project DIR] [--target T] [--host-file F] [--json]`
-prints what `explainRoute` returns: one route in detail, or without a path a
-one-line-per-route table (methods, handler, state, execution mode, middleware
-count, policies, cache outcome and target support). `--target` narrows the support columns to
-one deployment target; `--host-file` supplies the operator registry so
-extension requirements show their provider. An unknown route exits 1 and names
-the nearest patterns. Everything comes from the compiled configuration: no
-request is evaluated, no function runs and no binding is read.
-
-`urlcode manifest [--project DIR] [--json]` emits the semantic manifest:
-`schemaVersion`, the `urlcode` version, the entry file and its includes, the
-`revision` (the same digest `inspectExtensionRevision` returns, so an operator
-pin can be checked against it), the config `configVersion`, every route (path,
-methods, handler, state, execution mode (`sandbox`, with `sandboxReason` when
-the route declares one), middleware, inputs, policy names, extension
-requirements, cache outcome, binding names, egress origins, capabilities and
-per-target support), the union of capabilities used, extension declarations
-(version, configuration keys, mounts and protected routes), recipe provenance
-(from a `recipe.yaml` beside the entry file when one exists), external
-requirements (environment and secret names, proxy and signal origins,
-extensions), the function and middleware
-modules with the routes that use them, and per-target compatibility. Without
-`--json` a short summary prints. The manifest is deterministic: the same
-project produces the same bytes. `urlcode build` writes the same document as
-`manifest.json` beside its output, and `buildManifest` returns it from the SDK.
-It is generated output, never a checked-in source of truth; regenerate it
-rather than editing it.
-
-`serveMcp({project, input?, output?, origin?, allowAuthoring?, hostFile?})` serves one
-operator-selected root on stdio. Its tools are `inspect`, `validate`,
-`capabilities`, `get_capability`, `get_schema`, `explain`, `get_manifest`,
-`import_preview`, `export_preview`, `recipes_list`, `recipes_show`,
-`search_recipes`, `search_examples` and `get_context`. When the operator starts
-the server with `--host-file`, it loads that trusted module once for the session
-and additionally advertises `get_extensions`, which returns the
-`inspectExtensions` report; without the option the tool is absent and calls to
-it are rejected. Tools accept no project/file/output path argument; recipe names
-come from the fixed catalog, `get_capability` names from the capability catalog,
-`get_schema` paths from the bundled schema, and the two searches match bundled
-metadata locally (see [recipes](RECIPES.md)).
-There is no shell, arbitrary file read, remote fetch, binding access, write or
-route-execution tool without the explicit [authoring mode](#authoring-mode) flag. Configuration includes and module references retain the
-runtime's existing root containment checks. Returned project and recipe content
-is data, not trusted instructions for the consuming agent.
-
-The server implements the MCP **2025-11-25** lifecycle and stdio framing. Clients
-initialize, verify the returned protocol version, then send
-`notifications/initialized` before tool operations. Other requested revisions
-negotiate to this explicit supported version; a client that cannot support it
-must disconnect. Newer lifecycle revisions are not claimed. Requests use UTF-8
-newline-delimited JSON-RPC 2.0, with one request at a time and stream backpressure.
-There is a 1 MiB input-frame and output-message limit; oversized input terminates
-the session after a fixed error, and truncated/invalid frames return protocol
-errors. Import text is additionally capped at 512 KiB. Tool schemas reject
-unknown arguments. Tool operation errors are generic to avoid exposing local
-source paths, credentials or configuration excerpts; inspect locally for details.
-
-## Registering the server
-
-`urlcode init` (and `init --with`) writes `.mcp.json` at the project root, the
-shape Claude Code and Codex read:
-
-```json
-{ "mcpServers": { "urlcode": { "command": "urlcode", "args": ["mcp", "--project", "."] } } }
-```
-
-For an `init --with` site the file sits beside `host.mjs` and passes
-`--project app`. An existing `.mcp.json` is never overwritten. The file registers
-the read-only server only: `--allow-authoring` (and `--host-file`) are operator
-choices added by hand, never by `init` or by an agent.
-
-- **Claude Code** reads `.mcp.json` in the project directory as a project-scoped
-  server and asks for approval on first use. Without a global install, replace
-  `"command": "urlcode"` with `"node"` and prefix the arguments with
-  `node_modules/@jimhoyd/urlcode/dist/cli.js`.
-- **Codex** reads the same `mcpServers` shape; alternatively register it in
-  `~/.codex/config.toml`:
-
-  ```toml
-  [mcp_servers.urlcode]
-  command = "urlcode"
-  args = ["mcp", "--project", "."]
-  ```
-- **Any stdio client** spawns `urlcode mcp --project DIR` with the project as the
-  working directory, speaks newline-delimited JSON-RPC 2.0 over stdin/stdout,
-  and follows the 2025-11-25 lifecycle described above. Nothing listens on a
-  port; closing stdin ends the session.
-
-The generated `AGENTS.md` and the packaged skill tell agents to prefer
-`get_context`, `get_capability`, `get_schema`, `search_recipes`, `explain` and
-`get_manifest` when the server is registered and to fall back to the matching
-CLI commands otherwise.
-
-## Authoring mode
-
-`urlcode mcp --allow-authoring --project DIR` adds six tools to the fourteen read
-tools above. The flag is honored from the operator's command line only: no
-tool argument, environment variable or client capability enables it, and
-without it the server is exactly the read-only server described above.
-
-What it can do, all inside the selected project root (resolved with realpath):
-
-- `create_route {path, handler, middleware?, file?}` adds one route to
-  `urlcode.yaml` or to an include listed in it. `handler` is a route object
-  (`{redirect: {...}}`, `{function: {...}}`, `{page: {...}}`, ...) or a short
-  form: an `http(s)://` URL becomes a redirect, a `.js`/`.mjs` path becomes a
-  function whose `{param}` path segments expand to required bounded string
-  parameters and matching `args`. `middleware` entries are sources or objects.
-  The merged project is checked before the write (schema, duplicate routes,
-  the `auth` short form, and the same reference compilation `urlcode add`
-  performs when every referenced source exists). The edit runs under the
-  authoring lock and replaces the file atomically. Missing sources are listed
-  in `missingSources` for `scaffold_feature`.
-- `add_recipe {name, destination, dryRun?}` runs `recipes add` into a new
-  directory under the project. The parent must exist; an existing destination
-  is refused, never merged. `dryRun` reports the destination and writes nothing.
-- `scaffold_feature {dryRun?}` runs `urlcode scaffold`: placeholder modules,
-  pages and directories for references the YAML makes and the disk lacks.
-  Existing files are preserved, never overwritten.
-- `run_validate`, `run_test`, `run_audit` spawn `urlcode validate --local`,
-  `urlcode test` and `urlcode audit` against the project with a minimal
-  environment (`PATH` only), a two-minute deadline and stdout/stderr each capped
-  at 32 KiB. The result carries `exitCode`, `signal`, `stdout`, `stderr` and
-  `truncated`. `run_test` activates the local runtime and executes fixtures,
-  under the same rules as the CLI.
-
-Every tool returns `validation`, the `validateProject` verdict of the project
-after the operation (or `valid: false` with a generic note; use `run_validate`
-for the CLI report).
-
-What it cannot do:
-
-- Write outside the project root. Paths are project-relative; absolute paths,
-  `..`, backslashes, drive letters, and any symlink on the walk are refused
-  before the write, and the recipe, scaffold and `urlcode add` paths keep their
-  own containment checks.
-- Touch `.env*`, anything under `.git`, `node_modules`, `package.json`,
-  credential files (`.pem`, `.key`, `.p12`, `.pfx`), the authoring lock, or
-  operator files by name: `*policy*.json`, `*compliance*`, `host.mjs` /
-  `host-file.mjs` and link stores (`.sqlite`, `.db` and their WAL/SHM files).
-  Operator files belong outside the checkout in the first place.
-- Create or change grants, read bindings or secret values, deploy, build, run
-  arbitrary commands, delete or edit existing files (except the one YAML file a
-  `create_route` targets), or serve a project other than the one the operator
-  selected.
-
-Authoring mode is a local, unauthenticated stdio process for an operator who
-already trusts the assistant to edit this checkout. Review the resulting diff
-as you would any contributor's before running `serve` or deploying.
-
-Only tools are advertised. Resources, prompts, subscriptions, sampling,
-elicitation, HTTP transport, cancellation and durable tasks are not implemented.
-Closing stdin ends the session after the current bounded operation. Existing
-configuration-loader and semantic-compiler deadlines still apply. This local
-process is not an authenticated remote service or an independent security review.
-
-Protocol references: [MCP stdio transport](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports),
-[MCP lifecycle](https://modelcontextprotocol.io/specification/2025-11-25/basic/lifecycle),
-and [MCP tools](https://modelcontextprotocol.io/specification/2025-11-25/server/tools).

package/docs/TUNNELS.md

@@ -1,72 +0,0 @@
-# Public tunnels for local development
-
-A tunnel gives a project running on your machine a public HTTPS address, which
-is what you need to test redirects from a phone, receive a provider's webhook,
-complete an OAuth callback or show someone a work in progress.
-
-URLCode has one requirement that matters here, and one warning.
-
-## Always pass `--origin`
-
-Forwarded headers are deliberately not trusted, so the runtime cannot infer its
-public address. Without `--origin`, functions receive `http://127.0.0.1:3000/...`
-as `request.url` even though the visitor arrived over HTTPS at a public host —
-so anything built from the request URL is wrong: OAuth redirect URIs, absolute
-links in generated HTML, canonical URLs, signature checks.
-
-```sh
-urlcode dev --project . --origin https://your-subdomain.ngrok-free.app
-```
-
-The startup record reports what was chosen, so you can confirm it:
-
-```json
-{"event":"listening","address":"127.0.0.1","port":3000,"mode":"dev","origin":"https://your-subdomain.ngrok-free.app"}
-```
-
-`--origin` must be a bare HTTP(S) origin: no path, no credentials, no trailing
-slash. It works with `serve` too, and behind a reverse proxy it is the same
-mechanism.
-
-## ngrok
-
-Start the tunnel, then start URLCode with the origin it gave you:
-
-```sh
-ngrok http 3000
-urlcode dev --project . --origin https://your-subdomain.ngrok-free.app
-```
-
-Because that address changes on every restart of a free tunnel,
-[`examples/tunnel/dev-with-ngrok.sh`](../examples/tunnel/dev-with-ngrok.sh)
-reads it from the ngrok agent's local API and passes it for you:
-
-```sh
-ngrok http 3000                       # terminal 1
-PROJECT=. ./examples/tunnel/dev-with-ngrok.sh   # terminal 2
-```
-
-It selects the HTTPS tunnel forwarding to your port and refuses to guess when
-there is no match, so a second unrelated tunnel on the same agent cannot send
-your traffic somewhere unexpected. `--print` shows the resolved origin without
-starting anything. It discovers a tunnel; it does not start, stop or configure
-ngrok, and it holds no ngrok credentials.
-
-Other tunnels — Cloudflare Tunnel, Tailscale Funnel, localtunnel, an SSH remote
-forward — work the same way: get the public origin, pass it to `--origin`.
-
-## What you are exposing
-
-A tunnel makes a development server reachable by anyone with the URL, including
-scanners that find it within minutes.
-
-- `dev` loads `.env.local` and watches files. Any secret in that file is
-  available to the functions you just published.
-- The runtime has **no authentication and no rate limiting**. Put access control
-  in the tunnel: ngrok's OAuth, OIDC or basic auth; Cloudflare Access; a
-  Tailscale ACL.
-- Prefer `serve` with a fixed snapshot, a project containing no real secrets,
-  and a tunnel you shut down when finished.
-
-A tunnel is for development and demos. For a real deployment, terminate TLS at a
-proxy you control and read [operations](OPERATIONS.md).

package/docs/TYPESCRIPT-AUTHORING.md

@@ -1,87 +0,0 @@
-# Build-time TypeScript guests
-
-TypeScript guest authoring is a separate build step. Serving still accepts only
-JavaScript ES modules. The build never imports application modules into Node
-or runs application code, and it is `sandbox`-aware per route
-(docs/SPIKE-DEFAULT-TRUST-MODEL.md): a route that declares `sandbox: true` is
-transpiled under the sandbox's own module rules (relative imports only, no
-dynamic import/bare specifiers, the module/size limits below), exactly as
-before; a trusted (non-`sandbox: true`) route is transpiled without those
-import/size restrictions, since it will run with full Node access — bare/npm
-imports, dynamic `import()`, `import.meta` — once served. Both modes still
-diagnose only syntax, not semantics, and neither imports application code into
-the build process in a way that executes it.
-
-```sh
-urlcode recipes add typescript --out ./hello-source
-urlcode build-typescript --project ./hello-source --out ./hello-built --dry-run
-urlcode build-typescript --project ./hello-source --out ./hello-built
-urlcode validate --local --project ./hello-built
-urlcode serve --project ./hello-built
-```
-
-The SDK equivalent is
-`await buildTypeScriptProject(source, output, {dryRun: false})`. The report lists
-emitted modules and files and explicitly returns `typeChecked: false`.
-
-Point `function.source` or `middleware[].source` at a `.ts`, `.js` or `.mjs`
-module. Use explicit relative extensions in imports, such as
-`import {message} from './message.ts'`. The build emits `.ts` as `.js` and
-rewrites the runtime imports and YAML source references. Existing JavaScript
-modules are preserved. Output name collisions, including case-only collisions,
-are refused for portability. Source `.d.ts` entries are not executable modules.
-The runtime's existing handling of relative imports/re-exports applies to the
-emitted graph; unsupported re-export forms remain refused.
-
-The trusted pinned TypeScript compiler transpiles ES2022/ES modules with fixed
-settings. It does not read `tsconfig.json`, package scripts, plugins, compiler
-transformers, dependency packages, Node declarations or ambient environment
-files. It diagnoses syntax errors, but does **not** perform semantic type
-checking, in either mode. CommonJS import/export syntax and imports outside
-the project are always refused. Type-only relative imports are erased without
-reading their targets.
-
-For a `sandbox: true` route, bare/npm imports (including static type-only
-imports), dynamic runtime imports, `import.meta` and import attributes are
-refused, and the source graph is limited to 128 modules, 1 MiB per source and
-4 MiB aggregate; the emitted graph must also pass the runtime's own sandboxed
-source parser and byte limits before publication. For a trusted route, none of
-that applies: bare/npm specifiers, dynamic `import()`, `import.meta` and
-import attributes pass through unchanged (resolved by Node at serve time, not
-by this build), and there is no module-count or aggregate-size ceiling — only
-a generous 16 MiB per-source read cap that bounds authoring-time memory. A
-module may be shared by trusted and sandboxed routes: it is emitted once, and
-every module reachable from a `sandbox: true` route is still validated under
-the sandbox rules and budgets above, which does not disqualify the trusted
-route that also imports it. In both modes,
-no import extension inference occurs — relative imports of project modules
-still need an explicit `.ts`/`.js`/`.mjs` extension to be rewritten and
-followed. This does not execute the modules or replace normal route, policy,
-binding or sandbox validation at activation. Unsupported host/browser APIs
-remain unavailable in QuickJS, even if TypeScript accepts their names. Run
-`urlcode validate --local` and project tests on the output.
-
-Includes are flattened into a duplicate-checked entry document. Only referenced
-modules, page/download assets, static trees, site favicon/llms files and the
-`tests/requests.json` fixtures (when present) are snapshotted. Unreferenced files, dotenv, hidden files, package manifests and
-credential extensions are not copied. An explicit reference to a forbidden file
-fails rather than silently excluding it. Asset limits are 16 MiB per file,
-64 MiB aggregate and 10,000 output files. Empty static directories are refused;
-add an asset before building. Paths have at most 32 segments and 1,024 characters;
-symlinked source files/directories and multiply linked files are refused.
-The input project and output parent must be stable and controlled by the caller
-while building; this is not a hardened service for concurrent hostile writers.
-
-Output must be a new directory whose parent already exists. Dependencies are
-written before an atomic rename publishes the complete entry YAML; existing
-outputs are never overwritten. Failed builds remove their newly created output.
-Dry-run still transpiles and validates an isolated temporary snapshot, then
-removes it; it never writes the requested output. Configuration parsing keeps
-the loader's worker limits; transpilation runs in the authoring process and is
-not a sandboxed multi-tenant compilation service.
-
-Create operator grants against the **built** configuration/code revision.
-Transpilation and flattened includes change the snapshot digest, so source
-project grants must not be reused. External capabilities remain denied without
-an exact revision-pinned operator policy. The build never resolves bindings or
-copies credentials; it preserves logical binding declarations only.

package/docs/TYPESCRIPT.md

@@ -1,123 +0,0 @@
-# Using URLCode from TypeScript
-
-The runtime is written in TypeScript and the published package ships
-declarations for every export, so an operator application, a plugin, an
-observer, a compliance rules module or a build script can be type-checked
-against the same contract the runtime enforces at load time. Nothing in the
-project format changes: YAML and sandboxed functions are unaffected, and a
-JavaScript application keeps working exactly as before.
-
-## What ships
-
-The tarball contains `dist/`: one `.js` per runtime module, `dist/types/*.d.ts`
-beside them, and `dist/BUILD-MANIFEST.json` with a SHA-256 per emitted file.
-`package.json` resolves every subpath through export conditions:
-
-| Import | Runtime | Declarations |
-|---|---|---|
-| `urlcode` | `dist/index.js` | `dist/types/index.d.ts` |
-| `@jimhoyd/urlcode/plugins`, `@jimhoyd/urlcode/policies`, `@jimhoyd/urlcode/observability`, `@jimhoyd/urlcode/compliance`, `@jimhoyd/urlcode/prerender`, `@jimhoyd/urlcode/extensions`, `@jimhoyd/urlcode/sandbox` | `dist/<name>.js` | `dist/types/<name>.d.ts` |
-| `@jimhoyd/urlcode/aws`, `@jimhoyd/urlcode/vercel`, `@jimhoyd/urlcode/cloudflare` | `dist/<name>.js` | `dist/types/<name>.d.ts` |
-| `@jimhoyd/urlcode/schema` | `schemas/urlcode.schema.json` | — |
-
-Each entry has three conditions: `types` (the declarations), `default` (the
-built JavaScript) and `development`, which points at the `.ts` source and
-exists only so the repository's own tests and examples can import the package
-by name without a build (`node --conditions=development`). An installed
-package never uses it; Node refuses to strip types under `node_modules`.
-
-Use `"module": "NodeNext"` (or `"bundler"`) resolution so the `exports` map
-and its `types` condition apply. The declarations reference Node's types
-(`Buffer`, `node:http`, `NodeJS.Timeout`), so a consumer needs `@types/node`,
-as any Node application already has. The package smoke test installs the
-packed tarball and type-checks a consumer that imports every subpath, so a
-release cannot ship a declaration that does not resolve.
-
-## The main exported types
-
-- `urlcode`: `Runtime`, `RuntimeOptions`, `RuntimeRequest`, `RequestTrace`,
-  `Server`, `ServerOptions`, `HostPlugin`, `Observer`, `TestPlan`.
-- `@jimhoyd/urlcode/plugins`: `Plugin`, `PluginRuntime`, `PolicyRequest`,
-  `HandlerResult`, `HeaderPair`, `TargetName`. See [plugins](PLUGINS.md).
-- `@jimhoyd/urlcode/policies`: `PolicyModule`, `PolicyRegistry`, `PolicyRequest`,
-  `PolicyContext`, `PolicyChain`, `PolicyShared`. See [policies](POLICIES.md).
-- `@jimhoyd/urlcode/observability`: `Observer`, `ObserverEvent`, `MetricsSnapshot`,
-  `Metrics`, `RecordContext`. See [observability](OBSERVABILITY.md).
-- `@jimhoyd/urlcode/compliance`: `ComplianceRule`, `ProjectRule`, `RouteRule`,
-  `ProjectContext`, `RouteContext`, `RawFinding`, `Finding`,
-  `ComplianceOptions`, `ComplianceReport`, `ComplianceProfileName`. See
-  [compliance](COMPLIANCE.md).
-- `@jimhoyd/urlcode/prerender`: `PrerenderOptions`, `PrerenderedPage`,
-  `NativeProjectOptions`. See [prerendering](PRERENDER.md).
-- `@jimhoyd/urlcode/aws`, `@jimhoyd/urlcode/vercel`, `@jimhoyd/urlcode/cloudflare`: `LambdaEvent`,
-  `LambdaHandler`, `LambdaHandlerOptions`; `VercelHandler`,
-  `VercelHandlerOptions`; `Artifact`, `WorkerRoute`, `Validators`.
-- `@jimhoyd/urlcode/sandbox`: `SandboxPool`, `SandboxEntry`, `SandboxTarget`,
-  `SandboxInvocation`, `SandboxPoolOptions`, `functionFile`. The public
-  sandboxed-execution primitive: the same QuickJS/worker-thread engine that
-  already backs a `sandbox: true` `function`/`middleware` route
-  (`FunctionPool`, internally), generalized to an explicit list of
-  `{source, export}` entries instead of anything route/YAML-shaped, for an
-  extension package that needs to run a project-supplied hook through real
-  isolation when the project's own config declares `sandbox: true` on it
-  (see [EXTENSIONS.md](EXTENSIONS.md#project-level-lifecycle-hooks) and
-  [FUNCTION-SECURITY.md](FUNCTION-SECURITY.md)). There is no trusted-mode
-  export here: a hook that does not declare `sandbox: true` is ordinary
-  project code the extension `import()`s directly via
-  `ExtensionActivation.root`, no primitive required.
-
-  ```ts
-  import { SandboxPool, functionFile } from '@jimhoyd/urlcode/sandbox';
-
-  const source = await functionFile(root, hookConfig.source); // root: ExtensionActivation.root
-  const entries = [{ source, export: hookConfig.export ?? 'default' }];
-  const pool = await new SandboxPool(entries, { root, workers: 1 }).start();
-  const result = await pool.execute({ entry: entries[0] }, request, context, undefined);
-  await pool.close();
-  ```
-
-```ts
-import { startServer, type ServerOptions, type Observer } from '@jimhoyd/urlcode';
-import type { Plugin } from '@jimhoyd/urlcode/plugins';
-
-const audit: Plugin = { name: 'audit', version: '1.0.0', targets: ['node'], onError(request, error) { console.error(request.route, error); } };
-const forwarder: Observer = { name: 'forwarder', version: '1.0.0', onEvent(event) { queue.push(event); } };
-const options: ServerOptions = { project: './site', port: 3000, plugins: [audit], observers: [forwarder], metrics: true };
-const server = await startServer(options);
-await server.close();
-```
-
-## How `dist/` is built, and why it is the same JavaScript
-
-`npm run build` (`scripts/build.ts`) runs Node's own type stripping over every
-`src/*.ts`, the same transform that runs the source in development, and
-rewrites relative specifiers from `.ts` to `.js`. It does not bundle, minify,
-down-level or transform syntax, and it refuses to emit a file whose line count
-differs from its source, so every line and column of `dist/x.js` is the
-corresponding line of `src/x.ts` with types turned into whitespace. The
-`.d.ts` files come from `tsc` and never touch runtime output; the build fails
-on any type error. `dist` is never committed: the release workflow builds it
-in the digest-pinned container, records the Node and TypeScript versions and
-the per-file hashes in the signed manifest, and CI's `build-fidelity` job
-builds twice and diffs the trees. See [release security](RELEASE-SECURITY.md).
-
-## No runtime cost
-
-Because the shipped JavaScript is the stripped source, the package runs what
-it ran before the conversion. The measurement in
-[performance](PERFORMANCE.md#typescript-conversion-2026-09-17) compared the
-last plain-JavaScript commit with `dist/` on the same machine: CLI cold start,
-routing throughput, p95 latency and RSS are within run-to-run spread. Running
-the `.ts` source directly, as `npm run dev` does in a clone, costs about
-190 ms of cold start and 35 MiB for the stripping itself; that mode is the
-developer loop and never ships.
-
-## Contributing in TypeScript
-
-The source, scripts, tests and benchmarks are checked by `npm run typecheck`
-(strict, `noUncheckedIndexedAccess`, `exactOptionalPropertyTypes`,
-`erasableSyntaxOnly`), which `npm run verify` runs. Only erasable syntax is
-allowed, so no enums, namespaces or parameter properties: what Node can strip
-is exactly what the build emits. Contributors need Node 22.18+ to run the
-source; installed packages still run on 22.13+. See
-[local development](LOCAL-DEVELOPMENT.md).