@jimhoyd/urlcode 0.4.1 → 0.4.6

package/dist/extensions.js

@@ -1,6 +1,8 @@
 import Ajv from 'ajv/dist/2020.js';
+import { randomUUID } from 'node:crypto';
+import { pathToFileURL } from 'node:url';
 import { assert, HttpError } from './errors.js';
-import { loadDocument } from './config.js';
+import { functionFile, loadDocument } from './config.js';
 import { prepareFunctionSnapshot } from './policy.js';
 import { validateHeaderName, validateHeaderValue } from './header-validation.js';
                                                         
@@ -52,9 +54,99 @@ import { validateHeaderName, validateHeaderValue } from './header-validation.js'
  * vary on credentials. Everything else under the mount stays no-store.
  */
                                                            
+                                                                                                                  
+                                                              
+                                                
+/** Machine-readable contract for one project hook an extension exposes. */
+                                        
+              
+                         
+                     
+                     
+                       
+ 
+                                                                                                                         
+/** One project-owned customization surface, shown to people and authoring agents by CLI/MCP inspection. */
+                                            
+                              
+              
+                     
+                                                                                     
+               
+                                                                                
+                  
+ 
+/**
+ * Machine-readable guidance for changing an installed extension without
+ * copying its behavior into the application. This is descriptive only: it
+ * grants nothing and is never executed by the runtime.
+ */
+                                             
+                     
+                                                
+                                
+ 
+                                                                                                      
+/** Shared schema for project hook references. Omission means trusted execution. */
+export const extensionHookReferenceSchema={
+  oneOf:[
+    {type:'string',minLength:1,maxLength:1024},
+    {type:'object',additionalProperties:false,required:['source'],properties:{
+      source:{type:'string',minLength:1,maxLength:1024},
+      export:{type:'string',pattern:'^[A-Za-z_][A-Za-z0-9_]*$'},
+      sandbox:{type:'boolean'},
+      sandboxReason:{type:'string',minLength:1,maxLength:512},
+    }},
+  ],
+}         ;
+/** Builds the strict `config.hooks` schema from an extension's declared hook names. */
+export function extensionHooksSchema(contracts                                 )        {
+  return {type:'object',additionalProperties:false,properties:Object.fromEntries(contracts.map(contract=>[contract.name,extensionHookReferenceSchema]))};
+}
+/**
+ * Loads project hooks once per activation. Project hooks are trusted first-party
+ * code by default, matching function/middleware routes. Sandboxed arbitrary-value
+ * hooks are not part of contract v1 and are refused rather than run trusted.
+ */
+export async function loadExtensionHooks                  (config                                           ,contracts                                 ,context                                 )                                  {
+  const known=new Map(contracts.map(contract=>[contract.name,contract]));
+  const hooks                                        =Object.create(null)                                           ;
+  if(config===undefined)return hooks                           ;
+  assert(config&&typeof config==='object'&&!Array.isArray(config),'Extension hooks must be an object');
+  const epoch=randomUUID();
+  for(const [name,raw] of Object.entries(config)){
+    const contract=known.get(name);assert(contract,`Unknown extension hook: ${name}`);
+    assert(typeof raw==='string'||raw&&typeof raw==='object'&&!Array.isArray(raw),`Invalid extension hook: ${name}`);
+    const reference                       =typeof raw==='string'?{source:raw}:raw                          ;
+    if(reference.sandbox===true)throw new Error(`hook ${name}: sandbox: true is not supported for extension hooks; hooks run trusted by default`);
+    const exportName=reference.export??'default';
+    let modulePath       ;
+    try{modulePath=await functionFile(context.root,reference.source);}
+    catch(error){throw new Error(`hook ${name}: failed to load module "${reference.source}"`,{cause:error});}
+    let module                       ;
+    try{module=await import(pathToFileURL(modulePath).href+'?urlcode-extension-hook-epoch='+epoch)                          ;}
+    catch(error){throw new Error(`hook ${name}: failed to load module "${reference.source}"`,{cause:error});}
+    const fn=module[exportName];
+    if(typeof fn!=='function')throw new Error(`hook ${name}: export "${exportName}" in "${reference.source}" is not a function`);
+    const ajv=new Ajv.default({strict:false,allErrors:false});
+    const validateInput=ajv.compile(contract.inputSchema);
+    const validateOutput=contract.outputSchema?ajv.compile(contract.outputSchema):undefined;
+    hooks[name]=(input        )        =>{
+      assert(validateInput(input),`Invalid extension hook input: ${name}`);
+      const validate=(output        )        =>{if(validateOutput)assert(validateOutput(output),`Invalid extension hook output: ${name}`);return output;};
+      const output=(fn                            )(input);
+      return output instanceof Promise?output.then(validate):validate(output);
+    };
+  }
+  return hooks                           ;
+}
                                    
                                                                        
                                                                                                               
