@jimhoyd/urlcode 0.3.0 → 0.4.0-alpha.1

package/dist/explain.js

@@ -0,0 +1,132 @@
+import {relative} from 'node:path';
+import Ajv from 'ajv/dist/2020.js';
+import {analyzeCompiledCapabilities,capabilityTargets,routeCapabilities} from './capabilities.js';
+                                                                       
+import {effectiveExtensionPolicies} from './extensions.js';
+                                                      
+import {effectivePolicies} from './policies.js';
+                                                                                                    
+                                                
+                                                                  
+                                                        
+
+// Effective route behavior read from the compiled IR (config → router →
+// policies), never from request execution. Everything here is safe to print:
+// binding values are replaced by their names, module paths are made
+// project-relative and secrets never appear.
+
+const handlerNames=['extension','proxy','conditional','redirect','function','page','static','download','respond','link']                                          ;
+
+                                                                                      
+                                                                                                                   
+                                                                                                                                                     
+                                                                                                                  
+                                 
+                                                                                                   
+                                                                              
+ 
+                                                                                                                        
+                                   
+                                                                                                                        
+                                                                                                              
+                                                                   
+                                                                                                              
+                       
+                                                                                                   
+                                           
+                                                                                                                   
+              
+ 
+                                                                                                                                    
+
+const relativeSource=(root       ,source       )       =>relative(root,source).split('\\').join('/');
+function origin(url       )        {try{return new URL(url).origin;}catch{return url;}}
+
+function handlerOf(route              ,root       )                  {
+  const kind=handlerNames.find(key=>route[key]);
+  switch(kind){
+    case 'extension':return {kind,name:route.extension};
+    case 'proxy':return {kind,url:route.proxy .url,...(route.proxy .query?{query:route.proxy .query}:{}),...(route.proxy .requestHeaders?{requestHeaders:route.proxy .requestHeaders}:{}),...(route.proxy .responseHeaders?{responseHeaders:route.proxy .responseHeaders}:{})};
+    case 'conditional':{
+      const branch=(entry              )=>entry.redirect?{redirect:{url:entry.redirect.url,status:entry.redirect.status??302}}:{respond:{status:entry.reply?.status??200}};
+      return {kind,cases:(route.conditionalRoutes?.cases??[]).map(item=>({match:item.match,...branch(item.route)})),...(route.conditionalRoutes?.fallback?{fallback:branch(route.conditionalRoutes.fallback)}:{})};
+    }
+    case 'redirect':return {kind,url:route.redirect .url,status:route.redirect .status??302,...(route.redirect .query?{query:route.redirect .query}:{})};
+    case 'function':return {kind,source:relativeSource(root,route.function .source),export:route.function .export,...(route.function .args?{args:route.function .args}:{})};
+    case 'page':return {kind,file:route.page .file,...(route.page .contentType?{contentType:route.page .contentType}:{})};
+    case 'static':return {kind,directory:route.static .directory,...(route.static .index?{index:route.static .index}:{})};
+    case 'download':return {kind,file:route.download .file,...(route.download .filename?{filename:route.download .filename}:{}),...(route.download .contentType?{contentType:route.download .contentType}:{})};
+    case 'respond':return {kind,status:route.reply?.status??route.respond .status??200};
+    case 'link':return {kind,collection:route.link .collection};
+    default:return {kind:'none'};
+  }
+}
+function cacheOf(route              ,chain                      ,extensionPolicies         )                {
+  const forced=route.extension?'extension mount':extensionPolicies.length?'extension-protected route':route.proxy?'proxy':route.match||route.conditional?'conditional routing':undefined;
+  if(forced)return {outcome:'no-store',cacheControl:'no-store',forcedNoStore:true,reason:`The runtime replaces every cache header on this ${forced} with no-store`};
+  const policy=chain?.describe.cache;
+  if(policy){const cacheControl=policy.cacheControl;return {outcome:policy.strategy??'policy',...(cacheControl===undefined?{}:{cacheControl}),forcedNoStore:false,reason:policy.target==='delegated'?'policies.cache is delegated to the provider on this target':'policies.cache compiled for this route'};}
+  const header=route.responseHeaders.find(([name])=>name.toLowerCase()==='cache-control');
+  if(header)return {outcome:'explicit response header',cacheControl:header[1],forcedNoStore:false,reason:'response.headers declares Cache-Control'};
+  const asset=route.page?.cacheControl??route.download?.cacheControl??route.static?.cacheControl;
+  if(asset)return {outcome:'asset handler',cacheControl:asset,forcedNoStore:false,reason:'the asset declaration sets cacheControl'};
+  return {outcome:'none',forcedNoStore:false,reason:'no cache policy or Cache-Control header is declared'};
+}
+function providerOf(name       ,requirement                                 ,options               )                             {
+  if(!options.extensions)return undefined;
+  const registration=options.extensions.find(entry=>entry.name===name);
+  if(!registration)return {registered:false};
+  let requirementValid             =null;
+  if(requirement)try{requirementValid=registration.policySchema?Boolean(new Ajv.default({strict:false,allErrors:false}).compile(registration.policySchema)(requirement)):false;}catch{requirementValid=false;}
+  return {registered:true,version:registration.version,targets:[...registration.targets],revisionMatch:options.projectSha256===undefined?false:registration.projectSha256===options.projectSha256,requirementValid};
+}
+function targetsOf(loaded               ,route              )                                        {
+  const table={exact:new Map([[route.pattern,route]]),byLength:new Map(),mounts:[],modules:[],count:1};
+  const result={}                                          ;
+  for(const target of capabilityTargets){
+    const report=analyzeCompiledCapabilities(loaded.document,table,target);
+    const issues=report.issues.filter(issue=>issue.path===route.pattern).map(({capability,support,reason})=>({capability,support,reason}));
+    result[target]={compatible:issues.length===0,issues};
+  }
+  return result;
+}
+export function routeState(route              ,now       )            {return route.enabled===false?'disabled':route.expiresAt&&now>=route.expiresAt?'expired':'active';}
+/** Describe one compiled route. `chain` is the policy chain compiled for it, when the project declares policies. */
+export function explainCompiledRoute(loaded               ,route              ,chain                      ,options               ={})                  {
+  const root=loaded.root,declared=loaded.routes[route.pattern];
+  const extensionRequirements=effectiveExtensionPolicies(loaded.document,route),extensionNames=Object.keys(extensionRequirements).sort();
+  const extensions                                             ={};
+  for(const name of extensionNames){const provider=providerOf(name,extensionRequirements[name],options);extensions[name]={requirement:extensionRequirements[name] ,...(provider?{provider}:{})};}
+  const env                                    ={};
+  for(const [alias,ref]of Object.entries(declared?.env??{}))env[alias]=ref.env?{env:ref.env}:{literal:true};
+  const secrets                                        ={};
+  for(const [alias,ref]of Object.entries(declared?.secrets??{}))secrets[alias]={secret:ref.secret};
+  const inventory=chain?.describe??{};
+  const names=[...Object.keys(effectivePolicies(loaded.document,route)),...extensionNames.map(name=>`extensions.${name}`)];
+  const handler=handlerOf(route,root);
+  if(handler.kind==='extension'){const provider=providerOf(route.extension ,undefined,options);if(provider)handler.provider=provider;}
+  const egress                           ={...(route.proxy?{proxy:origin(route.proxy.url)}:{}),...(route.signals?.length?{signals:[...new Set(route.signals.map(signal=>origin(signal.url)))]}:{})};
+  return {
+    matched:true,path:route.pattern,...(route.description?{description:route.description}:{}),...(route.generated?{generated:route.generated}:{}),
+    state:routeState(route,options.now??Date.now()),enabled:route.enabled!==false,...(route.expires?{expires:route.expires}:{}),
+    methods:[...route.methods],conditional:Boolean(route.match||route.conditional),handler,
+    middleware:route.middleware.map(item=>({source:relativeSource(root,item.source),export:item.export})),
+    inputs:{parameters:route.parameters.map(({name,in:location,required,schema})=>({name,in:location,required,schema})),...(route.request?.body?{body:route.request.body}:{})},
+    policies:{names,inventory,extensions},
+    cache:cacheOf(route,chain,extensionNames),
+    bindings:{env,secrets},egress,
+    responseHeaders:route.responseHeaders.map(([name,value])=>[name,value]),
+    capabilities:routeCapabilities(route,loaded.document),targets:targetsOf(loaded,route),
+    note:'Derived from the compiled configuration; request conditions, parameter values and handler execution are not evaluated.',
+  };
+}
+// Edit distance between a requested path and each pattern, so a typo points
+// at the route the author probably meant.
+function distance(a       ,b       )        {
+  const previous=Array.from({length:b.length+1},(_,i)=>i);
+  for(let i=1;i<=a.length;i++){let diagonal=previous[0] ;previous[0]=i;for(let j=1;j<=b.length;j++){const temp=previous[j] ;previous[j]=Math.min(previous[j] +1,previous[j-1] +1,diagonal+(a[i-1]===b[j-1]?0:1));diagonal=temp;}}
+  return previous[b.length] ;
+}
+export function nearestRoutes(target       ,patterns                 ,limit=3)          {
+  return [...patterns].map(pattern=>({pattern,score:distance(target.toLowerCase(),pattern.toLowerCase())})).sort((a,b)=>a.score-b.score||(a.pattern<b.pattern?-1:1)).slice(0,limit).map(item=>item.pattern);
+}

