@jimhoyd/urlcode 0.4.2 → 0.4.6

package/dist/body-schema.js

@@ -0,0 +1,159 @@
+import { assert } from './errors.js';
+import { assertSafePattern, maxPatternInputLength } from './pattern-guard.js';
+
+/**
+ * The JSON Schema subset a route may declare for `request.body.schema`.
+ * It is interpreted here rather than compiled by Ajv so the same code runs on
+ * every host, including the Worker, with no code generation and no author
+ * regex outside `pattern-guard.ts`.
+ */
+                             
+                                                                                   
+                                                                                               
+                                                                  
+                                                                            
+                                                                           
+ 
+export const uuidFormat = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const types = ['object', 'array', 'string', 'integer', 'number', 'boolean', 'null'];
+const keywords = new Set(['type','properties','required','additionalProperties','items','enum','minLength','maxLength','pattern','format','minimum','maximum','minItems','maxItems']);
+const limits = { depth: 6, nodes: 128, properties: 64, enums: 64, length: 8192, items: 10000 };
+const isRecord = (value         )                                   => typeof value === 'object' && value !== null && !Array.isArray(value);
+const own = (object        , key        )          => Object.hasOwn(object, key);
+const patterns = new WeakMap                    ();
+
+/** Rejects, at load time, any schema outside the supported subset or its limits. */
+export function assertBodySchema(schema         )                               {
+  let nodes = 0;
+  const walk = (node         , depth        )       => {
+    assert(isRecord(node), 'Body schema must be an object');
+    assert(depth <= limits.depth && ++nodes <= limits.nodes, 'Body schema is too large or deeply nested');
+    for (const key of Object.keys(node)) assert(keywords.has(key), `Unsupported body schema keyword: ${key}`);
+    const kind = node.type;
+    assert(kind === undefined || (typeof kind === 'string' && types.includes(kind)), 'Body schema type must be one of ' + types.join(', '));
+    const isKind = (...allowed          )          => typeof kind === 'string' && allowed.includes(kind);
+    const uses = (...names          )          => names.some(name => own(node, name));
+    assert(!uses('properties', 'required', 'additionalProperties') || isKind('object'), 'properties, required and additionalProperties require type object');
+    assert(!uses('items', 'minItems', 'maxItems') || isKind('array'), 'items, minItems and maxItems require type array');
+    assert(!uses('minLength', 'maxLength', 'pattern', 'format') || isKind('string'), 'String keywords require type string');
+    assert(!uses('minimum', 'maximum') || isKind('integer', 'number'), 'Numeric bounds require type integer or number');
+    for (const name of ['minLength', 'maxLength', 'minItems', 'maxItems']) {
+      if (!own(node, name)) continue;
+      const value = node[name], cap = name.endsWith('Items') ? limits.items : limits.length;
+      assert(Number.isInteger(value) && (value          ) >= 0 && (value          ) <= cap, `${name} must be an integer from 0 to ${cap}`);
+    }
+    for (const name of ['minimum', 'maximum']) assert(!own(node, name) || (typeof node[name] === 'number' && Number.isFinite(node[name])), `${name} must be a finite number`);
+    if (own(node, 'format')) assert(node.format === 'uuid', 'Unsupported body schema format (supported: uuid)');
+    if (own(node, 'pattern')) {
+      assert(typeof node.pattern === 'string', 'pattern must be a string');
+      assertSafePattern(node.pattern);
+      assert(typeof node.maxLength === 'number' && node.maxLength <= maxPatternInputLength, `pattern requires maxLength of at most ${maxPatternInputLength}`);
+    }
+    if (own(node, 'enum')) {
+      assert(Array.isArray(node.enum) && node.enum.length >= 1 && node.enum.length <= limits.enums, `enum must list 1 to ${limits.enums} values`);
+      assert(node.enum.every(value => value === null || ['string', 'number', 'boolean'].includes(typeof value)), 'enum values must be scalars');
+    }
+    if (own(node, 'required')) {
+      assert(Array.isArray(node.required) && node.required.every(name => typeof name === 'string') && new Set(node.required).size === node.required.length, 'required must be a list of unique names');
+      const declared = isRecord(node.properties) ? node.properties : {};
+      assert((node.required            ).every(name => own(declared, name)), 'required names must be declared in properties');
+    }
+    if (own(node, 'additionalProperties')) assert(typeof node.additionalProperties === 'boolean', 'additionalProperties must be true or false');
+    if (own(node, 'properties')) {
+      assert(isRecord(node.properties) && Object.keys(node.properties).length <= limits.properties, `properties must declare at most ${limits.properties} names`);
+      for (const child of Object.values(node.properties)) walk(child, depth + 1);
+    }
+    if (own(node, 'items')) walk(node.items, depth + 1);
+  };
+  walk(schema, 1);
+}
+
+const describe = (value         )         => value === null ? 'null' : Array.isArray(value) ? 'array' : typeof value;
+/**
+ * One validation failure. `pointer` is an RFC 6901 pointer built only from names
+ * the schema declared (array positions appear as `[]`, not an index), `keyword`
+ * is the schema keyword that failed, and `expected` is the schema's own
+ * constraint. Nothing the client sent is ever placed in an issue.
+ */
+                                                                                                                                                                            
+const escapePointer = (name        )         => name.replace(/~/g, '~0').replace(/\//g, '~1');
+/** Structured failures for `value`; `checkBodySchema` renders the same list as text. */
+export function bodySchemaIssues(schema            , value         , path = '', issues                    = [], max = 8)                    {
+  const fail = (keyword        , message        , extra                           = {})       => { if (issues.length < max) issues.push({ pointer: path, keyword, message, ...extra }); };
+  const kind = schema.type;
+  if (kind) {
+    const actual = describe(value);
+    const ok = kind === 'integer' ? Number.isInteger(value) : kind === 'number' ? typeof value === 'number' : actual === kind;
+    if (!ok) { fail('type', `must be ${kind === 'array' || kind === 'object' || kind === 'integer' ? 'an' : 'a'} ${kind}`, { expected: kind }); return issues; }
+  }
+  if (schema.enum && !schema.enum.some(item => item === value)) {
+    const listable = schema.enum.length <= 16 && schema.enum.every(item => typeof item !== 'string' || item.length <= 64);
+    fail('enum', 'must be one of the declared values', listable ? { expected: schema.enum } : {});
+  }
+  if (typeof value === 'string') {
+    if (schema.minLength !== undefined && [...value].length < schema.minLength) fail('minLength', `must be at least ${schema.minLength} characters`, { expected: schema.minLength });
+    if (schema.maxLength !== undefined && [...value].length > schema.maxLength) fail('maxLength', `must be at most ${schema.maxLength} characters`, { expected: schema.maxLength });
+    else {
+      if (schema.format === 'uuid' && !uuidFormat.test(value)) fail('format', 'must be a uuid', { expected: 'uuid' });
+      if (schema.pattern !== undefined) {
+        let regex = patterns.get(schema);
+        if (!regex) patterns.set(schema, regex = new RegExp(schema.pattern, 'u'));
+        if (!regex.test(value)) fail('pattern', 'does not match the declared pattern');
+      }
+    }
+  }
+  if (typeof value === 'number') {
+    if (schema.minimum !== undefined && value < schema.minimum) fail('minimum', `must be at least ${schema.minimum}`, { expected: schema.minimum });
+    if (schema.maximum !== undefined && value > schema.maximum) fail('maximum', `must be at most ${schema.maximum}`, { expected: schema.maximum });
+  }
+  if (Array.isArray(value)) {
+    if (schema.minItems !== undefined && value.length < schema.minItems) fail('minItems', `must have at least ${schema.minItems} items`, { expected: schema.minItems });
+    if (schema.maxItems !== undefined && value.length > schema.maxItems) fail('maxItems', `must have at most ${schema.maxItems} items`, { expected: schema.maxItems });
+    else if (schema.items) for (const item of value) { if (issues.length >= max) break; bodySchemaIssues(schema.items, item, `${path}/[]`, issues, max); }
+  }
+  if (isRecord(value)) {
+    const declared = schema.properties || {};
+    for (const name of schema.required || []) if (!own(value, name)) fail('required', `is missing required property ${name}`, { property: name });
+    if (schema.additionalProperties === false && Object.keys(value).some(name => !own(declared, name))) fail('additionalProperties', 'has a property the schema does not declare');
+    for (const [name, child] of Object.entries(declared)) if (own(value, name)) bodySchemaIssues(child, value[name], `${path}/${escapePointer(name)}`, issues, max);
+  }
+  return issues;
+}
+/**
+ * Returns fixed-wording failures for `value`, each naming only a path the
+ * schema itself declared (array positions appear as `[]`). Nothing the client
+ * sent is echoed, so the answer stays safe to render as plain text.
+ */
+export function checkBodySchema(schema            , value         )           {
+  return bodySchemaIssues(schema, value).map(bodySchemaLine);
+}
+/** The plain-text line for an issue: array positions print as `[]` appended to the path, root as `/`. */
+export const bodySchemaLine = (issue                 )         => `${issue.pointer.replace(/\/\[\]/g, '[]') || '/'} ${issue.message}`;
+
+/**
+ * Negotiation rule (conservative): the structured answer is sent only when the
+ * Accept header names application/json explicitly with q > 0 and no higher q
+ * for an explicit text/plain. Wildcard ranges, a missing header and everything
+ * else keep the plain-text answer, so curl, browsers and existing clients see
+ * no change.
+ */
+export function prefersJson(accept                           )          {
+  if (!accept || accept.length > 1024) return false;
+  let json = 0, text = 0;
+  for (const range of accept.split(',')) {
+    const [type = '', ...params] = range.split(';').map(part => part.trim().toLowerCase());
+    const q = params.find(param => param.startsWith('q='));
+    const weight = q === undefined ? 1 : /^q=(?:0(?:\.\d{0,3})?|1(?:\.0{0,3})?)$/.test(q) ? Number(q.slice(2)) : 0; // a malformed weight never opts in
+    if (type === 'application/json') json = Math.max(json, weight);
+    else if (type === 'text/plain') text = Math.max(text, weight);
+  }
+  return json > 0 && json >= text;
+}
+const maxIssueBytes = 4096;
+/** Renders the JSON answer: never more than `maxIssueBytes`, dropping trailing issues and saying so. */
+export function bodySchemaJson(issues                   )         {
+  const shape = (list                   , truncated         )         => JSON.stringify({ error: 'body_validation_failed', message: 'Request body failed validation', ...(truncated ? { truncated } : {}), issues: list });
+  let list = issues, text = shape(list, false);
+  while (new TextEncoder().encode(text).length > maxIssueBytes && list.length) { list = list.slice(0, -1); text = shape(list, true); }
+  return text;
+}

package/dist/build-cloudflare.js

@@ -3,6 +3,7 @@ import { mkdir, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import Ajv from 'ajv/dist/2020.js';
 import standaloneCode from 'ajv/dist/standalone/index.js';
+import { uuidFormat } from './body-schema.js';
 import { loadDocument } from './config.js';
 import { compileRoutes } from './router.js';
 import { assert } from './errors.js';
@@ -100,6 +101,7 @@ export async function buildCloudflare(project        , { out = 'dist/cloudflare'
   assert(routes.length, 'No routes to build');
 
   const ajv = new Ajv.default({ code:{ source:true, esm:true }, strict:false, allErrors:false });
+  ajv.addFormat('uuid',uuidFormat); // the same allowlisted format router.ts registers; without it the compiled validator silently ignores `format`
   const validators                         = {}, serialised                  = [];
   for (const route of routes) {
     const parameters                      = [];

package/dist/capabilities.js

@@ -248,7 +248,7 @@ export const capabilityDetails                                           = {
   enabled: { kind: 'routing', summary: 'Route on/off switch; disabled routes are still validated.', schema: ['enabled'], constraints: ['Boolean; defaults to true'], grants: [] },
   expires: { kind: 'routing', summary: 'Timestamp after which the route stops matching.', schema: ['expires'], constraints: ['UTC timestamp YYYY-MM-DDTHH:MM:SS[.mmm]Z; expired routes are still validated'], grants: [] },
   'request.body': { kind: 'request', summary: 'Request body admission limits and format.', schema: ['request.body'],
-    constraints: ['`maxBytes` 0 to 1048576; up to 16 lowercase `contentTypes`', '`format` text or json'], grants: [] },
+    constraints: ['`maxBytes` 0 to 1048576; up to 16 lowercase `contentTypes`', '`format` text or json', '`schema` (JSON only): a bounded JSON Schema subset; failures return 422'], grants: [] },
   'response.headers': { kind: 'request', summary: 'Static response headers added to the reply.', schema: ['response.headers'],
     constraints: ['At most 64 headers; values up to 4096 characters or lists of at most 16', 'Cloudflare coalesces duplicate headers'], grants: [] },
   bindings: { kind: 'binding', summary: 'Route `env` literals/references and `secrets` references.', schema: ['env', 'secrets'],

package/dist/cli.js

@@ -15,7 +15,7 @@ import {scaffoldProject} from './scaffold.js';
 import { initProject, addRedirect } from './authoring.js';
 import { initProjectWith, parseWithNames } from './init-with.js';
 import { collectDependencySet, installSteps, parsePin } from './project-dependencies.js';
-import { runProjectTests } from './project-tests.js';
+import { runProjectTests, startRestartable } from './project-tests.js';
 import { verifyDeployment, failLevels } from './verify-deployment.js';
                                                      
 import { loadOperatorPolicy, prepareFunctionSnapshot, requestedPermissions } from './policy.js';
@@ -28,9 +28,11 @@ import { loadComplianceRules, profileNames as complianceProfiles } from './compl
 import { parseRouteSnapshot, diffRoutes, renderRouteDiff } from './route-diff.js';
 import { readFile } from 'node:fs/promises';
 
-const usage = `URLCode 0.4.2 — local/self-hosted runtime
-  urlcode init <directory> [--with ui,auth,admin] [--manifest|--no-manifest] [--pin @scope/pkg=specifier]
-    # --with: layered site from installed @jimhoyd/urlcode-<name> packages, with a package.json pinning them exactly; name ui first
+const usage = `URLCode 0.4.6 — local/self-hosted runtime
+  urlcode init <directory> [--template page] [--with ui,auth,admin] [--ack extension:id] [--manifest|--no-manifest] [--pin @scope/pkg=specifier]
+    # --template page: the smallest project (urlcode.yaml, public/index.html, README.md, tests/requests.json), one page route; not combinable with --with
+    # --with: layered site from installed @jimhoyd/urlcode-<name> packages, with a package.json pinning them exactly; --with is an unordered set, core orders the host from each extension's declared requirements and refuses a missing requirement, conflict or cycle before writing
+    # --ack: repeatable, qualified acknowledgement of a risk an extension names when it refuses (for example store:public-write); do not pass it pre-emptively, the refusal prints the exact command. Rejected when no scaffold consumes it
     # --manifest: also pin the runtime for a route-only project; --no-manifest: --with without a package.json
     # --pin: record a local path or tarball instead of the registry version; repeatable. No install is ever run for you.
   urlcode scaffold [--project directory] [--dry-run]
@@ -57,6 +59,7 @@ const usage = `URLCode 0.4.2 — local/self-hosted runtime
     [--compliance baseline|strict|privacy|none] [--compliance-rules ...] [--compliance-ignore id,id] [--compliance-warn]
     # compares the running deployment's responses with what this project declares; never follows redirects, no --insecure
   urlcode permissions [--project directory]  # inspect requested bindings and egress origins; grants nothing
+  urlcode test [--project directory] [--verbose]  # quiet by default: prints failing cases and the summary; --verbose adds every request log
   urlcode explain [/route] [--project directory] [--target self-hosted|cloudflare|aws|vercel|static] [--host-file ...] [--json]
     # effective methods, handler, middleware, inputs, policies, cache outcome, bindings and target support from the compiled configuration
   urlcode manifest [--project directory] [--json]  # generated semantic manifest; build writes the same file as manifest.json
@@ -83,14 +86,14 @@ Dev loads .env.local and watches; serve does neither. Functions run trusted and
 const print = (value         )          => process.stdout.write(typeof value === 'string' ? value : JSON.stringify(value) + '\n');
 const options = {
   json:{ type:'boolean' }, yaml:{ type:'boolean' }, report:{type:'string'}, 'accept-provider-differences':{type:'boolean'},
-  project:{ type:'string', default:'.' }, 'host-file':{type:'string'}, with:{type:'string'},
-  manifest:{type:'boolean'}, 'no-manifest':{type:'boolean'}, pin:{type:'string', multiple:true},
+  project:{ type:'string', default:'.' }, 'host-file':{type:'string'}, with:{type:'string'}, template:{type:'string'},
+  manifest:{type:'boolean'}, 'no-manifest':{type:'boolean'}, pin:{type:'string', multiple:true}, ack:{type:'string', multiple:true},
   port:{ type:'string' }, host:{ type:'string', default:'127.0.0.1' },
   'expect-routes':{type:'string'}, requests:{type:'string'}, concurrency:{type:'string'}, seconds:{type:'string'}, 'max-p95-ms':{type:'string'}, warmup:{type:'string'}, target:{type:'string'},
   workers:{type:'string'}, 'function-timeout-ms':{type:'string'}, 'max-response-bytes':{type:'string'}, 'max-body-bytes':{type:'string'},
   'max-in-flight':{type:'string'}, 'max-in-flight-health':{type:'string'}, 'request-log':{type:'string'}, 'trust-request-id':{type:'boolean'}, 'trusted-proxies':{type:'string'}, metrics:{type:'boolean'},
   release:{type:'string'}, 'git-commit':{type:'string'}, 'timeout-ms':{type:'string'}, 'fail-on':{type:'string'}, 'expect-metrics':{type:'boolean'},
-  budget:{type:'string'}, stats:{type:'boolean'}, out:{type:'string'}, 'dry-run':{type:'boolean'}, compare:{type:'string'}, format:{type:'string'}, compliance:{type:'string'}, 'compliance-rules':{type:'string'}, 'compliance-ignore':{type:'string'}, 'compliance-warn':{type:'boolean'}, policy:{ type:'string' }, origin:{ type:'string' }, alias:{ type:'string' }, local:{ type:'boolean' }, 'allow-authoring':{ type:'boolean' }, help:{ type:'boolean', short:'h' },
+  budget:{type:'string'}, stats:{type:'boolean'}, out:{type:'string'}, 'dry-run':{type:'boolean'}, compare:{type:'string'}, format:{type:'string'}, compliance:{type:'string'}, 'compliance-rules':{type:'string'}, 'compliance-ignore':{type:'string'}, 'compliance-warn':{type:'boolean'}, policy:{ type:'string' }, origin:{ type:'string' }, alias:{ type:'string' }, local:{ type:'boolean' }, verbose:{ type:'boolean' }, 'allow-authoring':{ type:'boolean' }, help:{ type:'boolean', short:'h' },
 }         ;
                                                                                                           
                                                                                                                                                                                                                         
@@ -136,10 +139,17 @@ function formatExtensions(report                     )         {
   for (const item of report.extensions) lines.push(`Registered: ${item.name} (contract ${item.version}; targets ${item.targets.join(', ') || '(none)'}; ${item.declared ? 'declared' : 'not declared'}; revision ${item.revisionPinned ? 'pinned' : 'NOT pinned'})`,
     `  mounts: ${item.mounts.join(', ') || '(none)'}`, `  policy routes: ${item.policyRoutes.join(', ') || '(none)'}`, `  credential headers: ${item.credentialHeaders.join(', ') || '(none)'}`,
     `  hooks: ${item.hooks.length ? item.hooks.map(hook => `${String((hook                   ).name)} (${String((hook                   ).kind)})`).join(', ') : '(none)'}`,
+    `  authoring: ${item.authoring ? JSON.stringify(item.authoring) : '(none)'}`,
     `  configuration schema: ${JSON.stringify(item.schema)}`, `  policy schema: ${item.policySchema ? JSON.stringify(item.policySchema) : '(none)'}`);
   lines.push(report.note);
   return lines.join('\n') + '\n';
 }
+// Name the bound host and port (from the error, never user text) and a next step. Values are validated, not echoed.
+function addressInUseMessage(error         )         {
+  const { address,port } = error                                         ;
+  const where = typeof port === 'number' && Number.isInteger(port) && port > 0 && port < 65536 ? `Port ${port}${typeof address === 'string' && /^[0-9A-Fa-f:.]{2,45}$/.test(address) ? ` on ${address}` : ''}` : 'The port';
+  return `${where} is already in use; pick another with --port N, or stop the process using it`;
+}
 const errorMessages                                     = { ERR_PARSE_ARGS_UNKNOWN_OPTION:'Unknown option; use --help', EEXIST:'Destination or edit lock already exists', ENOENT:'Required file or directory not found', EADDRINUSE:'Port is already in use', EACCES:'Permission denied' };
 let operatorHost               = {};
 let serving = false;
@@ -154,9 +164,11 @@ try {
       // The MCP server and context command load and release the host themselves.
       if (command !== 'mcp' && command !== 'context') operatorHost = await loadOperatorHost(values['host-file'], values.project);
     }
+    if (values.template !== undefined && command !== 'init') throw new ConfigError('--template is only supported by init');
     if (values.with !== undefined && command !== 'init') throw new ConfigError('--with is only supported by init');
     if ((values.manifest || values['no-manifest'] || values.pin !== undefined) && command !== 'init') throw new ConfigError('--manifest/--no-manifest/--pin are only supported by init');
     if (values.manifest && values['no-manifest']) throw new ConfigError('Use either --manifest or --no-manifest');
+    if (values.ack !== undefined && (command !== 'init' || values.with === undefined)) throw new ConfigError('--ack is only supported by init with --with');
     if (values['allow-authoring'] && command !== 'mcp') throw new ConfigError('--allow-authoring is only supported by mcp');
     const hostOptions = { extensions: operatorHost.extensions, plugins: operatorHost.plugins };
     if ((!['import','recipes','recipe','examples','example','bulk-import'].includes(command) && extra.length) || (!['init','add','import','recipes','recipe','examples','example','bulk-import','explain','capabilities','schema'].includes(command) && arg)) throw new ConfigError('Unexpected positional arguments');
@@ -204,7 +216,9 @@ try {
           if(!['json','markdown'].includes(format))throw new ConfigError('Use --format json or markdown');
           if(values.format!==undefined && values.compare===undefined)throw new ConfigError('--format applies to routes --compare');
           const started=performance.now();
-          const app=await startServer({...hostOptions,project:values.project,port:0,local:true,permissions,origin:values.origin,log:()=>{}});
+          const serverOptions={...hostOptions,project:values.project,port:0,local:true,permissions,origin:values.origin,log:()=>{}};
+          // Only audit replays fixtures, so only audit needs a server its restart steps can restart.
+          const app=command==='audit'?await startRestartable(serverOptions):await startServer(serverOptions);
           const startupMs=performance.now()-started;
           try {
             if(command==='routes') {
@@ -281,13 +295,15 @@ try {
           const wanted = values.with === undefined ? values.manifest === true : !values['no-manifest'];
           const pins = new Map((values.pin ?? []).map(parsePin));
           if (pins.size && !wanted) throw new ConfigError('--pin needs a manifest; drop --no-manifest or add --manifest');
+          if (values.template !== undefined && values.template !== 'default' && values.template !== 'page') throw new ConfigError('--template must be page');
+          if (values.template === 'page' && values.with !== undefined) throw new ConfigError('--template page cannot be combined with --with');
           if (values.with === undefined) {
             const set = wanted ? await collectDependencySet([], [], { overrides: pins }) : undefined;
-            const created = await initProject(arg, { manifest: set });
+            const created = await initProject(arg, { manifest: set, template: values.template === 'page' ? 'page' : 'default' });
             print(set ? { event:'created', dependencies:set.pins, nextSteps:installSteps(created, set) } : { event:'created' });
             break;
           }
-          const created = await initProjectWith(arg, parseWithNames(values.with), { manifest: wanted, pins });
+          const created = await initProjectWith(arg, parseWithNames(values.with), { manifest: wanted, pins, acknowledgements: values.ack ?? [] });
           print({ event:'created', ...created, review:`Review ${created.project}/urlcode.yaml and pin its revision explicitly (for example PROJECT_SHA256=${created.projectSha256}); re-review after any project change` });
           break;
         }
@@ -299,7 +315,7 @@ try {
           if (!arg) throw new ConfigError('Provide an HTTP(S) destination URL');
           print({ event:'added', path:await addRedirect(values.project,arg,values.alias) }); break;
         case 'test': {
-          const result = await runProjectTests(values.project, { ...hostOptions, log:print, permissions, origin:values.origin });
+          const result = await runProjectTests(values.project, { ...hostOptions, log:values.verbose ? print : (event       ) => { if ((event                                 ).event === 'test' && (event                   ).pass === false) print(event); }, permissions, origin:values.origin });
           print(result); if (result.failed) process.exitCode = 1; break;
         }
         case 'doctor':
@@ -324,7 +340,7 @@ try {
   }
 } catch (error) {
   const code = typeof error === 'object' && error !== null && 'code' in error && typeof error.code === 'string' ? error.code : undefined;
-  const message = (error instanceof ConfigError || error instanceof HttpError) ? error.message : ((code !== undefined ? errorMessages[code] : undefined) || 'Operation failed; check project files, module dependencies and command options');
+  const message = code === 'EADDRINUSE' ? addressInUseMessage(error) : (error instanceof ConfigError || error instanceof HttpError) ? error.message : ((code !== undefined ? errorMessages[code] : undefined) || 'Operation failed; check project files, module dependencies and command options');
   process.stderr.write(JSON.stringify({ event:'error', message }) + '\n'); process.exitCode = 1;
 } finally {
   if (!serving) {

package/dist/config.js

@@ -4,8 +4,10 @@ import { resolve, relative, isAbsolute, extname } from 'node:path';
 import { createHash } from 'node:crypto';
 import { parseDocument, visit, isAlias, isScalar, isMap, isNode } from 'yaml';
 import Ajv from 'ajv/dist/2020.js';
+                                       
 import { assert, ConfigError } from './errors.js';
-                                                                                                                                      
+import { reservedResponseHeaders } from './http-policy.js';
+                                                                                                                                                   
 
 /** What config-worker.ts posts back: the loaded document, or the ConfigError message. */
                                                                                
@@ -14,7 +16,7 @@ import { assert, ConfigError } from './errors.js';
 // The schema file is this package's own; JSON.parse gives unknown and Ajv takes it as a schema object.
 const schema = JSON.parse(await readFile(new URL('../schemas/urlcode.schema.json', import.meta.url), 'utf8'))          ;
 // Node hands the CJS module.exports (the class) to a default import; TypeScript types it as the namespace, whose .default is the same class.
-const validate = new Ajv.default({ allErrors: false, strict: true, strictRequired: false, allowUnionTypes: true }).compile(schema);
+const validate = new Ajv.default({ allErrors: false, verbose: true, strict: true, strictRequired: false, allowUnionTypes: true }).compile(schema);
 export const MAX_CONFIG_BYTES = 32 * 1024 * 1024;
 export function parseYaml(text        )          {
   assert(Buffer.byteLength(text) <= MAX_CONFIG_BYTES, 'Configuration exceeds 32 MiB');
@@ -48,15 +50,80 @@ export function parseYaml(text        )          {
   inspect(data);
   return data;
 }
-export function validateDocument(data         )                  {
+const MAX_NAMED_KEY = 64;
+const quoteKey = (key        ) => JSON.stringify(key.length > MAX_NAMED_KEY ? `${key.slice(0, MAX_NAMED_KEY)}...` : key);
+const MAX_LISTED_KEYS = 10;
+const editDistance = (a        , b        )         => {
+  let row = Array.from({ length: b.length + 1 }, (_, j) => j);
+  for (let i = 1; i <= a.length; i++) {
+    const next = [i];
+    for (let j = 1; j <= b.length; j++) next[j] = Math.min(row[j]  + 1, next[j - 1]  + 1, row[j - 1]  + (a[i - 1] === b[j - 1] ? 0 : 1));
+    row = next;
+  }
+  return row[b.length] ;
+};
+/** The allowed key an unknown key most likely meant: case-insensitive match, a prefix (3+ chars) either way, or edit distance <= 2. */
+function closestKey(key        , allowed          )                     {
+  if (key.length > MAX_NAMED_KEY) return undefined;
+  const k = key.toLowerCase();
+  let best                    ;
+  let bestScore = Infinity;
+  for (const candidate of allowed) {
+    const c = candidate.toLowerCase();
+    const prefix = Math.min(k.length, c.length) >= 3 && (c.startsWith(k) || k.startsWith(c));
+    const score = k === c ? 0 : Math.min(editDistance(k, c), prefix ? 2 : Infinity);
+    if (score <= 2 && score < bestScore) { best = candidate; bestScore = score; }
+  }
+  return best;
+}
+/**
+ * One line for the first schema violation. Closed-key-set failures name the offending key and the keys the
+ * schema allows, and required failures name the missing key, because a bare keyword sends the reader hunting.
+ * Only key names, which come from the schema or the author's own mapping keys, are echoed, never values
+ * (values may hold secrets), and never more than MAX_NAMED_KEY characters of a key.
+ */
+export function describeSchemaError(e             )         {
+  const base = `Invalid configuration at ${e.instancePath || '/'} (${e.keyword})`;
+  const parent = e.parentSchema                                                        ;
+  if (e.keyword === 'additionalProperties') {
+    const key = String((e.params                                    ).additionalProperty);
+    const allowed = Object.keys(parent?.properties ?? {});
+    const close = closestKey(key, allowed);
+    let list = '; no keys are allowed here';
+    if (close) list = `; did you mean ${quoteKey(close)}?`;
+    else if (allowed.length > MAX_LISTED_KEYS) list = `; allowed keys: ${allowed.slice(0, MAX_LISTED_KEYS).join(', ')}, ... (${allowed.length - MAX_LISTED_KEYS} more)`;
+    else if (allowed.length) list = `; allowed keys: ${allowed.join(', ')}`;
+    return `${base}: unknown key ${quoteKey(key)}${list} (run urlcode schema <path> for the shape)`;
+  }
+  if (e.keyword === 'required') return `${base}: missing required key ${quoteKey(String((e.params                                 ).missingProperty))}`;
+  return base;
+}
+export function validateDocument(data         , inherited                              )                  {
   if (!validate(data)) {
     const e = validate.errors [0] ;
-    throw new ConfigError(`Invalid configuration at ${e.instancePath || '/'} (${e.keyword})`);
+    throw new ConfigError(describeSchemaError(e));
   }
   const document = data                   ; // trust boundary: the schema just admitted it
-  for (const [pattern, route] of Object.entries(document.routes)) document.routes[pattern] = normalizeRoute(pattern, route);
+  for (const [name, block] of Object.entries(document.shared ?? {}))
+    for (const header of Object.keys(block.response?.headers ?? {})) assert(!reservedResponseHeaders.has(header.toLowerCase()), `shared.${name}: response header ${header} is owned by the runtime or handler`);
+  for (const [pattern, route] of Object.entries(document.routes)) document.routes[pattern] = expandShared(pattern, normalizeRoute(pattern, route), inherited ?? document.shared);
   return document;
 }
+/**
+ * Resolves `use: <name>` at load time. The route's own `request` or `response` key wins as a whole block
+ * (no deep merge); otherwise the shared block's key is copied in. `use` is removed, so the route hash,
+ * audit and routes output show what actually applies. An unknown name fails validation.
+ */
+function expandShared(pattern        , route             , shared                                         )              {
+  if (route.use === undefined) return route;
+  const block = shared !== undefined && Object.hasOwn(shared, route.use) ? shared[route.use] : undefined;
+  assert(block, `${pattern}: use references unknown shared block ${route.use}`);
+  const { use: _use, ...rest } = route;
+  const result              = { ...rest };
+  if (rest.request === undefined && block.request !== undefined) result.request = structuredClone(block.request);
+  if (rest.response === undefined && block.response !== undefined) result.response = structuredClone(block.response);
+  return result;
+}
 /** The input declaration a short-form function gets for each `{param}` it does not declare itself. */
 export const SHORT_FORM_PATH_SCHEMA = { type: 'string', minLength: 1, maxLength: 128 }         ;
 // A short-form path is checked here, before the file system, so the error can name the route.
@@ -185,9 +252,10 @@ export async function loadDocumentInWorker(project        )
     const path = await safeFile(root, include);
     assert(!files.includes(path), 'Duplicate include');
     files.push(path);
-    const part = validateDocument(await readConfig(path, budget));
+    const part = validateDocument(await readConfig(path, budget), document.shared ?? {});
     assert(!part.includes?.length, 'Nested includes are unsupported');
     assert(part.site===undefined, 'site may only be set in the entry urlcode.yaml');
+    assert(part.shared===undefined, 'shared may only be set in the entry urlcode.yaml');
     for(const [name,extension]of Object.entries(part.extensions??{})){assert(!Object.hasOwn(extensions,name),'Duplicate extension declaration across files');extensions[name]=extension;assert(Object.keys(extensions).length<=16,'Maximum 16 extensions per project');}
     for (const [pattern, route] of Object.entries(part.routes)) {
       assert(!Object.hasOwn(routes, pattern), 'Duplicate route across files');

package/dist/context.js

@@ -1,4 +1,4 @@
-import {readdir,readFile} from 'node:fs/promises';
+import {readFile} from 'node:fs/promises';
 import {relative} from 'node:path';
 import {stringify} from 'yaml';
 import {loadDocument} from './config.js';
@@ -51,6 +51,7 @@ const constraints                                                  ={
  pathShape:{value:'exact or {param}',note:'No greedy captures or general-purpose wildcards; a segment is a literal or a named placeholder'},
  wildcardMounts:{value:false,note:'Only static and extension routes mount a subtree; nothing else matches below its path'},
  yamlInterpolation:{value:false,note:'No ${...} templating; bind typed inputs through parameters, args and context'},
+ builtInBeforeCode:{value:true,note:'Check built-ins before writing code: policies.security (security headers), cacheControl (four fixed values on page/download/static), request.body (size, type, JSON), methods, policies.throttle/agents/compression/cache, site (robots, sitemap, favicon, security.txt); no native storage or CORS'},
  secretsByOperatorGrant:{value:true,note:'Projects request named env and secret bindings; only an operator policy pinned to the project revision grants them'},
 };
 const routesOf=(table                                          )                =>[...table.exact.values(),...[...table.byLength.values()].flat(),...table.mounts];
@@ -146,10 +147,7 @@ function fitBudget(context               ,budget       )                {
  if(!fits())throw new Error(`Context budget ${budget} is below the smallest rendering`);
  return omitted.length?{...context,omitted}:context;
 }
-/** Estimated size of the shipped documentation (docs/*.md and llms.txt), for comparison with an emitted context. */
+/** Estimated size of the shipped offline documentation bundle, for comparison with an emitted context. */
 export async function documentationTokens()                 {
- const docs=new URL('../docs/',import.meta.url);let chars=0;
- for(const name of (await readdir(docs)).filter(name=>name.endsWith('.md')).sort())chars+=(await readFile(new URL(name,docs),'utf8')).length;
- chars+=(await readFile(new URL('../llms.txt',import.meta.url),'utf8')).length;
- return Math.ceil(chars/4);
+ return Math.ceil((await readFile(new URL('../llms-full.txt',import.meta.url),'utf8')).length/4);
 }

package/dist/errors.js

@@ -1,7 +1,9 @@
 export class ConfigError extends Error {}
 export class HttpError extends Error {
            status        ;
-  constructor(status        , message        ) { super(message); this.status = status; }
+  /** A pre-rendered, fixed-content answer that replaces the plain-text message (used for negotiated 422 bodies). */
+           answer                                                   ;
+  constructor(status        , message        , answer                                        ) { super(message); this.status = status; this.answer = answer; }
 }
 export function assert(condition         , message        )                    {
   if (!condition) throw new ConfigError(message);

package/dist/examples.js

@@ -21,7 +21,7 @@ import {assert} from './errors.js';
                                                                                                      
  
 // Fixed package data, like the recipe catalog: names come from here, metadata from each example.yaml.
-export const exampleNames=['assets','aws','cloudflare','compliance','conditions','cookbook','egress','extensions','monitoring','prerender','provider-conformance','tunnel','vercel']         ;
+export const exampleNames=['assets','aws','body-validation','cloudflare','compliance','conditions','cookbook','coverage-waiver','data-dir','egress','extensions','lifecycle','monitoring','not-found','prerender','provider-conformance','shared-blocks','tunnel','vercel']         ;
 export const routeIndexFile='route-index.json';
 const examplesRoot=fileURLToPath(new URL('../examples/',import.meta.url));
 const root=(name        )=>examplesRoot+name+'/';

package/dist/extensions.js

@@ -65,6 +65,27 @@ import { validateHeaderName, validateHeaderValue } from './header-validation.js'
                      
                        
  
+                                                                                                                         
+/** One project-owned customization surface, shown to people and authoring agents by CLI/MCP inspection. */
+                                            
+                              
+              
+                     
+                                                                                     
+               
+                                                                                
+                  
+ 
+/**
+ * Machine-readable guidance for changing an installed extension without
+ * copying its behavior into the application. This is descriptive only: it
+ * grants nothing and is never executed by the runtime.
+ */
+                                             
+                     
+                                                
+                                
+ 
                                                                                                       
 /** Shared schema for project hook references. Omission means trusted execution. */
 export const extensionHookReferenceSchema={
@@ -124,6 +145,8 @@ export async function loadExtensionHooks                  (config
                                                                                                               
                                                                                  
                                           
+                                                                            
+                                        
      
                                                                                    
                                                                         
@@ -151,20 +174,39 @@ export async function loadExtensionHooks                  (config
                  
                                                                                        
                   
-                                                                                               
+                                                                                                                                                        
                           
+     
+                                                                                                                                   
+                                                                                                                                      
+                                                                                                                                 
+                                                                                           
+     
+                                     
  
                                                                                       
                                  
                                        
               
+     
+                                                                                                                                      
+                                                                                                                            
+                                                                                                                           
+                                                                                                                                 
+                                                         
+     
+                                                                               
+                                                                                                                                                                                       
+                         
+                                                                                                                                        
+                       
                                                                                                              
                                                                    
                                                                                                                             
                                                                                       
                                                                                                              
                        
-                                                                                                               
+                                                                                                                   
                                     
                                                                           
                              
@@ -175,6 +217,7 @@ export async function loadExtensionHooks                  (config
                                                                                                                              
 const namePattern=/^[a-z][a-z0-9-]{0,63}$/;
 const hookNamePattern=/^[a-z][A-Za-z0-9]{0,63}$/;
+const authoringNamePattern=/^[A-Za-z0-9][A-Za-z0-9 ._/-]{0,127}$/;
 const cacheHeaders=new Set(['cache-control','cdn-cache-control','vercel-cdn-cache-control','surrogate-control']);
 const segmentPattern=/^[A-Za-z0-9_-][A-Za-z0-9._-]{0,63}$/;
 export const immutableCacheControl='public, max-age=31536000, immutable';
@@ -230,6 +273,21 @@ export function prepareExtensions(document                ,routes
       assert(hook.inputSchema&&typeof hook.inputSchema==='object'&&(!hook.outputSchema||typeof hook.outputSchema==='object'),'Invalid extension hook contract');
       hookNames.add(hook.name);
     }
+    if(registration.authoring!==undefined){
+      const authoring=registration.authoring;
+      assert(authoring&&typeof authoring==='object'&&typeof authoring.description==='string'&&authoring.description.length>=1&&authoring.description.length<=1024,'Invalid extension authoring contract');
+      assert(Array.isArray(authoring.surfaces)&&authoring.surfaces.length<=64,'Invalid extension authoring surfaces');
+      const surfaceNames=new Set        ();
+      for(const surface of authoring.surfaces){
+        assert(surface&&typeof surface==='object'&&['configuration','theme','copy','component','template','stylesheet','hook','extension'].includes(surface.kind),'Invalid extension authoring surface kind');
+        assert(typeof surface.name==='string'&&authoringNamePattern.test(surface.name)&&!surfaceNames.has(surface.name),'Invalid extension authoring surface name');
+        assert(typeof surface.description==='string'&&surface.description.length>=1&&surface.description.length<=1024,'Invalid extension authoring surface description');
+        assert(surface.path===undefined||typeof surface.path==='string'&&surface.path.length>=1&&surface.path.length<=1024,'Invalid extension authoring surface path');
+        assert(surface.command===undefined||typeof surface.command==='string'&&surface.command.length>=1&&surface.command.length<=2048,'Invalid extension authoring surface command');
+        surfaceNames.add(surface.name);
+      }
+      assert(authoring.fastChecks===undefined||Array.isArray(authoring.fastChecks)&&authoring.fastChecks.length<=32&&authoring.fastChecks.every(check=>typeof check==='string'&&check.length>=1&&check.length<=2048),'Invalid extension authoring fast checks');
+    }
     provided.set(registration.name,registration);
   }
   const declarations=document.extensions??{};