@jimhoyd/urlcode 0.3.0

package/examples/aws/urlcode.yaml

@@ -0,0 +1,19 @@
+version: "1"
+routes:
+  /go:
+    redirect:
+      url: https://example.com/target
+  /u/{id}:
+    parameters:
+      - {name: id, in: path, required: true, schema: {type: string}}
+    redirect:
+      url: https://example.com/users/{id}
+  /health:
+    respond:
+      json: {ok: true}
+  /:
+    page:
+      file: public/index.html
+  /files/*:
+    static:
+      directory: public

package/examples/cloudflare/README.md

@@ -0,0 +1,18 @@
+# URLCode on Cloudflare Workers
+
+A declarative project compiled to a Worker. See
+[the target guide](../../docs/CLOUDFLARE.md) for what is and is not supported.
+
+```sh
+urlcode test --project .   # the same assertions run against the local runtime
+npm run build              # writes dist/{index,artifact,validators}.js
+npx wrangler deploy
+```
+
+The build is the deploy unit: `dist/` is generated, never edited, and never
+committed. Rebuild after every change to `urlcode.yaml` — the Worker reads the
+artifact, not the YAML.
+
+`wrangler.toml` sets no `nodejs_compat` flag on purpose. The runtime and the
+precompiled schema validators use Web standards only, so nothing here needs a
+Node compatibility layer.

package/examples/cloudflare/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "urlcode-cloudflare-example",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "urlcode build --target cloudflare --project . --out dist"
+  },
+  "dependencies": {
+    "@jimhoyd/urlcode": "^0.3.0"
+  },
+  "devDependencies": {
+    "wrangler": "^4"
+  }
+}

package/examples/cloudflare/tests/requests.json

@@ -0,0 +1,9 @@
+[
+  {"path": "/go", "status": 302, "expectHeaders": {"location": "https://example.com/target"}},
+  {"path": "/u/42", "status": 302, "expectHeaders": {"location": "https://example.com/users/42"}},
+  {"path": "/search?q=links", "status": 302, "expectHeaders": {"location": "https://example.com/search?q=links"}},
+  {"path": "/search", "status": 302, "expectHeaders": {"location": "https://example.com/search?q=urlcode"}},
+  {"path": "/health", "status": 200, "expectBody": "{\"ok\":true}"},
+  {"path": "/nothing-here", "status": 404},
+  {"path": "/go", "method": "HEAD", "status": 302, "expectHeaders": {"location": "https://example.com/target"}, "expectBody": ""}
+]

package/examples/cloudflare/urlcode.yaml

@@ -0,0 +1,24 @@
+version: "1"
+routes:
+  /go:
+    redirect:
+      url: https://example.com/target
+  /u/{id}:
+    parameters:
+      - {name: id, in: path, required: true, schema: {type: string}}
+    redirect:
+      url: https://example.com/users/{id}
+  /search:
+    parameters:
+      - {name: q, in: query, required: false, schema: {type: string, maxLength: 64, default: urlcode}}
+    redirect:
+      url: https://example.com/search
+      query:
+        map:
+          q: {from: query, name: q}
+  /health:
+    respond:
+      json: {ok: true}
+    response:
+      headers:
+        cache-control: no-store

package/examples/cloudflare/wrangler.toml

@@ -0,0 +1,5 @@
+name = "urlcode-example"
+main = "dist/index.js"
+compatibility_date = "2025-09-01"
+# No nodejs_compat: the runtime and the generated validators use Web standards
+# only, so the Worker starts without a Node compatibility layer.

package/examples/compliance/README.md

@@ -0,0 +1,20 @@
+# Custom compliance rules
+
+`rules.mjs` is an operator rules module for `urlcode audit --compliance-rules`.
+It adds three rules (an approved redirect host list, a description on every
+route, a reminder to declare the origin), disables the built-in expired-routes
+notice and raises the security-headers rule to `high`. See
+[docs/COMPLIANCE.md](../../docs/COMPLIANCE.md) for the contract.
+
+Run it against the cookbook from the runtime checkout. The module must be an
+absolute path outside the audited project:
+
+```sh
+node src/cli.ts audit --project examples/cookbook \
+  --compliance baseline --compliance-rules "$PWD/examples/compliance/rules.mjs" --compliance-warn
+```
+
+Without `--compliance-warn` the run exits 1: the override makes the cookbook's
+routes without `policies.security` high findings. The report's `compliance`
+section lists every finding with its rule, severity, route, message,
+remediation and the standard it cites.

package/examples/compliance/rules.mjs

@@ -0,0 +1,65 @@
+// Operator compliance rules for `urlcode audit --compliance-rules`.
+// Runnable against the cookbook from the runtime checkout:
+//
+//   node src/cli.js audit --project examples/cookbook \
+//     --compliance baseline --compliance-rules "$PWD/examples/compliance/rules.mjs" --compliance-warn
+//
+// The file must sit outside the audited project (it is trusted host code, the
+// same rule as --policy). It exports `rules` to add, `disable` to drop
+// built-in rules by id, and `override` to change fields of an existing rule.
+// Every check reads only the context runCompliance hands it: the parsed YAML
+// (`document`, `routes`), the runtime's test plan (`plan`), the effective
+// policies per route (`policies`, `effective`), the declared `origin` and the
+// declared `host` settings.
+
+// Which redirect hosts this operator considers their own.
+const allowedHosts = ['example.com', 'www.example.com'];
+
+export const rules = [
+  {
+    id: 'acme/redirect-hosts',
+    title: 'Redirects only leave for approved hosts',
+    standard: { name: 'ACME link policy', reference: 'https://example.com/policies/links', section: 'Outbound redirects' },
+    severity: 'high',
+    appliesTo: 'route',
+    check({ route, config }) {
+      const url = config.redirect?.url;
+      if (route.state !== 'active' || typeof url !== 'string') return [];
+      // Templates such as https://host/{id} still start with a fixed host.
+      let host;
+      try { host = new URL(url.replace(/\{[^}]*\}/g, 'x')).hostname; } catch { return [{ message: `${route.path} redirect target could not be parsed`, remediation: 'Use an absolute https URL' }]; }
+      if (allowedHosts.includes(host)) return [];
+      return [{ message: `${route.path} redirects to ${host}, which is not an approved host`, remediation: `Redirect only to ${allowedHosts.join(', ')} or extend the allow list in rules.mjs` }];
+    },
+  },
+  {
+    id: 'acme/described-routes',
+    title: 'Every active route carries a description',
+    standard: { name: 'ACME YAML conventions', reference: 'https://example.com/policies/yaml' },
+    severity: 'low',
+    appliesTo: 'route',
+    check({ route, config }) {
+      if (route.state !== 'active' || typeof config.description === 'string') return [];
+      return [{ message: `${route.path} has no description`, remediation: 'Add a one-line description so audits and reviews can name the route by purpose' }];
+    },
+  },
+  {
+    id: 'acme/declared-origin',
+    title: 'The audit declares the public origin',
+    standard: { name: 'ACME deployment checklist', reference: 'https://example.com/policies/deploy' },
+    severity: 'info',
+    appliesTo: 'project',
+    check({ origin }) {
+      if (origin) return [];
+      return [{ message: 'No --origin was declared, so origin-dependent rules cannot confirm https', remediation: 'Pass --origin https://your.host to audit' }];
+    },
+  },
+];
+
+// The cookbook keeps an expired route on purpose to show a 410.
+export const disable = ['rfc9110/expired-routes'];
+
+// This operator treats a missing security profile as blocking.
+export const override = {
+  'oshp/security-headers': { severity: 'high' },
+};

package/examples/cookbook/README.md

@@ -0,0 +1,21 @@
+# Runnable YAML cookbook
+
+25 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
+external services are required. Redirects target example.com; tests never follow them.
+
+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 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
+starter remains the recommended starting point for a new application.

package/examples/cookbook/functions/choice.mjs

@@ -0,0 +1,4 @@
+export default function choice(request, {args}) {
+  const destinations = {docs: 'https://example.com/docs', home: 'https://example.com/'};
+  return Response.redirect(destinations[args.destination], 302);
+}

package/examples/cookbook/functions/echo.mjs

@@ -0,0 +1,3 @@
+export default async function echo(request) {
+  return Response.json(await request.json());
+}

package/examples/cookbook/functions/hello.mjs

@@ -0,0 +1,3 @@
+export function hello(request, {args}) {
+  return Response.json({message: `${args.greeting}, ${args.name}${args.excited ? args.punctuation : '.'}`});
+}

package/examples/cookbook/functions/text.mjs

@@ -0,0 +1,3 @@
+export default async function text(request) {
+  return new Response(await request.text());
+}

package/examples/cookbook/middleware/headers.mjs

@@ -0,0 +1,6 @@
+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;
+}

package/examples/cookbook/public/about.html

@@ -0,0 +1 @@
+<!doctype html><title>About URLCode</title>About

package/examples/cookbook/public/assets/index.html

@@ -0,0 +1 @@
+<!doctype html><title>Assets</title>Assets

package/examples/cookbook/public/assets/site.css

@@ -0,0 +1 @@
+body { color: navy; }

package/examples/cookbook/public/favicon.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16"><rect width="16" height="16" rx="3" fill="#1d4ed8"/><text x="8" y="12" font-size="10" text-anchor="middle" fill="#fff" font-family="sans-serif">U</text></svg>

package/examples/cookbook/public/guide.txt

@@ -0,0 +1 @@
+URLCode guide

package/examples/cookbook/public/llms.txt

@@ -0,0 +1,6 @@
+# Cookbook
+
+> A runnable URLCode example project. Routes are declared in urlcode.yaml.
+
+- /status: JSON health response
+- /about: HTML page

package/examples/cookbook/routes/code.yaml

@@ -0,0 +1,55 @@
+version: "1"
+routes:
+  /hello/{name}:
+    description: Validated input, named export, arguments, literal environment and middleware
+    parameters:
+      - name: name
+        in: path
+        required: true
+        schema: {type: string, minLength: 1, maxLength: 80}
+      - name: excited
+        in: query
+        schema: {type: boolean, default: false}
+    env:
+      GREETING: {value: Hello}
+    middleware:
+      - source: middleware/headers.mjs
+        export: decorate
+    function:
+      source: functions/hello.mjs
+      export: hello
+      args:
+        name: {from: path, name: name}
+        excited: {from: query, name: excited}
+        greeting: {env: GREETING}
+        punctuation: "!"
+    response:
+      headers:
+        X-App: cookbook
+  /echo:
+    methods: [POST]
+    request:
+      body:
+        required: true
+        maxBytes: 4096
+        contentTypes: [application/json]
+        format: json
+    function: {source: functions/echo.mjs}
+  /text:
+    methods: [POST]
+    request:
+      body:
+        required: true
+        maxBytes: 1024
+        contentTypes: [text/plain]
+        format: text
+    function: {source: functions/text.mjs}
+  /choice:
+    parameters:
+      - name: destination
+        in: query
+        schema: {type: string, enum: [docs, home], default: docs}
+    function:
+      source: functions/choice.mjs
+      args:
+        destination: {from: query, name: destination}

package/examples/cookbook/routes/files.yaml

@@ -0,0 +1,17 @@
+version: "1"
+routes:
+  /about:
+    page:
+      file: public/about.html
+      cacheControl: no-cache
+  /assets/*:
+    static:
+      directory: public/assets
+      index: index.html
+      cacheControl: public, max-age=3600
+  /download:
+    download:
+      file: public/guide.txt
+      filename: urlcode-guide.txt
+      contentType: text/plain
+      cacheControl: no-store

package/examples/cookbook/routes/policies.yaml

@@ -0,0 +1,28 @@
+version: "1"
+routes:
+  /secure:
+    description: OWASP Secure Headers profile on a declared response; explicit headers still win
+    respond: {text: Hardened response}
+    policies:
+      security: {headers: oshp, unset: [Cross-Origin-Embedder-Policy]}
+    response:
+      headers:
+        Referrer-Policy: no-referrer
+  /no-bots:
+    description: Deny the bundled AI-crawler list and any curl; allow one named crawler
+    redirect: {url: https://example.com/article}
+    policies:
+      agents:
+        deny: [ai-crawlers]
+        denyPatterns: ["^curl/"]
+        allowPatterns: ["^Mozilla/5\\.0 \\(compatible; Googlebot/"]
+  /cached:
+    description: Public caching with a named strategy; the origin does not cache
+    respond: {json: {cached: true}}
+    policies:
+      cache: {strategy: public, maxAge: 60}
+  /budget:
+    description: Per-route request budget with standard RateLimit headers
+    respond: {text: Budgeted}
+    policies:
+      throttle: {quota: 100, window: 60, partition: route}

package/examples/cookbook/routes/redirects.yaml

@@ -0,0 +1,38 @@
+version: "1"
+routes:
+  /go:
+    redirect: {url: 'https://example.com/'}
+  /moved:
+    redirect: {url: 'https://example.com/new', status: 308}
+    response:
+      headers:
+        Cache-Control: public, max-age=60
+  /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]
+  /paused:
+    enabled: false
+    redirect: {url: 'https://example.com/'}
+  /expired:
+    expires: "2020-01-01T00:00:00Z"
+    redirect: {url: 'https://example.com/'}

package/examples/cookbook/routes/responses.yaml

@@ -0,0 +1,26 @@
+version: "1"
+routes:
+  /status:
+    respond: {json: {ok: true, service: cookbook}}
+  /notice:
+    respond: {text: Temporarily unavailable, status: 503}
+    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"
+  /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