@jimhoyd/urlcode 0.3.0 → 0.4.0-alpha.2

package/dist/conditions.js

@@ -0,0 +1,88 @@
+import { assert, HttpError } from './errors.js';
+
+/** Bounded conjunction of exact string comparisons; no regex or implicit detection. */
+                             
+                                                                                                     
+                                 
+ 
+                                                                                                                                                                 
+const token = /^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/;
+export function normalizeMatch(match            )             {
+  assert(match && typeof match === 'object' && !Array.isArray(match), 'match must be an object');
+  assert(Object.keys(match).length > 0 && Object.keys(match).every(key => ['query','headers','cookies','host','method'].includes(key)), 'Unsupported or empty match');
+  const normalized             = {};
+  for (const group of ['query','headers','cookies']         ) if (match[group] !== undefined) {
+    assert(match[group] !== null && typeof match[group] === 'object' && !Array.isArray(match[group]), `match.${group} must be an object`);
+    const fields = Object.entries(match[group]);
+    assert(fields.length > 0 && fields.length <= 16, `match.${group} requires 1–16 entries`);
+    const values                        = Object.create(null)                         ;
+    for (const [name,value] of fields) {
+      const key = group === 'headers' ? name.toLowerCase() : name;
+      assert(token.test(key) && key.length <= 128 && !Object.hasOwn(values,key), `Invalid or duplicate match.${group} name`);
+      assert(typeof value === 'string' && value.length <= 1024 && !/[\u0000-\u001f\u007f]/.test(value), `Invalid match.${group} value`);
+      if (group === 'headers') assert(!['host','cookie','authorization','proxy-authorization','connection','transfer-encoding','content-length','keep-alive','proxy-authenticate','te','trailer','upgrade'].includes(key), 'Use match.host/cookies; credential and transport headers cannot be conditions');
+      if (group === 'cookies') assert(!/[;,\s"\\]/.test(value), 'Cookie conditions use unquoted wire values');
+      values[key] = value;
+    }
+    normalized[group] = values;
+  }
+  if (match.method !== undefined) {
+    assert(['GET','HEAD','POST','PUT','PATCH','DELETE','OPTIONS'].includes(match.method), 'Invalid match.method');
+    normalized.method = match.method;
+  }
+  if (match.host !== undefined) {
+    assert(typeof match.host === 'string' && match.host.length <= 255 && /^[a-z0-9.-]+(?::[0-9]{1,5})?$/i.test(match.host), 'match.host must be a literal host with optional port');
+    const url = new URL('https://' + match.host);
+    assert(url.host === match.host.toLowerCase(), 'match.host must be a canonical authority');
+    normalized.host = url.host;
+  }
+  assert(Object.keys(normalized).length > 0, 'Empty match');
+  return normalized;
+}
+function equalities(match            )                     {
+  const values = new Map               ();
+  for (const group of ['query','headers','cookies']         ) for (const [name,value] of Object.entries(match[group] ?? {})) values.set(`${group}:${name}`,value);
+  if (match.host) values.set('host',match.host);
+  if (match.method) values.set('method',match.method);
+  return values;
+}
+/** Cases must be disjoint: at least one shared fact must demand different values. */
+export function assertDisjointMatches(matches              )       {
+  assert(Array.isArray(matches) && matches.length >= 1 && matches.length <= 16, 'Conditional routes require 1–16 cases');
+  const facts = matches.map(normalizeMatch).map(equalities);
+  for (let i = 0; i < facts.length; i++) for (let j = i + 1; j < facts.length; j++) {
+    assert([...facts[i] ].some(([key,value]) => facts[j] .has(key) && facts[j] .get(key) !== value), `Conditional cases ${i + 1} and ${j + 1} overlap`);
+  }
+}
+export function matchesRoute(match            , request                  )          {
+  if (match.method && match.method !== request.method) return false;
+  // The operator's origin is authoritative, never forwarded/client Host text.
+  if (match.host && new URL(request.origin).host !== match.host) return false;
+  for (const [name,value] of Object.entries(match.query ?? {})) {
+    const actual = request.query.getAll(name);
+    if (actual.length > 1) throw new HttpError(400,'Duplicate condition query input');
+    if (actual.length !== 1 || actual[0] !== value) return false;
+  }
+  for (const [name,value] of Object.entries(match.headers ?? {})) {
+    if ((request.headerCounts?.[name] ?? 0) > 1) throw new HttpError(400,'Duplicate condition header input');
+    if (request.headers.get(name) !== value) return false;
+  }
+  if (match.cookies) {
+    const raw = request.headers.get('cookie') ?? '';
+    if (raw.length > 8192) throw new HttpError(400,'Cookie conditions exceed input limit');
+    const values = new Map                 ();
+    for (const part of raw.split(';')) {
+      const index = part.indexOf('=');
+      if (index < 0) continue;
+      const name = part.slice(0,index).trim(), value = part.slice(index + 1).trim();
+      if (!Object.hasOwn(match.cookies,name)) continue;
+      const entries = values.get(name) ?? []; entries.push(value); values.set(name,entries);
+    }
+    for (const [name,value] of Object.entries(match.cookies)) {
+      const actual = values.get(name) ?? [];
+      if (actual.length > 1) throw new HttpError(400,'Duplicate condition cookie input');
+      if (actual.length !== 1 || actual[0] !== value) return false;
+    }
+  }
+  return true;
+}

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,50 @@ 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}`;
+ * a route-level `cache` becomes `policies.cache` (refused alongside a direct `policies.cache`).
+ * Everything downstream (routes, audit, the compiled table) sees only the long form.
+ */
+export function normalizeRoute(pattern        , route                                   )              {
+  const authored = route                       ;
+  const needsFunction = typeof authored.function === 'string';
+  const needsMiddleware = authored.middleware?.some(entry => typeof entry === 'string') ?? false;
+  const needsCache = authored.cache !== undefined;
+  if (!needsFunction && !needsMiddleware && !needsCache) return route               ;
+  const result              = { ...(route               ) };
+  if (needsMiddleware) result.middleware = authored.middleware .map((entry)                   => typeof entry === 'string' ? { source: modulePath(pattern, 'middleware', entry) } : entry);
+  if (needsFunction) {
+    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;
+  }
+  if (needsCache) {
+    assert(result.policies?.cache === undefined, `Route ${pattern} declares both cache and policies.cache; use one form`);
+    result.policies = { ...result.policies, cache: authored.cache  };
+    delete result.cache;
+  }
+  return result;
 }
 export async function safeFile(root        , file         )                  {
   root = await realpath(root);
@@ -64,7 +107,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 +154,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 || []) {
@@ -125,17 +187,18 @@ export async function loadDocumentInWorker(project        )
     files.push(path);
     const part = validateDocument(await readConfig(path, budget));
     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}: document.site ? {routes, site:document.site} : 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,155 @@
+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','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:true,note:'Trusted (default) functions and middleware run in-process with full Node network access; route `sandbox: true` runs that route in a WASM sandbox without fetch or sockets, where outbound calls must be proxy or signals routes under operator grants'},
+ nodeApis:{value:true,note:'Trusted (default) functions and middleware have full Node built-ins, process, filesystem and npm packages available, same as any other project code; route `sandbox: true` restricts that route to relative ES-module imports only, no Node built-ins/filesystem/npm packages'},
+ 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, 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');
+  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)},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),sandbox:route.sandbox===true,...(route.sandboxReason?{sandboxReason:route.sandboxReason}:{})})).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:[]},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);}
+  }
+}