@jimhoyd/urlcode 0.3.0 → 0.4.0-alpha.1

package/dist/config.js

@@ -5,7 +5,7 @@ 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';
-                                                                               
+                                                                                                                                      
 
 /** What config-worker.ts posts back: the loaded document, or the ConfigError message. */
                                                                                
@@ -53,7 +53,41 @@ export function validateDocument(data         )                  {
     const e = validate.errors [0] ;
     throw new ConfigError(`Invalid configuration at ${e.instancePath || '/'} (${e.keyword})`);
   }
-  return data                   ; // trust boundary: the schema just admitted it
+  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);
+  return document;
+}
+/** 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.
+function modulePath(pattern        , kind                           , file        )         {
+  const relativePosix = !isAbsolute(file) && !/^(?:[A-Za-z]:|[\\/])/.test(file);
+  const segments = file.split(/[\\/]/);
+  assert(relativePosix && segments.every(s => s !== '..') && ['.mjs', '.js'].includes(extname(file)) && !file.endsWith('/') && !file.endsWith('\\'),
+    `${pattern}: ${kind} short form must be a project-relative .mjs or .js path without .. segments`);
+  return file;
+}
+/**
+ * Expands the YAML short forms into the canonical long form. `function: functions/x.mjs`
+ * becomes `{source, args}` with an argument per `{param}` in the path, declaring any
+ * parameter the route does not declare itself; a string middleware entry becomes `{source}`.
+ * Everything downstream (routes, audit, the compiled table) sees only the long form.
+ */
+export function normalizeRoute(pattern        , route                                   )              {
+  const authored = route                       ;
+  if (typeof authored.function !== 'string' && !authored.middleware?.some(entry => typeof entry === 'string')) return route               ;
+  const result              = { ...(route               ) };
+  if (authored.middleware) result.middleware = authored.middleware.map((entry)                   => typeof entry === 'string' ? { source: modulePath(pattern, 'middleware', entry) } : entry);
+  if (typeof authored.function === 'string') {
+    const source = modulePath(pattern, 'function', authored.function);
+    const names = pattern.split('/').flatMap(part => { const match = /^\{([A-Za-z_][A-Za-z0-9_]*)\}$/.exec(part); return match ? [match[1] ] : []; });
+    const declared = authored.parameters ?? [];
+    const parameters = [...declared, ...names.filter(name => !declared.some(p => p.in === 'path' && p.name === name)).map(name => ({ name, in: 'path'         , required: true, schema: { ...SHORT_FORM_PATH_SCHEMA } }))];
+    const expanded                 = { source, args: Object.fromEntries(names.map(name => [name, { from: 'path'         , name }])) };
+    if (parameters.length) result.parameters = parameters;
+    result.function = expanded;
+  }
+  return result;
 }
 export async function safeFile(root        , file         )                  {
   root = await realpath(root);
@@ -64,7 +98,7 @@ export async function safeFile(root        , file         )                  {
   assert((await stat(actual)).isFile(), 'Reference must point to a file');
   return actual;
 }
-export const MAX_PROJECT_CONFIG_BYTES = 64 * 1024 * 1024;
+const MAX_PROJECT_CONFIG_BYTES = 64 * 1024 * 1024;
 async function readConfig(file        , budget                       )                   {
   const handle = await open(file, 'r');
   try {
@@ -111,12 +145,31 @@ export async function loadDocument(project        , {timeoutMs=10000}
     });
   } finally { try { await worker?.terminate(); } finally { activeLoads--; } }
 }
+/**
+ * Expands the route-level `auth` short form into the canonical `policies.extensions.auth` requirement so every
+ * downstream consumer (compiler, routes, audit, explain, revision hash) sees one form. `auth: {required: false}`
+ * documents intent and emits nothing. Refuses routes that use both forms or lack an `extensions.auth` declaration.
+ */
+export function normalizeRouteAuth(document                                     , routes                             )       {
+  for (const [pattern, route] of Object.entries(routes)) {
+    if (route.auth === undefined) continue;
+    assert(document.extensions?.auth !== undefined, `Route ${pattern} declares auth but the project declares no extensions.auth`);
+    const extensions = route.policies?.extensions;
+    assert(extensions !== false, `Route ${pattern} declares auth alongside policies.extensions: false`);
+    assert(!(extensions && Object.hasOwn(extensions, 'auth')), `Route ${pattern} declares both auth and policies.extensions.auth; use one form`);
+    const { required = true, ...requirement } = route.auth === true ? {} : route.auth;
+    delete route.auth;
+    if (!required) continue;
+    route.policies = { ...route.policies, extensions: { ...extensions, auth: requirement } };
+  }
+}
 export async function loadDocumentInWorker(project        )                          {
   const budget={remaining:MAX_PROJECT_CONFIG_BYTES};
   const root = await realpath(project);
   const file = await safeFile(root, 'urlcode.yaml');
   const document = validateDocument(await readConfig(file, budget));
   const routes                              = Object.assign(Object.create(null)                               , document.routes);
+  const extensions = Object.assign(Object.create(null),document.extensions??{})                                              ;
   const files = [file];
   let routeCount=Object.keys(routes).length;
   for (const include of document.includes || []) {
@@ -127,15 +180,18 @@ export async function loadDocumentInWorker(project        )
     assert(!part.includes?.length, 'Nested includes are unsupported');
     assert(part.dynamicLinks===undefined, 'dynamicLinks may only be set in the entry urlcode.yaml');
     assert(part.site===undefined, 'site 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');
       routes[pattern] = route;
       assert(++routeCount <= 100000, 'Maximum 100000 routes per project');
     }
   }
