@jimhoyd/urlcode 0.5.5 → 0.5.8

package/dist/vercel.js

@@ -12,6 +12,17 @@ import { assert, HttpError } from './errors.js';
 
 const platformOrigins = ['VERCEL_PROJECT_PRODUCTION_URL','VERCEL_URL','VERCEL_BRANCH_URL'];
 
+// `x-forwarded-for` is documented as overwritten (not appended to) by
+// Vercel's edge, but only when Vercel itself is the client-facing proxy; a
+// project's own proxy in front of Vercel can still set it before Vercel ever
+// sees the request. `x-vercel-forwarded-for` is Vercel's own copy of the same
+// value and is the header Vercel's docs say to prefer for exactly that reason
+// (https://vercel.com/docs/headers/request-headers#x-vercel-forwarded-for).
+// Exported so the adapter's client-IP resolution can be verified directly.
+export function forwardedClient(headers         , headerCounts                        )                     {
+  return headerCounts['x-vercel-forwarded-for'] === 1 ? (headers.get('x-vercel-forwarded-for') ?? '').split(',')[0]?.trim() || undefined : undefined;
+}
+
 function readBody(req                 , limit        )                  {
   if (req.headers['content-length'] && Number(req.headers['content-length']) > limit) return Promise.reject(new HttpError(413,'Request body too large'));
   return new Promise((resolve,reject) => {
@@ -49,9 +60,7 @@ export function createVercelHandler({ project = process.cwd(), origin, environme
       }
       const limit = Math.min(maxBodyBytes, runtime.requestLimit(target) ?? maxBodyBytes);
       const body = await readBody(req,limit);
-      // The platform terminates TLS and sets the forwarded header itself, so
-      // its leftmost entry is the client; the socket peer is the platform.
-      const forwarded = headerCounts['x-forwarded-for'] === 1 ? (headers.get('x-forwarded-for') ?? '').split(',')[0]?.trim() : undefined;
+      const forwarded = forwardedClient(headers, headerCounts);
       const publicOrigin = resolveOrigin(origin,environment,platformOrigins) ?? 'http://localhost';
       const result = await runtime.handle({ target, method, headers, headerCounts, body,
         origin: publicOrigin, client: forwarded || req.socket?.remoteAddress });

package/dist/verify-deployment.js

@@ -3,6 +3,7 @@ import { request, Agent } from 'node:http';
 import { request as secureRequest, Agent as SecureAgent } from 'node:https';
 import { randomBytes } from 'node:crypto';
 import { assert } from './errors.js';
+import { isRecord } from './object-guards.js';
 import { createRuntime } from './runtime.js';
                                                    
 import { benchmarkTarget, hit, readFixtures, runFixtures, isStepsFixture, probeAgent } from './readiness.js';
@@ -26,7 +27,7 @@ import { lists as bundledAgents } from '../data/agents/index.js';
 // snapshot would; it says nothing about the host, the proxy or the network.
                                                 
                                        
-                                                                                                                                                                    
+                                                                                                                                                             
                                                                                                                                               
                                                                             
                                                                                                                                                       
@@ -46,32 +47,49 @@ const MAX_REQUESTS = 10000;
 const BODY_LIMIT = 1048576;
 const SNIPPET = 200;
 const siteTypes                         = { 'site.robots': 'text/plain', 'site.sitemap': 'application/xml', 'site.securityTxt': 'text/plain', 'site.llms': 'text/plain', 'site.notFound': 'text/html' };
-const isRecord = (value         )                                   => value !== null && typeof value === 'object' && !Array.isArray(value);
 const snippet = (body        )         => body.length > SNIPPET ? `${body.length} bytes: ${body.subarray(0, SNIPPET).toString('utf8')}` : body.toString('utf8');
 const tlsCode = /CERT|TLS|SSL|SELF_SIGNED/;
 
 // One request, one answer. Bodies are read up to 1 MiB and never logged
 // beyond the snippet a failing assertion carries. Redirects are not followed
 // and a transport error is reported as text, never thrown.
+//
+// `timeout` on a Node request/response is an *idle* timer: it only fires
+// once a socket has gone quiet, so a deployment that drips one byte just
+// under that interval keeps resetting it and can hold this probe open
+// indefinitely. A single wall-clock deadline covering the whole request
+// (connect through body) closes that gap. Past `BODY_LIMIT` the response is
+// destroyed rather than left to keep streaming into a discard loop: this
+// probe only ever needs a bounded snippet, never the rest of an oversized
+// or endless body.
 function probe(target                 , { path, method = 'GET', headers = {} }       , agent       , timeoutMs        )                  {
   return new Promise(resolve => {
-    const fail = (error         ) => {
+    let settled = false;
+    const finish = (answer        )       => { if (settled) return; settled = true; clearTimeout(deadline); resolve(answer); };
+    const fail = (error         )       => {
       const code = isRecord(error) && typeof error.code === 'string' ? error.code : error instanceof Error ? error.message : 'transport';
-      resolve({ status: 0, headers: {}, body: Buffer.alloc(0), error: code });
+      finish({ status: 0, headers: {}, body: Buffer.alloc(0), error: code });
     };
     let req                           ;
+    const deadline = setTimeout(() => { req?.destroy(new Error('timeout')); }, timeoutMs);
     try {
       const options                 = { host: target.hostname, port: target.port, path, method, agent, timeout: timeoutMs,
         headers: { host: target.hostname, 'user-agent': probeAgent, 'accept-encoding': 'identity', ...headers } };
       req = (target.protocol === 'https:' ? secureRequest : request)(options, (res                 ) => {
+        const out                         = {};
+        for (const [key, value] of Object.entries(res.headers)) if (value !== undefined) out[key] = Array.isArray(value) ? value.join(', ') : value;
         const chunks           = []; let size = 0;
-        res.on('data', (chunk        ) => { if (size < BODY_LIMIT) chunks.push(chunk); size += chunk.length; });
-        res.on('error', fail);
-        res.on('end', () => {
-          const out                         = {};
-          for (const [key, value] of Object.entries(res.headers)) if (value !== undefined) out[key] = Array.isArray(value) ? value.join(', ') : value;
-          resolve({ status: res.statusCode ?? 0, headers: out, body: Buffer.concat(chunks) });
+        const done = ()       => finish({ status: res.statusCode ?? 0, headers: out, body: Buffer.concat(chunks) });
+        res.on('data', (chunk        ) => {
+          if (size < BODY_LIMIT) chunks.push(chunk);
+          size += chunk.length;
+          if (size > BODY_LIMIT) res.destroy();
         });
+        res.on('error', fail);
+        res.on('end', done);
+        // A body cut off by the BODY_LIMIT destroy() above ends here, not on
+        // 'end'; the snippet already collected is still a valid answer.
+        res.on('close', () => { if (!settled) done(); });
       });
       req.on('error', fail); req.on('timeout', () => req?.destroy(new Error('timeout'))); req.end();
     } catch (error) { req?.destroy(); fail(error); }
@@ -148,7 +166,7 @@ export async function verifyDeployment(project        , { target, origin, expect
     const parse = (answer        )                                      => { try { const json          = JSON.parse(answer.body.toString('utf8')); return isRecord(json) ? json : undefined; } catch { return undefined; } };
     const healthJson = parse(health);
     check(health.status === 200 && healthJson?.status === 'ok' && typeof healthJson.version === 'string' && typeof healthJson.routes === 'number',
-      { check: 'probes', severity: 'high', message: '/_urlcode/health must answer 200 with {status:"ok",version,routes}', expected: '200', observed: `${health.status} ${snippet(health.body)}` });
+      { check: 'probes', severity: 'high', message: '/_urlcode/health must answer 200 with {status:"ok",version,routes}; start the target with --health-details (or --metrics) if it currently answers {status} only', expected: '200', observed: `${health.status} ${snippet(health.body)}` });
     const ready = await send({ path: '/_urlcode/ready' }), readyJson = parse(ready);
     check(ready.status === 200 && readyJson?.status === 'ok', { check: 'probes', severity: 'high', message: '/_urlcode/ready must answer 200 (the deployment reports itself degraded or is not URLCode)', expected: '200', observed: `${ready.status} ${snippet(ready.body)}` });
     if (typeof readyJson?.version === 'string') version.observed = readyJson.version;

package/docs/AI-AUTHORING.md

@@ -63,6 +63,11 @@ The root [llms.txt](../llms.txt) is a compact discovery index; the generated
 reading order for agents that want complete context in one fetch. It is a convenience,
 not a runtime protocol or a guarantee that AI clients automatically consume it.
 The generated reference is checked against the schema in `npm run verify`.
+[URLCode AI](https://urlcode.ai/) is the optional hosted companion for shared
+skills and LLM tooling. It complements the project-local MCP server; see
+[hosted AI MCP setup](TOOLING.md#optional-hosted-ai-mcp) for its authenticated
+remote connection details. Its machine-readable entry point is
+[`https://urlcode.ai/llms.txt`](https://urlcode.ai/llms.txt).
 
 Follow [organization and readability practices](BEST-PRACTICES.md): preserve local
 conventions, use clear names, keep middleware focused and avoid needless layers.
@@ -138,7 +143,7 @@ urlcode benchmark --project ./my-links --requests 100 --concurrency 2
 ```
 
 Use the intentional actual count, not always 2. Runtime checkout users can replace
-`urlcode` with `node src/cli.ts`. Template users can use the equivalent npm scripts.
+`urlcode` with `node packages/core/src/cli.ts`. Template users can use the equivalent npm scripts.
 External bindings require an already reviewed policy; add `--policy` where needed.
 The benchmark operates locally; it is not a load test of an external deployment.
 
@@ -432,6 +437,10 @@ the operator, never by tool arguments; `--allow-authoring` on the operator's
 command line adds project-confined route, recipe, scaffold and runner tools.
 `urlcode init` writes `.mcp.json` so Claude Code and Codex register the read-only
 server for the project ([registering the server](TOOLING.md#registering-the-server)).
+The optional hosted URLCode AI MCP is a separate authenticated connection for
+shared skills and LLM tools; it does not replace the local project server. Its
+endpoint and credential-handling requirements are in
+[hosted AI MCP setup](TOOLING.md#optional-hosted-ai-mcp).
 Inspection is not activation/deployment readiness: real grants, asset snapshots
 and service availability still need normal runtime checks. Provider conformance replay is local evidence; only
 explicit live [deployment observations](PROVIDER-VERIFICATION.md) test ingress.

package/docs/FUNCTION-SECURITY.md

@@ -82,6 +82,10 @@ into it; only the default for routes that declare neither option has changed.
 - A fresh guest heap/module state per invocation prevents state crossing requests.
 - 32 MiB guest heap, 512 KiB stack, source/input/output/header limits, bounded
   concurrency, guest interruption and an independent worker termination deadline.
+- The guest's result is recorded where guest code cannot rewrite it, and the
+  host checks its shape before trusting it. A result that states a body length
+  for any method other than HEAD is invalid and answers 502; the runtime frames
+  the response by the bytes it sends ([responses](HTTP.md#responses)).
 - External bindings are denied by default. Project YAML cannot self-authorize.
   Operator grants are exact-name, route-scoped and pinned to configuration/source.
 

package/docs/README.md

@@ -8,7 +8,7 @@ Use documentation from the same pinned revision as your runtime.
 | Understand what URLCode does | [Framework](FRAMEWORK.md) |
 | Build my first project | [Installation](INSTALL.md), then [YAML guide](YAML-GUIDE.md) |
 | Build a site with UI, accounts and admin | [Composing a site](COMPOSING-A-SITE.md) |
-| Have an AI author a project | [AI authoring](AI-AUTHORING.md), [agent index](../llms.txt) |
+| Have an AI author a project | [AI authoring](AI-AUTHORING.md), [agent index](../llms.txt), [hosted agent guide](https://urlcode.ai/llms.txt) |
 | Deploy and operate a project | [Operations](OPERATIONS.md) |
 | Contribute to URLCode | [Contributing](../CONTRIBUTING.md), [local development](LOCAL-DEVELOPMENT.md) |
 
@@ -26,7 +26,7 @@ The [specification](SPECIFICATION.md) owns implemented semantics; the
 | Load authoring/operations rules into an agent | [Authoring skill](../.claude/skills/urlcode-authoring/SKILL.md), [operations skill](../.claude/skills/urlcode-operations/SKILL.md), [how they are distributed](AI-AUTHORING.md#agent-skills) |
 | Understand exact behavior | [Specification](SPECIFICATION.md), [routing](ROUTING.md), [HTTP](HTTP.md) |
 | Run examples | [Executable cookbook](../examples/cookbook/README.md), [prerender recipe](../examples/prerender/README.md), [small starter](STARTERS.md) |
-| Let an AI build routes | [The framework](FRAMEWORK.md), [AI authoring guide](AI-AUTHORING.md), [llms.txt](../llms.txt), [SDK and read-only MCP](TOOLING.md) |
+| Let an AI build routes | [The framework](FRAMEWORK.md), [AI authoring guide](AI-AUTHORING.md), [llms.txt](../llms.txt), [hosted agent guide](https://urlcode.ai/llms.txt), [SDK and read-only MCP](TOOLING.md) |
 | Reuse code around routes | [Middleware](MIDDLEWARE.md), [middleware examples](MIDDLEWARE-EXAMPLES.md) |
 | Handle secrets and decide what to sandbox | [Function security](FUNCTION-SECURITY.md) |
 | Author guest functions in TypeScript | [Build-time guest transpilation](TYPESCRIPT-AUTHORING.md) |

package/docs/TOOLING.md

@@ -330,7 +330,7 @@ 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. A project that pins the runtime in its
-  `package.json` (`--template redirects`, `--with`, `--manifest`) gets
+  `package.json` (`--with`, `--manifest`) gets
   `"command": "npx"` with `--no --package @jimhoyd/urlcode urlcode mcp ...`, which runs the
   installed copy and never fetches (do not use a bare `npx urlcode`: that names an unrelated
   registry package). A project without one keeps the bare `urlcode` command for a global
@@ -354,6 +354,32 @@ The generated `AGENTS.md` and the packaged skill tell agents to prefer
 `get_manifest` when the server is registered and to fall back to the matching
 CLI commands otherwise.
 
+## Optional hosted AI MCP
+
+The local `urlcode mcp` server remains the project-aware URLCode integration:
+it reads the selected checkout, validates its configuration and never needs a
+network credential. Do not replace its generated `.mcp.json` entry with a
+hosted service.
+
+[URLCode AI](https://urlcode.ai/) is a separate, opt-in hosted service for
+shared skills and LLM-assisted work. A client that supports authenticated HTTP
+MCP can add it as a second server with these connection details:
+
+- URL: `https://mcp.urlcode.ai/mcp`
+- request header: `Authorization: Bearer <URLCODE_AI_TOKEN>`
+
+Store `URLCODE_AI_TOKEN` in the MCP client's secret or environment-variable
+facility. Do not put a literal bearer token in `.mcp.json`, `urlcode.yaml`, a
+checked-in client configuration, or a shell history. Each client has its own
+remote-server configuration syntax, so configure that endpoint explicitly in
+the client rather than asking `urlcode init` to generate it.
+
+The hosted tools are not a proxy for this local server: they do not receive the
+project root and do not replace local `get_context`, validation, manifest,
+extension-artifact or authoring tools. Keep the local server registered for
+framework- and project-specific work; add the hosted server only where its
+shared skill catalog or LLM tools are useful.
+
 ## Authoring mode
 
 `urlcode mcp --allow-authoring --project DIR` adds six tools to the twenty-two read

package/examples/assets/Makefile

@@ -1,6 +1,6 @@
 .DEFAULT_GOAL := help
 
-# Install the runtime separately, or override: URLCODE='node /path/to/urlcode/src/cli.js'
+# Install the runtime separately, or override: URLCODE='node /path/to/urlcode/dist/cli.js'
 URLCODE ?= urlcode
 HOST ?= 127.0.0.1
 PORT ?= 3000

package/examples/assets/example.yaml

@@ -9,9 +9,9 @@ files: [urlcode.yaml, functions/hello.mjs, public/about.html, public/guide.txt,
 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
+    - node packages/core/src/cli.ts validate --local --project examples/assets
+    - node packages/core/src/cli.ts test --project examples/assets
+    - node packages/core/src/cli.ts audit --project examples/assets --expect-routes 5
 behavior:
   - native page, static and download routes serve snapshotted files with explicit caching
   - one trusted function shows the two kinds of route side by side

package/examples/aws/example.yaml

@@ -12,9 +12,9 @@ files: [urlcode.yaml, handler.mjs, template.yaml, public/index.html, public/note
 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
+    - node packages/core/src/cli.ts validate --local --project examples/aws
+    - node packages/core/src/cli.ts test --project examples/aws
+    - node packages/core/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

@@ -12,8 +12,8 @@ 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
+    - node packages/core/src/cli.ts validate --local --project examples/cloudflare
+    - node packages/core/src/cli.ts test --project examples/cloudflare
+    - node packages/core/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/README.md

@@ -10,7 +10,7 @@ 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 \
+node packages/core/src/cli.ts audit --project examples/cookbook \
   --compliance baseline --compliance-rules "$PWD/examples/compliance/rules.mjs" --compliance-warn
 ```
 

package/examples/compliance/example.yaml

@@ -6,6 +6,6 @@ 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
+    - node packages/core/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/compliance/rules.mjs

@@ -1,7 +1,7 @@
 // Operator compliance rules for `urlcode audit --compliance-rules`.
-// Runnable against the cookbook from the runtime checkout:
+// Runnable against the cookbook from the runtime checkout (after `npm run build`):
 //
-//   node src/cli.js audit --project examples/cookbook \
+//   node dist/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

package/examples/conditions/example.yaml

@@ -12,8 +12,8 @@ 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
+    - node packages/core/src/cli.ts validate --local --project examples/conditions --origin https://conditions.example.test
+    - node packages/core/src/cli.ts test --project examples/conditions --origin https://conditions.example.test
+    - node packages/core/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/cookbook/README.md

@@ -11,10 +11,10 @@ external services are required. Redirects target example.com; tests never follow
 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 40
-node src/cli.ts dev --project examples/cookbook
+node packages/core/src/cli.ts validate --project examples/cookbook
+node packages/core/src/cli.ts test --project examples/cookbook
+node packages/core/src/cli.ts audit --project examples/cookbook --expect-routes 40
+node packages/core/src/cli.ts dev --project examples/cookbook
 ```
 
 The [YAML guide](../../docs/YAML-GUIDE.md) explains the recipes and binding policy.

package/examples/cookbook/example.yaml

@@ -9,9 +9,9 @@ files: [urlcode.yaml, routes/code.yaml, routes/redirects.yaml, routes/responses.
 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
+    - node packages/core/src/cli.ts validate --local --project examples/cookbook
+    - node packages/core/src/cli.ts test --project examples/cookbook
+    - node packages/core/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/coverage-waiver/example.yaml

@@ -9,8 +9,8 @@ files: [urlcode.yaml, functions/notes.mjs, tests/requests.json, README.md]
 tests:
   fixtures: tests/requests.json
   commands:
-    - node src/cli.ts validate --local --project examples/coverage-waiver
-    - node src/cli.ts test --project examples/coverage-waiver
-    - node src/cli.ts audit --project examples/coverage-waiver --expect-routes 1
+    - node packages/core/src/cli.ts validate --local --project examples/coverage-waiver
+    - node packages/core/src/cli.ts test --project examples/coverage-waiver
+    - node packages/core/src/cli.ts audit --project examples/coverage-waiver --expect-routes 1
 behavior:
   - POST /notes is waived from coverage with a reason; GET is asserted by a fixture; the waiver is listed by audit, not hidden

package/examples/egress/example.yaml

@@ -13,7 +13,7 @@ grants:
 files: [urlcode.yaml, README.md]
 tests:
   commands:
-    - node src/cli.ts permissions --project examples/egress
-    - node src/cli.ts validate --local --project examples/egress --policy /operator/egress-policy.json
+    - node packages/core/src/cli.ts permissions --project examples/egress
+    - node packages/core/src/cli.ts validate --local --project examples/egress --policy /operator/egress-policy.json
 behavior:
   - without the policy the project refuses to activate; nothing here reaches the network during authoring inspection

package/examples/extensions/example.yaml

@@ -16,6 +16,6 @@ grants:
 files: [urlcode.yaml, README.md]
 tests:
   commands:
-    - node src/cli.ts validate --local --project examples/extensions --host-file /operator/host.mjs --origin https://extensions.example.test
+    - node packages/core/src/cli.ts validate --local --project examples/extensions --host-file /operator/host.mjs --origin https://extensions.example.test
 behavior:
   - "/account uses auth: {role: member}; routes and audit show the expanded policies.extensions.auth form"

package/examples/lifecycle/example.yaml

@@ -12,8 +12,8 @@ files: [urlcode.yaml, functions/notes.mjs, tests/requests.json, README.md]
 tests:
   fixtures: tests/requests.json
   commands:
-    - node src/cli.ts test --project examples/lifecycle
-    - node src/cli.ts audit --project examples/lifecycle --expect-routes 2
+    - node packages/core/src/cli.ts test --project examples/lifecycle
+    - node packages/core/src/cli.ts audit --project examples/lifecycle --expect-routes 2
 behavior:
   - a note created by POST /notes is readable, replaceable and still present after the runtime restarts on the same data directory
   - the id and Location the create response returns are captured and substituted into later steps as {{id}} and {{where}}

package/examples/not-found/README.md

@@ -5,6 +5,6 @@ route, with status 404 and `text/html`. See
 [site conventions](../../docs/SITE.md#notfound--404html).
 
 ```sh
-node src/cli.ts test --project examples/not-found
-node src/cli.ts build --target static --project examples/not-found   # writes 404.html
+node packages/core/src/cli.ts test --project examples/not-found
+node packages/core/src/cli.ts build --target static --project examples/not-found   # writes 404.html
 ```

package/examples/not-found/example.yaml

@@ -9,9 +9,9 @@ files: [urlcode.yaml, public/index.html, public/404.html, tests/requests.json, R
 tests:
   fixtures: tests/requests.json
   commands:
-    - node src/cli.ts validate --local --project examples/not-found
-    - node src/cli.ts test --project examples/not-found
-    - node src/cli.ts audit --project examples/not-found --expect-routes 2
+    - node packages/core/src/cli.ts validate --local --project examples/not-found
+    - node packages/core/src/cli.ts test --project examples/not-found
+    - node packages/core/src/cli.ts audit --project examples/not-found --expect-routes 2
 behavior:
   - an unmatched GET or HEAD is answered with the page and status 404
   - other methods keep the plain-text 404

package/examples/prerender/README.md

@@ -14,11 +14,11 @@ runs no code at all.
 From the runtime checkout:
 
 ```sh
-node src/cli.ts dev --project examples/prerender        # the dynamic source, live
-node src/cli.ts test --project examples/prerender       # 7 fixtures
+node packages/core/src/cli.ts dev --project examples/prerender        # the dynamic source, live
+node packages/core/src/cli.ts test --project examples/prerender       # 7 fixtures
 node examples/prerender/prerender.mjs examples/prerender /absolute/out
-node src/cli.ts test --project /absolute/out            # fixtures the build wrote
-node src/cli.ts audit --project /absolute/out --expect-routes 3
+node packages/core/src/cli.ts test --project /absolute/out            # fixtures the build wrote
+node packages/core/src/cli.ts audit --project /absolute/out --expect-routes 3
 ```
 
 The same three URLs answer identically before and after. The difference is what

package/examples/prerender/example.yaml

@@ -9,8 +9,8 @@ files: [urlcode.yaml, functions/page.mjs, middleware/template.mjs, prerender.mjs
 tests:
   fixtures: tests/requests.json
   commands:
-    - node src/cli.ts test --project examples/prerender
+    - node packages/core/src/cli.ts test --project examples/prerender
     - node examples/prerender/prerender.mjs examples/prerender /absolute/out
-    - node src/cli.ts audit --project /absolute/out --expect-routes 3
+    - node packages/core/src/cli.ts audit --project /absolute/out --expect-routes 3
 behavior:
   - the rendered project serves the same bytes from native page routes with no sandbox on the request path

package/examples/provider-conformance/example.yaml

@@ -8,7 +8,7 @@ routes: 5
 files: [urlcode.yaml, README.md]
 tests:
   commands:
-    - node src/cli.ts validate --local --project examples/provider-conformance
-    - node src/cli.ts verify-provider --target self-hosted --origin https://owned-fixture.example
+    - node packages/core/src/cli.ts validate --local --project examples/provider-conformance
+    - node packages/core/src/cli.ts verify-provider --target self-hosted --origin https://owned-fixture.example
 behavior:
   - no functions, bindings, assets or policies, so every target activates it; never mix it into a real project

package/examples/shared-blocks/example.yaml

@@ -10,8 +10,8 @@ files: [urlcode.yaml, tests/requests.json, README.md]
 tests:
   fixtures: tests/requests.json
   commands:
-    - node src/cli.ts validate --local --project examples/shared-blocks
-    - node src/cli.ts test --project examples/shared-blocks
-    - node src/cli.ts audit --project examples/shared-blocks --expect-routes 4
+    - node packages/core/src/cli.ts validate --local --project examples/shared-blocks
+    - node packages/core/src/cli.ts test --project examples/shared-blocks
+    - node packages/core/src/cli.ts audit --project examples/shared-blocks --expect-routes 4
 behavior:
   - a route's own request or response key replaces the shared block whole; nothing is deep merged

package/examples/vercel/example.yaml

@@ -12,8 +12,8 @@ files: [urlcode.yaml, api/index.js, vercel.json, public/index.html, public/notes
 tests:
   fixtures: tests/requests.json
   commands:
-    - node src/cli.ts validate --local --project examples/vercel
-    - node src/cli.ts test --project examples/vercel
-    - node src/cli.ts audit --project examples/vercel --expect-routes 5
+    - node packages/core/src/cli.ts validate --local --project examples/vercel
+    - node packages/core/src/cli.ts test --project examples/vercel
+    - node packages/core/src/cli.ts audit --project examples/vercel --expect-routes 5
 behavior:
   - every route is native, so the project activates on Vercel without the sandbox