@jimhoyd/urlcode 0.3.0 → 0.4.0-alpha.2

package/dist/interchange.js

@@ -0,0 +1,189 @@
+import { stringify } from 'yaml';
+import { parseYaml, validateDocument, MAX_CONFIG_BYTES } from './config.js';
+import { compileRoutes } from './router.js';
+                                                                               
+
+                                                                                                               
+                                                                                                                                                   
+                                   
+                                                                                      
+                                                                                
+ 
+                                                                                                                                                                                                   
+                                                                                                                                      
+                                                                                                                                                   
+                                                                        
+const formats = new Set(['csv','json','yaml','netlify','cloudflare','vercel','netlify-toml']);
+const providers = new Set(['netlify','cloudflare','vercel','netlify-toml']);
+const statuses = new Set([301,302,303,307,308]);
+function record(value         )                          {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('Expected an object');
+  return value                           ;
+}
+function keys(value                         , allowed          )       {
+  if (Object.keys(value).some(key => !allowed.includes(key))) throw new Error('Unsupported field; conversion would discard behavior');
+}
+function row(value         , index        )      {
+  const item = record(value); keys(item, ['path','url','status']);
+  if (typeof item.path !== 'string' || typeof item.url !== 'string' || (item.status !== undefined && typeof item.status !== 'number')) throw new Error('Expected path and url strings and optional numeric status');
+  const status = item.status === undefined ? 302 : item.status          ;
+  if (!statuses.has(status)) throw new Error('Unsupported redirect status');
+  if (!/^\/[A-Za-z0-9_./~-]*$/.test(item.path)) throw new Error('Only literal ASCII paths are supported; patterns, escapes and conditions require the runtime');
+  if (/[{}]/.test(item.url)) throw new Error('Destination placeholders require the runtime');
+  return {path:item.path,url:item.url,status,row:index};
+}
+/** RFC 4180-style fields, including quoted commas/newlines and escaped quotes. */
+function csv(text        )                                {
+  const result                                = []; let cells          = [], cell = '', quoted = false, closed = false, line = 1, start = 1;
+  for (let i=0;i<text.length;i++) {
+    const ch=text[i] ;
+    if (quoted) { if(ch==='"') { if(text[i+1]==='"'){cell+='"';i++;}else{quoted=false;closed=true;} }else{cell+=ch;if(ch==='\n')line++;} continue; }
+    if(ch==='"'){if(cell || closed)throw new Error(`Invalid CSV quoting at row ${line}`);quoted=true;continue;}
+    if(ch===',' || ch==='\n' || ch==='\r') {
+      cells.push(cell);cell='';closed=false;
+      if(ch!==','){if(ch==='\r'&&text[i+1]==='\n')i++;result.push({cells,row:start});cells=[];line++;start=line;}
+      continue;
+    }
+    if(closed)throw new Error(`Unexpected data after CSV quote at row ${line}`);cell+=ch;
+  }
+  if(quoted)throw new Error(`Unterminated CSV quote at row ${start}`);
+  if(cell || cells.length || closed){cells.push(cell);result.push({cells,row:start});}
+  return result;
+}
+function parseRows(format                   , text        , add                                    )       {
+  if(format==='csv') {
+    const entries=csv(text), header=entries.shift()?.cells;
+    if(!header || header.join(',')!=='path,url,status')throw new Error('CSV header must be path,url,status');
+    for(const entry of entries){if(entry.cells.length!==3)throw new Error(`CSV row ${entry.row} must have three fields`);add({path:entry.cells[0],url:entry.cells[1],...(entry.cells[2] ? {status:Number(entry.cells[2])}: {})},entry.row);}
+  }else if(format==='netlify'||format==='cloudflare') {
+    for(const [i,line] of text.split(/\r?\n/).entries()) {
+      const trimmed=line.trim();if(!trimmed||trimmed.startsWith('#'))continue;
+      const fields=trimmed.split(/\s+/);if(fields.length<2||fields.length>3)throw new Error(`Unsupported redirect fields at row ${i+1}`);
+      const status=fields[2] === undefined ? (format==='netlify'?301:302) : Number(fields[2]);
+      add({path:fields[0],url:fields[1],status},i+1);
+    }
+  }else if(format==='netlify-toml') {
+    // Deliberately a redirects-only grammar, not a general TOML implementation.
+    let current                                 , start=0;
+    const finish=()=>{if(current)add({path:current.from,url:current.to,status:current.status??301},start);};
+    for(const [i,line]of text.split(/\r?\n/).entries()) {
+      const value=line.trim();if(!value||value.startsWith('#'))continue;
+      if(value==='[[redirects]]'){finish();current={};start=i+1;continue;}
+      const match=/^(from|to|status)\s*=\s*(.+)$/.exec(value);
+      if(!current||!match||Object.hasOwn(current,match[1] ))throw new Error(`Unsupported or duplicate TOML declaration at row ${i+1}`);
+      const key=match[1] , literal=match[2] ;
+      if(key==='status'){if(!/^\d{3}$/.test(literal))throw new Error(`Invalid TOML status at row ${i+1}`);current[key]=Number(literal);}
+      else { if(!/^"[^"\\\u0000-\u001f]*"$/u.test(literal))throw new Error(`Only unescaped basic TOML strings are supported at row ${i+1}`);current[key]=literal.slice(1,-1); }
+    }
+    finish();
+  }else {
+    const data        =format==='json'||format==='vercel'?JSON.parse(text):parseYaml(text);
+    // Apply the same reserved-key/depth/JSON-value policy to JSON inputs.
+    if(format==='json'||format==='vercel')parseYaml(text);
+    if(format==='vercel') {
+      const doc=record(data);keys(doc,['redirects']);if(!Array.isArray(doc.redirects))throw new Error('Expected redirects array');
+      doc.redirects.forEach((value        ,i       )=>{const entry=record(value);keys(entry,['source','destination','permanent','statusCode']);
+        if(entry.permanent!==undefined&&(typeof entry.permanent!=='boolean'||entry.statusCode!==undefined))throw new Error(`Invalid permanent/statusCode at row ${i+1}`);
+        if(entry.permanent===undefined&&entry.statusCode===undefined)throw new Error(`Specify permanent or statusCode at row ${i+1}`);
+        add({path:entry.source,url:entry.destination,status:entry.statusCode??(entry.permanent?308:307)},i+1);});
+    }else {if(!Array.isArray(data))throw new Error('Expected an array of {path,url,status} rows');data.forEach((value        ,i       )=>add(value,i+1));}
+  }
+}
+function providerRows(format                  , rows      )      {
+  if(!providers.has(format))return;
+  if(rows.some(entry=> /:[A-Za-z_]|[*$]/.test(entry.url.replace(/^https?:\/\//,''))))throw new Error('Provider placeholder-like destinations cannot be converted safely');
+  if(format==='cloudflare'&&(rows.length>2000||rows.some(entry=>`${entry.path} ${entry.url} ${entry.status}`.length>1000)))throw new Error('Cloudflare Pages supports at most 2,000 static redirects and 1,000 characters per rule');
+}
+function differences(format                   , accepted        , source       )                        {
+  if(!providers.has(format))return [];
+  return [{severity:accepted?'warning':'error',code:'provider-semantics',source,message:(format==='netlify'||format==='netlify-toml'?'Netlify may forward incoming query parameters and let existing assets shadow redirects. ':'The provider request/query normalization and redirect method coverage are not guaranteed to match URLCode. ')+(format==='cloudflare'?'Cloudflare Pages Functions take precedence over _redirects. ':'')+'URLCode drops incoming queries and limits these routes to GET/HEAD; provider redirects can cover other methods. Only literal GET/HEAD requests without incoming queries, conflicting assets/functions or normalization are in scope. Explicit acknowledgment produces a non-lossless migration candidate; use the runtime for exact behavior.'}];
+}
+async function validateRows(rows      , source       , diagnostics                       )                          {
+  const routes                           =Object.create(null)                              ;
+  for(const entry of rows) {
+    if(Object.hasOwn(routes,entry.path)){diagnostics.push({severity:'error',code:'duplicate-path',source,row:entry.row,path:entry.path,message:'Duplicate route path; no rule is overwritten'});continue;}
+    routes[entry.path]={redirect:{url:entry.url,status:entry.status                                         }};
+  }
+  const document                ={version:'1',routes};
+  try {
+    validateDocument(document);
+    await compileRoutes({root:'.',document,routes,files:[],version:'interchange'},{});
+  }catch(error){
+    // On failure identify offending rows without exposing destination values.
+    let located=false, examined=0;
+    const deadline=performance.now()+10000;
+    for(let offset=0;offset<rows.length;offset+=128){
+      if(performance.now()>deadline||diagnostics.length>=100)break;
+      const chunk=rows.slice(offset,offset+128);
+      const subset                ={version:'1',routes:Object.fromEntries(chunk.map(entry=>[entry.path,routes[entry.path] ]))};
+      try{validateDocument(subset);await compileRoutes({root:'.',document:subset,routes:subset.routes,files:[],version:'interchange'},{});examined+=chunk.length;continue;}catch{/* Locate the failure inside this bounded chunk. */}
+      for(const entry of chunk){examined++;const one                ={version:'1',routes:{[entry.path]:routes[entry.path] }};
+        try{validateDocument(one);await compileRoutes({root:'.',document:one,routes:one.routes,files:[],version:'interchange'},{});}
+        catch{located=true;diagnostics.push({severity:'error',code:'invalid-route',source,row:entry.row,path:entry.path,message:'Invalid route path or redirect destination under the URLCode contract'});}
+        if(diagnostics.length>=100||performance.now()>deadline)break;
+      }
+    }
+    if(examined<rows.length)diagnostics.push({severity:'error',code:'diagnostic-limit',source,message:'Diagnostic scan stopped at its resource limit; remaining rows were not classified'});
+    if(!located)diagnostics.push({severity:'error',code:'invalid-project',source,message:error instanceof Error?error.message:'Invalid project'});
+  }
+  return document;
+}
+function counts(routeCount       , diagnostics                       , ok        )                  {
+  const runtimeRequiredRoutes=diagnostics.filter(item=>item.code==='runtime-required').length;
+  const unsupportedRows=diagnostics.filter(item=>['unsupported-row','invalid-route','duplicate-path'].includes(item.code)).length;
+  const providerDifferenceRoutes=diagnostics.some(item=>item.code==='provider-semantics')?routeCount:0;
+  return {convertedRoutes:ok?routeCount:0,nativeEquivalentRoutes:ok&&diagnostics.length===0?routeCount:0,runtimeRequiredRoutes,unsupportedRows,providerDifferenceRoutes,
+    fullyScanned:!diagnostics.some(item=>['invalid-input','invalid-project','diagnostic-limit'].includes(item.code))&&diagnostics.length<100};
+}
+function report(document                , diagnostics                       , output       )                  {
+  const ok=!diagnostics.some(d=>d.severity==='error');
+  const routeCount=Object.keys(document.routes).length;
+  return {ok,lossless:diagnostics.length===0,routeCount,counts:counts(routeCount,diagnostics,ok),diagnostics,...(ok?{document,output}:{})};
+}
+/** Pure conversion: does not read projects, resolve bindings, execute guests or write files. */
+export async function importRoutes(options                    )                           {
+  const source=options.source??'<input>', diagnostics                       =[],rows      =[];
+  try{
+    if(!formats.has(options.format))throw new Error('Unknown interchange format');
+    if(Buffer.byteLength(options.text)>MAX_CONFIG_BYTES)throw new Error('Input exceeds 32 MiB');
+    parseRows(options.format,options.text,(value,index)=>{
+      if(rows.length>=100000)throw new Error('Input exceeds 100,000 routes');
+      try{rows.push(row(value,index));}catch(error){diagnostics.push({severity:'error',code:'unsupported-row',source,row:index,message:error instanceof Error?error.message:'Invalid row'});}
+      if(diagnostics.length>=100)throw new Error('Stopped after 100 invalid rows');
+    });
+    providerRows(options.format,rows);
+    diagnostics.push(...differences(options.format,options.acceptProviderDifferences===true,source));
+    rows.sort((a,b)=>a.path<b.path?-1:a.path>b.path?1:0);
+    const document=await validateRows(rows,source,diagnostics);
+    return report(document,diagnostics,stringify(document));
+  }catch(error){diagnostics.push({severity:'error',code:'invalid-input',source,message:error instanceof SyntaxError?'Invalid input syntax':error instanceof Error?error.message:'Invalid input'});return{ok:false,lossless:false,routeCount:rows.length,counts:counts(rows.length,diagnostics,false),diagnostics};}
+}
+function encodedCsv(value       )        { return /[",\r\n]/.test(value)?`"${value.replaceAll('"','""')}"`:value; }
+export async function exportRoutes(options                    )                           {
+  const source=options.source??'<project>',diagnostics                       =[],rows      =[];
+  try{
+    if(!formats.has(options.format))throw new Error('Unknown interchange format');
+    keys(record(options.document),['version','routes']);validateDocument(options.document);
+    if(Object.keys(options.document.routes).length>100000)throw new Error('Input exceeds 100,000 routes');
+    for(const [path,config]of Object.entries(options.document.routes)) {
+      try{keys(record(config),['redirect']);if(!config.redirect)throw new Error('Only redirects can be exported');keys(record(config.redirect),['url','status']);rows.push(row({path,url:config.redirect.url,status:config.redirect.status??302},rows.length+1));}
+      catch{diagnostics.push({severity:'error',code:'runtime-required',source,path,message:'Only literal redirects with default methods and no extra behavior can be exported'});}
+    }
+    rows.sort((a,b)=>a.path<b.path?-1:a.path>b.path?1:0);
+    providerRows(options.format,rows);
+    diagnostics.push(...differences(options.format,options.acceptProviderDifferences===true,source));
+    const document=await validateRows(rows,source,diagnostics);
+    const simple=rows.map(({path,url,status})=>({path,url,status}));let output       ;
+    switch(options.format){
+      case 'csv':output='path,url,status\n'+simple.map(r=>[r.path,r.url,String(r.status)].map(encodedCsv).join(',')+'\n').join('');break;
+      case 'json':output=JSON.stringify(simple,null,2)+'\n';break;
+      case 'yaml':output=stringify(simple);break;
+      case 'vercel':output=JSON.stringify({redirects:simple.map(r=>({source:r.path,destination:r.url,statusCode:r.status}))},null,2)+'\n';break;
+      case 'netlify-toml':
+        if(simple.some(r=>/["\\]/.test(r.url)))throw new Error('TOML subset cannot represent escaped destination strings');
+        output=simple.map(r=>`[[redirects]]\nfrom = "${r.path}"\nto = "${r.url}"\nstatus = ${r.status}\n`).join('\n');break;
+      default:output=simple.map(r=>`${r.path} ${r.url} ${r.status}\n`).join('');
+    }
+    return report(document,diagnostics,output);
+  }catch(error){diagnostics.push({severity:'error',code:'invalid-project',source,message:error instanceof Error?error.message:'Invalid project'});return{ok:false,lossless:false,routeCount:rows.length,counts:counts(rows.length,diagnostics,false),diagnostics};}
+}

package/dist/manifest.js

@@ -0,0 +1,109 @@
+import {readFile} from 'node:fs/promises';
+import {join,relative} from 'node:path';
+import {capabilityTargets,analyzeCompiledCapabilities,routeCapabilities} from './capabilities.js';
+                                                                       
+import {parseYaml,safeFile} from './config.js';
+import {effectiveExtensionPolicies} from './extensions.js';
+import {egressUrl} from './egress.js';
+import {prepare} from './tooling.js';
+                                                 
+import {explainCompiledRoute} from './explain.js';
+                                                   
+
+// A generated description of what a project declares, for agents, reviews and
+// deployment tooling. It is derived from the compiled IR on every call, never
+// checked in as a source of truth, and it is deterministic: the same project
+// yields the same bytes. Nothing in it is a binding value or source text.
+
+export const MANIFEST_SCHEMA_VERSION=2;
+                                
+                                                                                                                                               
+                                                                                                                                            
+                                                                                                       
+                                                                                                             
+                                           
+ 
+                                                                                 
+                                                                                                     
+                           
+                                                                                                                                    
+                                                                           
+                                                                                                          
+                             
+                                                                                                        
+                                                          
+                                                                      
+ 
+const compare=(a       ,b       )       =>a<b?-1:a>b?1:0;
+const sorted=(values                 )         =>[...new Set(values)].sort(compare);
+const packageVersion=(JSON.parse(await readFile(new URL('../package.json',import.meta.url),'utf8'))                    ).version;
+function origin(url       )        {try{return egressUrl(url).origin;}catch{return url;}}
+/**
+ * Recipe provenance is read from an optional `recipe.yaml` beside the entry
+ * file (the shape `urlcode recipes` metadata uses: `id`, `description`, ...).
+ * Only its identifying fields are copied; an absent or unreadable file means no provenance.
+ */
+async function recipeProvenance(root       )                             {
+  let path       ;
+  try{path=await safeFile(root,'recipe.yaml');}catch{return [];}
+  let data        ;
+  try{data=parseYaml(await readFile(path,'utf8'));}catch{return [];}
+  if(!data||typeof data!=='object'||Array.isArray(data))return [];
+  const record=data                          ;
+  if(typeof record.id!=='string'||!/^[a-z0-9][a-z0-9-]{0,63}$/.test(record.id))return [];
+  const entry                 ={id:record.id};
+  for(const key of ['description','version','source']         )if(typeof record[key]==='string'&&record[key].length<=512)entry[key]=record[key];
+  return [entry];
+}
+/** Build the semantic manifest for a project from its compiled IR. Deterministic for a given project. */
+export async function buildManifest(project       ,options               ={})                   {
+  const {loaded,compiled,routes,chains,projectSha256}=await prepare(project,options);
+  const explanations=routes.map(route=>explainCompiledRoute(loaded,route,chains.get(route.pattern),{projectSha256,now:0})).sort((a,b)=>compare(a.path,b.path));
+  const functions=new Map                       (),middleware=new Map                       ();
+  const register=(table                           ,source       ,name       ,path       )=>{const key=`${source}#${name}`;const entry=table.get(key)??{source,export:name,routes:[]};entry.routes.push(path);table.set(key,entry);};
+  const env=new Set        (),secrets=new Set        (),proxy=new Set        (),signals=new Set        ();
+  const manifestRoutes                =[];
+  for(const explanation of explanations){
+    const declared=loaded.routes[explanation.path];
+    const routeEnv=sorted(Object.values(declared?.env??{}).flatMap(ref=>ref.env?[ref.env]:[])),routeSecrets=sorted(Object.values(declared?.secrets??{}).map(ref=>ref.secret));
+    for(const name of routeEnv)env.add(name);for(const name of routeSecrets)secrets.add(name);
+    if(declared?.proxy)proxy.add(origin(declared.proxy.url));for(const signal of declared?.signals??[])signals.add(origin(signal.url));
+    if(explanation.handler.kind==='function')register(functions,explanation.handler.source          ,explanation.handler.export          ,explanation.path);
+    for(const item of explanation.middleware)register(middleware,item.source,item.export,explanation.path);
+    const extensions                                      ={};
+    for(const name of Object.keys(explanation.policies.extensions).sort(compare))extensions[name]=explanation.policies.extensions[name] .requirement;
+    const targets={}                                    ;
+    for(const target of capabilityTargets)targets[target]=explanation.targets[target].compatible;
+    manifestRoutes.push({
+      path:explanation.path,methods:explanation.methods,handler:explanation.handler,enabled:explanation.enabled,
+      ...(explanation.expires?{expires:explanation.expires}:{}),...(explanation.generated?{generated:explanation.generated}:{}),...(explanation.description?{description:explanation.description}:{}),
+      middleware:explanation.middleware,parameters:explanation.inputs.parameters,...(explanation.inputs.body?{body:explanation.inputs.body}:{}),
+      policies:explanation.policies.names,extensions,cache:explanation.cache,bindings:{env:routeEnv,secrets:routeSecrets},egress:explanation.egress,
+      capabilities:explanation.capabilities,targets,
+    });
+  }
+  const extensionDeclarations                       ={};
+  for(const name of Object.keys(loaded.document.extensions??{}).sort(compare)){
+    const declaration=loaded.document.extensions [name] ;
+    extensionDeclarations[name]={version:declaration.version,configKeys:sorted(Object.keys(declaration.config??{})),
+      mounts:sorted(Object.entries(loaded.routes).filter(([,route])=>route.extension===name).map(([path])=>path)),
+      protectedRoutes:sorted(Object.entries(loaded.routes).filter(([,route])=>Object.hasOwn(effectiveExtensionPolicies(loaded.document,route),name)).map(([path])=>path))};
+  }
+  const targets={}                       ;
+  for(const target of capabilityTargets){const report=analyzeCompiledCapabilities(loaded.document,compiled,target,options.extensions);targets[target]={compatible:report.compatible,issues:report.issues.length};}
+  const capabilities=new Set                ();
+  for(const route of routes)for(const capability of routeCapabilities(route,loaded.document))capabilities.add(capability);
+  const modules=(table                           )=>[...table.values()].map(entry=>({...entry,routes:sorted(entry.routes)})).sort((a,b)=>compare(a.source,b.source)||compare(a.export,b.export));
+  return {
+    schemaVersion:MANIFEST_SCHEMA_VERSION,urlcode:packageVersion,entry:'urlcode.yaml',
+    files:loaded.files.map(file=>relative(loaded.root,file).split('\\').join('/')),
+    revision:projectSha256,configVersion:loaded.version,routeCount:manifestRoutes.length,routes:manifestRoutes,
+    capabilities:[...capabilities].sort(compare),extensions:extensionDeclarations,recipes:await recipeProvenance(loaded.root),
+    external:{env:sorted(env),secrets:sorted(secrets),egress:{proxy:sorted(proxy),signals:sorted(signals)},extensions:Object.keys(extensionDeclarations)},
+    functions:modules(functions),middleware:modules(middleware),targets,
+  };
+}
+/** The manifest as `build` writes it: two-space JSON with a trailing newline. */
+export function renderManifest(manifest         )        {return JSON.stringify(manifest,null,2)+'\n';}
+export const manifestFileName='manifest.json';
+export function manifestPath(out       )        {return join(out,manifestFileName);}

package/dist/match.js

@@ -19,7 +19,7 @@ import { HttpError } from './errors.js';
                                                                                                                    
 /** The part of a compiled route that request-time matching reads. router.ts widens it. */
                                  
-                                                                                     
+                                                                                                         
                                                                                         
  
                                                                                                                                              
@@ -64,7 +64,7 @@ export function matchRoute                          (compiled
       return p === actual;
     })) return { route, path };
   }
-  for (const route of compiled.mounts) if (route.prefix !== undefined && target.path.startsWith(route.prefix)) return { route, path: dict() };
+  for (const route of compiled.mounts) if (route.prefix !== undefined && (target.path.startsWith(route.prefix)||(route.extension&&target.path===route.prefix.slice(0,-1)))) return { route, path: dict() };
   return null;
 }
 function scalar(value        , type            )         {

package/dist/mcp-authoring.js

@@ -0,0 +1,147 @@
+import {lstat,readFile,open,rename,rm,mkdtemp} from 'node:fs/promises';
+import {join,extname,isAbsolute} from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {spawn} from 'node:child_process';
+import {parseDocument,isMap} from 'yaml';
+import {loadDocument,validateDocument,parseYaml,normalizeRouteAuth,MAX_CONFIG_BYTES} from './config.js';
+import {compileRoutes} from './router.js';
+import {prepareFunctionSnapshot,requestedPermissions} from './policy.js';
+import {validateProject} from './tooling.js';
+import {scaffoldProject} from './scaffold.js';
+import {addRecipe} from './recipes.js';
+import {authoringPath} from './authoring-files.js';
+import {assert} from './errors.js';
+                                                                            
+
+/**
+ * Authoring tools for `urlcode mcp --allow-authoring`. Every write lands inside
+ * the operator-selected project root (after realpath), through the existing
+ * authoring, recipe and scaffold paths. Nothing here reads bindings, creates
+ * grants, deploys, or touches operator policy, compliance rules, host files or
+ * link stores. The runners spawn the CLI against the same root only.
+ */
+const text={type:'string',maxLength:1024};
+const handler={anyOf:[{type:'string',maxLength:2048},{type:'object'}]};
+const middleware={type:'array',maxItems:32,items:{anyOf:[{type:'string',maxLength:1024},{type:'object'}]}};
+export const authoringDefinitions=[
+ {name:'create_route',description:'Add one route to urlcode.yaml or a named include under the project. The merged project is validated before the write; missing function sources are reported for scaffold_feature.',properties:{path:{type:'string',maxLength:2048},handler,middleware,file:text},required:['path','handler']},
+ {name:'add_recipe',description:'Copy a bundled recipe into a new directory inside the project (recipes add). dryRun reports the destination and writes nothing.',properties:{name:{type:'string',maxLength:64},destination:text,dryRun:{type:'boolean'}},required:['name','destination']},
+ {name:'scaffold_feature',description:'Create placeholder modules, pages and directories the project YAML references and that do not exist yet; existing files are never edited.',properties:{dryRun:{type:'boolean'}},required:[]},
+ {name:'run_validate',description:'Run `urlcode validate --local` against the project; returns exit code and bounded output.',properties:{},required:[]},
+ {name:'run_test',description:'Run `urlcode test` against the project (activates the local runtime and executes fixtures); returns exit code and bounded output.',properties:{},required:[]},
+ {name:'run_audit',description:'Run `urlcode audit` against the project; returns exit code and bounded output.',properties:{},required:[]},
+];
+const isCode=(error        ,code       )        =>error instanceof Error&&'code' in error&&error.code===code;
+// Operator-owned material never lives under an authoring write, even when an
+// operator mistakenly placed it in the checkout.
+const operatorFile=/^(?:.*policy.*\.json|.*compliance.*\.(?:json|mjs|js|cjs|ts)|host(?:-file)?\.(?:mjs|js|cjs|ts)|.*\.(?:sqlite3?|db)(?:-wal|-shm|-journal)?|urlcode\.yaml\.lock)$/i;
+/** A project-relative path an authoring tool may create or replace: no absolute, `..`, hidden (`.env*`, `.git`), credential or operator names, and no symlink anywhere on the walk. */
+export async function confinedPath(root       ,path        )                 {
+ assert(typeof path==='string'&&path.length>0&&!isAbsolute(path)&&!path.includes('\\')&&!/^[A-Za-z]:/.test(path),'Authoring paths must be project-relative');
+ authoringPath(path);
+ const parts=path.split('/');
+ assert(parts.every(part=>!operatorFile.test(part)&&!/^\.env/i.test(part)&&part!=='.git'),'Authoring never writes operator, credential or version-control files');
+ let file=root;
+ for(const part of parts){
+  file=join(file,part);let info;
+  try{info=await lstat(file);}catch(error){if(isCode(error,'ENOENT'))break;throw error;}
+  assert(!info.isSymbolicLink(),'Authoring through symlinks is forbidden');
+ }
+ return join(root,path);
+}
+async function verdict(root       ,origin        ) {
+ try{return await validateProject(root,origin?{origin}:{});}
+ catch{return {valid:false         ,note:'Project does not validate; call run_validate for the CLI report.'};}
+}
+function object(value        )                                {return value!==null&&typeof value==='object'&&!Array.isArray(value);}
+function expandHandler(path       ,handler        )                        {
+ if(object(handler))return handler;
+ assert(typeof handler==='string','Handler must be a route object or a short form');
+ if(/^https?:\/\//.test(handler))return {redirect:{url:handler}};
+ assert(['.js','.mjs'].includes(extname(handler)),'Short-form handler must be an HTTP(S) URL or a .js/.mjs function source');
+ // Written as the YAML short form; validateDocument expands it to the canonical parameters/args (see normalizeRoute).
+ return {function:handler};
+}
+function expandMiddleware(value        )                                       {
+ if(value===undefined)return undefined;
+ assert(Array.isArray(value),'middleware must be a list');
+ return value.map(entry=>{if(typeof entry==='string')return entry;assert(object(entry),'middleware entries must be sources or objects');return entry                               ;});
+}
+async function sources(root       ,route            )                                              {
+ const present         =[],missing         =[];
+ for(const definition of [...(route.middleware??[]),...(route.function?[route.function]:[])]){
+  const source=definition.source;
+  let exists=false;try{await confinedPath(root,source);exists=(await lstat(join(root,source))).isFile();}catch(error){if(!isCode(error,'ENOENT'))throw error;}
+  (exists?present:missing).push(source);
+ }
+ return {present,missing:[...new Set(missing)]};
+}
+async function createRoute(root       ,args                       ,origin        ) {
+ const path=args.path;assert(typeof path==='string'&&path.startsWith('/'),'Route path must start with /');
+ const loaded=await loadDocument(root);
+ const file=typeof args.file==='string'?args.file:'urlcode.yaml';
+ assert(file==='urlcode.yaml'||(loaded.document.includes??[]).includes(file),'file must be urlcode.yaml or an include listed in it');
+ const target=await confinedPath(root,file);
+ assert(!Object.hasOwn(loaded.routes,path),'Route already exists');
+ const route={...expandHandler(path,args.handler)};
+ const middleware=expandMiddleware(args.middleware);if(middleware)route.middleware=middleware;
+ const lockPath=join(root,'urlcode.yaml.lock'),lock=await open(lockPath,'wx',0o600);
+ let temp                 ;
+ try {
+  const original=await readFile(target);assert(original.length<=MAX_CONFIG_BYTES,'Configuration exceeds 32 MiB');
+  const latest=await loadDocument(root);assert(!Object.hasOwn(latest.routes,path),'Route already exists');
+  const doc=parseDocument(original.toString('utf8'),{uniqueKeys:false});
+  doc.setIn(['routes',path],route);
+  const routesNode=doc.getIn(['routes']);if(isMap(routesNode))routesNode.flow=false;
+  const data=validateDocument(parseYaml(String(doc)));
+  const added=data.routes[path];assert(added,'Route was not written');
+  const routes={...latest.routes,[path]:added};
+  normalizeRouteAuth(latest.document,routes);
+  const candidate               ={...latest,routes};
+  const {present,missing}=await sources(root,added);
+  if(!missing.length){
+   // Same pre-write check as `urlcode add`: shape and references with dummy values, no credential reads, no execution, no grant.
+   const snapshot=await prepareFunctionSnapshot(candidate),bindings                      =Object.create(null)                         ;
+   for(const value of Object.values(routes)){for(const ref of Object.values(value.env||{}))if(ref.env)bindings[ref.env]='validation-only';for(const ref of Object.values(value.secrets||{}))bindings[ref.secret]='validation-only';}
+   await compileRoutes(candidate,bindings,requestedPermissions(candidate,snapshot),snapshot.projectSha256);
+  }
+  temp=await mkdtemp(join(root,'.urlcode-edit-'));
+  const temporary=join(temp,'edit.yaml'),out=await open(temporary,'wx',0o600);
+  try{await out.writeFile(String(doc));await out.sync();}finally{await out.close();}
+  assert((await readFile(target)).equals(original),'Configuration changed during edit; retry');
+  await rename(temporary,target);
+  return {created:true,path,file,route:added,sources:present,missingSources:missing,next:missing.length?'Call scaffold_feature to create placeholder modules, then implement them.':null,validation:await verdict(root,origin)};
+ } finally {if(temp)await rm(temp,{recursive:true,force:true});await lock.close();await rm(lockPath,{force:true});}
+}
+const outputLimit=32768;
+function bounded(chunks         )                                 {
+ const all=Buffer.concat(chunks);return {text:all.subarray(0,outputLimit).toString('utf8'),truncated:all.length>outputLimit};
+}
+async function runCli(root       ,command                          ,origin        ) {
+ const cli=fileURLToPath(new URL('./cli.js',import.meta.url));
+ const args=[cli,command,'--project',root,...(command==='validate'?['--local']:[]),...(origin?['--origin',origin]:[])];
+ // A fresh minimal environment: the runner never forwards this process's ambient variables to the project.
+ const child=spawn(process.execPath,args,{cwd:root,env:{PATH:process.env.PATH??''},stdio:['ignore','pipe','pipe']});
+ const stdout         =[],stderr         =[];let total=0;
+ const collect=(sink         )=>(chunk       )=>{if(total<outputLimit*4){sink.push(chunk);total+=chunk.length;}};
+ child.stdout.on('data',collect(stdout));child.stderr.on('data',collect(stderr));
+ const timer=setTimeout(()=>child.kill('SIGKILL'),120000);
+ const exit=await new Promise                                               ((resolve,reject)=>{child.once('error',reject);child.once('close',(code,signal)=>resolve({code,signal}));}).finally(()=>clearTimeout(timer));
+ const out=bounded(stdout),err=bounded(stderr);
+ return {command,exitCode:exit.code,signal:exit.signal,stdout:out.text,stderr:err.text,truncated:out.truncated||err.truncated};
+}
+export async function callAuthoringTool(root       ,name       ,args                       ,origin        )                  {
+ switch(name){
+  case 'create_route':return createRoute(root,args,origin);
+  case 'add_recipe':{
+   const destination=await confinedPath(root,args.destination);
+   const report=await addRecipe(args.name          ,destination,{dryRun:args.dryRun===true});
+   return {...report,output:args.destination,validation:await verdict(root,origin)};
+  }
+  case 'scaffold_feature':return {...await scaffoldProject(root,{dryRun:args.dryRun===true}),validation:await verdict(root,origin)};
+  case 'run_validate':return runCli(root,'validate',origin);
+  case 'run_test':return runCli(root,'test',origin);
+  case 'run_audit':return runCli(root,'audit',origin);
+  default:throw new Error('Unknown tool');
+ }
+}

package/dist/mcp.js

@@ -0,0 +1,97 @@
+import {realpath} from 'node:fs/promises';
+                                                   
+import {once} from 'node:events';
+import {Ajv} from 'ajv';
+import {inspectProject,validateProject,explainRoute,getCapabilities,getCapability,getSchemaFragment,previewImport,previewExport,listRecipes,showRecipe,searchRecipes,searchExamples,describeExtensions,buildContext} from './tooling.js';
+import {loadOperatorHost} from './operator-host.js';
+import {buildManifest} from './manifest.js';
+                                                        
+import {authoringDefinitions,callAuthoringTool} from './mcp-authoring.js';
+const protocolVersion='2025-11-25';
+const maxBytes=1048576;
+const text={type:'string',maxLength:8192};
+const format={enum:['csv','json','yaml','netlify','cloudflare','vercel','netlify-toml']};
+const definitions=[
+ {name:'inspect',description:'Inspect semantically validated route metadata without binding values or code execution.',properties:{target:text,offset:{type:'integer',minimum:0},limit:{type:'integer',minimum:1,maximum:1000}}},
+ {name:'validate',description:'Validate project syntax and route/policy semantics without activation.',properties:{}},
+ {name:'capabilities',description:'Describe implementation compatibility, separately from deployment evidence.',properties:{target:text}},
+ {name:'get_capability',description:'Describe one catalog capability: schema fragment, constraints, grants, target support and bundled recipe/cookbook uses.',properties:{name:{type:'string',maxLength:64}},required:['name']},
+ {name:'get_schema',description:'Return the resolved JSON Schema fragment for a dotted urlcode.yaml path such as route, redirect or policies.cache.',properties:{path:{type:'string',maxLength:256}},required:['path']},
+ {name:'explain',description:'Explain the route a path selects from the compiled configuration: methods, handler, middleware, inputs, policies, cache outcome, bindings and target support. Nothing executes.',properties:{target:text},required:['target']},
+ {name:'get_manifest',description:'The generated semantic manifest: routes, capabilities, extensions, external requirements, functions, target support and the revision digest.',properties:{}},
+ {name:'import_preview',description:'Preview redirect conversion from supplied text; writes no files.',properties:{format,text:{type:'string',maxLength:524288},acceptProviderDifferences:{type:'boolean'}},required:['format','text']},
+ {name:'export_preview',description:'Preview redirect export from this project; writes no files.',properties:{format,acceptProviderDifferences:{type:'boolean'}},required:['format']},
+ {name:'recipes_list',description:'List bundled local recipes.',properties:{}},
+ {name:'recipes_show',description:'Show a bundled local recipe without writing it; metadata (capabilities, targets, grants, inputs, expected behavior) comes before file contents.',properties:{name:{type:'string',maxLength:64}},required:['name']},
+ {name:'search_recipes',description:'Search bundled recipes by id, description, tags and capabilities; local text matching, no service. Check here before generating a common route by hand.',properties:{text:{type:'string',maxLength:256}},required:['text']},
+ {name:'search_examples',description:'Search bundled runnable examples and the cookbook route index; returns the smallest matching example and its route.',properties:{text:{type:'string',maxLength:256}},required:['text']},
+ {name:'get_context',description:'Emit the compact project context an authoring agent needs: versions, project summary, constraints, target support and exact commands, derived from the compiled project. Optional token budget drops sections in a fixed order.',properties:{target:text,budget:{type:'integer',minimum:1}}},
+];
+// Only the operator's own --host-file exposes registered extension contracts; no tool argument can name one.
+const hostDefinition={name:'get_extensions',description:'List operator-registered extension contracts with configuration and policy JSON Schemas and where the project mounts them; activates nothing.',properties:{}};
+const ajv=new Ajv({strict:false});
+const readTools=definitions.map(def=>({name:def.name,description:def.description,inputSchema:{type:'object',properties:def.properties,required:def.required??[],additionalProperties:false},annotations:{readOnlyHint:true,destructiveHint:false,openWorldHint:false}}));
+const hostTool={name:hostDefinition.name,description:hostDefinition.description,inputSchema:{type:'object',properties:hostDefinition.properties,required:[],additionalProperties:false},annotations:{readOnlyHint:true,destructiveHint:false,openWorldHint:false}};
+const authoringTools=authoringDefinitions.map(def=>({name:def.name,description:def.description,inputSchema:{type:'object',properties:def.properties,required:def.required,additionalProperties:false},annotations:{readOnlyHint:false,destructiveHint:false,openWorldHint:false}}));
+const validators=new Map([...readTools,hostTool,...authoringTools].map(tool=>[tool.name,ajv.compile(tool.inputSchema)]));
+function object(value        )                                {return value!==null&&typeof value==='object'&&!Array.isArray(value);}
+/** `allowAuthoring` and `hostFile` are set only by the `--allow-authoring` and `--host-file` command-line flags; tool arguments and the environment never enable them. */
+                                                                                                                                     
+/** Operator selects the only project root. Read tools have no path, credential, write or execution authority; authoring tools write inside that root only. */
+export async function serveMcp(options           )               {
+ const project=await realpath(options.project),input=options.input??process.stdin,output=options.output??process.stdout;
+ const authoring=options.allowAuthoring===true,tools=[...readTools,...(options.hostFile===undefined?[]:[hostTool]),...(authoring?authoringTools:[])],names=new Set(tools.map(tool=>tool.name));
+ const host=await loadOperatorHost(options.hostFile,project);
+ try{await serve();}finally{await host.close?.();}
+ async function serve()               {
+ let initialized=false,ready=false,pending=Buffer.alloc(0);
+ const send=async(value        )=> {let line=JSON.stringify(value);if(Buffer.byteLength(line)>maxBytes)line=JSON.stringify({jsonrpc:'2.0',id:object(value)?value.id??null:null,error:{code:-32603,message:'Result exceeds output limit'}});if(!output.write(line+'\n'))await once(output,'drain');};
+ const error=(id        ,code       ,message       )=>send({jsonrpc:'2.0',id,error:{code,message}});
+ const call=async(name       ,args                       )                 => {
+  const base=options.origin?{origin:options.origin}:{};
+  switch(name){
+   case 'inspect':return inspectProject(project,{...base,...args}                                        );
+   case 'validate':return validateProject(project,base);
+   case 'capabilities':return getCapabilities(args.target                    );
+   case 'get_capability':return getCapability(args.name          );
+   case 'get_schema':return getSchemaFragment(args.path          );
+   case 'explain':return explainRoute(project,args.target          ,base);
+   case 'get_manifest':return buildManifest(project,base);
+   case 'import_preview':return previewImport({format:args.format                     ,text:args.text          ,acceptProviderDifferences:args.acceptProviderDifferences===true});
+   case 'export_preview':return previewExport(project,args.format                     ,args.acceptProviderDifferences===true);
+   case 'recipes_list':return listRecipes();
+   case 'recipes_show':return showRecipe(args.name          );
+   case 'search_recipes':return searchRecipes(args.text          );
+   case 'search_examples':return searchExamples(args.text          );
+   case 'get_extensions':return describeExtensions(project,host.extensions??[]);
+   case 'get_context':return buildContext(project,{projectFlag:'.',...(typeof args.target==='string'?{target:args.target}:{}),...(typeof args.budget==='number'?{budget:args.budget}:{})});
+   default:if(authoring)return callAuthoringTool(project,name,args,options.origin);throw new Error('Unknown tool');
+  }
+ };
+ const line=async(bytes       )=> {
+  let message        ;try{message=JSON.parse(new TextDecoder('utf-8',{fatal:true}).decode(bytes));}catch{await error(null,-32700,'Parse error');return;}
+  if(!object(message)||message.jsonrpc!=='2.0'||typeof message.method!=='string'||('id'in message&&typeof message.id!=='string'&&!(typeof message.id==='number'&&Number.isSafeInteger(message.id)))) {await error(null,-32600,'Invalid request');return;}
+  const id=message.id;
+  if(id===undefined){if(message.method==='notifications/initialized'&&initialized)ready=true;return;}
+  const params=message.params??{};
+  if(!object(params)){await error(id,-32602,'Invalid params');return;}
+  if(message.method==='initialize') {
+   if(initialized){await error(id,-32600,'Already initialized');return;}
+   if(typeof params.protocolVersion!=='string'||!object(params.capabilities)||!object(params.clientInfo)||typeof params.clientInfo.name!=='string'||typeof params.clientInfo.version!=='string'){await error(id,-32602,'Invalid initialize params');return;}
+   initialized=true;await send({jsonrpc:'2.0',id,result:{protocolVersion,capabilities:{tools:{}},serverInfo:{name:'urlcode',version:'0.4.0-alpha.2'}}});return;
+  }
+  if(message.method==='ping'){await send({jsonrpc:'2.0',id,result:{}});return;}
+  if(!ready){await error(id,-32002,'Initialize first');return;}
+  if(message.method==='tools/list'){await send({jsonrpc:'2.0',id,result:{tools}});return;}
+  if(message.method!=='tools/call'){await error(id,-32601,'Method not found');return;}
+  const name=params.name,args=params.arguments??{};
+  if(typeof name!=='string'||!names.has(name)||!validators.get(name) (args)){await error(id,-32602,'Invalid tool or arguments');return;}
+  try{const result=await call(name,args                          );await send({jsonrpc:'2.0',id,result:{content:[{type:'text',text:JSON.stringify(result)}]}});}catch{await send({jsonrpc:'2.0',id,result:{isError:true,content:[{type:'text',text:'Operation failed validation; inspect locally for details.'}]}});}
+ };
+ for await(const chunk of input){const bytes=Buffer.isBuffer(chunk)?chunk:Buffer.from(chunk          );let start=0;
+  for(let index=0;index<bytes.length;index++){if(bytes[index]!==10)continue;if(pending.length+index-start>maxBytes){await error(null,-32600,'Message exceeds input limit');return;}const message=Buffer.concat([pending,bytes.subarray(start,index)]);pending=Buffer.alloc(0);start=index+1;await line(message);}
+  if(pending.length+bytes.length-start>maxBytes){await error(null,-32600,'Message exceeds input limit');return;}pending=Buffer.concat([pending,bytes.subarray(start)]);
+ }
+ if(pending.length)await error(null,-32700,'Truncated message');
+ }
+}