+  if(Object.keys(extensions).length)document.extensions=extensions;
+  normalizeRouteAuth(document, routes);
   assert(Object.keys(routes).length <= 100000, 'Maximum 100000 routes per project');
   assert(document.dynamicLinks===true || !Object.values(routes).some(route=>route.link), 'Link routes require dynamicLinks: true in urlcode.yaml');
-  return { root, document, routes, files, version: createHash('sha256').update(JSON.stringify(document.site ? {...(document.dynamicLinks===true?{routes,dynamicLinks:true}:{routes}), site:document.site} : document.dynamicLinks===true?{routes,dynamicLinks:true}:routes)).digest('hex').slice(0, 16) };
+  return { root, document, routes, files, version: createHash('sha256').update(JSON.stringify(document.extensions?{routes,extensions:document.extensions,policies:document.policies,profiles:document.profiles,site:document.site,dynamicLinks:document.dynamicLinks}: document.site ? {...(document.dynamicLinks===true?{routes,dynamicLinks:true}:{routes}), site:document.site} : document.dynamicLinks===true?{routes,dynamicLinks:true}:routes)).digest('hex').slice(0, 16) };
 }
 export async function loadBindings(root        , local = false, environment                                     = process.env)                                              {
   const vars                         = {};

package/dist/context.js

@@ -0,0 +1,156 @@
+import {readdir,readFile} from 'node:fs/promises';
+import {relative} from 'node:path';
+import {stringify} from 'yaml';
+import {loadDocument} from './config.js';
+import {applySite} from './site.js';
+import {prepareFunctionSnapshot,requestedPermissions} from './policy.js';
+import {compileRoutes} from './router.js';
+import {compilePolicies,closePolicies,effectivePolicies,registry} from './policies.js';
+import {capabilityTargets,getCapabilities,normalizeCapabilityTarget,routeCapabilities} from './capabilities.js';
+                                                                       
+import {loadOperatorHost} from './operator-host.js';
+                                                                      
+
+                                 
+                                                           
+                          
+                                                                                                                               
+                            
+                                                                                                    
+                          
+                                                                                                     
+                               
+ 
+                                                                                             
+                                 
+                           
+          
+                                                                                
+                                                           
+                                                                              
+                                                                    
+                                             
+   
+                                                         
+                                                                              
+                                                                                                                       
+                                 
+                           
+ 
+/** Characters divided by four, rounded up: an estimate, not a tokenizer. */
+export function estimateTokens(text       )        {return Math.ceil(text.length/4);}
+export function renderContext(context               )        {return stringify(context,{lineWidth:0,aliasDuplicateObjects:false});}
+const handlerNames=['redirect','respond','page','static','download','function','link','proxy','conditional','extension']         ;
+const policyNames=Object.keys(registry).sort()                ;
+// Fixed for every project: what generation must not attempt, whatever the documentation says.
+const constraints                                                  ={
+ guestNetwork:{value:false,note:'Functions and middleware run in a WASM sandbox without fetch or sockets; outbound calls are proxy or signals routes under operator grants'},
+ nodeApis:{value:false,note:'No Node built-ins, process, filesystem or npm packages in guest code; relative ES-module imports only'},
+ regexRoutes:{value:false,note:'Paths are whole segments: exact literals or {param} placeholders declared as required string parameters'},
+ oneHandlerPerRoute:{value:true,note:'Exactly one of redirect, respond, page, static, download, function, link, proxy, conditional or extension; middleware wraps it'},
+ 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'},
+ 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];
+const sorted=(values                 )=>[...new Set(values)].sort();
+async function packageVersion()                 {return (JSON.parse(await readFile(new URL('../package.json',import.meta.url),'utf8'))                    ).version;}
+/** Same loader and semantic compiler as inspectProject: no binding reads, no guest execution, no network. */
+async function compile(project       ) {
+ const loaded=await loadDocument(project);await applySite(loaded,{});
+ const snapshot=await prepareFunctionSnapshot(loaded),bindings                      =Object.create(null);
+ for(const route of Object.values(loaded.routes)) {for(const ref of Object.values(route.env||{}))if(ref.env)bindings[ref.env]='validation-only';for(const ref of Object.values(route.secrets||{}))bindings[ref.secret]='validation-only';}
+ const compiled=await compileRoutes(loaded,bindings,requestedPermissions(loaded,snapshot),snapshot.projectSha256),routes=routesOf(compiled);
+ const shared             ={target:'node',routes:routes.length,log:()=>{}};
+ try {for(const route of routes)await compilePolicies(loaded.document,route,{route,shared,target:'node',root:loaded.root});}finally{await closePolicies(shared);}
+ return {loaded,compiled,routes};
+}
+function handlerOf(route              )        {return handlerNames.find(name=>route[name])??'none';}
+/** Derived only from the compiled project and the capability catalog, never from prose. Key order is fixed. */
+export async function buildContext(project       ,options               ={})                         {
+ const budget=options.budget;
+ if(budget!==undefined&&(!Number.isSafeInteger(budget)||budget<1))throw new Error('Invalid context budget');
+ const selected                   =options.target===undefined?[...capabilityTargets]:[normalizeCapabilityTarget(options.target)];
+ const host=await loadOperatorHost(options.hostFile,project);
+ try {
+  const {loaded,compiled,routes}=await compile(project),document=loaded.document;
+  const handlers                      ={},policyCounts                      ={},used=new Set                ();
+  for(const name of handlerNames)handlers[name]=0;
+  for(const name of policyNames)policyCounts[name]=0;
+  if(Object.keys(document.extensions??{}).length)used.add('extension');
+  if(document.dynamicLinks)used.add('dynamicLinks');
+  for(const route of routes) {
+   handlers[handlerOf(route)]=(handlers[handlerOf(route)]??0)+1;
+   for(const capability of routeCapabilities(route,document))used.add(capability);
+   const effective=effectivePolicies(document,route);
+   for(const name of policyNames)if(effective[name])policyCounts[name] ++;
+  }
+  for(const name of handlerNames)if(!handlers[name])delete handlers[name];
+  for(const name of policyNames)if(!policyCounts[name])delete policyCounts[name];
+  const declared=Object.values(loaded.routes),env=new Set        (),secrets=new Set        (),functions=new Set        (),middleware=new Set        ();
+  for(const route of declared) {
+   for(const ref of Object.values(route.env??{}))if(ref.env)env.add(ref.env);
+   for(const ref of Object.values(route.secrets??{}))secrets.add(ref.secret);
+   if(route.function)functions.add(route.function.source);
+   for(const item of route.middleware??[])middleware.add(item.source);
+  }
+  const topLevel=effectivePolicies(document,undefined);
+  const catalog=getCapabilities();
+  const targets                                       ={};
+  for(const target of selected) {
+   const entry={deployment:catalog.targets.find(item=>item.target===target) .deployment,supported:[]            ,conditional:[]            ,refused:[]            ,unknown:[]            };
+   for(const row of catalog.capabilities) {
+    if(!used.has(row.capability))continue;
+    const support=row.targets[target]?.support??'unknown';
+    (support==='refused'?entry.refused:support==='conditional'?entry.conditional:support==='unknown'?entry.unknown:entry.supported).push(row.capability);
+   }
+   targets[target]=entry;
+  }
+  const flag=options.projectFlag??project;
+  const context               ={
+   urlcode:await packageVersion(),schema:'1',
+   project:{
+    entry:'urlcode.yaml',routes:compiled.count,handlers,extensions:sorted(Object.keys(document.extensions??{})),
+    policies:{project:policyNames.filter(name=>topLevel[name]),routes:policyCounts},
+    bindings:{env:sorted(env),secrets:sorted(secrets)},dynamicLinks:document.dynamicLinks===true,site:sorted(Object.keys(document.site??{})),
+    files:{includes:loaded.files.slice(1).map(file=>relative(loaded.root,file).split('\\').join('/')),functions:sorted(functions),middleware:sorted(middleware)},
+    ...(options.hostFile===undefined?{}:{host:{extensions:sorted((host.extensions??[]).map(item=>item.name)),plugins:(host.plugins??[]).length}}),
+   },
+   routes:routes.map(route=>({path:route.pattern,methods:route.methods,handler:handlerOf(route)})).sort((a,b)=>a.path<b.path?-1:a.path>b.path?1:0),
+   constraints:{...constraints},
+   targets,
+   commands:{
+    validate:`urlcode validate --local --project ${flag}`,
+    test:`urlcode test --project ${flag}`,
+    audit:`urlcode audit --project ${flag} --expect-routes ${compiled.count}`,
+    routes:`urlcode routes --project ${flag}`,
+    capabilities:`urlcode capabilities${options.target===undefined?'':` --target ${selected[0]}`}`,
+   },
+  };
+  return budget===undefined?context:fitBudget(context,budget);
+ } finally {await host.close?.();}
+}
+// Sections leave in this order; each step is a fixed transformation so two runs agree.
+const drops                                                  =[
+ ['routes',context=>{delete context.routes;}],
+ ['targets',context=>{delete context.targets;}],
+ ['constraintNotes',context=>{for(const [key,item] of Object.entries(context.constraints))context.constraints[key]=typeof item==='object'?item.value:item;}],
+ ['files',context=>{delete context.project.files;}],
+ ['commands',context=>{delete context.commands;}],
+ ['summary',context=>{context.project={entry:context.project.entry,routes:context.project.routes,handlers:context.project.handlers,extensions:[],policies:{project:[],routes:{}},bindings:{env:[],secrets:[]},dynamicLinks:context.project.dynamicLinks,site:[]};}],
+];
+function fitBudget(context               ,budget       )                {
+ const omitted                 =[];
+ const fits=()=>estimateTokens(renderContext(omitted.length?{...context,omitted}:context))<=budget;
+ for(const [section,drop] of drops) {if(fits())break;drop(context);omitted.push(section);}
+ 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. */
+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);
+}