+                                                                                 
+                                          
+                                                                            
+                                        
      
                                                                                    
                                                                         
@@ -82,20 +174,39 @@ import { validateHeaderName, validateHeaderValue } from './header-validation.js'
                  
                                                                                        
                   
-                                                                                               
+                                                                                                                                                        
                           
+     
+                                                                                                                                   
+                                                                                                                                      
+                                                                                                                                 
+                                                                                           
+     
+                                     
  
                                                                                       
                                  
                                        
               
+     
+                                                                                                                                      
+                                                                                                                            
+                                                                                                                           
+                                                                                                                                 
+                                                         
+     
+                                                                               
+                                                                                                                                                                                       
+                         
+                                                                                                                                        
+                       
                                                                                                              
                                                                    
                                                                                                                             
                                                                                       
                                                                                                              
                        
-                                                                                                               
+                                                                                                                   
                                     
                                                                           
                              
@@ -105,6 +216,8 @@ import { validateHeaderName, validateHeaderValue } from './header-validation.js'
                                                                                                  
                                                                                                                              
 const namePattern=/^[a-z][a-z0-9-]{0,63}$/;
+const hookNamePattern=/^[a-z][A-Za-z0-9]{0,63}$/;
+const authoringNamePattern=/^[A-Za-z0-9][A-Za-z0-9 ._/-]{0,127}$/;
 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';
@@ -153,6 +266,28 @@ export function prepareExtensions(document                ,routes
     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');
+    const hookNames=new Set        ();
+    for(const hook of registration.hooks??[]){
+      assert(hook&&typeof hook==='object'&&hookNamePattern.test(hook.name)&&!hookNames.has(hook.name),'Invalid extension hook contract');
+      assert(['filter','action'].includes(hook.kind)&&typeof hook.description==='string'&&hook.description.length>=1&&hook.description.length<=512,'Invalid extension hook contract');
+      assert(hook.inputSchema&&typeof hook.inputSchema==='object'&&(!hook.outputSchema||typeof hook.outputSchema==='object'),'Invalid extension hook contract');
+      hookNames.add(hook.name);
+    }
+    if(registration.authoring!==undefined){
+      const authoring=registration.authoring;
+      assert(authoring&&typeof authoring==='object'&&typeof authoring.description==='string'&&authoring.description.length>=1&&authoring.description.length<=1024,'Invalid extension authoring contract');
+      assert(Array.isArray(authoring.surfaces)&&authoring.surfaces.length<=64,'Invalid extension authoring surfaces');
+      const surfaceNames=new Set        ();
+      for(const surface of authoring.surfaces){
+        assert(surface&&typeof surface==='object'&&['configuration','theme','copy','component','template','stylesheet','hook','extension'].includes(surface.kind),'Invalid extension authoring surface kind');
+        assert(typeof surface.name==='string'&&authoringNamePattern.test(surface.name)&&!surfaceNames.has(surface.name),'Invalid extension authoring surface name');
+        assert(typeof surface.description==='string'&&surface.description.length>=1&&surface.description.length<=1024,'Invalid extension authoring surface description');
+        assert(surface.path===undefined||typeof surface.path==='string'&&surface.path.length>=1&&surface.path.length<=1024,'Invalid extension authoring surface path');
+        assert(surface.command===undefined||typeof surface.command==='string'&&surface.command.length>=1&&surface.command.length<=2048,'Invalid extension authoring surface command');
+        surfaceNames.add(surface.name);
+      }
+      assert(authoring.fastChecks===undefined||Array.isArray(authoring.fastChecks)&&authoring.fastChecks.length<=32&&authoring.fastChecks.every(check=>typeof check==='string'&&check.length>=1&&check.length<=2048),'Invalid extension authoring fast checks');
+    }
     provided.set(registration.name,registration);
   }
   const declarations=document.extensions??{};

