@jimhoyd/urlcode 0.3.0 → 0.4.0-alpha.2

package/docs/yaml/functions.md

@@ -0,0 +1,160 @@
+# YAML guide: Functions, inputs and methods
+
+Snippets are entries under `routes:` unless stated otherwise; the [guide index](../YAML-GUIDE.md) lists every page.
+
+## 1. A URL that runs code
+
+A complete `urlcode.yaml`:
+
+```yaml
+version: "1"
+routes:
+  /hello/{name}:
+    function: functions/hello.mjs
+    env:
+      GREETING: {value: Hello}
+```
+
+Create `functions/hello.mjs`:
+
+```js
+export default function hello(request, {args, env}) {
+  return Response.json({message: `${env.GREETING}, ${args.name}!`});
+}
+```
+
+GET `/hello/Ada` returns JSON. HEAD invokes the function and suppresses the body.
+
+`function: functions/hello.mjs` is the short form. The loader expands it to the
+long form before anything else reads the route: every `{param}` in the path
+becomes a required string input (`minLength: 1`, `maxLength: 128`) and a
+matching `args` entry, so the route above is the same route as
+
+```yaml
+  /hello/{name}:
+    parameters:
+      - name: name
+        in: path
+        required: true
+        schema: {type: string, minLength: 1, maxLength: 128}
+    function:
+      source: functions/hello.mjs
+      args:
+        name: {from: path, name: name}
+    env:
+      GREETING: {value: Hello}
+```
+
+A path parameter the route declares itself keeps its own schema; only the
+undeclared ones get the default. Use the long form when you need a named
+`export`, query, header, `env` or `secret` arguments, or a tighter path schema.
+`routes`, `audit` and `explain` show the expansion. Middleware has the same
+short form: `middleware: [middleware/headers.mjs]` means
+`middleware: [{source: middleware/headers.mjs}]`. The path must be
+project-relative, end in `.mjs` or `.js` and contain no `..` segment.
+Methods default to GET and HEAD. Function paths resolve from the project root,
+not the YAML file's directory. `.js` and `.mjs` ES modules work; TypeScript, Node
+APIs, npm imports, network access and filesystem access do not.
+
+## 4. Input types and constraints
+
+Use this list under a route's `parameters` when those inputs are needed:
+
+```yaml
+    parameters:
+      - name: search
+        in: query
+        required: true
+        schema: {type: string, minLength: 1, maxLength: 200}
+      - name: page
+        in: query
+        schema: {type: integer, minimum: 1, default: 1}
+      - name: weight
+        in: query
+        schema: {type: number, minimum: 0, maximum: 1}
+      - name: preview
+        in: query
+        schema: {type: boolean, default: false}
+      - name: category
+        in: query
+        schema: {type: string, enum: [docs, news], default: docs}
+      - name: ids
+        in: query
+        schema: {type: array, items: {type: integer}, maxItems: 10}
+```
+
+Path inputs must be required strings with no default. Query/header scalar types
+are string, integer, number and boolean; arrays are query-only. Booleans are
+exactly `true`/`false`; numbers do not accept exponent notation or whitespace.
+Defaults apply to absence, not empty strings. Duplicate scalar values fail.
+Required, missing and invalid inputs return 400. This is a documented subset,
+not full OpenAPI/JSON Schema: no `pattern`, `format`, nested input objects,
+`oneOf`, `style` or `explode` in parameter schemas.
+
+## 5. Methods and body validation
+
+```yaml
+  /echo:
+    methods: [POST]
+    request:
+      body:
+        required: true
+        maxBytes: 4096
+        contentTypes: [application/json]
+        format: json
+    function:
+      source: functions/echo.mjs
+```
+
+```js
+export default async function echo(request) {
+  return Response.json(await request.json());
+}
+```
+
+This validates JSON syntax/media type/UTF-8 and body size, not an application
+object schema. Validate business fields in code. Empty required body: 400;
+oversized body: 413; wrong media type: 415. For text, use `contentTypes:
+[text/plain]`, `format: text`, and `request.text()`; see the runnable `/text`
+recipe. `maxBytes: 0` can reject nonempty bodies. Bodies are buffered, not streamed.
+
+Allowed methods: GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS. An explicit list
+replaces the defaults: `[GET]` does not add HEAD. Wrong method returns 405 with
+Allow. Asset handlers accept only GET/HEAD. Body bytes are not automatically
+mapped to function arguments.
+
+## 6. All function argument sources
+
+Within `function.args`, supported values are:
+
+```yaml
+      args:
+        label: campaign
+        attempts: 3
+        preview: false
+        code: {from: path, name: code}
+        page: {from: query, name: page}
+        channel: {from: header, name: x-channel}
+        greeting: {env: GREETING}
+        token: {secret: TOKEN}
+```
+
+This is a field-shape illustration: declare the referenced path/query/header
+inputs and route binding aliases before using it. Null, array and arbitrary
+object arguments are not supported. Read `context.args` or directly access
+`context.inputs.path/query/header`, `context.env` and `context.secrets`.
+`function.export` selects a named export; omit it for `default`.
+
+For a dynamic redirect, use validated choices instead of accepting any URL:
+
+```js
+export default function choice(request, {args}) {
+  const destinations = {docs: 'https://example.com/docs', home: 'https://example.com/'};
+  return Response.redirect(destinations[args.destination], 302);
+}
+```
+
+The runnable `/choice` recipe declares an enum query input and binds it to args.
+Functions can return `Response.json(...)`, `new Response('text', {status, headers})`,
+or `Response.redirect(...)`. HTML is a string response with Content-Type text/html;
+escape untrusted values yourself. See the exact [guest API](../SPECIFICATION.md#functions).

package/docs/yaml/middleware.md

@@ -0,0 +1,29 @@
+# YAML guide: Middleware
+
+Snippets are entries under `routes:` unless stated otherwise; the [guide index](../YAML-GUIDE.md) lists every page.
+
+## 7. Middleware before and after a handler
+
+```yaml
+  /go-with-header:
+    middleware:
+      - source: middleware/headers.mjs
+        export: decorate
+    redirect: {url: 'https://example.com/'}
+```
+
+```js
+export async function decorate(request, context, next) {
+  context.state.example = 'cookbook';
+  const response = await next();
+  response.headers.set('x-middleware', context.state.example);
+  return response;
+}
+```
+
+Entries run in declared order before the handler and reverse order afterward.
+Return a Response early to skip downstream code; call `next()` at most once.
+Up to 16 middleware entries share one sandbox/deadline and approved route
+bindings. Native bodies are opaque; preserving them requires retaining original
+status/headers. Return a new Response to replace native content or destination.
+YAML response headers apply last. See [middleware](../MIDDLEWARE.md) for details.

package/docs/yaml/organization.md

@@ -0,0 +1,74 @@
+# YAML guide: Bindings, split files and tests
+
+Snippets are entries under `routes:` unless stated otherwise; the [guide index](../YAML-GUIDE.md) lists every page.
+
+## 12. Environment and secret references
+
+Route-level shape (references only, never secret values):
+
+```yaml
+    env:
+      GREETING: {value: Hello}
+      REGION: {env: APP_REGION}
+    secrets:
+      TOKEN: {secret: APP_TOKEN}
+```
+
+Literal non-secret env needs no grant. External env and secrets require an
+operator-owned policy outside the checkout, granting exact names to the route
+and pinning the reviewed config/code digest. `urlcode permissions --project
+./my-links` prints a proposed policy; review it and store it outside the app.
+Then pass `--policy /operator/path/policy.json` to validate/dev/test/serve.
+This inspection does not authorize the project or execute its code.
+
+Use ignored `.env.local` for local values; process environment wins. Production
+`serve` reads process environment, never `.env.local`. Let your supervisor resolve
+provider secrets and inject them; direct provider secret-store adapters do not
+exist yet. Every config/code change invalidates the grant; rotate values by
+restarting/redeploying. Never return a secret in an example response. Middleware
+and functions on an approved route can read its bindings. See [policy setup](../FUNCTION-SECURITY.md).
+
+## 13. Split files and folders
+
+Complete entry point:
+
+```yaml
+version: "1"
+includes:
+  - routes/code.yaml
+  - routes/marketing/links.yaml
+routes: {}
+```
+
+Each included file contains `version: "1"` and `routes`. No nested includes,
+globs, anchors, merge keys or remote includes. References always use project-root
+paths. Duplicate routes fail; include order is not priority. See [organization](../ORGANIZATION.md)
+and [matching/regex/wildcard rules](../ROUTING.md).
+
+## 14. Assert inputs and outputs
+
+Save a JSON array as `tests/requests.json`:
+
+```json
+[
+  {"path":"/hello/Ada","status":200,"expectBody":"{\"message\":\"Hello, Ada!\"}"},
+  {"path":"/hello/Ada","method":"HEAD","status":200,"expectBody":""},
+  {"path":"/go","status":302,"expectHeaders":{"location":"https://example.com/"}},
+  {"path":"/go","method":"POST","status":405,"expectHeaders":{"allow":"GET, HEAD"}}
+]
+```
+
+This fixture targets recipes 1 and 2 together; the runnable cookbook has its own
+matching expectations. Supported test fields: `path`, optional `method`, request
+`headers` and string `body`, required `status`, optional exact string `expectBody`
+and string-map `expectHeaders`. Tests do not follow external redirects. There
+are no route-local YAML test fields or JSON-path assertions yet.
+
+Run validate, test, routes, and audit with an intentional expected count. Test
+both positive and negative inputs, every allowed method, HEAD, middleware short
+circuits and relevant asset conditions. Audit needs meaningful body/header
+assertions; a status-only success is insufficient. Benchmarks and recovery drills
+are separate from functional correctness. See [readiness](../READINESS.md).
+
+See [organization and readability practices](../BEST-PRACTICES.md) for conventions
+that keep larger projects easy to maintain.

package/docs/yaml/policies.md

@@ -0,0 +1,37 @@
+# YAML guide: Policies and profiles
+
+Snippets are entries under `routes:` unless stated otherwise; the [guide index](../YAML-GUIDE.md) lists every page.
+
+## 16. Hardened profile and per-route overrides
+
+```yaml
+version: "1"
+policies:
+  profile: hardened               # security, agents, throttle, compression, cache
+  throttle: { quota: 60, window: 60 }   # tighten one number; the rest stays
+profiles:
+  public-api:
+    security: { headers: oshp-no-csp, set: { x-robots-tag: noindex } }
+    cache: { strategy: swr, maxAge: 30, staleWhileRevalidate: 300 }
+routes:
+  /:
+    page: {source: pages/index.html}
+  /api/lookup/{id}:
+    parameters:
+      - {name: id, in: path, required: true, schema: {type: string, maxLength: 64}}
+    function: {source: functions/lookup.mjs}
+    policies:
+      profile: public-api          # merges over the project layer
+      throttle: {quota: 10, window: 60, partition: client-route}
+  /healthz:
+    respond: {text: ok}
+    policies: {throttle: false, agents: false}
+```
+
+Everything under `policies` is optional and off unless declared. The project
+block sets defaults, a route block adjusts them, `false` removes one policy for
+that route and an object merges shallowly over what is below it. `hardened`
+is the only built-in profile; `profiles` defines your own. Serve with
+`--trusted-proxies` when a proxy sits in front so `client` partitioning sees
+the real peer. Not every target accepts every policy: see the per-target
+table in [policies](../POLICIES.md) before deploying the same YAML to an adapter.

package/docs/yaml/redirects.md

@@ -0,0 +1,64 @@
+# YAML guide: Redirects
+
+Snippets are entries under `routes:` unless stated otherwise; the [guide index](../YAML-GUIDE.md) lists every page.
+
+## 2. Ordinary and permanent redirects
+
+The following snippets are **entries under `routes:`** unless stated otherwise:
+
+```yaml
+  /go:
+    redirect:
+      url: https://example.com/
+  /moved:
+    redirect:
+      url: https://example.com/new
+      status: 308
+    response:
+      headers:
+        Cache-Control: public, max-age=60
+```
+
+302 is the default. Allowed codes are 301, 302, 303, 307 and 308. Choose status
+and cache policy deliberately: a cached permanent redirect can outlive a server
+rollback. Requests' query strings are not forwarded by default. No function or
+middleware means no sandbox execution for these routes.
+
+## 3. Parameterized redirects and explicit query forwarding
+
+```yaml
+  /product/{id}:
+    parameters:
+      - name: id
+        in: path
+        required: true
+        schema: {type: string, minLength: 1, maxLength: 64}
+      - name: page
+        in: query
+        schema: {type: integer, minimum: 1, maximum: 100, default: 1}
+      - name: tag
+        in: query
+        schema: {type: array, items: {type: string}, maxItems: 3}
+      - name: x-channel
+        in: header
+        schema: {type: string, enum: [web, email], default: web}
+    redirect:
+      url: https://example.com/products/{id}
+      query:
+        map:
+          page: {from: query, name: page}
+          label: {from: query, name: tag}
+          channel: {from: header, name: x-channel}
+        pass: [utm_source]
+```
+
+`/product/abc?page=2&tag=red&tag=blue&utm_source=news&ignored=no` redirects to
+`https://example.com/products/abc?page=2&label=red&label=blue&channel=web&utm_source=news`.
+The unknown `ignored` key is dropped. Missing `page` becomes 1. Arrays produce
+repeated destination keys. Invalid page values return 400 before redirecting.
+
+Destination hosts/schemes are literal HTTP(S); path placeholders are safely
+encoded. No arbitrary input-controlled host, credentials, secret interpolation,
+or unrestricted `pass: true`. Mapping/passthrough keys must not collide with
+existing destination keys. Header inputs are client-supplied values, not proof
+of identity. See [input and redirect semantics](../SPECIFICATION.md).

package/docs/yaml/responses.md

@@ -0,0 +1,57 @@
+# YAML guide: Declared responses, headers and cookies
+
+Snippets are entries under `routes:` unless stated otherwise; the [guide index](../YAML-GUIDE.md) lists every page.
+
+## 8. Native responses, headers and cookies
+
+```yaml
+  /status:
+    respond:
+      json: {ok: true, service: my-links}
+  /notice:
+    respond:
+      status: 503
+      text: Temporarily unavailable
+    response:
+      headers:
+        Retry-After: "60"
+  /empty:
+    respond: {status: 204}
+  /cookie-demo:
+    respond: {text: Non-secret preferences only}
+    response:
+      headers:
+        Set-Cookie:
+          - "theme=light; Path=/; Secure; SameSite=Lax"
+          - "notice=seen; Path=/; HttpOnly; Secure; SameSite=Lax"
+```
+
+`respond` defaults to 200. Use text or JSON, never both. Omit both for an empty
+body; 204/205 must have no body. 206/304 belong to native asset handling.
+Header values are literal strings; quote numeric-looking values. Only Set-Cookie
+accepts arrays. Do not put live session tokens in YAML. Secure cookies require
+HTTPS at the browser. Functions can create dynamic cookies, but no cookie
+parsing/signing/authentication framework is built in.
+
+Do not set Content-Length, Location, Allow, ETag, Content-Range or other
+runtime-owned headers in YAML. Use the corresponding handler. The full reserved
+list and precedence rules are in [HTTP](../HTTP.md).
+
+## 9. Explicit OPTIONS response (not automatic CORS)
+
+```yaml
+  /preflight:
+    methods: [OPTIONS]
+    respond: {status: 204}
+    response:
+      headers:
+        Access-Control-Allow-Origin: https://app.example.com
+        Access-Control-Allow-Methods: GET, HEAD
+        Access-Control-Allow-Headers: Content-Type
+```
+
+This teaches declared headers only; it is not a working cross-origin GET API.
+For a real API, OPTIONS and the actual methods must be handled on the same URL,
+and actual responses also need the appropriate CORS headers. Because one path
+has one handler, use a function with `[GET, HEAD, OPTIONS]` to branch on method.
+Never reflect arbitrary Origin with credentials. Automatic CORS is unsupported.

package/docs/yaml/site.md

@@ -0,0 +1,24 @@
+# YAML guide: Site conventions
+
+Snippets are entries under `routes:` unless stated otherwise; the [guide index](../YAML-GUIDE.md) lists every page.
+
+## 17. Site conventions
+
+Generate the well-known files from a top-level `site` block instead of writing
+them by hand. Each declared key becomes one native route counted by
+`routes`/`audit`; a declared route at the same path wins.
+
+```yaml
+site:
+  robots:
+    disallow: [ai-crawlers, /admin]
+    sitemap: true                 # Sitemap line needs --origin
+  favicon: public/favicon.svg     # served at /favicon.ico
+  securityTxt:
+    contact: [mailto:security@example.com]
+    expires: "2099-01-01T00:00:00Z"
+  llms: public/llms.txt           # served at /llms.txt
+  # sitemap: true                 # /sitemap.xml; refuses to start without --origin
+```
+
+See [site conventions](../SITE.md) for every field, exclusions and target support.

package/examples/assets/example.yaml

@@ -0,0 +1,17 @@
+id: assets
+description: Pages, a static directory, a download and one function next to them; the asset snapshot and cache rules in one small runnable project.
+tags: [assets, static, page, download, html, files, cache, snapshot, function]
+complexity: intermediate
+capabilities: [bindings, download, enabled, function, methods, page, parameters, redirect, static]
+targets: {self-hosted: compatible, aws: refused, vercel: refused, cloudflare: refused, static: refused}
+routes: 5
+files: [urlcode.yaml, functions/hello.mjs, public/about.html, public/guide.txt, public/assets/example.txt, tests/requests.json, README.md]
+tests:
+  fixtures: tests/requests.json
+  commands:
+    - node src/cli.ts validate --local --project examples/assets
+    - node src/cli.ts test --project examples/assets
+    - node src/cli.ts audit --project examples/assets --expect-routes 5
+behavior:
+  - native page, static and download routes serve snapshotted files with explicit caching
+  - one sandboxed function shows the two kinds of route side by side

package/examples/aws/example.yaml

@@ -0,0 +1,20 @@
+id: aws
+description: Native-handler project served by an AWS Lambda Function URL through the aws adapter.
+tags: [aws, lambda, serverless, deploy, adapter, native, page, static, redirect, respond, sam]
+complexity: intermediate
+capabilities: [enabled, methods, page, parameters, redirect, respond, static]
+targets: {self-hosted: compatible, aws: compatible, vercel: compatible, cloudflare: refused, static: refused}
+routes: 5
+services:
+  - name: AWS Lambda
+    description: A Function URL deployed from template.yaml; local tests replay the adapter without an account.
+files: [urlcode.yaml, handler.mjs, template.yaml, public/index.html, public/notes.txt, tests/requests.json, README.md]
+tests:
+  fixtures: tests/requests.json
+  commands:
+    - node src/cli.ts validate --local --project examples/aws
+    - node src/cli.ts test --project examples/aws
+    - node src/cli.ts audit --project examples/aws --expect-routes 5
+behavior:
+  - every route is native, so the project activates on Lambda without the sandbox
+  - handler.mjs wraps the project with createLambdaHandler; deployment itself is unverified evidence

package/examples/cloudflare/example.yaml

@@ -0,0 +1,19 @@
+id: cloudflare
+description: Declarative redirect and respond project compiled into a Cloudflare Worker artifact.
+tags: [cloudflare, workers, wrangler, compile, deploy, serverless, redirect, respond, native]
+complexity: intermediate
+capabilities: [enabled, methods, parameters, redirect, respond, response.headers]
+targets: {self-hosted: compatible, aws: compatible, vercel: compatible, cloudflare: compatible, static: refused}
+routes: 4
+services:
+  - name: Cloudflare Workers
+    description: wrangler deploys the artifact that urlcode build-cloudflare emits; local tests replay the compiled routes.
+files: [urlcode.yaml, wrangler.toml, tests/requests.json, README.md]
+tests:
+  fixtures: tests/requests.json
+  commands:
+    - node src/cli.ts validate --local --project examples/cloudflare
+    - node src/cli.ts test --project examples/cloudflare
+    - node src/cli.ts audit --project examples/cloudflare --expect-routes 4
+behavior:
+  - only capabilities the Worker lowering supports appear, so the build succeeds on every target

package/examples/compliance/example.yaml

@@ -0,0 +1,11 @@
+id: compliance
+description: An operator rules module for urlcode audit --compliance-rules that adds, disables and re-grades compliance rules.
+tags: [compliance, audit, rules, operator, policy, redirect-hosts, security-headers]
+complexity: advanced
+runnable: false
+files: [rules.mjs, README.md]
+tests:
+  commands:
+    - node src/cli.ts audit --project examples/cookbook --compliance baseline --compliance-rules "$PWD/examples/compliance/rules.mjs" --compliance-warn
+behavior:
+  - three custom rules run alongside the built-in profile; one built-in notice is disabled and one severity raised

package/examples/conditions/README.md

@@ -0,0 +1,12 @@
+# Exact routing conditions
+
+Run the executable fixture with the operator-owned public origin:
+
+```sh
+urlcode test --project examples/conditions --origin https://conditions.example.test
+```
+
+The 11 requests cover disjoint campaign cases, fallback, header/cookie guards,
+duplicate rejection, HEAD and trusted-origin matching. All data is synthetic.
+Conditions compare request inputs; they do not authorize users or grant guest
+capabilities. See [the condition contract](../../docs/CONDITIONS.md).

package/examples/conditions/example.yaml

@@ -0,0 +1,19 @@
+id: conditions
+description: Exact query, header, cookie, host and method conditions choosing between disjoint redirect and respond branches.
+tags: [conditions, conditional, match, query, header, cookie, host, method, redirect, respond, disjoint]
+complexity: intermediate
+capabilities: [conditional, conditions, enabled, methods, redirect, respond]
+targets: {self-hosted: compatible, aws: compatible, vercel: compatible, cloudflare: refused, static: refused}
+routes: 4
+grants:
+  - kind: origin
+    description: The public origin passed as --origin, because host conditions compare against it.
+files: [urlcode.yaml, tests/requests.json, README.md]
+tests:
+  fixtures: tests/requests.json
+  commands:
+    - node src/cli.ts validate --local --project examples/conditions --origin https://conditions.example.test
+    - node src/cli.ts test --project examples/conditions --origin https://conditions.example.test
+    - node src/cli.ts audit --project examples/conditions --expect-routes 4 --origin https://conditions.example.test
+behavior:
+  - cases are provably disjoint and every branch stays no-store; no branch is authentication

package/examples/conditions/tests/requests.json

@@ -0,0 +1,13 @@
+[
+  {"path":"/campaign?source=newsletter","status":307,"expectHeaders":{"location":"https://example.test/newsletter","cache-control":"no-store"}},
+  {"path":"/campaign?source=partner","status":200,"expectBody":"{\"campaign\":\"partner\"}"},
+  {"path":"/campaign","status":200,"expectBody":"Choose a campaign"},
+  {"path":"/campaign?source=newsletter&source=partner","status":400},
+  {"path":"/campaign","method":"HEAD","status":200,"expectBody":""},
+  {"path":"/beta","status":404},
+  {"path":"/beta","headers":{"x-beta-user":"true","cookie":"bucket=beta"},"status":200,"expectBody":"beta preview"},
+  {"path":"/beta","headers":{"x-beta-user":"true","cookie":"bucket=beta; bucket=other"},"status":400},
+  {"path":"/host","headers":{"host":"attacker.example.test","x-forwarded-host":"attacker.example.test"},"status":200,"expectBody":"trusted origin"},
+  {"path":"/limited","status":200,"expectBody":"get only"},
+  {"path":"/limited","method":"HEAD","status":404,"expectBody":""}
+]

package/examples/conditions/urlcode.yaml

@@ -0,0 +1,24 @@
+version: "1"
+routes:
+  /campaign:
+    conditional:
+      cases:
+        - match: {query: {source: newsletter}}
+          redirect: {url: https://example.test/newsletter, status: 307}
+        - match: {query: {source: partner}}
+          respond: {json: {campaign: partner}}
+      fallback:
+        respond: {text: Choose a campaign}
+  /beta:
+    match:
+      headers: {x-beta-user: "true"}
+      cookies: {bucket: beta}
+    respond: {text: beta preview}
+  /host:
+    match: {host: conditions.example.test}
+    respond: {text: trusted origin}
+  /limited:
+    conditional:
+      cases:
+        - match: {method: GET}
+          respond: {text: get only}

package/examples/cookbook/README.md

@@ -1,9 +1,11 @@
 # Runnable YAML cookbook
 
-25 routes covering all six handlers, middleware, inputs, body validation, response
+40 routes covering all six handlers, middleware, inputs, body validation, response
 headers, cookies, methods, expiry, assets, included files and host policies
 (security headers, agent denial, caching and a request budget) plus generated site
-conventions (robots.txt, favicon, security.txt, llms.txt). No credentials or
+conventions (robots.txt, favicon, security.txt, llms.txt). Fifteen of the routes
+exercise the fourteen reusable modules in `middleware/`, described in
+[middleware examples](../../docs/MIDDLEWARE-EXAMPLES.md). No credentials or
 external services are required. Redirects target example.com; tests never follow them.
 
 From the runtime checkout:
@@ -11,11 +13,13 @@ From the runtime checkout:
 ```sh
 node src/cli.ts validate --project examples/cookbook
 node src/cli.ts test --project examples/cookbook
-node src/cli.ts audit --project examples/cookbook --expect-routes 25
+node src/cli.ts audit --project examples/cookbook --expect-routes 40
 node src/cli.ts dev --project examples/cookbook
 ```
 
 The [YAML guide](../../docs/YAML-GUIDE.md) explains the recipes and binding policy.
 `/notice` deliberately returns 503, `/paused` 404 and `/expired` 410. `/preflight`
-is an OPTIONS/header example, not a complete cross-origin API. The small default
+is an OPTIONS/header example, not a complete cross-origin API; `/cors/data` is the
+middleware version. `/maintenance` returns 503 without its bypass header and
+`/inspect` echoes request details only with `X-Debug: 1`. The small default
 starter remains the recommended starting point for a new application.

package/examples/cookbook/example.yaml

@@ -0,0 +1,17 @@
+id: cookbook
+description: Forty runnable routes covering every handler, middleware, inputs, body validation, headers, assets, includes, host policies and site conventions; route-index.json tags each one.
+tags: [cookbook, reference, routes, handlers, middleware, policies, site, includes, parameters, cookies, methods, expiry, assets, everything]
+complexity: advanced
+capabilities: [bindings, download, enabled, expires, function, methods, middleware, page, parameters, policies.agents, policies.cache, policies.security, policies.throttle, redirect, request.body, respond, response.headers, static]
+targets: {self-hosted: compatible, aws: refused, vercel: refused, cloudflare: refused, static: refused}
+routes: 40
+files: [urlcode.yaml, routes/code.yaml, routes/redirects.yaml, routes/responses.yaml, routes/files.yaml, routes/policies.yaml, routes/middleware.yaml, route-index.json, tests/requests.json, README.md]
+tests:
+  fixtures: tests/requests.json
+  commands:
+    - node src/cli.ts validate --local --project examples/cookbook
+    - node src/cli.ts test --project examples/cookbook
+    - node src/cli.ts audit --project examples/cookbook --expect-routes 40
+behavior:
+  - urlcode examples search finds single routes here through the generated route-index.json
+  - fifteen routes exercise the fourteen middleware modules that the middleware recipe copies

package/examples/cookbook/functions/catalog.mjs

@@ -0,0 +1,3 @@
+export default function catalog() {
+  return Response.json({version: 3, items: ['alpha', 'beta']});
+}

package/examples/cookbook/functions/fail.mjs

@@ -0,0 +1,4 @@
+export default function fail(request, {args}) {
+  if (args.fail) throw new Error('simulated failure');
+  return Response.json({healthy: true});
+}

package/examples/cookbook/functions/items.mjs

@@ -0,0 +1,3 @@
+export default function items() {
+  return Response.json([{id: 1, name: 'first'}, {id: 2, name: 'second'}]);
+}