@jimhoyd/urlcode 0.4.2 → 0.4.7

package/dist/readiness.js

@@ -27,12 +27,27 @@ import { runCompliance } from './compliance.js';
                               
                                                                                                                                      
                                                                                       
+                                                                                                           
+                                                    
  
+/** Where a captured value comes from: a dotted path into a JSON response body, or one response header. */
+                                                                
+/** A step that closes and restarts the runtime on the same project and data directory. */
+                                              
+/** An ordered fixture: requests that share captured values, optionally with restarts between them. */
+                                                                      
+                                                 
+export const isStepsFixture = (fixture         )                          => 'steps' in fixture;
+export const isRestartable = (app              )                        => typeof (app                           ).restart === 'function';
+const isRestart = (step                           )                      => 'restart' in step;
                                                                                                                                  
-                                                                                                
+/** `captured` holds values from a step's `capture`; callers use it for substitution only and never print it. */
+                                                                                                                                   
                                                                                               
 /** A started server as the audit and benchmark see it. structural: the real type is startServer's result in src/server.ts. */
                                                                                                                                               
+/** An app that can also close and restart itself on the same project and data directory (fixture `restart` steps). */
+                                                                                 
                                                                            
                                                                                                                                         
                               
@@ -40,9 +55,18 @@ import { runCompliance } from './compliance.js';
                                                                          
                                                                                                
                             
-                                                                                                                       
-                                                                                                                                    
+                                                                                                                                   
+                                                            
                                                                                                                                                             
+                                                                                                                                    
+                                                                            
+                                                                                                             
+                                                                          
+                                                                                                                                            
+                                                                      
+                                                                                                             
+                                                                        
+                                                                                 
                                                                                
                                                                                         
                                                    
@@ -70,7 +94,7 @@ function routeAdvisories(route               )           {
   const advisories           = [];
   const runsCode = Boolean(route.function) || Boolean(route.middleware?.length);
   if (runsCode && route.methods.includes('POST') && route.request?.body && !route.sandbox && !route.sandboxReason) {
-    advisories.push("This route accepts POST with a declared request.body policy but declares neither sandbox: true nor sandboxReason; consider whether this route needs sandbox: true.");
+    advisories.push("This route accepts POST with a declared request.body policy but declares neither sandbox: true nor sandboxReason; consider whether this route needs sandbox: true. If it is trusted first-party code (anything that touches the filesystem must be trusted; a sandbox has no filesystem), add to the route: sandboxReason: \"Reviewed first-party code; trusted deliberately.\" If it isolates untrusted input, add sandbox: true and a sandboxReason saying why.");
   }
   return advisories;
 }
@@ -80,6 +104,7 @@ export function projectPlan(compiled                               )
   const inventory                   = routes.map(route => { const advisories = routeAdvisories(route); return { path:route.pattern, handler:handlers.find(key => route[key]), methods:route.methods, middleware:route.middleware?.length || 0,
     policies:[...(route.policy ? Object.keys(route.policy.describe) : []),...(route.extensionPolicyNames??[]).map(name=>`extensions.${name}`)],
     sandbox:route.sandbox === true, ...(route.sandboxReason ? { sandboxReason:route.sandboxReason } : {}),
+    ...(route.coveredElsewhere ? { coveredElsewhere:route.coveredElsewhere } : {}),
     ...(route.generated ? { generated:route.generated } : {}),
     ...(advisories.length ? { advisories } : {}),
     state:route.enabled === false ? 'disabled' : route.expiresAt && now >= route.expiresAt ? 'expired' : 'active' }; });
@@ -112,7 +137,33 @@ export function projectPlan(compiled                               )
   }
   return {inventory,cases,resolve:path => matchRoute(compiled,parseTarget(path))?.route.pattern};
 }