package/dist/http-policy.js

@@ -2,9 +2,11 @@ import { validateHeaderName, validateHeaderValue } from './header-validation.js'
 import { assert, HttpError } from './errors.js';
                                                                     
                                               
+import { assertBodySchema, bodySchemaIssues, bodySchemaLine, bodySchemaJson, prefersJson } from './body-schema.js';
+                                                   
 
                                                                                
-                                                                                                                               
+                                                                                                                                                    
 /** A static reply compiled from `respond`; the body is bytes so every host, including the Worker, shares the type. */
                                                                                   
 /** The declared HTTP surface of a route: response headers, request body policy and a static reply. */
@@ -18,14 +20,14 @@ import { assert, HttpError } from './errors.js';
 const encoder = new TextEncoder();
 const byteLength = (value        )         => encoder.encode(value).length;
 
-const reserved = new Set(['connection','keep-alive','transfer-encoding','content-length','upgrade','trailer','proxy-authenticate','proxy-authorization','te','location','allow','content-range','accept-ranges','etag','last-modified','content-encoding','x-request-id','x-content-type-options']);
+export const reservedResponseHeaders = new Set(['connection','keep-alive','transfer-encoding','content-length','upgrade','trailer','proxy-authenticate','proxy-authorization','te','location','allow','content-range','accept-ranges','etag','last-modified','content-encoding','x-request-id','x-content-type-options']);
 export function compileHttp(route           )       {
   const seen = new Set        (); let size = 0;
   const responseHeaders               = route.responseHeaders = [];
   for (const [name,value] of Object.entries(route.response?.headers || {})) {
     const key = name.toLowerCase();
     assert(!seen.has(key), 'Duplicate response header (case insensitive)'); seen.add(key);
-    assert(!reserved.has(key), 'Response header is owned by the runtime or handler');
+    assert(!reservedResponseHeaders.has(key), 'Response header is owned by the runtime or handler');
     assert(!Array.isArray(value) || key === 'set-cookie', 'Only Set-Cookie supports a header array');
     assert(!(route.page || route.static || route.download) || !['content-type','content-disposition','cache-control'].includes(key), 'Configure asset metadata on its handler');
     for (const item of Array.isArray(value) ? value : [value]) {
@@ -36,6 +38,11 @@ export function compileHttp(route           )       {
     }
   }
   assert(size <= 16384, 'Response headers exceed 16 KiB');
+  const bodySchema = route.request?.body?.schema;
+  if (bodySchema !== undefined) {
+    assert(route.request?.body?.format === 'json', 'request.body.schema requires format json');
+    assertBodySchema(bodySchema);
+  }
   if (route.respond) {
     const status = route.respond.status ?? 200;
     assert(![206,304].includes(status), 'Use native asset handlers for partial/conditional responses');
@@ -61,7 +68,15 @@ export function checkRequest(route           , body            , headers
     try { text = new TextDecoder('utf-8',{fatal:true}).decode(body); } catch { throw new HttpError(400,'Body must be UTF-8'); }
     if (policy.format === 'json') {
       if (!/^application\/(?:[\w.+-]+\+)?json$/.test(type)) throw new HttpError(415,'Expected JSON media type');
-      try { JSON.parse(text); } catch { throw new HttpError(400,'Invalid JSON body'); }
+      let parsed         ;
+      try { parsed = JSON.parse(text); } catch { throw new HttpError(400,'Invalid JSON body'); }
+      if (policy.schema) {
+        const issues = bodySchemaIssues(policy.schema, parsed);
+        if (issues.length) {
+          const text = `Request body failed validation\n${issues.map(bodySchemaLine).join('\n')}`;
+          throw new HttpError(422, text, prefersJson(headers.get('accept')) ? { contentType: 'application/json', text: bodySchemaJson(issues) } : undefined);
+        }
+      }
     }
   }
 }

package/dist/http-response.js

@@ -61,13 +61,13 @@ export function writeResponse(res                , result               , option
 // or sniffed whatever a project declares.
 export function errorResponse(error         , { requestId, method, headers = [] }                                              )              {
   const status = error instanceof HttpError ? error.status : 500;
-  const fixed               = [['content-type','text/plain; charset=utf-8'],['cache-control','no-store'],['x-request-id',requestId],['x-content-type-options','nosniff']];
+  const fixed               = [['content-type',error instanceof HttpError && error.answer ? error.answer.contentType : 'text/plain; charset=utf-8'],['cache-control','no-store'],['x-request-id',requestId],['x-content-type-options','nosniff']];
   const taken = new Set(fixed.map(([key]) => key));
   const extra = headers.filter(([key]) => !taken.has(key.toLowerCase()) && !forbiddenHeaders.has(key.toLowerCase()));
   // Runtime error messages are fixed words, and the answer is text/plain
   // with nosniff; markup characters are still stripped so the body can never
   // be read as HTML by a client that ignores both.
-  const text = `${error instanceof HttpError ? String(error.message).replace(/[<>&"']/g, '') : 'Internal server error'}\n`;
+  const text = error instanceof HttpError && error.answer ? error.answer.text + '\n' : `${error instanceof HttpError ? String(error.message).replace(/[<>&"']/g, '') : 'Internal server error'}\n`;
   const body = method === 'HEAD' ? undefined : text;
   // Stated explicitly so every host agrees, as prepareResponse does for results.
   return { status, headers: [...fixed, ['content-length', String(new TextEncoder().encode(text).length)], ...extra], body };

package/dist/init-with.js

@@ -14,13 +14,16 @@ import { ConfigError, assert } from './errors.js';
 
 /** Directory names inside the generated site. The route project lives under `app/`; everything else is operator-owned. */
 const PROJECT_DIRECTORY = 'app', HOST_FILE = 'host.mjs', ROUTES_FILE = 'routes/extensions.yaml';
-const namePattern = /^[a-z][a-z0-9-]{0,63}$/;
+const acknowledgementPattern = /^[a-z][a-z0-9-]{0,63}:[a-z][a-z0-9-]{0,63}$/;
+const namePattern = /^[a-z][a-z0-9-]{0,63}$/, capabilityPattern = /^[a-z][a-z0-9.:-]{0,63}$/;
                                   
                            
                                                                                                  
                                  
                                                                                             
                                                  
+                                                                                                                                                      
+                                                   
  
                                                                                                                                                                                          
 
@@ -35,12 +38,48 @@ const isCode = (error         , code        )          => error instanceof Error
 const strings = (value         )                    => Array.isArray(value) && value.every(item => typeof item === 'string');
 const record = (value         )                                   => value !== null && typeof value === 'object' && !Array.isArray(value);
 
+/**
+ * Orders the requested set from the scaffolds' declared `requires`, `after`, `provides` and `conflicts`, never from
+ * the `--with` spelling. Kahn's algorithm with the lexically smallest ready extension first, so the result is
+ * deterministic and identical for every permutation. Refuses a missing requirement, a conflict or a cycle by name.
+ */
+export function orderScaffolds(results                           )                   {
+  const byName = new Map                        (), providers = new Map                ();
+  for (const result of results) byName.set(result.name, result);
+  for (const result of results) for (const capability of result.provides ?? []) {
+    assert(!byName.has(capability) || capability === result.name, `${result.name} provides ${capability}, which is also an extension name`);
+    assert(!providers.has(capability) || providers.get(capability) === result.name, `Capability ${capability} is provided by both ${providers.get(capability)} and ${result.name}`);
+    providers.set(capability, result.name);
+  }
+  const locate = (dependency        )                     => byName.has(dependency) ? dependency : providers.get(dependency);
+  const edges = new Map                     (results.map(result => [result.name, new Set        ()]));
+  for (const result of results) {
+    for (const other of result.conflicts ?? []) { const target = locate(other); assert(target === undefined || target === result.name, `${result.name} conflicts with ${target}; remove one from --with`); }
+    for (const dependency of result.requires ?? []) {
+      const target = locate(dependency);
+      assert(target !== undefined, `${result.name} requires ${dependency}${byName.has(dependency) ? '' : ', which is not part of this composition; add the extension that provides it to --with'}`);
+      if (target !== result.name) edges.get(result.name) .add(target);
+    }
+    for (const dependency of result.after ?? []) { const target = locate(dependency); if (target !== undefined && target !== result.name) edges.get(result.name) .add(target); }
+  }
+  const ordered                   = [], placed = new Set        ();
+  while (ordered.length < results.length) {
+    const ready = [...byName.keys()].filter(name => !placed.has(name) && [...edges.get(name) ].every(dependency => placed.has(dependency))).sort();
+    if (ready.length === 0) {
+      const stuck = [...byName.keys()].filter(name => !placed.has(name)).sort();
+      throw new ConfigError(`Extension ordering has a cycle among ${stuck.map(name => `${name} (needs ${[...edges.get(name) ].filter(dependency => !placed.has(dependency)).sort().join(', ')})`).join('; ')}`);
+    }
+    placed.add(ready[0] ); ordered.push(byName.get(ready[0] ) );
+  }
+  return ordered;
+}
+
 /**
  * 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.
  */
-async function loadScaffold(name        , request                 , cwd        )                          {
+async function loadScaffold(name        , request                 , cwd        , retry                        )                          {
   const pkg = packageName(name);
   let entry        ;
   try { entry = createRequire(join(cwd, 'package.json')).resolve(pkg); }
@@ -53,11 +92,20 @@ async function loadScaffold(name        , request                 , cwd        )
   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)}`); }
+  catch (error) {
+    // A refusal that names an acknowledgement id gets the exact command that would proceed; the extension owns the id and the risk wording, core only formats the retry.
+    const id = record(error) ? error.acknowledgement : undefined;
+    const message = error instanceof Error ? error.message : String(error);
+    if (typeof id === 'string' && acknowledgementPattern.test(id) && id.startsWith(`${name}:`) && !request.acknowledgements.includes(id)) throw new ConfigError(`${pkg} scaffold refused: ${message}. If you accept that risk, re-run with the acknowledgement: ${retry(id)}`);
+    throw new ConfigError(`${pkg} scaffold refused: ${message}`);
+  }
   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(result.acknowledged === undefined || (strings(result.acknowledged) && result.acknowledged.every(id => request.acknowledgements.includes(id) && id.startsWith(`${name}:`))), `${pkg} scaffold acknowledged may only list ${name}:<id> acknowledgements the operator passed`);
+  assert(result.routeNotes === undefined || (strings(result.routeNotes) && result.routeNotes.every(note => note.length <= 300 && !/[\r\n]/.test(note))), `${pkg} scaffold routeNotes must be single-line strings`);
   assert(strings(result.nextSteps) && typeof result.readme === 'string', `${pkg} scaffold must return readme text and nextSteps strings`);
+  for (const key of ['provides', 'requires', 'after', 'conflicts']         ) assert(result[key] === undefined || (strings(result[key]) && (result[key]            ).every(item => capabilityPattern.test(item))), `${pkg} scaffold ${key} must list extension names or capability names`);
   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                             ;
@@ -78,7 +126,8 @@ async function write(target        , content                     , mode = 0o644)
 }
 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);
+  // Extensions that need the same module (node:url, for example) each list it; an identical line is written once so the host stays valid ESM.
+  for (const result of results) for (const line of result.hostImports) if (!lines.includes(line)) lines.push(line);
   lines.push('');
   for (const result of results) if (result.hostSetup.length) lines.push(...result.hostSetup);
   lines.push('export default {', '  extensions: [');
@@ -121,14 +170,26 @@ function renderReadme(directory        , names                   , results
  * `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(), manifest = true, pins }                  = {})                          {
-  assert(names.length > 0, 'Provide at least one --with name');
+export async function initProjectWith(destination        , requested                   , { cwd = process.cwd(), manifest = true, pins, acknowledgements = [] }                  = {})                          {
+  assert(requested.length > 0, 'Provide at least one --with name');
+  assert(new Set(requested).size === requested.length, 'Duplicate --with names');
+  // --with is an unordered set: scaffolds see one canonical name order, and the emitted order comes from their declared requirements.
+  const sorted = [...requested].sort();
   const directory = resolve(destination), project = join(directory, PROJECT_DIRECTORY), hostFile = join(directory, HOST_FILE);
-  const request                  = { directory, project, hostFile, names };
+  assert(acknowledgements.every(id => acknowledgementPattern.test(id)), 'Use --ack <extension>:<id>, for example --ack store:public-write');
+  const acked = [...new Set(acknowledgements)].sort();
+  const request                  = { directory, project, hostFile, names: sorted, acknowledgements: acked };
+  const quote = (value        )         => /^[\w@%+=:,./-]+$/.test(value) ? value : `'${value.replaceAll("'", `'\\''`)}'`;
+  const retry = (id        )         => ['urlcode init', quote(destination), '--with', requested.join(','), ...(manifest ? [] : ['--no-manifest']), ...[...(pins ?? [])].flatMap(([pkg, specifier]) => ['--pin', quote(`${pkg}=${specifier}`)]), ...[...acked, id].sort().flatMap(item => ['--ack', item])].join(' ');
   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));
+    for (const name of sorted) results.push(await loadScaffold(name, request, cwd, retry));
+    const consumed = new Set(results.flatMap(result => result.acknowledged ?? []));
+    const unused = acked.filter(id => !consumed.has(id));
+    assert(unused.length === 0, `--ack ${unused.join(', ')} has no effect here: no scaffold in --with (${sorted.join(', ')}) consumed it. Remove it, or check the extension name and id in that extension's documentation`);
+    results.splice(0, results.length, ...orderScaffolds(results));
+    const names = results.map(result => result.name);
     // Cross-result conflicts are refused before the destination exists.
     const extensions                          = Object.create(null)                           , routes                          = Object.create(null)                           , env                         = {};
     const owners = new Map                ();
@@ -161,7 +222,8 @@ export async function initProjectWith(destination        , names
       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}`);
+      const notes = results.flatMap(result => (result.routeNotes ?? []).map(note => `# ${result.name}: ${note}\n`)).join('');
+      await write(join(project, ROUTES_FILE), `# Routes added by urlcode init --with ${names.join(',')}. Mounts are exclusive to the named extension.\n${notes}${fragment}`);
       await rm(yamlFile); await write(yamlFile, String(doc));
       await loadDocument(project);
       const projectSha256 = await inspectExtensionRevision(project);

package/dist/mcp.js

@@ -7,6 +7,7 @@ import {loadOperatorHost} from './operator-host.js';
 import {buildManifest} from './manifest.js';
                                                         
 import {authoringDefinitions,callAuthoringTool} from './mcp-authoring.js';
+import {listSkills,getSkill,searchDocs,getExample,validateYaml,explainError} from './agent-context.js';
 const protocolVersion='2025-11-25';
 const maxBytes=1048576;
 const text={type:'string',maxLength:8192};
@@ -25,10 +26,16 @@ const definitions=[
  {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:'list_skills',description:'List compact metadata for the bundled agent skills. Load a skill only when it applies.',properties:{}},
+ {name:'get_skill',description:'Load one bundled agent SKILL.md by name.',properties:{name:{type:'string',maxLength:64}},required:['name']},
+ {name:'search_docs',description:'Deterministically search the small packaged agent documentation corpus and return at most three short excerpts.',properties:{text:{type:'string',maxLength:256}},required:['text']},
+ {name:'get_example',description:'Return the README and urlcode.yaml from one bundled runnable example.',properties:{name:{type:'string',maxLength:64}},required:['name']},
+ {name:'validate_yaml',description:'Validate supplied URLCode YAML syntax and schema only. It never reads includes, source files, bindings or a project directory.',properties:{yaml:{type:'string',maxLength:524288}},required:['yaml']},
+ {name:'explain_error',description:'Give deterministic next-step guidance for supplied URLCode validation output.',properties:{error:{type:'string',maxLength:8192}},required:['error']},
  {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 hostDefinition={name:'get_extensions',description:'List operator-registered extension contracts, schemas, hooks, and supported project-owned customization surfaces with fast checks; use these before generating replacement framework code. 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}};
@@ -63,6 +70,12 @@ export async function serveMcp(options           )               {
    case 'recipes_show':return showRecipe(args.name          );
    case 'search_recipes':return searchRecipes(args.text          );
    case 'search_examples':return searchExamples(args.text          );
+   case 'list_skills':return listSkills();
+   case 'get_skill':return getSkill(args.name          );
+   case 'search_docs':return searchDocs(args.text          );
+   case 'get_example':return getExample(args.name          );
+   case 'validate_yaml':return validateYaml(args.yaml          );
+   case 'explain_error':return explainError(args.error          );
    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');
@@ -78,7 +91,7 @@ export async function serveMcp(options           )               {
   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.1'}}});return;
+   initialized=true;await send({jsonrpc:'2.0',id,result:{protocolVersion,capabilities:{tools:{}},serverInfo:{name:'urlcode',version:'0.4.6'}}});return;
   }
   if(message.method==='ping'){await send({jsonrpc:'2.0',id,result:{}});return;}
   if(!ready){await error(id,-32002,'Initialize first');return;}

package/dist/pattern-guard.js

@@ -0,0 +1,32 @@
+import { assert } from './errors.js';
+
+export const maxPatternLength = 128;
+export const maxPatternInputLength = 128;
+const maxUnboundedQuantifiers = 3;
+
+/**
+ * Accepts an author regex only when it is conservatively safe to run on every
+ * request in the host process. Node has no linear-time engine, so this refuses
+ * the constructs that make backtracking blow up — repeated groups, lookaround
+ * and backreferences — and caps unbounded quantifiers. It is a restriction, not
+ * a proof: callers must also bound the input length to `maxPatternInputLength`.
+ */
+export function assertSafePattern(pattern        )       {
+  assert(pattern.length > 0 && pattern.length <= maxPatternLength, `Pattern must be 1 to ${maxPatternLength} characters`);
+  try { new RegExp(pattern, 'u'); } catch { assert(false, 'Invalid pattern'); }
+  let unbounded = 0, inClass = false;
+  for (let i = 0; i < pattern.length; i++) {
+    const char = pattern[i] ;
+    if (char === '\\') {
+      const next = pattern[i + 1] ?? '';
+      assert(inClass || !/[1-9k]/.test(next), 'Pattern backreferences are not supported');
+      i++; continue;
+    }
+    if (inClass) { if (char === ']') inClass = false; continue; }
+    if (char === '[') { inClass = true; continue; }
+    if (char === '(') assert(!/^\(\?<?[=!]/.test(pattern.slice(i, i + 4)), 'Pattern lookaround is not supported');
+    if (char === ')') assert(!/^(?:[*+]|\{\d+,\})/.test(pattern.slice(i + 1)), 'Pattern cannot repeat a group without a bound');
+    if (char === '*' || char === '+' || (char === '{' && /^\{\d+,\}/.test(pattern.slice(i)))) unbounded++;
+  }
+  assert(unbounded <= maxUnboundedQuantifiers, `Pattern allows at most ${maxUnboundedQuantifiers} unbounded quantifiers`);
+}

package/dist/policy.js

@@ -32,6 +32,22 @@ export async function prepareFunctionSnapshot(loaded                )
     if (route.sandbox) { for (const definition of [...middleware, ...(fn ? [fn] : [])]) sandboxed.push({pattern,function:definition}); }
     else trusted.push({middleware, function: fn});
   }
+  // Extension hooks are a core primitive even though their names and payloads
+  // belong to each extension. Include every declared entry module in the
+  // reviewed project revision, so editing trusted hook code invalidates the
+  // operator's extension pin just like editing a trusted route function.
+  for(const [extension,declaration] of Object.entries(loaded.document.extensions??{})){
+    const hooks=declaration.config.hooks;
+    if(hooks===undefined)continue;
+    assert(hooks&&typeof hooks==='object'&&!Array.isArray(hooks),`Extension ${extension} hooks must be an object`);
+    for(const [name,raw] of Object.entries(hooks                          )){
+      assert(typeof raw==='string'||raw&&typeof raw==='object'&&!Array.isArray(raw),`Invalid extension hook: ${extension}.${name}`);
+      const reference=typeof raw==='string'?{source:raw}:raw                                     ;
+      assert(typeof reference.source==='string',`Invalid extension hook: ${extension}.${name}`);
+      assert(reference.export===undefined||typeof reference.export==='string',`Invalid extension hook: ${extension}.${name}`);
+      trusted.push({function:await resolveOne({source:reference.source,...(reference.export===undefined?{}:{export:reference.export          })})});
+    }
+  }
   const collected = await collectFunctionSources(sandboxed,loaded.root);
   const trustedSources = await collectTrustedSources(trusted,loaded.root);
   // The hash operator grants pin to still covers trusted routes' own source, so

package/dist/project-tests.js

@@ -1,23 +1,47 @@
-import { realpath } from 'node:fs/promises';
+import { mkdtemp, realpath, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
 import { Agent } from 'node:http';
 import { startServer } from './server.js';
-                                                 
-import { readCases, hit } from './readiness.js';
+                                                         
+import { readFixtures, runFixtures } from './readiness.js';
+                                                     
                                         
 
                                                                                                                                                                                                                       
                                                                     
 
+/**
+ * A server that fixture `restart` steps can close and start again on the same project and the
+ * same data directory. The data directory is fresh and empty, offered to the project as
+ * `URLCODE_DATA_DIR`, and removed by `close()`; on a filesystem where it cannot be created, none is offered. `restart()` gets a new port; read `address` after it.
+ */
+export async function startRestartable(options               )                                                       {
+  // A read-only filesystem (a locked-down container) has nowhere to put it: run without one instead of
+  // failing every test run. A project that reads `URLCODE_DATA_DIR` then refuses to activate, as it would unset.
+  const dataDir = await mkdtemp(join(tmpdir(), 'urlcode-data-')).catch(() => undefined);
+  const cleanup = async ()                => { if (dataDir !== undefined) await rm(dataDir, { recursive: true, force: true }); };
+  let current                    ;
+  try { current = await startServer({ ...options, dataDir }); } catch (error) { await cleanup(); throw error; }
+  const running = ()         => { if (!current) throw new Error('Server is not running'); return current; };
+  return {
+    get address() { return running().address; }, get root() { return running().root; }, testPlan: () => running().testPlan(),
+    async restart() { const old = running(); current = undefined; await old.close(); current = await startServer({ ...options, dataDir }); },
+    async close() { try { await current?.close(); } finally { current = undefined; await cleanup(); } },
+  };
+}
+
 export async function runProjectTests(project        , { log = () => {}, permissions, origin, extensions, plugins }                     = {})                             {
-  const root = await realpath(project), cases = await readCases(root);
-  const app = await startServer({ project, port: 0, local: true, log, permissions, origin, extensions, plugins });
-  const agent = new Agent({keepAlive:true,maxSockets:1}); let failed = 0;
+  const root = await realpath(project), fixtures = await readFixtures(root);
+  const app = await startRestartable({ project, port: 0, local: true, log, permissions, origin, extensions, plugins });
+  const agent = new Agent({keepAlive:true,maxSockets:1}); let failed = 0, total = 0;
   try {
-    for (const [i,test] of cases.entries()) {
-      const result=await hit(app,test,agent);
+    // Only case number, pass and status are logged: never a path, header or body, which may hold captured values.
+    await runFixtures(fixtures, { app, agent, restart: () => app.restart() }, ({ case: n, result }) => {
+      total++;
       if(!result.pass)failed++;
-      log({event:'test',case:i+1,pass:result.pass,status:result.status});
-    }
+      log({event:'test',case:n,pass:result.pass,status:result.status});
+    });
   } finally {agent.destroy();await app.close();}
-  return {total:cases.length,failed};
+  return {total,failed};
 }