package/dist/ecosystem-cli.js

@@ -0,0 +1,88 @@
+import {basename} from 'node:path';
+import {assert} from './errors.js';
+import {readConversionInput} from './interchange-cli.js';
+
+                   
+                                                                                                                
+                                                                                 
+                                                                                                                                                             
+ 
+export async function runEcosystemCommand(command       ,args         ,options        ,print                         )               {
+  if(command==='recipes'||command==='recipe'){
+    const {listRecipes,showRecipe,searchRecipes,addRecipe}=await import('./recipes.js');
+    const [operation='list',name]=args;
+    assert(args.length<=2,'Unexpected recipe arguments');
+    if(operation==='list'){assert(name===undefined,'Unexpected recipe name');const recipes=await listRecipes();print(options.json?recipes:formatCatalog(recipes));}
+    else if(operation==='search'){assert(name,'Provide search text');const found=await searchRecipes(name);print(options.json?found:formatSearch(found.query,found.results));}
+    else if(operation==='show'){assert(name,'Provide a recipe name');const recipe=await showRecipe(name);print(options.json?recipe:formatMetadata(recipe)+Object.entries(recipe.content).map(([file,text])=>`\n--- ${file}\n${text}`).join(''));}
+    else if(operation==='add'){assert(name && options.out,'Provide a recipe name and --out new-directory');print(await addRecipe(name,options.out,{dryRun:options['dry-run']}));}
+    else assert(false,'Use recipes list, search, show or add');
+  }else if(command==='examples'||command==='example'){
+    const {listExamples,searchExamples}=await import('./examples.js');
+    const [operation='list',text]=args;
+    assert(args.length<=2,'Unexpected example arguments');
+    if(operation==='list'){assert(text===undefined,'Unexpected example name');const examples=await listExamples();print(options.json?examples:formatCatalog(examples));}
+    else if(operation==='search'){
+      assert(text,'Provide search text');const found=await searchExamples(text);
+      if(options.json)print(found);
+      else{
+        const lines=[formatSearch(found.query,found.results)];
+        if(found.best)lines.push(`\nSmallest runnable match: examples/${found.best.id} (${found.best.routes??0} routes)`+(found.best.route?`, route ${found.best.route.path} in ${found.best.route.file}`:''));
+        for(const result of found.results)for(const route of result.matchedRoutes.slice(0,5))lines.push(`  ${result.id} ${route.path.padEnd(24)} ${route.file}  ${route.tags.join(' ')}`);
+        print(lines.join('\n')+'\n');
+      }
+    }
+    else assert(false,'Use examples list or search');
+  }else if(command==='build-typescript'){
+    assert(args.length===0 && options.out,'Provide --out new-directory');
+    const {buildTypeScriptProject}=await import('./typescript-authoring.js');
+    print(await buildTypeScriptProject(options.project,options.out,{dryRun:options['dry-run']}));
+  }else if(command==='bulk-import'){
+    const format=options.format??args[0],input=options.input??args[options.format?0:1];
+    assert(args.length<=(options.format?1:2),'Unexpected bulk import arguments');
+    assert(format==='csv'||format==='json'||format==='yaml','Use bulk-import csv|json|yaml <file> --out new-directory');
+    assert(input && options.out,'Provide an input file and --out new-directory');
+    const {importBulkProject}=await import('./bulk.js');
+    const report=await importBulkProject(await readConversionInput(input),format,options.out,{dryRun:options['dry-run'],source:basename(input)});
+    print(report);if(!report.ok)process.exitCode=1;
+  }else if(command==='verify-provider'){
+    assert(args.length===0,'Unexpected provider verification arguments');
+    const target=options.target;
+    assert(target==='self-hosted'||target==='aws'||target==='vercel'||target==='cloudflare','Provide --target self-hosted|aws|vercel|cloudflare');
+    assert(options.origin,'Provide --origin https://owned-fixture.example');
+    assert(options['timeout-ms']===undefined || /^\d{1,5}$/.test(options['timeout-ms']),'Invalid --timeout-ms');
+    const {verifyProviderDeployment}=await import('./provider-verification.js');
+    const report=await verifyProviderDeployment(target,options.origin,{
+      ...(options['timeout-ms']===undefined?{}:{timeoutMs:Number(options['timeout-ms'])}),
+      ...(options.release===undefined?{}:{release:options.release}),
+      ...(options['git-commit']===undefined?{}:{gitCommit:options['git-commit']}),
+    });
+    print(report);if(!report.pass)process.exitCode=1;
+  }else if(command==='mcp'){
+    assert(args.length===0,'Unexpected MCP arguments');
+    const {serveMcp}=await import('./mcp.js');
+    // The flags reach the server from parsed argv only; no tool argument or environment variable can set them.
+    await serveMcp({project:options.project,...(options.origin===undefined?{}:{origin:options.origin}),...(options['allow-authoring']?{allowAuthoring:true}:{}),...(options['host-file']===undefined?{}:{hostFile:options['host-file']})});
+  }else assert(false,'Unknown ecosystem command');
+}
+
+                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        
+function formatCatalog(entries          )        {
+  return entries.map(entry=>`${entry.id.padEnd(24)} ${entry.complexity.padEnd(13)} ${String(entry.routes??'-').padStart(2)} routes  ${entry.description}`).join('\n')+'\n';
+}
+function formatSearch(query       ,results                                            )        {
+  if(!results.length)return `No match for "${query}"\n`;
+  return results.map(entry=>`${entry.id.padEnd(24)} score ${String(entry.score).padStart(2)}  ${entry.description}\n${''.padEnd(24)} tags: ${entry.tags.join(' ')}`).join('\n')+'\n';
+}
+/** Metadata first, so a reader sees what a recipe needs before its files scroll past. */
+function formatMetadata(entry        )        {
+  const lines=[`${entry.id}: ${entry.description}`,`complexity: ${entry.complexity}   routes: ${entry.routes??'-'}   runnable: ${entry.runnable!==false}`,`tags: ${entry.tags.join(' ')}`];
+  if(entry.capabilities?.length)lines.push(`capabilities: ${entry.capabilities.join(' ')}`);
+  if(entry.targets)lines.push(`targets: ${Object.entries(entry.targets).map(([target,verdict])=>`${target}=${verdict}`).join(' ')}`);
+  for(const [title,items] of [['services',entry.services],['grants',entry.grants]]         )if(items?.length)lines.push(`${title}:`,...items.map(item=>`  - ${'kind' in item?item.kind:item.name}: ${item.description}`));
+  if(entry.inputs?.length)lines.push('inputs:',...entry.inputs.map(input=>`  - ${input.name} (${input.file}): ${input.description}`));
+  if(entry.tests)lines.push('tests:',...(entry.tests.fixtures?[`  fixtures: ${entry.tests.fixtures}`]:[]),...entry.tests.commands.map(command=>`  $ ${command}`));
+  if(entry.behavior?.length)lines.push('behavior:',...entry.behavior.map(line=>`  - ${line}`));
+  lines.push(`files: ${entry.files.join(' ')}`);
+  return lines.join('\n')+'\n';
+}

