@jimhoyd/urlcode 0.3.0 → 0.4.0-alpha.2

package/docs/STARTERS.md

@@ -30,7 +30,9 @@ Neither path forks the runtime or needs a hosting account or database.
 ## Files and growth
 
 `urlcode.yaml` includes a function route file and a redirect file in a nested
-folder. A JavaScript function, HTTP assertions and optional Makefile are included.
+folder. A JavaScript function, HTTP assertions and optional Makefile are included,
+plus `.github/workflows/urlcode.yml`, which runs the [project checks action](CI.md)
+on every push and pull request once the project is on GitHub.
 See [organization](ORGANIZATION.md) for choosing your own layout. Defaults allow
 GET/HEAD and use redirect 302; add configuration only when changing behavior.
 
@@ -40,6 +42,24 @@ application files. Add pages, downloads, more functions and business-specific
 features to this same project. Update tests and the expected route count as it grows.
 See [readiness](READINESS.md) and [security](FUNCTION-SECURITY.md).
 
+To start an extended site instead, install the extension packages from npm
+(`npm install @jimhoyd/urlcode-auth @jimhoyd/urlcode-admin`, published as
+`0.1.0-alpha.x` prereleases) in the directory you run from and pass their names: `urlcode init ../my-site --with
+auth,admin` writes the same starter under `my-site/app/`, merges each package's
+routes and declarations into it, and generates one `host.mjs` and README beside
+it. The contract each package fulfils is in [extensions](EXTENSIONS.md#scaffolding-with-init---with).
+
+Both paths carry an `AGENTS.md` for repository-aware assistants. `urlcode init`
+generates it from the installed runtime's capability catalog (the same source as
+`urlcode capabilities`), so it names only the handlers, policies and site keys
+that version implements, plus the exact `validate`, `test` and `audit` commands
+with the starter's route count. The committed copy in `starters/default` is
+regenerated from the same function and a test keeps the two identical. The file
+points at the agent skill the package ships at `skills/urlcode/SKILL.md`.
+Both paths also write `.mcp.json`, which registers the read-only `urlcode mcp`
+server for Claude Code and Codex (`--project app` for an extended site); it is
+never overwritten and carries no `--allow-authoring` ([tooling](TOOLING.md#registering-the-server)).
+
 `examples/assets` contains a larger runnable file/page/download demonstration:
 `make dev PROJECT=examples/assets`. It is an example, not a separate init choice.
 

package/docs/STATIC.md

@@ -0,0 +1,94 @@
+# Deploying to static hosting (S3 + CloudFront)
+
+The `static` target is the bottom rung of the [capability
+ladder](SPIKE-CORE-LAYERING.md#the-full-ladder-one-contract-one-vocabulary-per-level):
+the same `urlcode.yaml` a self-hosted server or a serverless adapter runs, with
+no server process at all. `urlcode build --target static` compiles a project
+ahead of time into plain files and two small JSON manifests meant for an S3
+bucket served through CloudFront — nothing here executes a request.
+
+```sh
+urlcode build --target static --project . --out dist --origin https://links.example
+```
+
+## Declarative routes only, and less than that
+
+This target serves **redirects**, **declared responses** (`respond:`) and
+static files (`page`, `static`, `download`) — no path parameters, no query
+passthrough or mapping, GET/HEAD only, and no `enabled: false` or `expires`
+(there is no server to answer a disabled or expired route with 404/410, so the
+build refuses one instead of silently serving it forever). Everything else is
+refused **at build time**, with the route pattern and the reason named:
+
+| Handler / feature | Why it is refused |
+| --- | --- |
+| `function`, `middleware` | no server, so no dynamic or sandboxed execution |
+| `extension`, `policies.extensions` | no server, so no operator extension registry |
+| `proxy`, `signals` | no server, so no bounded or fire-and-forget egress |
+| `conditional`, `match` (`conditions`) | no server, so no request-time condition matching |
+| `parameters`, `request.body` | no server, so no request-time validation |
+| `response.headers` | no server, so no per-request headers; set them as S3 object metadata or a CloudFront response headers policy instead |
+| `env`, `secrets` (`bindings`) | no server, so no per-request binding resolution |
+| every `policies.*` | no server, so no runtime policy enforcement |
+| a redirect with a `{parameter}` in its path | S3's per-object redirect is keyed to one exact object, not a pattern |
+| a redirect with `query.pass`/`query.map` | S3's per-object redirect cannot compute a target per request |
+| a redirect with a `status` other than 301 | S3's per-object website redirect always answers 301 |
+| a route declaring methods other than GET/HEAD | static hosting only ever answers GET/HEAD |
+| a route with `enabled: false` or `expires` | no server to answer a disabled/expired route; remove the route instead |
+
+Run `urlcode capabilities --target static` for the full catalog.
+
+## What the build emits
+
+`--out` (default `dist/static`) receives:
+
+- `objects/<key>` — the actual files to upload, one per served route. A `page`
+  or `download` route becomes one file; a `static` mount becomes one file per
+  entry in its directory. Object keys match the S3 convention: the route
+  pattern with its leading `/` stripped, and `/` itself becomes `index.html`
+  (matching a bucket's own "Index document" setting). A redirect route also
+  gets a zero-byte placeholder object at its key, so it exists to carry
+  metadata.
+- `objects.json` — `{ format, objects: [{ key, contentType, cacheControl?,
+  contentDisposition? }] }`. Plain file upload loses this metadata (S3 does not
+  reliably infer content type or cache headers from an extension-less key), so
+  a deploy step reads this file and sets each object's own `Content-Type`,
+  `Cache-Control` and `Content-Disposition` from it, for example with
+  `aws s3 cp --content-type ... --cache-control ...` per entry, or an
+  equivalent `aws s3 sync` post-processing step.
+- `redirects.json` — `{ format, redirects: [{ key, location, status: 301 }] }`.
+  Each entry is applied as the S3 object's
+  [website redirect location](https://docs.aws.amazon.com/AmazonS3/latest/userguide/how-to-page-redirect.html)
+  metadata (`x-amz-website-redirect-location`), for example
+  `aws s3api put-object --website-redirect-location <location> --bucket ... --key <key>`.
+  S3 always answers a request for that key with a 301 to `location`
+  regardless of the object's own content — this is why a declared `status`
+  other than 301 is refused rather than silently downgraded.
+- `manifest.json` — the same project-level semantic manifest every target
+  writes (see [tooling](TOOLING.md)).
+
+None of these are edited by hand, and `dist/` belongs in `.gitignore`. This
+target ships no runtime import (there is nothing to run), so there is no
+`@jimhoyd/urlcode/static` entry point — the build output is the deployment.
+
+## What this is not: GitHub Pages
+
+**This target's claimed support is S3 + CloudFront, not GitHub Pages.**
+GitHub Pages has no per-object redirect metadata and no server-side rewrite
+layer, so a `redirect` route compiled the way this target compiles it (S3
+object metadata) has no equivalent there — the only options are a
+meta-refresh/JavaScript page (visibly a redirect, not an HTTP one: search
+engines, curl and anything that does not run JavaScript sees the source page,
+not a 3xx) or a static 404-page trick, both lower fidelity than what every
+other target in this project does for the same route. Rather than claim a
+portability promise this platform cannot keep, GitHub Pages is out of scope
+for this target. If you need Pages, treat it as a distinct target with its own
+explicit fidelity caveat, not a rename of this one.
+
+## Verification status
+
+This target has local build tests only (`test/static.test.ts`): the compiled
+object layout, the redirect manifest, and every refusal above. **It has not
+been deployed to S3 or fronted by CloudFront.** Bucket policy, CloudFront
+caching behavior, TLS/domain setup and the exact `aws s3` invocations above are
+unverified until a real deployment exercises them.

package/docs/TOOLING.md

@@ -0,0 +1,295 @@
+# 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 (no guest network,
+  no Node APIs, no regex routes, one handler per route, exact or `{param}`
+  path segments, subtree mounts only for static and extension routes, no YAML
+  interpolation, secrets by operator grant only), each with a value and a note.
+- `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, 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, 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

@@ -65,9 +65,6 @@ scanners that find it within minutes.
 - 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.
-- **Never tunnel the link-management API.** It is a separate listener bound to
-  loopback on purpose, holding credentials that can rewrite live links. Tunnel
-  the application port only.
 - Prefer `serve` with a fixed snapshot, a project containing no real secrets,
   and a tunnel you shut down when finished.
 

package/docs/TYPESCRIPT-AUTHORING.md

@@ -0,0 +1,82 @@
+# 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 size ceiling. 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

@@ -16,7 +16,7 @@ beside them, and `dist/BUILD-MANIFEST.json` with a SHA-256 per emitted file.
 | 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` | `dist/<name>.js` | `dist/types/<name>.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` | — |
 
@@ -36,9 +36,7 @@ release cannot ship a declaration that does not resolve.
 ## The main exported types
 
 - `urlcode`: `Runtime`, `RuntimeOptions`, `RuntimeRequest`, `RequestTrace`,
-  `Server`, `ServerOptions`, `HostPlugin`, `Observer`, `TestPlan`, `LinkStore`,
-  `LinkRow`, `LinkStoreOptions`, `LinkReader`, `LinkStoreBinding`, `LinkApi`,
-  `LinkApiOptions`, `LinkEvent`, `LinkObserverOptions`.
+  `Server`, `ServerOptions`, `HostPlugin`, `Observer`, `TestPlan`.
 - `@jimhoyd/urlcode/plugins`: `Plugin`, `PluginRuntime`, `PolicyRequest`,
   `HandlerResult`, `HeaderPair`, `TargetName`. See [plugins](PLUGINS.md).
 - `@jimhoyd/urlcode/policies`: `PolicyModule`, `PolicyRegistry`, `PolicyRequest`,
@@ -54,6 +52,29 @@ release cannot ship a declaration that does not resolve.
 - `@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';