-export async function readCases(root        , optional = false)                         {
+// Bounds for ordered fixtures. A fixture file is data a project author (or an agent) wrote;
+// none of these limits is a security boundary, they keep a mistake from becoming an unbounded run.
+const MAX_STEPS = 50, MAX_RESTARTS = 5, MAX_TOTAL_RESTARTS = 20, MAX_CAPTURES = 16, MAX_CAPTURE_BYTES = 4096, MAX_CAPTURE_BODY = 1024 * 1024;
+const nameShape = /^[A-Za-z_][A-Za-z0-9_]{0,31}$/, pathShape = /^[A-Za-z0-9_-]+(?:\.[A-Za-z0-9_-]+)*$/, control = /[\x00-\x1f\x7f]/;
+const templates = (text        )           => [...text.matchAll(/\{\{([A-Za-z_][A-Za-z0-9_]{0,31})\}\}/g)].map(m => m[1] ?? '');
+const templated = (test             )           => [test.path, test.body, test.expectBody, ...Object.values(test.headers ?? {}), ...Object.values(test.expectHeaders ?? {})].filter((v)              => v !== undefined);
+function checkCase(test         , inSteps         )                              {
+  assert(isRecord(test), 'Invalid request test');
+  // A step path may start with a {{name}} (a captured Location); it is checked again once filled in.
+  assert(typeof test.path === 'string' && (test.path.startsWith('/') || (inSteps && test.path.startsWith('{{'))) && !test.path.startsWith('//') && !/[\r\n]/.test(test.path), 'Test path must be local');
+  assert(Number.isInteger(test.status) && typeof test.status === 'number' && test.status >= 200 && test.status <= 599, 'Test must declare an HTTP status');
+  assert(!test.method || (typeof test.method === 'string' && ['GET','HEAD','POST','PUT','PATCH','DELETE','OPTIONS'].includes(test.method)), 'Invalid test method');
+  assert(test.body === undefined || typeof test.body === 'string', 'Test body must be text');
+  assert(test.expectBody === undefined || typeof test.expectBody === 'string', 'Expected body must be text');
+  for (const headers of [test.headers,test.expectHeaders]) assert(headers === undefined || (isRecord(headers) && Object.values(headers).every(v => typeof v === 'string')), 'Test headers must be string mappings');
+  assert(inSteps || test.capture === undefined, 'capture is only valid inside steps');
+  if (test.capture !== undefined) {
+    assert(isRecord(test.capture) && Object.keys(test.capture).length <= MAX_CAPTURES, `capture must be a mapping of at most ${MAX_CAPTURES} names`);
+    for (const [name,spec] of Object.entries(test.capture)) {
+      assert(nameShape.test(name), 'Capture names use letters, digits and underscores (at most 32, not starting with a digit)');
+      assert(isRecord(spec) && Object.keys(spec).length === 1, 'A capture is exactly one of {json: "a.b.0.c"} or {header: "name"}');
+      if (typeof spec.json === 'string') assert(spec.json.length <= 256 && pathShape.test(spec.json), 'Capture json path is dotted keys and array indexes, such as items.0.id');
+      else assert(typeof spec.header === 'string' && /^[A-Za-z0-9-]{1,64}$/.test(spec.header), 'A capture is exactly one of {json: "a.b.0.c"} or {header: "name"}');
+    }
+  }
+}
+export async function readFixtures(root        , optional = false)                     {
   if(optional) {
     try {await lstat(join(root,'tests/requests.json'));}
     catch(error){if(error instanceof Error && 'code' in error && error.code==='ENOENT')return [];throw error;}
@@ -122,16 +173,94 @@ export async function readCases(root        , optional = false)
   assert(bytes.length <= 16*1024*1024, 'Request fixture file exceeds 16 MiB');
   const cases          = JSON.parse(bytes.toString('utf8'));
   assert(Array.isArray(cases) && cases.length <= 10000 && (optional || cases.length), 'Request tests must be an array (maximum 10000)');
+  let requests = 0, restarts = 0;
   for (const test of cases             ) {
-    assert(isRecord(test), 'Invalid request test');
-    assert(typeof test.path === 'string' && test.path.startsWith('/') && !test.path.startsWith('//') && !/[\r\n]/.test(test.path), 'Test path must be local');
-    assert(Number.isInteger(test.status) && typeof test.status === 'number' && test.status >= 200 && test.status <= 599, 'Test must declare an HTTP status');
-    assert(!test.method || (typeof test.method === 'string' && ['GET','HEAD','POST','PUT','PATCH','DELETE','OPTIONS'].includes(test.method)), 'Invalid test method');
-    assert(test.body === undefined || typeof test.body === 'string', 'Test body must be text');
-    assert(test.expectBody === undefined || typeof test.expectBody === 'string', 'Expected body must be text');
-    for (const headers of [test.headers,test.expectHeaders]) assert(headers === undefined || (isRecord(headers) && Object.values(headers).every(v => typeof v === 'string')), 'Test headers must be string mappings');
+    if (!(isRecord(test) && 'steps' in test)) { checkCase(test,false); requests++; continue; }
+    assert(Object.keys(test).length === 1 && Array.isArray(test.steps) && test.steps.length >= 1 && test.steps.length <= MAX_STEPS, `steps must be the only key and hold 1-${MAX_STEPS} steps`);
+    const known = new Set        (); let here = 0;
+    for (const step of test.steps             ) {
+      if (isRecord(step) && 'restart' in step) {
+        assert(step.restart === true && Object.keys(step).length === 1, 'A restart step is exactly {"restart": true}');
+        assert(++here <= MAX_RESTARTS && ++restarts <= MAX_TOTAL_RESTARTS, `At most ${MAX_RESTARTS} restarts per fixture and ${MAX_TOTAL_RESTARTS} per file`);
+        continue;
+      }
+      checkCase(step,true); requests++;
+      for (const name of templated(step).flatMap(templates)) assert(known.has(name), 'A {{name}} reference needs an earlier step in the same fixture to capture it');
+      for (const name of Object.keys(step.capture ?? {})) known.add(name);
+    }
   }
-  return cases                 ; // trust boundary: fixture JSON, validated field by field above
+  assert(requests <= 10000, 'Request tests exceed 10000 requests in total');
+  return cases             ; // trust boundary: fixture JSON, validated field by field above
+}
+/** Single-request fixtures only: the benchmark replays these and cannot run ordered steps. */
+export async function readCases(root        , optional = false)                         {
+  return (await readFixtures(root,optional)).filter((fixture)                         => !isStepsFixture(fixture));
+}
+/** One request a fixture run sent: `test` is the request as sent (captured values filled in), `original` as written. Print `original`, never `test`. */
+                                                                                                                           
+                              
+                                                                        
+                                                                                                               
+                                              
+                                                                                                                                                                                            
+                                                                    
+ 
+const fill = (text        , values                    )                     => {
+  let missing = false;
+  const out = text.replace(/\{\{([A-Za-z_][A-Za-z0-9_]{0,31})\}\}/g, (_, name        ) => { const v = values.get(name); if (v === undefined) missing = true; return v ?? ''; });
+  return missing ? undefined : out;
+};
+function resolveStep(test             , values                    )                          {
+  const map = (headers                                   )                                           => {
+    if (headers === undefined) return undefined;
+    const out                        = {};
+    for (const [k,v] of Object.entries(headers)) { const f = fill(v,values); if (f === undefined) return null; out[k] = f; }
+    return out;
+  };
+  const path = fill(test.path,values), body = test.body === undefined ? undefined : fill(test.body,values), expectBody = test.expectBody === undefined ? undefined : fill(test.expectBody,values);
+  const headers = map(test.headers), expectHeaders = map(test.expectHeaders);
+  if (path === undefined || !path.startsWith('/') || path.startsWith('//') || /[\r\n]/.test(path) || headers === null || expectHeaders === null || (test.body !== undefined && body === undefined) || (test.expectBody !== undefined && expectBody === undefined)) return undefined;
+  return { ...test, path, headers, body, expectHeaders, expectBody };
+}
+/** Runs every fixture in file order. A step after a failed step in the same fixture is reported failed with error `skipped` and never sent, so a broken chain cannot pass. */
+export async function runFixtures(fixtures           , host             , visit                                             , firstCase = 1)                {
+  let n = firstCase;
+  for (const [f,fixture] of fixtures.entries()) {
+    if (!isStepsFixture(fixture)) { await visit({case:n++,fixture:f+1,test:fixture,original:fixture,result:await hit(host.app,fixture,host.agent,host.target)}); continue; }
+    if (fixture.steps.some(isRestart) && host.restart === undefined) {
+      const reason = 'contains a restart step, which needs a runtime this host can close and restart';
+      assert(host.skipped !== undefined, `Fixture ${f+1} ${reason}`);
+      host.skipped(f+1,reason); continue;
+    }
+    const values = new Map               (); let broken = false;
+    for (const step of fixture.steps) {
+      if (isRestart(step)) { if (!broken) { try { await host.restart?.(); } catch { broken = true; } } continue; }
+      const resolved = broken ? undefined : resolveStep(step,values);
+      let result            = {pass:false,status:0,durationMs:0,error:'skipped'};
+      if (resolved) {
+        const sent = await hit(host.app,resolved,host.agent,host.target);
+        if (sent.pass) for (const [name,value] of Object.entries(sent.captured ?? {})) values.set(name,value);
+        const {captured: _kept, ...visible} = sent; result = visible;
+      } else if (!broken) result = {pass:false,status:0,durationMs:0,error:'unresolved'};
+      if (!result.pass) broken = true;
+      await visit({case:n++,fixture:f+1,test:resolved ?? step,original:step,result});
+    }
+  }
+}
+function extract(spec             , headers                            , body        )                     {
+  let value         ;
+  if ('header' in spec) value = headers[spec.header.toLowerCase()];
+  else {
+    if (body.length > MAX_CAPTURE_BODY) return undefined;
+    try { value = JSON.parse(body.toString('utf8')); } catch { return undefined; }
+    for (const key of spec.json.split('.')) {
+      if (Array.isArray(value)) value = /^\d+$/.test(key) ? value[Number(key)] : undefined;
+      else if (isRecord(value) && Object.hasOwn(value,key)) value = value[key];
+      else return undefined;
+    }
+  }
+  const text = typeof value === 'string' ? value : (typeof value === 'number' && Number.isFinite(value)) || typeof value === 'boolean' ? String(value) : undefined;
+  return text !== undefined && text.length > 0 && Buffer.byteLength(text) <= MAX_CAPTURE_BYTES && !control.test(text) ? text : undefined;
 }
 export function benchmarkTarget(value        )                  {
   let url     ;
@@ -152,10 +281,17 @@ export function hit(app              ,test             ,agent       ,target
         : {host:'127.0.0.1',port:app.address.port,path:test.path,method:test.method || 'GET',headers:{'user-agent':probeAgent,...(test.headers || {})},agent,timeout:10000};
       req=send(options,(res                 )=>{
         let size=0;const chunks          =[];
-        res.on('data',(chunk        )=>{size+=chunk.length;if(size>16*1024*1024)res.destroy(new Error('Response limit'));else if(test.expectBody!==undefined)chunks.push(chunk);});
+        res.on('data',(chunk        )=>{size+=chunk.length;if(size>16*1024*1024)res.destroy(new Error('Response limit'));else if(test.expectBody!==undefined || (test.capture && size<=MAX_CAPTURE_BODY))chunks.push(chunk);});
         res.on('error',fail);
-        res.on('end',()=>resolve({status:res.statusCode ?? 0,durationMs:performance.now()-began,
-          pass:res.statusCode===test.status && Object.entries(test.expectHeaders || {}).every(([k,v])=>res.headers[k.toLowerCase()]===v) && (test.expectBody===undefined || Buffer.concat(chunks).toString()===test.expectBody)}));
+        res.on('end',()=>{
+          const status=res.statusCode ?? 0,durationMs=performance.now()-began,body=Buffer.concat(chunks);
+          let pass=status===test.status && Object.entries(test.expectHeaders || {}).every(([k,v])=>res.headers[k.toLowerCase()]===v) && (test.expectBody===undefined || body.toString()===test.expectBody);
+          if(!pass || !test.capture)return resolve({status,durationMs,pass});
+          // Values are kept only for later steps; a missing one fails the step without saying what the response held.
+          const captured                       ={};
+          for(const [name,spec] of Object.entries(test.capture)){const value=extract(spec,res.headers,body);if(value===undefined){pass=false;break;}captured[name]=value;}
+          resolve(pass?{status,durationMs,pass,captured}:{status,durationMs,pass,error:'capture'});
+        });
       });
       req.on('error',fail);req.on('timeout',()=>req?.destroy(new Error('Timeout')));req.end(test.body);
     } catch { req?.destroy();fail(); }
@@ -167,32 +303,48 @@ export function hit(app              ,test             ,agent       ,target
 // folded into it: the exit code decision belongs to the caller.
 export async function auditProject(app              , {expectRoutes,log=()=>{},compliance}               = {})                       {
   const began=performance.now();
-  const plan=app.testPlan(), fixtures=await readCases(app.root,true);
+  const plan=app.testPlan(), fixtures=await readFixtures(app.root,true);
   const metadata=new Map(plan.inventory.map(r=>[r.path,r]));
-  const cases=[...plan.cases,...fixtures], covered=new Set        (), unassertedCases          =[];let passed=0,failed=0;
+  const covered=new Set        (), unassertedCases          =[];let passed=0,failed=0,checks=0;
   const agent=new Agent({keepAlive:true,maxSockets:1});
+  // One accounting for generated cases and fixture steps, single or ordered: a step counts as
+  // a check, and covers a route/method only when it passes and asserts the response. Coverage
+  // uses the route the substituted path actually matched.
+  const record=(n        ,test             ,result           ,source                       )      =>{
+    checks++;const method=test.method || 'GET';
+    let route                  ;try {route=plan.resolve(test.path);} catch { /* Invalid-path negative fixture. */ }
+    const meta=route===undefined?undefined:metadata.get(route);
+    // Error-only fixtures cannot prove a function's normal path works.
+    const assertsResponse=test.expectBody!==undefined || Object.keys(test.expectHeaders || {}).length>0;
+    if(result.pass && meta?.state==='active' && result.status<400 && !assertsResponse)unassertedCases.push(n);
+    if(result.pass && assertsResponse && meta?.state==='active' && (result.status<400 || (meta.handler==='respond' && source==='generated')))covered.add(JSON.stringify([route,method]));
+    if(result.pass)passed++;else failed++;
+    log({event:'check',case:n,source,pass:result.pass,status:result.status,expectedStatus:test.status});
+  };
   try {
-    for (const [i,test] of cases.entries()) {
-      const result=await hit(app,test,agent);const method=test.method || 'GET';
-      let route                  ;try {route=plan.resolve(test.path);} catch { /* Invalid-path negative fixture. */ }
-      const meta=route===undefined?undefined:metadata.get(route);
-      // Error-only fixtures cannot prove a function's normal path works.
-      const assertsResponse=test.expectBody!==undefined || Object.keys(test.expectHeaders || {}).length>0;
-      if(result.pass && meta?.state==='active' && result.status<400 && !assertsResponse)unassertedCases.push(i+1);
-      if(result.pass && assertsResponse && meta?.state==='active' && (result.status<400 || (meta.handler==='respond' && i<plan.cases.length)))covered.add(JSON.stringify([route,method]));
-      if(result.pass)passed++;else failed++;
-      log({event:'check',case:i+1,source:i<plan.cases.length?'generated':'fixture',pass:result.pass,status:result.status,expectedStatus:test.status});
-    }
+    for (const [i,test] of plan.cases.entries()) record(i+1,test,await hit(app,test,agent),'generated');
+    const restart=isRestartable(app)?()=>app.restart():undefined;
+    await runFixtures(fixtures,{app,agent,restart},step=>record(step.case,step.test,step.result,'fixture'),plan.cases.length+1);
   } finally {agent.destroy();}
-  const uncovered=plan.inventory.filter(r=>r.state==='active').flatMap(r=>r.methods.filter(m=>!covered.has(JSON.stringify([r.path,m]))).map(method=>({route:r.path,method})));
-  const counts                       ={configured:plan.inventory.length,active:0,disabled:0,expired:0,byHandler:{}};
+  const missing=plan.inventory.filter(r=>r.state==='active').flatMap(r=>r.methods.filter(m=>!covered.has(JSON.stringify([r.path,m]))).map(method=>({route:r.path,method})));
+  const waivedRouteMethods                                   =[],ignoredWaivers                               =[],redundantWaivers                                 =[];
+  const uncovered=missing.filter(({route,method})=>{
+    const reason=metadata.get(route)?.coveredElsewhere?.[method];
+    if(reason===undefined)return true;
+    // A waiver excuses a missing fixture only where the route is otherwise shown to work normally.
+    const proven=[...covered].some(key=>(JSON.parse(key)                   )[0]===route);
+    (proven?waivedRouteMethods:ignoredWaivers).push({route,method,reason});
+    return !proven;
+  });
+  for(const r of plan.inventory)if(r.state==='active')for(const [method,reason] of Object.entries(r.coveredElsewhere??{}))if(covered.has(JSON.stringify([r.path,method])))redundantWaivers.push({route:r.path,method,reason});
+  const counts                       ={configured:plan.inventory.length,declared:plan.inventory.filter(r=>!r.generated).length,generated:plan.inventory.filter(r=>r.generated).length,active:0,disabled:0,expired:0,byHandler:{}};
   for(const route of plan.inventory){counts[route.state]++;const handler=String(route.handler);counts.byHandler[handler]=(counts.byHandler[handler]||0)+1;}
   const countMatches=expectRoutes===undefined || counts.configured===expectRoutes;
   const advisories=plan.inventory.flatMap(route=>(route.advisories??[]).map(message=>({route:route.path,message})));
   // The per-route capability table: which policies apply and whether this
   // host enforces, compiles or delegates each one. Refusals never get here.
   const notReadyReasons=[...(counts.active>0?[]:['no-active-routes']),...(countMatches?[]:['route-count-mismatch']),...(failed?['failed-checks']:[]),...(uncovered.length?['uncovered-route-methods']:[])];
-  return {elapsedMs:performance.now()-began,ready:!notReadyReasons.length,notReadyReasons,counts,expectedRoutes:expectRoutes ?? null,countMatches,checks:cases.length,passed,failed,coveredRouteMethods:covered.size,unassertedCases,uncovered,policies:plan.policies ?? {},compliance:compliance?await runCompliance(app,compliance):null,advisories};
+  return {elapsedMs:performance.now()-began,ready:!notReadyReasons.length,notReadyReasons,counts,expectedRoutes:expectRoutes ?? null,countMatches,checks,passed,failed,coveredRouteMethods:covered.size,unassertedCases,uncovered,waivedRouteMethods,ignoredWaivers,redundantWaivers,policies:plan.policies ?? {},compliance:compliance?await runCompliance(app,compliance):null,advisories};
 }
 export async function benchmarkProject(app              ,{requests=1000,concurrency=2,maxP95Ms,seconds=30,warmup=0,target}                  ={})                           {
   assert(Number.isInteger(requests)&&requests>=1&&requests<=100000,'Requests must be 1–100000');

package/dist/recipes.js

@@ -12,7 +12,7 @@ import {assert} from './errors.js';
                                                                                                                                      
 // This fixed local catalog is trusted package data, never an executable registry:
 // names come from here, metadata from each recipe's schema-checked recipe.yaml.
-export const recipeNames=['redirect','json-api','typescript','middleware','health-page','static-plus-api','cors-api','webhook-receiver','contact-form','authenticated-json-api','protected-download']         ;
+export const recipeNames=['redirect','json-api','typescript','middleware','health-page','static-page','static-plus-api','cors-api','webhook-receiver','contact-form','authenticated-json-api','protected-download','store-crud']         ;
 const recipesRoot=fileURLToPath(new URL('../recipes/',import.meta.url));
 const root=(name        )=>recipesRoot+name+'/';
 async function metadata(name        )                         {const value=await readMetadata(root(name),name,'recipe.yaml');return {name,...value};}

package/dist/router.js

@@ -7,6 +7,8 @@ import { normalizeMatch, assertDisjointMatches } from './conditions.js';
 import { effectivePolicies } from './policies.js';
 import { setImmediate as yieldTurn } from 'node:timers/promises';
 import { compileHttp } from './http-policy.js';
+import { assertSafePattern, maxPatternInputLength } from './pattern-guard.js';
+import { uuidFormat } from './body-schema.js';
 import Ajv from 'ajv/dist/2020.js';
 import { assert } from './errors.js';
 import { functionFile } from './config.js';
@@ -64,6 +66,7 @@ export async function compileRoutes(loaded                , bindings
   const exact = new Map                       (), dynamic                  = [], mounts                  = [], modules = new Map              ();
   // 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 ajv = new Ajv.default({ strict: false, allErrors: false }), validators = new Map                   ();
+  ajv.addFormat('uuid', uuidFormat);
   for (const [pattern, config] of Object.entries(loaded.routes)) {
     if (++processed % 64 === 0) await yieldTurn();
     assert(performance.now()<deadline, 'Route compilation deadline exceeded');
@@ -78,6 +81,14 @@ export async function compileRoutes(loaded                , bindings
     const { redirect: declaredRedirect, function: declaredFunction, ...declared } = config;
     const route                = { ...declared, pattern, parts, names, specificity: parts.length - names.length,
       methods: config.methods || methodsDefault, parameters: [], env: dict(), secrets: dict(), responseHeaders: [], middleware: [] };
+    if (config.coveredElsewhere) {
+      const waived = Object.entries(config.coveredElsewhere);
+      assert(waived.length > 0, 'coveredElsewhere must name at least one method');
+      for (const [method, reason] of waived) {
+        assert(route.methods.includes(method), `coveredElsewhere names ${method}, which is not one of the route's methods`);
+        assert(typeof reason === 'string' && reason.trim().length > 0, `coveredElsewhere.${method} needs a non-empty reason`);
+      }
+    }
     compileHttp(route);
     if (config.match) route.match = normalizeMatch(config.match);
     if(config.extension){assert(!config.middleware?.length&&!config.parameters?.length&&!config.env&&!config.secrets,'Extension handlers cannot declare guest middleware, parameters or bindings');assert(pattern.endsWith('/*')&&!names.length&&pattern!=='/*','Extension handler requires a non-root literal /* mount');}
@@ -113,6 +124,12 @@ export async function compileRoutes(loaded                , bindings
       assert(param.in !== 'path' || !own(schema, 'default'), 'Path parameters cannot have defaults');
       assert(!['minLength','maxLength'].some(k => own(schema,k)) || schema.type === 'string', 'String bounds require string type');
       assert(!['minimum','maximum'].some(k => own(schema,k)) || ['integer','number'].includes(schema.type), 'Numeric bounds require numeric type');
+      assert(!['pattern','format'].some(k => own(schema,k)) || schema.type === 'string', 'pattern and format require string type');
+      assert(!own(schema,'format') || schema.format === 'uuid', 'Unsupported parameter format (supported: uuid)');
+      if (own(schema,'pattern')) {
+        assert(typeof schema.pattern === 'string', 'pattern must be a string'); assertSafePattern(schema.pattern);
+        assert(typeof schema.maxLength === 'number' && schema.maxLength <= maxPatternInputLength, `pattern requires maxLength of at most ${maxPatternInputLength}`);
+      }
       assert(!own(schema,'maxItems') || schema.type === 'array', 'maxItems requires array type');
       const p                    = { ...param, name, required: param.required === true, validate: inputValidator(schema, ajv, validators) };
       if (own(schema, 'default')) assert(p.validate(schema.default), 'Invalid parameter default');

package/dist/runtime.js

@@ -26,7 +26,7 @@ import { createObserverSink } from './observability.js';
                                                                                   
 import { applySite } from './site.js';
                                                                     
-                                                                                                                                                 
+                                                                                                                                                                 
                                                             
 
                                                   
@@ -48,7 +48,22 @@ import { applySite } from './site.js';
                                                                                    
                                                                                   
                                        
+                                                                                                  
+                                                                                                        
+                                                                                                            
+                                     
  
+function withDataDirGrant(loaded                , projectSha256        , given                            )                             {
+  // An operator policy pinned to another revision stays as it is: it denies, exactly as it would without this option.
+  if (given && given.projectSha256 !== projectSha256) return given;
+  const routes                           = { ...(given?.routes ?? {}) };
+  for (const [pattern, route] of Object.entries(loaded.routes)) {
+    if (!Object.values(route.env || {}).some(ref => ref.env === 'URLCODE_DATA_DIR')) continue;
+    const grant = routes[pattern] ?? {};
+    routes[pattern] = { ...grant, env: [...new Set([...(grant.env ?? []), 'URLCODE_DATA_DIR'])] };
+  }
+  return { version: 1, projectSha256, routes };
+}
 /** Per-request facts the host may read after handle() settles; never request text. */
                                                                                          
                                  
@@ -93,7 +108,8 @@ export async function createRuntime(project        , rawOptions
   const egressGrants=authorizeEgress(loaded,snapshot.projectSha256,options.permissions);
   const extensionPlan=prepareExtensions(loaded.document,loaded.routes,options.extensions,{origin:options.origin??'',target:options.target??'node',projectSha256:snapshot.projectSha256,root:loaded.root});
   const bindings = await loadBindings(loaded.root, options.local, options.environment);
-  const compiled                     = await compileRoutes(loaded, bindings, options.permissions, snapshot.projectSha256, options.extensions);
+  const notFoundPage = loaded.document.site?.notFound !== undefined && loaded.document.site.notFound !== null;
+  const compiled                     = await compileRoutes(loaded, bindings, options.grantDataDir ? withDataDirGrant(loaded, snapshot.projectSha256, options.permissions) : options.permissions, snapshot.projectSha256, options.extensions);
   const routes = [...compiled.mounts, ...compiled.exact.values(), ...[...compiled.byLength.values()].flat()];
   const assets = await compileAssets(loaded.root, routes);
   // Host policies compile after assets so a policy can see what a route serves
@@ -195,7 +211,14 @@ export async function createRuntime(project        , rawOptions
       try {
         const parsed = parseTarget(target);
         const match = matchRoute(compiled, parsed);
-        if (!match) throw new HttpError(404, 'Not found');
+        if (!match) {
+          // site.notFound: answer an unmatched GET/HEAD with the configured page and status 404.
+          if (notFoundPage && (method === 'GET' || method === 'HEAD')) {
+            const page = await (this           ).handle({ target: '/404.html', method, headers, headerCounts, trace: {}, origin, ...(client ? { client } : {}) });
+            return { ...page, status: 404 };
+          }
+          throw new HttpError(404, 'Not found');
+        }
         const { route, path } = match;
         // Configured pattern only; never the request path, query or parameter values.
         trace.route = route.pattern;

package/dist/server.js

@@ -2,8 +2,9 @@ import http from 'node:http';
                                                  
                                             
 import { randomUUID, createHash } from 'node:crypto';
-import { readdir, lstat } from 'node:fs/promises';
-import { join } from 'node:path';
+import { readdir, lstat, mkdir, mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join, resolve as resolvePath } from 'node:path';
 import { createRuntime } from './runtime.js';
                                                                                     
 import { createJsonLogger } from './logging.js';
@@ -19,6 +20,12 @@ import { compileTrustedProxies, resolveClient } from './client-address.js';
                                                                                                                               
                                                                         
                                                                                                                                                             
+                                                                                                     
+                                                                                                 
+                                                                                                       
+                               
+                                                                                                                                                
+                                    
  
                          
                                                                                                             
@@ -78,7 +85,23 @@ function originForm(target        )         {
   if (rest === undefined) return target;
   return rest === '' || rest.startsWith('?') ? '/' + rest : rest;
 }
-export async function startServer({ project = '.', host = '127.0.0.1', port = 3000, watch = false,
+/** Starts the server. `port: 0` picks a free port, so this is also the in-process helper for tests:
+ * `startServer({ project, port: 0, local: true, isolateData: true })`. */
+export async function startServer(options                = {})                  {
+  const { dataDir, isolateData, ...rest } = options;
+  if (dataDir === undefined && !isolateData) return startServerCore(rest);
+  assert(dataDir === undefined || !isolateData, 'Use dataDir or isolateData, not both');
+  assert(dataDir === undefined || (typeof dataDir === 'string' && dataDir !== '' && !dataDir.includes('\0')), 'Data directory must be a path');
+  const owned = dataDir === undefined;
+  const dir = owned ? await mkdtemp(join(tmpdir(), 'urlcode-data-')) : resolvePath(dataDir);
+  try {
+    if (!owned) await mkdir(dir, { recursive: true });
+    const app = await startServerCore({ ...rest, environment: { ...(rest.environment ?? process.env), URLCODE_DATA_DIR: dir }, grantDataDir: true });
+    if (!owned) return app;
+    return { ...app, close: async () => { try { await app.close(); } finally { await rm(dir, { recursive: true, force: true }); } } };
+  } catch (error) { if (owned) await rm(dir, { recursive: true, force: true }); throw error; }
+}
+async function startServerCore({ project = '.', host = '127.0.0.1', port = 3000, watch = false,
   local = false, log = createJsonLogger(),
   maxBodyBytes = 1048576, maxInFlightRequests = 64, maxInFlightHealthRequests = 16,
   requestLog = 'minimal', trustRequestId = false, origin, trustedProxies = [],

package/dist/tooling.js

@@ -68,7 +68,7 @@ export async function previewImport(options                    ) {return importR
 export async function previewExport(project       ,format                  ,acceptProviderDifferences=false) {const loaded=await loadDocument(project);const {includes:_includes,...document}=loaded.document;return exportRoutes({format,document:{...document,routes:loaded.routes},acceptProviderDifferences});}
                                       
                                                               
-                                                                                                                                                                                                                           
+                                                                                                                                                                                                                                                 
                                                                                                   
  
 /** Reports registered extension contracts against the project's declarations. Never activates an extension. */
@@ -85,6 +85,7 @@ export async function describeExtensions(project       ,registrations
   credentialHeaders:Array.isArray(registration.credentialHeaders)?registration.credentialHeaders.map(String):[],
   schema:structuredClone(registration.schema??{}),policySchema:registration.policySchema?structuredClone(registration.policySchema):null,
   hooks:structuredClone(registration.hooks??[])            ,
+  authoring:registration.authoring?structuredClone(registration.authoring)          :null,
   declared:Object.hasOwn(loaded.document.extensions??{},registration.name),revisionPinned:registration.projectSha256===projectSha256,
   mounts:mountsOf(registration.name),policyRoutes:policyRoutesOf(registration.name),
  }));

package/dist/types/agent-context.d.ts

@@ -0,0 +1,44 @@
+export declare function listSkills(): {
+    name: "urlcode";
+    description: "Author URLCode projects declaratively, retrieve only the required contract, and validate the result.";
+}[];
+export declare function getSkill(name: string): Promise<{
+    name: "urlcode";
+    description: "Author URLCode projects declaratively, retrieve only the required contract, and validate the result.";
+    content: string;
+}>;
+/** Deterministic lexical search over a deliberately small, agent-facing corpus. */
+export declare function searchDocs(query: string): Promise<{
+    query: string;
+    results: {
+        id: "security" | "authoring" | "llms" | "yaml-reference" | "tooling";
+        title: "URLCode agent index" | "AI authoring" | "YAML reference" | "Tooling and local MCP" | "Function security";
+        summary: "Compact map of the framework, its declarative primitives and the minimum reference to load next." | "Declarative-first authoring workflow, retrieval order and framework constraints." | "Generated inventory of accepted URLCode YAML fields." | "Bounded local project inspection, validation and MCP tool behavior." | "Trusted versus sandboxed function behavior, bindings and operator grants.";
+        matched: string[];
+        excerpt: string;
+    }[];
+}>;
+/** Returns the two smallest high-value files of a fixed packaged example. */
+export declare function getExample(name: string): Promise<{
+    metadata: import("./examples.ts").ExampleSummary;
+    content: Record<string, string>;
+}>;
+/** Validates only supplied YAML syntax and the versioned document schema. It never resolves includes or reads source files. */
+export declare function validateYaml(text: string): {
+    valid: boolean;
+    scope: string;
+    version: "1";
+    routeCount: number;
+    error?: never;
+} | {
+    valid: boolean;
+    scope: string;
+    error: string;
+    version?: never;
+    routeCount?: never;
+};
+/** Short deterministic remediation for common validator output; no model call or project read occurs. */
+export declare function explainError(error: string): {
+    guidance: string;
+    nextTools: string[];
+};

package/dist/types/authoring.d.ts

@@ -5,6 +5,8 @@ export interface InitOptions {
      * initialization stays the default: a project whose runtime is managed elsewhere gets no manifest at all.
      */
     manifest?: DependencySet | undefined;
+    /** `default` (function, middleware, redirect) or `page`: urlcode.yaml, public/index.html, a README and fixtures only. */
+    template?: 'default' | 'page' | undefined;
 }
-export declare function initProject(destination: string, { manifest }?: InitOptions): Promise<string>;
+export declare function initProject(destination: string, { manifest, template }?: InitOptions): Promise<string>;
 export declare function addRedirect(project: string, destination: string, alias?: string | undefined): Promise<string>;

package/dist/types/body-schema.d.ts

@@ -0,0 +1,58 @@
+/**
+ * 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 interface BodySchema {
+    type?: 'object' | 'array' | 'string' | 'integer' | 'number' | 'boolean' | 'null';
+    properties?: Record<string, BodySchema>;
+    required?: string[];
+    additionalProperties?: boolean;
+    items?: BodySchema;
+    enum?: (string | number | boolean | null)[];
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+    format?: 'uuid';
+    minimum?: number;
+    maximum?: number;
+    minItems?: number;
+    maxItems?: number;
+}
+export declare const uuidFormat: RegExp;
+/** Rejects, at load time, any schema outside the supported subset or its limits. */
+export declare function assertBodySchema(schema: unknown): asserts schema is BodySchema;
+/**
+ * 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.
+ */
+export interface BodySchemaIssue {
+    pointer: string;
+    keyword: string;
+    message: string;
+    expected?: string | number | (string | number | boolean | null)[];
+    property?: string;
+}
+/** Structured failures for `value`; `checkBodySchema` renders the same list as text. */
+export declare function bodySchemaIssues(schema: BodySchema, value: unknown, path?: string, issues?: BodySchemaIssue[], max?: number): BodySchemaIssue[];
+/**
+ * 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 declare function checkBodySchema(schema: BodySchema, value: unknown): string[];
+/** The plain-text line for an issue: array positions print as `[]` appended to the path, root as `/`. */
+export declare const bodySchemaLine: (issue: BodySchemaIssue) => string;
+/**
+ * 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 declare function prefersJson(accept: string | null | undefined): boolean;
+/** Renders the JSON answer: never more than `maxIssueBytes`, dropping trailing issues and saying so. */
+export declare function bodySchemaJson(issues: BodySchemaIssue[]): string;