package/dist/egress.js

@@ -0,0 +1,98 @@
+import { lookup } from 'node:dns/promises';
+import { request } from 'node:https';
+import { isIP } from 'node:net';
+
+export const EGRESS_DNS_LIMIT=64;
+let unresolvedDns=0;
+                                                                                                                                        
+                                                                                                
+                                                                                                                                                                                 
+                                                                                       
+export class EgressError extends Error {          code                ; constructor(code                ) { super(`Egress ${code}`); this.code=code; } }
+/** Conservative public-unicast filter. IPv4-mapped IPv6 and transition mechanisms are denied. */
+export function isPublicAddress(address        )          {
+  if (isIP(address)===4) {
+    const [a=0,b=0,c=0] = address.split('.').map(Number);
+    return !(a===0 || a===10 || a===127 || a>=224 || (a===100&&b>=64&&b<=127) || (a===169&&b===254) || (a===172&&b>=16&&b<=31) || (a===192&&(b===168 || b===0 || (b===88&&c===99) || (b===0&&c===2))) || (a===198&&(b===18||b===19|| (b===51&&c===100))) || (a===203&&b===0&&c===113));
+  }
+  if (isIP(address)!==6) return false;
+  // Only ordinary global unicast; reject documentation and special 2001 allocations.
+  if(address.includes('.')) return false;
+  const first = parseInt(address.split(':')[0] ,16);
+  return first>=0x2000 && first<=0x3fff && !/^2001:/i.test(address) && !/^2002:/i.test(address) && !/^3fff:/i.test(address);
+}
+export function egressUrl(value        )      {
+  if(typeof value!=='string'||value.length>8192||/[\\\x00-\x20\x7f]/.test(value)) throw new EgressError('denied');
+  let url     ; try { url=new URL(value); } catch { throw new EgressError('denied'); }
+  if(url.protocol!=='https:' || url.username || url.password || url.hash || !url.hostname || url.hostname.endsWith('.') || url.hostname.includes('%')) throw new EgressError('denied');
+  return url;
+}
+const forbidden = new Set(['host','connection','keep-alive','proxy-authenticate','proxy-authorization','te','trailer','transfer-encoding','upgrade','content-length']);
+export function safeEgressHeaders(headers                       , maxBytes=16384)                        {
+  if(!headers||typeof headers!=='object'||Array.isArray(headers)) throw new EgressError('denied');
+  const result                        = Object.create(null); let bytes=0;
+  for(const [name,value] of Object.entries(headers)) {
+    const key=name.toLowerCase();
+    if(typeof value!=='string'||!/^[!#$%&'*+.^_`|~0-9a-z-]+$/.test(key) || forbidden.has(key) || /[\x00-\x1f\x7f]/.test(value)) throw new EgressError('denied');
+    bytes+=Buffer.byteLength(key)+Buffer.byteLength(value)+4;
+    if(bytes>maxBytes) throw new EgressError('limit'); result[key]=value;
+  }
+  return result;
+}
+/** Operator-owned transport. Never exposed to guests. Each request has its own nonpooled socket. */
+                                                                                                                                        
+export class EgressClient {
+           #dependencies                   ;          #origins             ;          #options                                              ;
+           #active = new Set                 ();          #pending = new Set                  (); #closed=false; #resolving=0;
+  constructor(options              , dependencies                   ={}) {
+    this.#dependencies=dependencies;
+    if(!Array.isArray(options.grantOrigins)||options.grantOrigins.length>64) throw new EgressError('denied');
+    this.#origins=new Set(options.grantOrigins.map(origin=> {const u=egressUrl(origin); if(u.pathname!=='/'||u.search) throw new EgressError('denied'); return u.origin;}));
+    this.#options={timeoutMs:5000,maxRequestBytes:1048576,maxResponseBytes:1048576,maxHeaderBytes:16384,concurrency:16,...options};
+    for(const value of Object.values(this.#options)) if(typeof value==='number'&&(!Number.isSafeInteger(value)||value<1)) throw new EgressError('denied');
+  }
+  request(input              )                         {
+    if(this.#closed) return Promise.reject(new EgressError('closed'));
+    if(this.#active.size>=this.#options.concurrency||this.#resolving>=this.#options.concurrency) return Promise.reject(new EgressError('busy'));
+    const controller=new AbortController(); this.#active.add(controller);
+    const pending=this.#request(input,controller).finally(()=>{this.#active.delete(controller);this.#pending.delete(pending);});
+    this.#pending.add(pending); return pending;
+  }
+  async close()               {this.#closed=true; for(const controller of this.#active) controller.abort(); await Promise.allSettled([...this.#pending]);}
+  async #resolve(hostname       )                                           {
+    if(this.#resolving>=this.#options.concurrency||unresolvedDns>=EGRESS_DNS_LIMIT) throw new EgressError('busy');
+    this.#resolving++;unresolvedDns++;
+    try {return await (this.#dependencies.resolve?this.#dependencies.resolve(hostname):lookup(hostname,{all:true,verbatim:true}));}
+    finally {this.#resolving--;unresolvedDns--;}
+  }
+  async #request(input              ,controller                )                         {
+    const opts=this.#options, url=egressUrl(input.url);
+    if(!this.#origins.has(url.origin)||! /^[A-Z]+$/.test(input.method)) throw new EgressError('denied');
+    if((input.body?.byteLength||0)>opts.maxRequestBytes) throw new EgressError('limit');
+    const headers=safeEgressHeaders(input.headers||{},opts.maxHeaderBytes);
+    let timedOut=false; const timer=setTimeout(()=>{timedOut=true;controller.abort();},opts.timeoutMs);
+    const abort=()=>controller.abort(); input.signal?.addEventListener('abort',abort,{once:true}); if(input.signal?.aborted) controller.abort();
+    try {
+      return await new Promise                ((resolve,reject)=>{
+        const fail=()=>reject(new EgressError(timedOut?'timeout':'aborted'));
+        controller.signal.addEventListener('abort',fail,{once:true}); if(controller.signal.aborted) {fail();return;}
+        void (async()=> {
+          const hostname=url.hostname.replace(/^\[|\]$/g,'');
+          const answers=isIP(hostname)?[{address:hostname,family:isIP(hostname)}]:await this.#resolve(hostname);
+          if(controller.signal.aborted) return;
+          if(!answers.length||answers.some(answer=>!isPublicAddress(answer.address))) throw new EgressError('denied');
+          const pinned=answers[0] ;
+          const req=(this.#dependencies.request||request)(url,{method:input.method,headers,agent:false,maxHeaderSize:opts.maxHeaderBytes,signal:controller.signal,
+            lookup:(_host,options,callback)=>options.all?callback(null,[pinned]):callback(null,pinned.address,pinned.family)},res=>{
+            const chunks         =[]; let size=0;
+            res.on('data',(chunk       )=>{size+=chunk.length; if(size>opts.maxResponseBytes) {reject(new EgressError('limit'));req.destroy();} else chunks.push(chunk);});
+            res.on('error',()=>reject(new EgressError('upstream')));
+            res.on('end',()=>{const result                      =Object.create(null); for(const [name,value] of Object.entries(res.headers)) if(typeof value==='string') result[name]=value; resolve({status:res.statusCode||502,headers:result,body:Buffer.concat(chunks)});});
+          });
+          req.on('error',()=>reject(new EgressError(controller.signal.aborted?(timedOut?'timeout':'aborted'):'upstream')));
+          req.end(input.body);
+        })().catch(error=>reject(error instanceof EgressError?error:new EgressError('upstream')));
+      });
+    } finally {clearTimeout(timer); input.signal?.removeEventListener('abort',abort);}
+  }
+}

package/dist/examples.js

@@ -0,0 +1,92 @@
+import {readFile} from 'node:fs/promises';
+import {basename} from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {loadDocument,parseYaml} from './config.js';
+import {applySite} from './site.js';
+import {routeCapabilities} from './capabilities.js';
+import {readMetadata,searchMetadata,searchTerms} from './catalog.js';
+                                                            
+import {assert} from './errors.js';
+                                            
+
+/** example.yaml, the same schema as recipe.yaml; `name` repeats `id`. */
+                                                                        
+/** One cookbook route in the generated tag index (examples/cookbook/route-index.json). */
+                                                                                                                                        
+                                                                                                      
+                                      
+                               
+                                                                                                                        
+                                                          
+                                                                                                     
+ 
+// 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','live-links','monitoring','prerender','provider-conformance','tunnel','vercel']         ;
+export const routeIndexFile='route-index.json';
+const examplesRoot=fileURLToPath(new URL('../examples/',import.meta.url));
+const root=(name        )=>examplesRoot+name+'/';
+async function metadata(name        )                          {const value=await readMetadata(root(name),name,'example.yaml');return {name,...value};}
+export async function listExamples()                            {
+  const result                  =[];
+  for(const name of exampleNames)result.push(await metadata(name));
+  return result;
+}
+const handlerNames=['extension','proxy','conditional','redirect','function','page','static','download','respond','link']         ;
+function handlerOf(route             )         {return handlerNames.find(name=>route[name]!==undefined)??'unknown';}
+/**
+ * Derives the per-route tag index of one project from its loaded routes: handler,
+ * methods, capabilities, policy names and middleware module names. The file each
+ * route comes from is read from the entry and its includes; routes that neither
+ * declares were generated by `site`.
+ */
+export async function buildRouteIndex(project        ,label        )                      {
+  const loaded=await loadDocument(project);await applySite(loaded,{});
+  const origin=new Map               ();
+  for(const file of ['urlcode.yaml',...(loaded.document.includes??[])]){
+    const parsed=parseYaml(await readFile(project+'/'+file,'utf8'))                                     ;
+    for(const path of Object.keys(parsed.routes??{}))origin.set(path,file);
+  }
+  const entries                   =Object.entries(loaded.routes).map(([path,route])=>{
+    const handler=handlerOf(route),file=origin.get(path)??'site';
+    const methods=route.methods??['GET','HEAD'];
+    const tags=new Set        ([handler,...(file==='site'?['site']:[]),...methods.map(method=>method.toLowerCase())]);
+    for(const capability of routeCapabilities(route,loaded.document))if(capability!=='methods'&&capability!=='enabled')tags.add(capability);
+    for(const module of route.middleware??[])tags.add(basename(module.source).replace(/\.[cm]?js$/,''));
+    if(route.enabled===false)tags.add('disabled');
+    if(route.expires)tags.add('expiring');
+    return {path,file,handler,methods,tags:[...tags],description:route.description??''};
+  });
+  return {format:1,project:label,routes:entries.length,entries};
+}
+export async function readRouteIndex(name        )                      {
+  const value         =JSON.parse(await readFile(root(name)+routeIndexFile,'utf8'));
+  assert(typeof value==='object'&&value!==null&&(value              ).format===1&&Array.isArray((value              ).entries),'Malformed route index');
+  return value              ;
+}
+function matchRoutes(index            ,terms          )                    {
+  const scored=index.entries.map(entry=>{
+    const text=[entry.path,entry.description].join(' ').toLowerCase();
+    let score=0;
+    for(const term of terms){if(entry.tags.includes(term))score+=4;else if(entry.tags.some(tag=>tag.includes(term)))score+=2;else if(text.includes(term))score+=1;}
+    return {entry,score};
+  }).filter(item=>item.score>0).sort((a,b)=>b.score-a.score);
+  return scored.map(item=>item.entry);
+}
+/**
+ * Searches example.yaml files and the cookbook's per-route index locally. Results
+ * are ordered smallest runnable example first, so `best` is the least code that
+ * demonstrates the match; cookbook hits carry their matching routes.
+ */
+export async function searchExamples(text        )                               {
+  const terms=searchTerms(text),examples=await listExamples();
+  const indexes=new Map                   ();
+  for(const example of examples)if(example.id==='cookbook')indexes.set(example.id,await readRouteIndex(example.id));
+  const routeText=(example                )=>(indexes.get(example.id)?.entries??[]).flatMap(entry=>[entry.path,entry.description,...entry.tags]);
+  const hits                             =searchMetadata(examples,text,routeText);
+  const results=hits.map(hit=>({...hit.entry,score:hit.score,matched:hit.matched,matchedRoutes:indexes.has(hit.entry.id)?matchRoutes(indexes.get(hit.entry.id) ,terms):[]}))
+    .sort((a,b)=>Number(b.runnable!==false)-Number(a.runnable!==false)||(a.routes??0)-(b.routes??0)||b.score-a.score);
+  const first=results.find(result=>result.runnable!==false);
+  let best                             =null;
+  if(first){const {score:_score,matched:_matched,matchedRoutes,...summary}=first;best={...summary,...(matchedRoutes[0]?{route:matchedRoutes[0]}:{})};}
+  return {query:text,count:results.length,best,results};
+}

package/dist/explain-cli.js

@@ -0,0 +1,64 @@
+import {ConfigError} from './errors.js';
+import {normalizeCapabilityTarget} from './capabilities.js';
+                                                        
+import {explainRoute,explainProject} from './tooling.js';
+                                                   
+import {buildManifest,renderManifest} from './manifest.js';
+                                                      
+
+                                                                                                                                                     
+const table=(rows           )       =>{const widths=rows[0] .map((_,i)=>Math.max(...rows.map(row=>row[i] .length)));return rows.map(row=>row.map((cell,i)=>cell.padEnd(widths[i] )).join('  ').trimEnd()).join('\n')+'\n';};
+const targetsOf=(target                 )                   =>target===undefined?['self-hosted','cloudflare','aws','vercel']:[normalizeCapabilityTarget(target)];
+function summary(explanation                 ,targets                   )        {
+  const handler=explanation.handler,detail=handler.kind==='function'?`${handler.source          }#${handler.export          }`:handler.kind==='redirect'?`${handler.status          } ${handler.url          }`:handler.kind==='extension'?handler.name          :handler.kind==='page'||handler.kind==='download'?handler.file          :handler.kind==='static'?handler.directory          :handler.kind==='proxy'?handler.url          :handler.kind==='respond'?String(handler.status):'';
+  const support=targets.map(target=>explanation.targets[target].compatible?target:`${target}:refused`).join(',');
+  return [explanation.path,explanation.methods.join(','),`${handler.kind}${detail?` ${detail}`:''}`,explanation.state,String(explanation.middleware.length),explanation.policies.names.join(',')||'-',explanation.cache.outcome,support].join('\t');
+}
+function detail(explanation                 ,targets                   )        {
+  const lines         =[`route: ${explanation.path}`];
+  if(explanation.description)lines.push(`description: ${explanation.description}`);
+  if(explanation.generated)lines.push(`generated: site.${explanation.generated}`);
+  lines.push(`state: ${explanation.state}${explanation.expires?` (expires ${explanation.expires})`:''}`,`methods: ${explanation.methods.join(', ')}`,`handler: ${JSON.stringify(explanation.handler)}`);
+  lines.push(`middleware: ${explanation.middleware.length?explanation.middleware.map(item=>`${item.source}#${item.export}`).join(' -> '):'none'}`);
+  lines.push(`inputs: ${explanation.inputs.parameters.length?explanation.inputs.parameters.map(p=>`${p.in}:${p.name}${p.required?'':'?'}`).join(', '):'none'}${explanation.inputs.body?`; body ${JSON.stringify(explanation.inputs.body)}`:''}`);
+  lines.push(`policies: ${explanation.policies.names.length?explanation.policies.names.join(', '):'none'}`);
+  for(const [name,entry] of Object.entries(explanation.policies.inventory))lines.push(`  ${name}: ${JSON.stringify(entry)}`);
+  for(const [name,entry] of Object.entries(explanation.policies.extensions))lines.push(`  extensions.${name}: requires ${JSON.stringify(entry.requirement)}${entry.provider?entry.provider.registered?` (provider registered, revision ${entry.provider.revisionMatch?'matches':'differs'}, requirement ${entry.provider.requirementValid===false?'invalid':'valid'})`:' (no provider in host file)':''}`);
+  lines.push(`cache: ${explanation.cache.outcome}${explanation.cache.cacheControl?` (${explanation.cache.cacheControl})`:''}${explanation.cache.forcedNoStore?' forced':''}; ${explanation.cache.reason}`);
+  const env=Object.entries(explanation.bindings.env).map(([alias,ref])=>`${alias}=${'env' in ref?`$${ref.env}`:'literal'}`),secrets=Object.entries(explanation.bindings.secrets).map(([alias,ref])=>`${alias}=secret:${ref.secret}`);
+  lines.push(`bindings: ${[...env,...secrets].join(', ')||'none'}`);
+  if(explanation.egress.proxy||explanation.egress.signals)lines.push(`egress: ${[explanation.egress.proxy?`proxy ${explanation.egress.proxy}`:'',...(explanation.egress.signals??[]).map(item=>`signal ${item}`)].filter(Boolean).join(', ')}`);
+  if(explanation.responseHeaders.length)lines.push(`response headers: ${explanation.responseHeaders.map(([name,value])=>`${name}: ${value}`).join('; ')}`);
+  lines.push(`capabilities: ${explanation.capabilities.join(', ')}`);
+  for(const target of targets){const support=explanation.targets[target];lines.push(`target ${target}: ${support.compatible?'supported':support.issues.map(issue=>`${issue.capability} ${issue.support} (${issue.reason})`).join('; ')}`);}
+  lines.push(`note: ${explanation.note}`);
+  return lines.join('\n')+'\n';
+}
+/** Returns the process exit code: 1 when a requested route does not exist. */
+export async function runExplainCommand(command                     ,route                 ,options        ,print                         )                 {
+  const base={...(options.origin===undefined?{}:{origin:options.origin}),...(options.extensions===undefined?{}:{extensions:options.extensions})};
+  if(command==='manifest'){
+    if(route!==undefined)throw new ConfigError('manifest takes no route argument');
+    const manifest=await buildManifest(options.project,base);
+    if(options.json){print(renderManifest(manifest));return 0;}
+    const lines=[`revision: ${manifest.revision}`,`urlcode: ${manifest.urlcode}`,`files: ${manifest.files.join(', ')}`,`routes: ${manifest.routeCount}`,`capabilities: ${manifest.capabilities.join(', ')}`,
+      `extensions: ${Object.keys(manifest.extensions).join(', ')||'none'}`,`recipes: ${manifest.recipes.map(recipe=>recipe.id).join(', ')||'none'}`,
+      `external: env ${manifest.external.env.join(', ')||'-'}; secrets ${manifest.external.secrets.join(', ')||'-'}; proxy ${manifest.external.egress.proxy.join(', ')||'-'}; signals ${manifest.external.egress.signals.join(', ')||'-'}; link stores ${manifest.external.linkStores.join(', ')||'-'}`,
+      `functions: ${manifest.functions.map(item=>`${item.source}#${item.export}`).join(', ')||'none'}`,`middleware: ${manifest.middleware.map(item=>`${item.source}#${item.export}`).join(', ')||'none'}`,
+      `targets: ${Object.entries(manifest.targets).map(([target,support])=>`${target} ${support.compatible?'supported':`${support.issues} issue${support.issues===1?'':'s'}`}`).join('; ')}`,'Use --json for the full manifest.'];
+    print(lines.join('\n')+'\n');return 0;
+  }
+  const targets=targetsOf(options.target);
+  if(route===undefined){
+    const report=await explainProject(options.project,base);
+    if(options.json){print(report);return 0;}
+    print(table([['route','methods','handler','state','mw','policies','cache','targets'],...report.routes.map(item=>summary(item,targets).split('\t'))]));return 0;
+  }
+  if(!route.startsWith('/'))throw new ConfigError('Provide an absolute route path such as /docs');
+  const explanation=await explainRoute(options.project,route,base);
+  if(!explanation.matched){
+    if(options.json)print(explanation);else print(`no route selects ${route}${explanation.nearest.length?`; nearest: ${explanation.nearest.join(', ')}`:''}\n`);
+    return 1;
+  }
+  print(options.json?explanation:detail(explanation,targets));return 0;
+}