package/dist/extensions.js

@@ -0,0 +1,172 @@
+import Ajv from 'ajv/dist/2020.js';
+import { assert, HttpError } from './errors.js';
+import { loadDocument } from './config.js';
+import { prepareFunctionSnapshot } from './policy.js';
+import { validateHeaderName, validateHeaderValue } from './header-validation.js';
+                                                        
+                                                                           
+                                                        
+                                                                                    
+                                                                            
+                                                                                                                         
+                                   
+                                                                                    
+                                                                                   
+                                        
+ 
+                                    
+                                                                        
+                                                                                                                                             
+                              
+ 
+/** Trusted operator code only. YAML declares names/configuration, never modules. */
+/**
+ * Content-hashed assets under `<mount><prefix>/` may be cached publicly. The
+ * extension owns the hashed filename; the runtime only relaxes its no-store floor
+ * for a GET/HEAD 200/304 that carries a strong ETag, sets no cookie and does not
+ * vary on credentials. Everything else under the mount stays no-store.
+ */
+                                                           
+                                   
+                                                                       
+                                                                                                              
+                                                                                                                             
+ 
+/** `urlcode init --with <name>` contract: what core hands `@jimhoyd/urlcode-<name>`'s `scaffold` export. Nothing is written by `scaffold`. */
+                                  
+                                                                                              
+                   
+                                                                                  
+                 
+                                                                                       
+                  
+                                                                                               
+                          
+ 
+                                                                                      
+                                 
+                                       
+              
+                                                                                                             
+                                                                   
+                                                                                                                            
+                                                                                      
+                                                                                                             
+                       
+                                                                                                               
+                                    
+                                                                          
+                             
+ 
+                                                                                                                                                       
+/** What the runtime knows about the request when it applies the privacy floor. */
+                                                                                                 
+                                                                                                                             
+const namePattern=/^[a-z][a-z0-9-]{0,63}$/;
+const cacheHeaders=new Set(['cache-control','cdn-cache-control','vercel-cdn-cache-control','surrogate-control']);
+const segmentPattern=/^[A-Za-z0-9_-][A-Za-z0-9._-]{0,63}$/;
+export const immutableCacheControl='public, max-age=31536000, immutable';
+/** A normalized absolute path prefix: literal segments only, no dot segments, no trailing slash. */
+function validateAssetPrefix(prefix        ,name       )        {
+  assert(typeof prefix==='string'&&prefix.length>=2&&prefix.length<=256&&prefix.startsWith('/')&&!prefix.endsWith('/'),`Extension ${name} immutableAssets.prefix must be a normalized absolute path`);
+  assert(prefix.slice(1).split('/').every(segment=>segmentPattern.test(segment)&&segment!=='.'&&segment!=='..'),`Extension ${name} immutableAssets.prefix must contain literal path segments only`);
+  return prefix;
+}
+function frozen   (value  )   {if(value&&typeof value==='object'){for(const child of Object.values(value))frozen(child);Object.freeze(value);}return value;}
+/** Inspection alone grants nothing; operators must explicitly pin the returned revision. */
+export async function inspectExtensionRevision(project       )                 {return (await prepareFunctionSnapshot(await loadDocument(project))).projectSha256;}
+export function effectiveExtensionPolicies(document                ,route                             )                                       {
+  const project=document.policies??{},local=route.policies??{};
+  const layers=[project.profile?document.profiles?.[project.profile]:undefined,project,local.profile?document.profiles?.[local.profile]:undefined,local];
+  const result                                      =Object.create(null)                                         ;
+  for(const layer of layers){if(layer?.extensions===false){for(const key of Object.keys(result))delete result[key];continue;}
+    for(const [name,value]of Object.entries(layer?.extensions??{})) {if(value===false)delete result[name];else result[name]={...result[name],...value};}
+  }
+  return result;
+}
+export function hasExtensionPolicy(document                ,route                             )         {return Object.keys(effectiveExtensionPolicies(document,route)).length>0;}
+export function prepareExtensions(document                ,routes                           ,registrations                             ,context                                   )                                          {
+  assert(registrations===undefined||Array.isArray(registrations)&&registrations.length<=16,'Extensions must be an array of at most 16 operator registrations');
+  const provided=new Map                         (),entries=new Map                        (),credentialHeaders=new Set        ();
+  for(const registration of registrations??[]){
+    assert(registration&&typeof registration==='object'&&typeof registration.name==='string'&&namePattern.test(registration.name),'Invalid extension registration');
+    assert(!provided.has(registration.name),'Duplicate extension provider');
+    assert(registration.version==='1'&&typeof registration.activate==='function','Invalid extension version or activation hook');
+    assert(Array.isArray(registration.targets)&&registration.targets.every(target=>['node','aws','vercel'].includes(target)),'Extension targets must be node, aws or vercel');
+    assert(typeof registration.projectSha256==='string'&&/^[a-f0-9]{64}$/.test(registration.projectSha256),'Extension requires an explicit operator revision pin');
+    provided.set(registration.name,registration);
+  }
+  const declarations=document.extensions??{};
+  if(Object.keys(declarations).length){let origin    ;try{origin=new URL(context.origin);}catch{throw new Error('Extensions require an explicit operator origin');}assert(['http:','https:'].includes(origin.protocol)&&!origin.username&&!origin.password&&origin.origin===context.origin,'Extensions require an explicit canonical HTTP(S) operator origin');}
+  for(const route of Object.values(routes)){
+    if(route.extension)assert(Object.hasOwn(declarations,route.extension),'Extension route has no declaration');
+    for(const name of Object.keys(effectiveExtensionPolicies(document,route)))assert(Object.hasOwn(declarations,name),'Extension policy has no declaration');
+  }
+  const preparations                                                                                                                                                                                   =[];
+  for(const [name,declaration]of Object.entries(declarations)){
+      const registration=provided.get(name);assert(registration,`Missing operator extension: ${name}`);
+      assert(registration.projectSha256===context.projectSha256,`Extension revision pin mismatch: ${name}`);
+      assert(registration.targets.includes(context.target),`Extension ${name} refuses target ${context.target}`);
+      assert(declaration.version===registration.version,`Extension contract version mismatch: ${name}`);
+      const config=structuredClone(declaration.config);
+      const ajv=new Ajv.default({strict:true,allErrors:false});
+      assert(ajv.compile(registration.schema)(config),`Invalid extension configuration: ${name}`);
+      const policyValidator=registration.policySchema?ajv.compile(registration.policySchema):undefined;
+      const policies=new Map                                         ();
+      for(const [path,route]of Object.entries(routes)){const policy=effectiveExtensionPolicies(document,route)[name];if(policy){assert(policyValidator&&policyValidator(policy),`Invalid extension policy: ${name} at ${path}`);policies.set(path,frozen(structuredClone(policy)));}}
+      const declaredHeaders=registration.credentialHeaders??[];
+      assert(Array.isArray(declaredHeaders)&&declaredHeaders.length<=64,'Invalid extension credential headers');
+      for(const header of declaredHeaders){assert(typeof header==='string'&&header.length<=128,'Invalid extension credential header');validateHeaderName(header);credentialHeaders.add(header.toLowerCase());}
+      // Session and bearer credentials never cross into application guests.
+      credentialHeaders.add('cookie');credentialHeaders.add('authorization');
+      const mounts=Object.entries(routes).filter(([,route])=>route.extension===name).map(([path])=>path.endsWith('/*')?path.slice(0,-2):path);
+      const assetPrefixes=registration.immutableAssets===undefined?[]:mounts.map(mount=>mount+validateAssetPrefix((registration.immutableAssets                            ).prefix,name)+'/');
+      preparations.push({name,registration,config:frozen(config),policies,mounts,assetPrefixes});
+  }
+  return {async activate(){
+    try{for(const {name,registration,config,policies,mounts,assetPrefixes}of preparations){
+      const instance=await registration.activate(config,frozen({...context,mounts}));
+      if(instance&&typeof instance==='object')entries.set(name,{instance,policies,assetPrefixes});
+      assert(instance&&typeof instance.handle==='function'&&(!policies.size||typeof instance.authorize==='function'),`Extension ${name} lacks a required handler or authorization hook`);
+      entries.set(name,{instance,policies,assetPrefixes});
+    }}catch(error){for(const entry of [...entries.values()].reverse())try{await entry.instance.close?.();}catch{/* Keep the activation failure. */}throw error;}
+    return {entries,credentialHeaders:[...credentialHeaders],async close(){for(const entry of [...entries.values()].reverse())try{await entry.instance.close?.();}catch{/* Operators own extension lifecycle diagnostics. */}}};
+  }};
+}
+const header=(headers                                      ,name       )         =>headers.filter(([key])=>key.toLowerCase()===name).map(([,value])=>value);
+const maxAge=(value       )                 =>{const match=/(?:^|[\s,])max-age\s*=\s*"?(\d+)/i.exec(value);return match?Number(match[1]):undefined;};
+/**
+ * The runtime decides; the extension cannot opt in from a response alone. The
+ * declared prefix, the GET/HEAD method, a 200/304 status, one strong ETag, no
+ * Set-Cookie and no Vary on Cookie/Authorization are all required. A stricter
+ * Cache-Control the extension set (no-store, no-cache, private or a shorter
+ * max-age) is preserved.
+ */
+export function immutableAssetResponse(result              ,asset                                )         {
+  if(!asset||!asset.prefixes.some(prefix=>asset.path.startsWith(prefix)))return false;
+  if(asset.method!=='GET'&&asset.method!=='HEAD')return false;
+  if(result.status!==200&&result.status!==304)return false;
+  const etag=header(result.headers,'etag');
+  if(etag.length!==1||!/^"[!#-~]+"$/.test(etag[0] ))return false;
+  if(header(result.headers,'set-cookie').length)return false;
+  if(header(result.headers,'vary').some(value=>value.split(',').some(field=>['cookie','authorization','*'].includes(field.trim().toLowerCase()))))return false;
+  return true;
+}
+function assetCacheControl(result              )        {
+  const declared=header(result.headers,'cache-control');
+  if(declared.length!==1)return immutableCacheControl;
+  const value=declared[0] ,lower=value.toLowerCase();
+  if(/(?:^|[\s,])(?:no-store|no-cache|private)(?:$|[\s,=])/.test(lower))return value;
+  const age=maxAge(value);
+  return age!==undefined&&age<31536000?value:immutableCacheControl;
+}
+/** Mandatory privacy floor after trusted response hooks, with bounded output. */
+export function extensionResponse(result              ,asset                       )               {
+  assert(result&&Number.isInteger(result.status)&&result.status>=200&&result.status<=599&&Array.isArray(result.headers),'Invalid extension response');
+  if(result.body&&Buffer.byteLength(result.body)>1048576)throw new HttpError(502,'Extension response exceeds limit');
+  let bytes=0;assert(result.headers.length<=256,'Extension response has too many headers');
+  for(const [name,value]of result.headers){validateHeaderName(name);validateHeaderValue(name,value);bytes+=Buffer.byteLength(name)+Buffer.byteLength(value)+4;}
+  if(bytes>16384)throw new HttpError(502,'Extension response headers exceed limit');
+  const cacheControl=immutableAssetResponse(result,asset)?assetCacheControl(result):'no-store';
+  return {...result,headers:[...result.headers.filter(([name])=>!cacheHeaders.has(name.toLowerCase())),['cache-control',cacheControl]]};
+}

package/dist/function-sources.js

@@ -17,6 +17,12 @@ import { assert } from './errors.js';
                              
  
 
+/** Snapshot budgets: what one set of guest modules may cost. Deliberate bounds
+ * of the sandbox contract (docs/FUNCTION-SECURITY.md), not tuning knobs. */
+export const MODULE_LIMIT = 128;
+export const MODULE_BYTE_LIMIT = 1048576;
+export const TOTAL_BYTE_LIMIT = 4194304;
+
 export function routeFunctions   (route                  )      { return [...(route.middleware || []), ...(route.function ? [route.function] : [])]; }
 
 // Parse and snapshot source without ever importing project code into Node.
@@ -28,11 +34,17 @@ export async function collectFunctionSources(routes                 , root
   async function collect(file        )                  {
     const name = '/' + relative(root,file).split(sep).join('/');
     if (Object.hasOwn(sources,name)) return name;
-    assert(Object.keys(sources).length < 128, 'Function module limit exceeded');
+    // Name the module that crossed the budget and the counts against their
+    // limits: the bare limit alone reads as a sandbox fault, when it usually
+    // means the project has outgrown what one snapshot holds. Prerendering
+    // splits a large site across snapshots rather than inheriting the bound as
+    // a page ceiling. See docs/PRERENDER.md#function-budgets.
+    assert(Object.keys(sources).length < MODULE_LIMIT, `Function module limit exceeded: ${name} is module ${Object.keys(sources).length + 1}, over the limit of ${MODULE_LIMIT} modules per snapshot`);
     const info = await stat(file);
-    assert(info.size <= 1048576 && bytes + info.size <= 4194304, 'Function source limit exceeded');
+    assert(info.size <= MODULE_BYTE_LIMIT, `Function source limit exceeded: ${name} is ${info.size} bytes, over the per-module limit of ${MODULE_BYTE_LIMIT} bytes`);
+    assert(bytes + info.size <= TOTAL_BYTE_LIMIT, `Function source limit exceeded: ${name} (${info.size} bytes) brings the snapshot to ${bytes + info.size} bytes, over the total limit of ${TOTAL_BYTE_LIMIT} bytes`);
     const code = await readFile(file,'utf8'); bytes += Buffer.byteLength(code);
-    assert(bytes <= 4194304, 'Function source limit exceeded');
+    assert(bytes <= TOTAL_BYTE_LIMIT, `Function source limit exceeded: ${name} brings the snapshot to ${bytes} bytes, over the total limit of ${TOTAL_BYTE_LIMIT} bytes`);
     sources[name] = code; const deps           = dependencies[name] = [];
     const [imports] = parse(code);
     for (const item of imports) {

package/dist/index.js

@@ -9,3 +9,40 @@ export {startLinkApi} from './link-api.js';
                                                            
                                                                                         
 export { events as observabilityEvents, validateObservers, createObserverSink, createMetrics, renderPrometheus } from './observability.js';
+
+export { getCapabilities, routeCapabilities, analyzeProjectCapabilities, analyzeCompiledCapabilities, assertTargetCompatibility, normalizeCapabilityTarget } from './capabilities.js';
+export { capabilityDetails } from './capabilities.js';
+                                                                                                                                                                                                                  
+
+export { importRoutes, exportRoutes } from './interchange.js';
+                                                                                                                                                              
+
+export {listRecipes, searchRecipes, showRecipe, addRecipe} from './recipes.js';
+                                                                                             
+export {listExamples, searchExamples} from './examples.js';
+                                                                                                    
+                                                                             
+export {buildTypeScriptProject} from './typescript-authoring.js';
+                                                                     
+export {importBulkProject} from './bulk.js';
+                                                                          
+export {inspectProject, validateProject, explainRoute, explainProject, previewImport, previewExport, getCapability, getSchemaFragment, schemaPathNames, inspectExtensions, describeExtensions, buildContext, renderContext, estimateTokens, documentationTokens} from './tooling.js';
+                                                                                                                                                                                                                                                                                                        
+export {buildManifest, renderManifest, MANIFEST_SCHEMA_VERSION} from './manifest.js';
+                                                                                             
+export {serveMcp} from './mcp.js';
+                                         
+export {providerConformanceCases, runProviderConformance, verifyProviderDeployment} from './provider-verification.js';
+                                                                                                                                                                                               
+export {normalizeMatch, assertDisjointMatches, matchesRoute} from './conditions.js';
+                                                                  
+
+export {buildCloudflare} from './build-cloudflare.js';
+                                                                                                                        
+export {runProjectTests} from './project-tests.js';
+                                                                              
+export {scaffoldProject} from './scaffold.js';
+                                                                                    
+export {initProject, addRedirect} from './authoring.js';
+export {initProjectWith} from './init-with.js';
+                                                                                   

package/dist/init-with.js

@@ -0,0 +1,165 @@
+import { mkdir, open, readFile, rm, unlink, lstat } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { basename, dirname, join, relative, resolve, sep } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { parseDocument, stringify } from 'yaml';
+import { initProject } from './authoring.js';
+import { mcpConfigFile, renderMcpConfig } from './agents-guide.js';
+import { loadDocument, parseYaml, validateDocument } from './config.js';
+import { inspectExtensionRevision } from './extensions.js';
+                                                                       
+import { ConfigError, assert } from './errors.js';
+
+/** Directory names inside the generated site. The route project lives under `app/`; everything else is operator-owned. */
+export const PROJECT_DIRECTORY = 'app', HOST_FILE = 'host.mjs', ROUTES_FILE = 'routes/extensions.yaml';
+const namePattern = /^[a-z][a-z0-9-]{0,63}$/;
+                                                             
+                                                                                                                                                          
+
+export function parseWithNames(value        )           {
+  const names = value.split(',').map(name => name.trim());
+  assert(names.length > 0 && names.every(name => namePattern.test(name)), 'Use --with name[,name] where each name is a lowercase extension package suffix such as auth');
+  assert(new Set(names).size === names.length, 'Duplicate --with names');
+  return names;
+}
+export const packageName = (name        )         => `@jimhoyd/urlcode-${name}`;
+const isCode = (error         , code        )          => error instanceof Error && 'code' in error && error.code === code;
+const strings = (value         )                    => Array.isArray(value) && value.every(item => typeof item === 'string');
+const record = (value         )                                   => value !== null && typeof value === 'object' && !Array.isArray(value);
+
+/**
+ * Resolves the extension package from the invoking directory (Node's package resolution with the default
+ * conditions), imports it, and calls its `scaffold` export. Nothing is bundled; core never imports these packages
+ * at build time. Refuses a missing package or a package without `scaffold` before anything is written.
+ */
+export async function loadScaffold(name        , request                 , cwd        )                          {
+  const pkg = packageName(name);
+  let entry        ;
+  try { entry = createRequire(join(cwd, 'package.json')).resolve(pkg); }
+  catch (error) {
+    if (isCode(error, 'MODULE_NOT_FOUND')) throw new ConfigError(`Extension package ${pkg} is not installed in ${cwd}; run: npm install ${pkg}`);
+    throw error;
+  }
+  const module = await import(pathToFileURL(entry).href)                           ;
+  const scaffold = module.scaffold;
+  if (typeof scaffold !== 'function') throw new ConfigError(`${pkg} does not export scaffold; upgrade it to a release that supports urlcode init --with, or add ${name} by hand following its README`);
+  let result         ;
+  try { result = await (scaffold                                         )(request); }
+  catch (error) { throw new ConfigError(`${pkg} scaffold refused: ${error instanceof Error ? error.message : String(error)}`); }
+  assert(record(result) && result.name === name, `${pkg} scaffold must return a result named ${name}`);
+  assert(record(result.extensions) && record(result.routes), `${pkg} scaffold must return extensions and routes objects`);
+  assert(strings(result.hostImports) && strings(result.hostSetup) && strings(result.hostEntries) && (result.hostClose === undefined || strings(result.hostClose)), `${pkg} scaffold must return host fragments as string arrays`);
+  assert(strings(result.nextSteps) && typeof result.readme === 'string', `${pkg} scaffold must return readme text and nextSteps strings`);
+  assert(result.env === undefined || (record(result.env) && Object.values(result.env).every(item => typeof item === 'string')), `${pkg} scaffold env must map names to descriptions`);
+  assert(Array.isArray(result.files) && result.files.every((file         ) => record(file) && typeof file.path === 'string' && (typeof file.content === 'string' || file.content instanceof Uint8Array) && (file.mode === undefined || (Number.isInteger(file.mode) && (file.mode          ) >= 0 && (file.mode          ) <= 0o777))), `${pkg} scaffold files must carry a path, content and an optional mode`);
+  return result                             ;
+}
+
+function filePath(root        , path        )         {
+  assert(typeof path === 'string' && path.length > 0 && path.length <= 1024 && !path.includes('\0'), 'Invalid scaffold file path');
+  const target = resolve(root, path), rel = relative(root, target);
+  assert(!path.startsWith('/') && rel === path.split('/').join(sep) && rel.length > 0 && !rel.startsWith('..'), `Scaffold file path must stay inside the site directory: ${path}`);
+  assert(rel !== PROJECT_DIRECTORY && !rel.startsWith(PROJECT_DIRECTORY + sep), `Scaffold files must stay outside the route project: ${path}`);
+  return target;
+}
+/** Creates the file exclusively: nothing generated is ever overwritten. */
+async function write(target        , content                     , mode = 0o644)                {
+  await mkdir(dirname(target), { recursive: true, mode: 0o700 });
+  const file = await open(target, 'wx', mode);
+  try { await file.writeFile(content); await file.sync(); } finally { await file.close(); }
+}
+export function renderHost(names                   , results                           )         {
+  const lines = [`// Generated by urlcode init --with ${names.join(',')}. Trusted operator code: keep it outside ${PROJECT_DIRECTORY}/ and review before serving.`];
+  for (const result of results) lines.push(...result.hostImports);
+  lines.push('');
+  for (const result of results) if (result.hostSetup.length) lines.push(...result.hostSetup);
+  lines.push('export default {', '  extensions: [');
+  for (const result of results) for (const entry of result.hostEntries) lines.push(`    ${entry},`);
+  lines.push('  ],', '  async close() {');
+  // Later extensions may depend on earlier setup, so release in reverse order.
+  for (const result of [...results].reverse()) for (const statement of result.hostClose ?? []) lines.push(`    ${statement}`);
+  lines.push('  },', '};');
+  return lines.join('\n') + '\n';
+}
+function demote(markdown        )         {
+  let fence = false;
+  return markdown.split('\n').map(line => { if (/^\s*(?:```|~~~)/.test(line)) fence = !fence; return !fence && /^#{1,5} /.test(line) ? `#${line}` : line; }).join('\n');
+}
+export function renderReadme(directory        , names                   , results                           , starter        , env                        , projectSha256        )         {
+  const steps = results.flatMap(result => result.nextSteps);
+  const parts = [`# ${basename(directory)}`, '',
+    `Created with \`urlcode init ${basename(directory)} --with ${names.join(',')}\`. \`${PROJECT_DIRECTORY}/\` is the route project (\`urlcode.yaml\`, functions, tests); \`${HOST_FILE}\` is the trusted operator host that wires the installed extension packages; operator modules and private data stay outside the project. Run every command with \`--project ${PROJECT_DIRECTORY} --host-file "$PWD/${HOST_FILE}"\`.`, '',
+    '## Starter', '', `The starter files live in \`${PROJECT_DIRECTORY}/\`; add \`--project ${PROJECT_DIRECTORY}\` and the host file to the commands below.`, '', demote(starter).trim(), ''];
+  for (const result of results) parts.push(`## Extension: ${result.name}`, '', result.readme.trim(), '');
+  parts.push('## Next steps', '', ...steps.map((step, index) => `${index + 1}. ${step}`), '');
+  if (Object.keys(env).length) parts.push('## Environment', '', ...Object.entries(env).map(([key, text]) => `- \`${key}\`: ${text}`), '');
+  parts.push('## Project revision', '', `\`${PROJECT_DIRECTORY}/urlcode.yaml\` currently has revision \`${projectSha256}\` (\`inspectExtensionRevision\`). Review the project, then pin exactly that value where the host expects it; any change to extension YAML, policies or mounts changes it and needs a new explicit review.`, '');
+  return parts.join('\n');
+}
+
+/**
+ * `urlcode init <directory> --with a,b`: the starter under `app/`, every extension's fragments merged into one
+ * `urlcode.yaml`, one `host.mjs`, one `README.md` and the extensions' own files. All packages are resolved and
+ * their scaffolds computed before anything is written, so a refusal leaves no directory behind.
+ */
+export async function initProjectWith(destination        , names                   , { cwd = process.cwd() }                  = {})                          {
+  assert(names.length > 0, 'Provide at least one --with name');
+  const directory = resolve(destination), project = join(directory, PROJECT_DIRECTORY), hostFile = join(directory, HOST_FILE);
+  const request                  = { directory, project, hostFile, names };
+  const results                   = [];
+  const wipe = ()       => { for (const result of results) for (const file of result.files) if (file.content instanceof Uint8Array) file.content.fill(0); };
+  try {
+    for (const name of names) results.push(await loadScaffold(name, request, cwd));
+    // Cross-result conflicts are refused before the destination exists.
+    const extensions                          = Object.create(null)                           , routes                          = Object.create(null)                           , env                         = {};
+    const owners = new Map                ();
+    for (const result of results) {
+      for (const [key, value] of Object.entries(result.extensions)) { assert(!Object.hasOwn(extensions, key), `Extension ${key} is declared by both ${owners.get('e:' + key)} and ${result.name}`); owners.set('e:' + key, result.name); extensions[key] = value; }
+      for (const [key, value] of Object.entries(result.routes)) { assert(!Object.hasOwn(routes, key), `Route ${key} is added by both ${owners.get('r:' + key)} and ${result.name}`); owners.set('r:' + key, result.name); routes[key] = value; }
+      for (const [key, value] of Object.entries(result.env ?? {})) { assert(!Object.hasOwn(env, key) || env[key] === value, `Environment variable ${key} is described differently by ${result.name}`); env[key] = value; }
+      const seen = new Set        ();
+      for (const file of result.files) { const path = filePath(directory, file.path); assert(!seen.has(path), `${result.name} scaffolds ${file.path} twice`); seen.add(path); }
+    }
+    await mkdir(dirname(directory), { recursive: true });
+    await mkdir(directory, { mode: 0o700 }); // refuses an existing destination
+    try {
+      await initProject(project);
+      const starter = await readFile(join(project, 'README.md'), 'utf8');
+      await unlink(join(project, 'README.md')); // its content moves into the site README
+      await unlink(join(project, mcpConfigFile)); // re-registered at the site root, pointing at app/
+      // Refuse routes or extensions the starter already declares, including in its included files.
+      const loaded = await loadDocument(project);
+      for (const key of Object.keys(routes)) assert(!Object.hasOwn(loaded.routes, key), `Route ${key} from ${owners.get('r:' + key)} already exists in the starter`);
+      for (const key of Object.keys(extensions)) assert(!Object.hasOwn(loaded.document.extensions ?? {}, key), `Extension ${key} from ${owners.get('e:' + key)} already exists in the starter`);
+      const yamlFile = join(project, 'urlcode.yaml'), original = await readFile(yamlFile, 'utf8');
+      const doc = parseDocument(original);
+      // Extensions are declared in the entry file; their routes go into a last include so the starter's own routes
+      // stay first in the loaded order and the entry file stays small.
+      doc.set('extensions', { ...loaded.document.extensions, ...extensions });
+      doc.addIn(['includes'], ROUTES_FILE);
+      const fragment = stringify({ version: '1', routes });
+      validateDocument(doc.toJS()); validateDocument(parseYaml(fragment));
+      await write(join(project, ROUTES_FILE), `# Routes added by urlcode init --with ${names.join(',')}. Mounts are exclusive to the named extension.\n${fragment}`);
+      await rm(yamlFile); await write(yamlFile, String(doc));
+      await loadDocument(project);
+      const projectSha256 = await inspectExtensionRevision(project);
+      const written = new Set        ();
+      for (const result of results) for (const file of result.files) {
+        const target = filePath(directory, file.path);
+        assert(!written.has(target), `Scaffold file ${file.path} is written by more than one extension`);
+        // Parent directories are created; existing files or symlinks anywhere on the path are refused.
+        let probe = dirname(target);
+        while (probe !== directory && probe.startsWith(directory)) { try { assert(!(await lstat(probe)).isSymbolicLink(), `Scaffold path passes through a symlink: ${file.path}`); } catch (error) { if (!isCode(error, 'ENOENT')) throw error; } probe = dirname(probe); }
+        await write(target, file.content, file.mode ?? 0o644); written.add(target);
+      }
+      await write(hostFile, renderHost(names, results), 0o600);
+      await write(join(directory, 'README.md'), renderReadme(directory, names, results, starter, env, projectSha256));
+      await write(join(directory, '.gitignore'), 'node_modules/\ndata/\n.env\n.env.*\n');
+      // The read-only MCP server for agents opened at the site root; --host-file and --allow-authoring stay operator choices.
+      await write(join(directory, mcpConfigFile), renderMcpConfig(PROJECT_DIRECTORY));
+      // AGENTS.md: initProject writes the application-level file into app/ once it produces one (NEXT-STEPS 1.1);
+      // nothing here overrides it. A site-level agent note would be assembled beside README.md at this point.
+      return { directory, project, hostFile, extensions: [...names], projectSha256, nextSteps: results.flatMap(result => result.nextSteps) };
+    } catch (error) { await rm(directory, { recursive: true, force: true }); throw error; }
+  } finally { wipe(); }
+}

package/dist/interchange-cli.js

@@ -0,0 +1,42 @@
+import { open, unlink } from 'node:fs/promises';
+import { extname } from 'node:path';
+import { loadDocument } from './config.js';
+import { importRoutes, exportRoutes } from './interchange.js';
+                                                                            
+import { assert } from './errors.js';
+                                                                                                                                                                                                                                
+export async function readConversionInput(file       )                 {
+  const handle=await open(file,'r');
+  try {
+    const stat=await handle.stat();assert(stat.isFile()&&stat.size<=32*1024*1024,'Conversion input must be a regular file of at most 32 MiB');
+    const buffer=Buffer.alloc(stat.size+1);let size=0;
+    while(size<buffer.length){const result=await handle.read(buffer,size,buffer.length-size,null);if(!result.bytesRead)break;size+=result.bytesRead;}
+    assert(size<=stat.size,'Conversion source grew during read');
+    return new TextDecoder('utf-8',{fatal:true}).decode(buffer.subarray(0,size));
+  } finally {await handle.close();}
+}
+export async function runInterchange(command                  ,args         ,options                      )                                                 {
+  assert(!options.report||options.report==='json','Use --report json');
+  const explicit=args.length===2?args[0]:undefined;
+  const file=args.length===2?args[1]:args[0];
+  assert(command==='import'?!!file&&args.length<=2:args.length===0,'Invalid conversion arguments');
+  const format=(options.format??(command==='export'?options.target:explicit??extname(file ).slice(1)))                     ;
+  let report                 ;
+  if(command==='import') report=await importRoutes({format,text:await readConversionInput(file ),source:file ,acceptProviderDifferences:options.acceptProviderDifferences===true});
+  else {
+    const loaded=await loadDocument(options.project);
+    const {includes:_includes,...document}=loaded.document;
+    report=await exportRoutes({format,document:{...document,routes:loaded.routes},source:options.project,acceptProviderDifferences:options.acceptProviderDifferences===true});
+  }
+  if(report.ok&&options.out&&!options.dryRun) {
+    const handle=await open(options.out,'wx',0o600);
+    try {await handle.writeFile(report.output );await handle.sync();}
+    catch(error){await handle.close();await unlink(options.out);throw error;}
+    await handle.close();
+  }
+  // Acknowledged non-lossless conversion always carries a report, even when
+  // output is written to a file; warnings cannot disappear into raw stdout.
+  const text=options.report==='json'||options.dryRun||options.out||!report.ok||!report.lossless
+    ? JSON.stringify(report)+'\n' : report.output ;
+  return {report,text};
+}