@jimhoyd/urlcode 0.4.8 → 0.5.5

package/dist/init-with.js

@@ -1,4 +1,4 @@
-import { mkdir, open, readFile, rm, unlink, lstat } from 'node:fs/promises';
+import { mkdir, mkdtemp, open, readFile, rename, rm, unlink, lstat } from 'node:fs/promises';
 import { createRequire } from 'node:module';
 import { basename, dirname, join, relative, resolve, sep } from 'node:path';
 import { pathToFileURL } from 'node:url';
@@ -11,6 +11,7 @@ import { inspectExtensionRevision } from './extensions.js';
 import { collectDependencySet, installSteps, renderPackageManifest } from './project-dependencies.js';
                                                                               
 import { ConfigError, assert } from './errors.js';
+import { installBundle, loadExtensionBundle,                      } from './extension-bundles.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';
@@ -24,6 +25,10 @@ const namePattern = /^[a-z][a-z0-9-]{0,63}$/, capabilityPattern = /^[a-z][a-z0-9
                                                  
                                                                                                                                                       
                                                    
+                                                                                                   
+                                     
+                                                                                        
+                                                
  
                                                                                                                                                                                          
 
@@ -79,15 +84,19 @@ export function orderScaffolds(results                           )
  * 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        , retry                        )                          {
+async function loadScaffold(name        , request                 , cwd        , retry                        , bundleProject         )                          {
   const pkg = packageName(name);
-  let entry        ;
-  try { entry = createRequire(join(cwd, 'package.json')).resolve(pkg); }
-  catch (error) {
-    if (isCode(error, 'MODULE_NOT_FOUND')) throw new ConfigError(`Extension package ${pkg} is not installed in ${cwd}; run: npm install ${pkg}`);
-    throw error;
+  let module                         ;
+  if (bundleProject) module = await loadExtensionBundle(bundleProject, name);
+  else {
+    let entry        ;
+    try { entry = createRequire(join(cwd, 'package.json')).resolve(pkg); }
+    catch (error) {
+      if (isCode(error, 'MODULE_NOT_FOUND')) throw new ConfigError(`Extension package ${pkg} is not installed in ${cwd}; run: npm install ${pkg}`);
+      throw error;
+    }
+    module = await import(pathToFileURL(entry).href)                           ;
   }
-  const module = await import(pathToFileURL(entry).href)                           ;
   const scaffold = module.scaffold;
   if (typeof scaffold !== 'function') throw new ConfigError(`${pkg} does not export scaffold; upgrade it to a release that supports urlcode init --with, or add ${name} by hand following its README`);
   let result         ;
@@ -102,6 +111,8 @@ async function loadScaffold(name        , request                 , cwd        ,
   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.hostBundleExports === undefined || (strings(result.hostBundleExports) && result.hostBundleExports.every(value => /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(value))), `${pkg} scaffold hostBundleExports must be JavaScript identifiers`);
+  if (request.distribution === 'bundle') assert(Array.isArray(result.hostBundleExports) && result.hostBundleExports.length > 0, `${pkg} scaffold must declare hostBundleExports for executable bundle distribution`);
   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`);
@@ -124,8 +135,17 @@ async function write(target        , content                     , mode = 0o644)
   const file = await open(target, 'wx', mode);
   try { await file.writeFile(content); await file.sync(); } finally { await file.close(); }
 }
-function renderHost(names                   , results                           )         {
+function renderHost(names                   , results                           , distribution               ='npm')         {
   const lines = [`// Generated by urlcode init --with ${names.join(',')}. Trusted operator code: keep it outside ${PROJECT_DIRECTORY}/ and review before serving.`];
+  if (distribution === 'bundle') {
+    lines.push("import {loadExtensionBundle} from '@jimhoyd/urlcode/extension-bundles';", "import {fileURLToPath} from 'node:url';", "const extensionBundleDirectory = fileURLToPath(new URL('.', import.meta.url));");
+    const exports = new Set        ();
+    for (const result of results) {
+      const names = result.hostBundleExports ;
+      for (const name of names) { assert(!exports.has(name), `Bundle host export ${name} is declared by more than one extension`); exports.add(name); }
+      lines.push(`const {${names.join(', ')}} = await loadExtensionBundle(extensionBundleDirectory, '${result.name}');`);
+    }
+  }
   // 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('');
@@ -142,23 +162,23 @@ function demote(markdown        )         {
   let fence = false;
   return markdown.split('\n').map(line => { if (/^\s*(?:```|~~~)/.test(line)) fence = !fence; return !fence && /^#{1,5} /.test(line) ? `#${line}` : line; }).join('\n');
 }
-function renderDependencySection(directory        , set               )         {
+function renderDependencySection(directory        , set               , bundle = false)         {
   const rows = set.pins.map(pin => `- \`${pin.name}\` ${pin.version} (${pin.role})${pin.specifier === pin.version ? '' : ` installed from \`${pin.specifier}\``}`);
   const lines = ['## Dependencies', '',
-    '`package.json` pins the runtime, every extension named in `--with` and their declared peers to the exact versions that were installed when this site was generated. Those versions were checked against each package\'s own `peerDependencies` as one set.', '',
+    bundle ? '`package.json` pins only the URLCode runtime. Executable extensions are locked GitHub Release bundles in `urlcode.extension-bundles.lock.json`, not npm dependencies.' : '`package.json` pins the runtime, every extension named in `--with` and their declared peers to the exact versions that were installed when this site was generated. Those versions were checked against each package\'s own `peerDependencies` as one set.', '',
     ...rows, '',
     ...installSteps(directory, set).flatMap(step => [step, '']),
     set.local ? 'At least one pin is a local path or tarball rather than a registry version: reproducing this install needs that path to exist, so keep it under your control or replace the specifier before publishing the site.' : 'The pins are registry versions; `npm install` resolves them without the network only if your cache or mirror already holds them.', '',
     'There is no upgrade command. Changing a pinned version today means editing `package.json` yourself and re-running `npm install`; review the extension changelogs first.', ''];
   return lines.join('\n');
 }
-function renderReadme(directory        , names                   , results                           , starter        , env                        , projectSha256        , set                            )         {
+function renderReadme(directory        , names                   , results                           , starter        , env                        , projectSha256        , set                            , distribution               ='npm')         {
   const steps = [...(set ? installSteps(directory, set) : []), ...results.flatMap(result => result.nextSteps)];
   const parts = [`# ${basename(directory)}`, '',
-    `Created with \`urlcode init ${basename(directory)} --with ${names.join(',')}\`. \`${PROJECT_DIRECTORY}/\` is the route project (\`urlcode.yaml\`, functions, tests); \`${HOST_FILE}\` is the trusted operator host that wires the installed extension packages; operator modules and private data stay outside the project. Run every command with \`--project ${PROJECT_DIRECTORY} --host-file "$PWD/${HOST_FILE}"\`.`, '',
+    `Created with \`urlcode init ${basename(directory)} --with ${names.join(',')}\`. \`${PROJECT_DIRECTORY}/\` is the route project (\`urlcode.yaml\`, functions, tests); \`${HOST_FILE}\` is the trusted operator host that wires ${distribution === 'bundle' ? 'the explicitly installed, verified extension bundles' : 'the installed extension packages'}; operator modules and private data stay outside the project. Run every command with \`--project ${PROJECT_DIRECTORY} --host-file "$PWD/${HOST_FILE}"\`.`, '',
     '## Starter', '', `The starter files live in \`${PROJECT_DIRECTORY}/\`; add \`--project ${PROJECT_DIRECTORY}\` and the host file to the commands below.`, '', demote(starter).trim(), ''];
   for (const result of results) parts.push(`## Extension: ${result.name}`, '', result.readme.trim(), '');
-  if (set) parts.push(renderDependencySection(directory, set));
+  if (set) parts.push(renderDependencySection(directory, set, distribution === 'bundle'));
   parts.push('## Next steps', '', ...steps.map((step, index) => `${index + 1}. ${step}`), '');
   if (Object.keys(env).length) parts.push('## Environment', '', ...Object.entries(env).map(([key, text]) => `- \`${key}\`: ${text}`), '');
   parts.push('## Project revision', '', `\`${PROJECT_DIRECTORY}/urlcode.yaml\` currently has revision \`${projectSha256}\` (\`inspectExtensionRevision\`). Review the project, then pin exactly that value where the host expects it; any change to extension YAML, policies or mounts changes it and needs a new explicit review.`, '');
@@ -170,7 +190,7 @@ 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        , requested                   , { cwd = process.cwd(), manifest = true, pins, acknowledgements = [] }                  = {})                          {
+export async function initProjectWith(destination        , requested                   , { cwd = process.cwd(), manifest = true, pins, acknowledgements = [], bundleRelease, bundleTransport }                  = {})                          {
   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.
@@ -178,13 +198,20 @@ export async function initProjectWith(destination        , requested
   const directory = resolve(destination), project = join(directory, PROJECT_DIRECTORY), hostFile = join(directory, HOST_FILE);
   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 distribution               =bundleRelease===undefined?'npm':'bundle';
+  const request                  = { directory, project, hostFile, names: sorted, acknowledgements: acked, distribution };
   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 retry = (id        )         => ['urlcode init', quote(destination), '--with', requested.join(','), ...(bundleRelease===undefined?[]:['--bundle-release',bundleRelease]), ...(manifest ? [] : ['--no-manifest']), ...[...(pins ?? [])].flatMap(([pkg, specifier]) => ['--pin', quote(`${pkg}=${specifier}`)]), ...[...acked, id].sort().flatMap(item => ['--ack', item])].join(' ');
   const results                   = [];
+  let bundleRoot                    ;
   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 sorted) results.push(await loadScaffold(name, request, cwd, retry));
+    if (bundleRelease) {
+      await mkdir(dirname(directory), { recursive: true });
+      bundleRoot=await mkdtemp(join(dirname(directory),'.urlcode-bundle-init-'));
+      for (const name of sorted) await installBundle(bundleRoot,bundleRelease,name,bundleTransport);
+    }
+    for (const name of sorted) results.push(await loadScaffold(name, request, cwd, retry, bundleRoot));
     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`);
@@ -202,11 +229,16 @@ export async function initProjectWith(destination        , requested
     }
     // Also resolved before the destination exists: an incompatible or incompletely installed set refuses with
     // nothing written. It runs after the scaffold conflicts so a composition error is still reported as one.
-    const dependencies = manifest ? await collectDependencySet(names, names.map(packageName), { cwd, ...(pins === undefined ? {} : { overrides: pins }) }) : undefined;
+    const dependencies = manifest ? await collectDependencySet(bundleRelease===undefined?names:[], bundleRelease===undefined?names.map(packageName):[], { cwd, ...(pins === undefined ? {} : { overrides: pins }) }) : undefined;
     await mkdir(dirname(directory), { recursive: true });
     await mkdir(directory, { mode: 0o700 }); // refuses an existing destination
     try {
       await initProject(project);
+      if (bundleRoot) {
+        await rename(join(bundleRoot,'.urlcode'),join(directory,'.urlcode'));
+        await rename(join(bundleRoot,'urlcode.extension-bundles.lock.json'),join(directory,'urlcode.extension-bundles.lock.json'));
+        await rm(bundleRoot,{recursive:true,force:true}); bundleRoot=undefined;
+      }
       const starter = await readFile(join(project, 'README.md'), 'utf8');
       await unlink(join(project, 'README.md')); // its content moves into the site README
       await unlink(join(project, mcpConfigFile)); // re-registered at the site root, pointing at app/
@@ -236,17 +268,17 @@ export async function initProjectWith(destination        , requested
         while (probe !== directory && probe.startsWith(directory)) { try { assert(!(await lstat(probe)).isSymbolicLink(), `Scaffold path passes through a symlink: ${file.path}`); } catch (error) { if (!isCode(error, 'ENOENT')) throw error; } probe = dirname(probe); }
         await write(target, file.content, file.mode ?? 0o644); written.add(target);
       }
-      await write(hostFile, renderHost(names, results), 0o600);
+      await write(hostFile, renderHost(names, results, distribution), 0o600);
       if (dependencies) await write(join(directory, 'package.json'), renderPackageManifest(directory, dependencies));
-      await write(join(directory, 'README.md'), renderReadme(directory, names, results, starter, env, projectSha256, dependencies));
+      await write(join(directory, 'README.md'), renderReadme(directory, names, results, starter, env, projectSha256, dependencies, distribution));
       await write(join(directory, '.gitignore'), 'node_modules/\ndata/\n.env\n.env.*\n');
       // The read-only MCP server for agents opened at the site root; --host-file and --allow-authoring stay operator choices.
-      await write(join(directory, mcpConfigFile), renderMcpConfig(PROJECT_DIRECTORY));
+      await write(join(directory, mcpConfigFile), renderMcpConfig(PROJECT_DIRECTORY, { local: dependencies !== undefined }));
       // AGENTS.md: initProject writes the application-level file into app/ once it produces one (NEXT-STEPS 1.1);
       // nothing here overrides it. A site-level agent note would be assembled beside README.md at this point.
       return { directory, project, hostFile, extensions: [...names], projectSha256,
         nextSteps: [...(dependencies ? installSteps(directory, dependencies) : []), ...results.flatMap(result => result.nextSteps)],
         dependencies: dependencies?.pins ?? [] };
     } catch (error) { await rm(directory, { recursive: true, force: true }); throw error; }
-  } finally { wipe(); }
+  } finally { if(bundleRoot)await rm(bundleRoot,{recursive:true,force:true}); wipe(); }
 }

package/dist/interchange.js

@@ -166,7 +166,7 @@ export async function exportRoutes(options                    )
     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));}
+      try{keys(record(config),['redirect']);if(!config.redirect)throw new Error('Only redirects can be exported');if(path.includes('*')||config.redirect.url.startsWith('/'))throw new Error('Suffix wildcards and root-relative destinations have no provider equivalent');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);

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. */
                                  
-                                                                                                         
+                                                                                                                             
                                                                                         
  
                                                                                                                                              
@@ -52,6 +52,8 @@ export function parseTarget(target        )         {
   if (parts.length > 32 || parts.some(p => p === '.' || p === '..')) throw new HttpError(400, 'Invalid path');
   return { path, parts, query: new URLSearchParams(query) };
 }
+/** Longest suffix a `/**` redirect captures; a longer one is simply not matched. */
+const wildcardMaxLength = 1024;
 export function matchRoute                          (compiled                   , target        )                  {
   const exact = compiled.exact.get(target.path);
   if (exact) return { route: exact, path: dict() };
@@ -64,7 +66,15 @@ 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)||(route.extension&&target.path===route.prefix.slice(0,-1)))) return { route, path: dict() };
+  for (const route of compiled.mounts) {
+    if (route.wildcard) {
+      // `/prefix/**`: one or more whole segments, no empty segment (so a redirect can never gain a `//`), bounded length.
+      const rest = route.prefix !== undefined && target.path.startsWith(route.prefix) ? target.path.slice(route.prefix.length) : '';
+      if (rest && rest.length <= wildcardMaxLength && !rest.split('/').includes('')) { const path = dict        (); path['**'] = rest; return { route, path }; }
+      continue;
+    }
+    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            )         {
@@ -102,14 +112,21 @@ export function contextFor(route                , path                        ,
     if (!p.validate(value)) throw new HttpError(400, 'Invalid parameter');
     (inputs[p.in]                                  )[p.name] = value;
   }
+  if (route.wildcard) inputs.path['**'] = path['**'] ?? '';
   return { inputs, env: route.env, secrets: route.secrets };
 }
 // The router accepts a placeholder only for a declared path input, and a path
 // input always matches a segment, so the '' fallback is unreachable through a
 // compiled route; it keeps a direct call with an undeclared name from writing
 // the text "undefined" into the location.
+// A root-relative destination (`/profiles/{id}`) is resolved against this placeholder origin only to normalize and encode it;
+// the origin never appears in the Location.
+const relativeBase = 'https://relative.invalid';
 export function redirectLocation(route                                             , context                , query                 )         {
-  const location = new URL(route.redirect.url.replace(/\{([^}]+)\}/g, (_m, name        ) => encodeURIComponent(context.inputs.path[name] ?? '')));
+  const relative = route.redirect.url.startsWith('/');
+  // `{**}` is the captured suffix: each segment encoded on its own, joined by the `/` that separated them.
+  const encode = (name        ) => name === '**' ? (context.inputs.path['**'] ?? '').split('/').map(encodeURIComponent).join('/') : encodeURIComponent(context.inputs.path[name] ?? '');
+  const location = new URL(route.redirect.url.replace(/\{([^}]+)\}/g, (_m, name        ) => encode(name)), relativeBase);
   function append(key        , value                )       {
     if (value === undefined) return;
     for (const item of Array.isArray(value) ? value : [value]) location.searchParams.append(key, String(item));
@@ -119,6 +136,7 @@ export function redirectLocation(route
     if (own(context.inputs.query, key)) append(key, context.inputs.query[key]);
     else for (const value of query.getAll(key)) append(key,value);
   }
-  if (location.href.length > 16384) throw new HttpError(400, 'Redirect URL too long');
-  return location.href;
+  const result = relative ? location.pathname + location.search + location.hash : location.href;
+  if (result.length > 16384) throw new HttpError(400, 'Redirect URL too long');
+  return result;
 }

package/dist/mcp.js

@@ -2,7 +2,7 @@ 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,buildTaskContext} from './tooling.js';
+import {inspectProject,validateProject,explainRoute,getCapabilities,getCapability,getSchemaFragment,previewImport,previewExport,listRecipes,showRecipe,searchRecipes,searchExamples,describeExtensions,buildContext,buildTaskContext,planFeature,reviewProject} from './tooling.js';
 import {loadOperatorHost} from './operator-host.js';
 import {buildManifest} from './manifest.js';
                                                         
@@ -36,6 +36,8 @@ const definitions=[
  {name:'get_extension_artifacts',description:'Validate and list the project\'s locked declarative extension artifacts and their allowlisted files. Artifacts are inert data and do not activate extension code.',properties:{}},
  {name:'get_extension_artifact',description:'Read one bounded JSON or Markdown file from a verified cached declarative extension artifact. The artifact name and member path must exist in the project lock/cache.',properties:{name:{type:'string',maxLength:64},path:{type:'string',maxLength:128}},required:['name','path']},
  {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. Pass `task: "redirects"` for a bounded, redirect-focused call instead (supported/gap shapes, exact YAML, this project\'s redirects). Optional token budget drops sections in a fixed order.',properties:{target:text,task:{enum:['redirects']},budget:{type:'integer',minimum:1}}},
+ {name:'plan_feature',description:'Plan a bounded feature from the compiled project, current capability catalog, local recipes, locked inert artifacts and already-loaded operator registrations. Returns contracts and next calls, never generated application code, binding values, remote content or mutations.',properties:{goal:{type:'string',minLength:1,maxLength:512},target:{enum:['self-hosted','cloudflare','aws','vercel','static']}},required:['goal']},
+ {name:'review_project',description:'Opt-in, read-only static review of the project\'s own function/middleware source for avoidable plumbing: native-alternative/extension-alternative/gap/manual-review. Already-loaded operator registrations (--host-file) sharpen extension-alternative findings with registered/revision-pinned state; without a host file that state stays conservative ("declared, setup unconfirmed"). No execution, no secrets, no network.',properties:{target:text}},
 ];
 // 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, schemas, hooks, and supported project-owned customization surfaces with fast checks; use these before generating replacement framework code. Activates nothing.',properties:{}};
@@ -85,6 +87,8 @@ export async function serveMcp(options           )               {
    case 'get_context':return typeof args.task==='string'
     ?buildTaskContext(project,args.task,{...(typeof args.budget==='number'?{budget:args.budget}:{})})
     :buildContext(project,{projectFlag:'.',...(typeof args.target==='string'?{target:args.target}:{}),...(typeof args.budget==='number'?{budget:args.budget}:{})});
+   case 'plan_feature':return planFeature(project,args.goal          ,{...(typeof args.target==='string'?{target:args.target}:{}),extensions:host.extensions});
+   case 'review_project':return reviewProject(project,{...base,...(typeof args.target==='string'?{target:args.target}:{}),extensions:host.extensions});
    default:if(authoring)return callAuthoringTool(project,name,args,options.origin);throw new Error('Unknown tool');
   }
  };
@@ -98,7 +102,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.8'}}});return;
+   initialized=true;await send({jsonrpc:'2.0',id,result:{protocolVersion,capabilities:{tools:{}},serverInfo:{name:'urlcode',version:'0.5.5'}}});return;
   }
   if(message.method==='ping'){await send({jsonrpc:'2.0',id,result:{}});return;}
   if(!ready){await error(id,-32002,'Initialize first');return;}

package/dist/readiness.js

@@ -119,11 +119,11 @@ export function projectPlan(compiled                               )
     if (route.extension || route.extensionPolicyNames?.length || route.proxy || route.signals?.length || route.match || route.conditional || route.function || route.middleware?.length || route.names.length) continue;
     // Required inputs need intentional fixtures; never invent business data.
     let context                ;
-    try { context = contextFor(route,{},new URLSearchParams(),new Headers()); } catch { continue; }
+    try { context = contextFor(route,route.wildcard ? {'**':'sample'} : {},new URLSearchParams(),new Headers()); } catch { continue; }
     if (route.request?.body?.required) continue;
     const files = route.asset instanceof Map ? route.asset : undefined;
     const prefix = route.prefix ?? '';
-    const paths = route.static && files ? [...files.keys()].map(key => prefix + key.split('/').map(encodeURIComponent).join('/')) : [route.pattern];
+    const paths = route.wildcard ? [prefix + 'sample'] : route.static && files ? [...files.keys()].map(key => prefix + key.split('/').map(encodeURIComponent).join('/')) : [route.pattern];
     for (const path of paths) for (const method of route.methods) {
       if (!['GET','HEAD'].includes(method)) continue;
       const test              = {path,method,status:(route.redirect ? route.redirect.status || 302 : route.reply?.status || 200)};

package/dist/review.js

@@ -0,0 +1,206 @@
+import {readFile} from 'node:fs/promises';
+import {relative, sep} from 'node:path';
+import {functionFile} from './config.js';
+import {routeFunctions, MODULE_BYTE_LIMIT} from './function-sources.js';
+import {prepare} from './tooling.js';
+                                                 
+import {effectivePolicies} from './policies.js';
+                                                      
+
+// Read-only static review; see docs/TOOLING.md#project-review.
+                                                                                                      
+                                                                                                                                
+                                                                        
+
+                                    
+                                                                   
+                                                                                              
+                                                                                                                                  
+                                                                                                                                                                                                                                                                                                                                                                                                                                                     
+                                                 
+ 
+                                
+                                                                            
+                                                                             
+ 
+
+export const reviewModuleByteLimit = MODULE_BYTE_LIMIT;
+export const reviewExcerptLimit = 240;
+
+                                                 
+function locate(source        , at        )        {
+  const start = Math.max(0, at - 40), end = Math.min(source.length, at + 200);
+  return {line: source.slice(0, at).split('\n').length, excerpt: source.slice(start, end).replace(/\s+/g, ' ').trim().slice(0, reviewExcerptLimit)};
+}
+const bodyHints = [/typeof\s+\w+\s*(!==|===)/, /\brequired\b/i, /\bmissing\b/i, /\binvalid\b/i, /throw\s+new\s+(Error|TypeError)/];
+function detectBodyValidation(source        )                    {
+  const parse = /JSON\.parse\s*\(/.exec(source);
+  return parse && bodyHints.filter(re => re.test(source)).length >= 2 ? locate(source, parse.index) : undefined;
+}
+const cookieHints = [/randomUUID\s*\(/, /randomBytes\s*\(/, /\bsession\b/i, /\btoken\b/i, /expires=/i, /httponly/i];
+function detectCookieSession(source        )                    {
+  const cookie = /set-cookie/i.exec(source);
+  return cookie && cookieHints.filter(re => re.test(source)).length >= 2 ? locate(source, cookie.index) : undefined;
+}
+function detectGlobalState(source        )                    {
+  const decl = /^(?:export\s+)?(?:let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*(?:\[\s*\]|\{\s*\}|new\s+Map\s*\(\s*\)|new\s+Set\s*\(\s*\)|0)\s*;?\s*$/m.exec(source);
+  if (!decl) return undefined;
+  const name = decl[1] , mutated = new RegExp(`\\b${name}\\s*(?:\\+\\+|--|\\+=|-=|\\.push\\s*\\(|\\.set\\s*\\(|\\.add\\s*\\(|\\.delete\\s*\\(|\\[[^\\]]*\\]\\s*=)`);
+  return mutated.test(source.slice(decl.index + decl[0].length)) ? locate(source, decl.index) : undefined;
+}
+function detectEgress(source        )                    {
+  const call = /\bfetch\s*\(|\bhttps?\.request\s*\(|\bhttps?\.get\s*\(/.exec(source);
+  return call ? locate(source, call.index) : undefined;
+}
+const methodCompare = /\brequest\s*\.\s*method\s*(?:===|==)\s*(['"])[A-Z]+\1/g;
+function detectMethodDispatch(source        )                    {
+  const compares = [...source.matchAll(methodCompare)];
+  if (compares.length >= 2) return locate(source, compares[0] .index );
+  const dispatch = /switch\s*\(\s*request\s*\.\s*method\s*\)/.exec(source);
+  if (!dispatch) return undefined;
+  const tail = source.slice(dispatch.index, dispatch.index + 2000);
+  const cases = [...tail.matchAll(/case\s+(['"])[A-Z]+\1\s*:/g)];
+  return cases.length >= 2 ? locate(source, dispatch.index) : undefined;
+}
+const rateLimitHints = [/\b(?:count|counts|hits|attempts|requests)\w*\s*(?:\+\+|\+=\s*1)/i, /Date\.now\s*\(\)/, /\bwindow\b/i, /\bquota\b/i, /retry-after/i, /too many requests/i];
+function detectRateLimit(source        )                    {
+  const anchor = /\b429\b/.exec(source) ?? /retry-after/i.exec(source);
+  return anchor && rateLimitHints.filter(re => re.test(source)).length >= 2 ? locate(source, anchor.index) : undefined;
+}
+const securityHeaderNames = ['x-frame-options', 'content-security-policy', 'strict-transport-security', 'x-content-type-options', 'referrer-policy', 'permissions-policy', 'x-xss-protection'];
+function detectSecurityHeaders(source        )                    {
+  const found = securityHeaderNames.filter(name => new RegExp(name, 'i').test(source));
+  if (found.length < 2) return undefined;
+  const first = new RegExp(found[0] , 'i').exec(source) ;
+  return locate(source, first.index);
+}
+
+const emptyCategory = ()                                 => ({'native-alternative': 0, 'extension-alternative': 0, gap: 0, 'manual-review': 0});
+/** Whether an operator extension is actually registered (not merely declared in YAML), from the caller-supplied registrations
+ * (InspectOptions.extensions) that a --host-file/MCP host already loaded; review.ts never loads or executes a host file itself.
+ * `undefined` when the caller supplied no registrations at all, meaning registration state is genuinely unconfirmed. */
+function extensionStatus(name        , extensions                                                                         , projectSha256        )                                                              {
+  if (extensions === undefined) return undefined;
+  const registration = extensions.find(item => item.name === name);
+  return registration ? {registered: true, revisionPinned: registration.projectSha256 === projectSha256} : {registered: false};
+}
+
+export async function reviewProject(project        , options                 = {})                         {
+  const {loaded, projectSha256, routes} = await prepare(project, options);
+  const declaredExtensions = new Set(Object.keys(loaded.document.extensions ?? {}));
+                                                                                                                                                                  
+  const modules = new Map                    ();
+  for (const route of routes) {
+    const declared = loaded.routes[route.pattern];
+    if (!declared) continue;
+    const hasSchema = declared.request?.body?.schema !== undefined;
+    const effective = effectivePolicies(loaded.document, declared);
+    const hasThrottle = Boolean(effective.throttle), hasSecurity = Boolean(effective.security);
+    for (const definition of routeFunctions(declared)) {
+      let absolute        ;
+      try { absolute = await functionFile(loaded.root, definition.source); } catch { continue; }
+      let info = modules.get(absolute);
+      if (!info) { info = {source: '/' + relative(loaded.root, absolute).split(sep).join('/'), routes: new Set(), routesMissingSchema: new Set(), routesWithThrottle: new Set(), routesWithSecurity: new Set()}; modules.set(absolute, info); }
+      info.routes.add(route.pattern);
+      if (!hasSchema) info.routesMissingSchema.add(route.pattern);
+      if (hasThrottle) info.routesWithThrottle.add(route.pattern);
+      if (hasSecurity) info.routesWithSecurity.add(route.pattern);
+    }
+  }
+  const observations                      = [], summary = emptyCategory();
+  for (const [absolute, info] of [...modules.entries()].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)) {
+    let source        ;
+    try { const text = await readFile(absolute, 'utf8'); source = text.length > reviewModuleByteLimit ? text.slice(0, reviewModuleByteLimit) : text; } catch { continue; }
+    const routesList = [...info.routes].sort();
+    const push = (match       , rest                                                        ) => {
+      const observation                    = {...rest, source: info.source, line: match.line, excerpt: match.excerpt};
+      observations.push(observation); summary[observation.category]++;
+    };
+
+    const bodyValidation = detectBodyValidation(source);
+    if (bodyValidation && info.routesMissingSchema.size) push(bodyValidation, {
+      category: 'native-alternative', signal: 'manual-body-validation', routes: [...info.routesMissingSchema].sort(), confidence: 'medium',
+      reason: 'JSON.parse plus hand checks; no request.body.schema.', capability: 'request.body',
+      note: 'request.body.schema validates this; see get_capability("request.body").',
+    });
+
+    const cookieSession = detectCookieSession(source);
+    if (cookieSession) {
+      const authDeclared = declaredExtensions.has('auth');
+      const authStatus = authDeclared ? extensionStatus('auth', options.extensions, projectSha256) : undefined;
+      push(cookieSession, {
+        category: authDeclared ? 'extension-alternative' : 'manual-review', signal: 'manual-cookie-session', routes: routesList, confidence: 'medium',
+        reason: 'Hand-built Set-Cookie with session values (id, token, expiry, HttpOnly).',
+        ...(authDeclared ? {extension: 'auth'} : {}),
+        ...(authStatus?.registered ? {registered: true, revisionPinned: authStatus.revisionPinned} : {}),
+        note: authDeclared
+          ? authStatus?.registered
+            ? authStatus.revisionPinned
+              ? 'auth is registered and revision-pinned to this project; hand-built cookies still need a human decision.'
+              : 'auth is registered but not revision-pinned to this project\'s current revision; hand-built cookies still need a human decision.'
+            : 'auth owns sessions once registered; hand-built cookies still need a human decision.'
+          : 'No session extension declared; needs human review (rotation, invalidation).',
+      });
+    }
+
+    const globalState = detectGlobalState(source);
+    if (globalState) {
+      const storeDeclared = declaredExtensions.has('store');
+      const storeStatus = storeDeclared ? extensionStatus('store', options.extensions, projectSha256) : undefined;
+      push(globalState, {
+        category: storeDeclared ? 'extension-alternative' : 'gap', signal: 'global-mutable-state', routes: routesList, confidence: 'medium',
+        reason: 'Module-scope let/var starts empty, later mutated: local state.',
+        ...(storeDeclared ? {extension: 'store'} : {}),
+        ...(storeStatus?.registered ? {registered: true, revisionPinned: storeStatus.revisionPinned} : {}),
+        note: storeDeclared
+          ? storeStatus?.registered
+            ? storeStatus.revisionPinned
+              ? 'store is registered and revision-pinned to this project; resets on restart, not shared across multiple instances.'
+              : 'store is registered but not revision-pinned to this project\'s current revision; resets on restart, not shared across multiple instances.'
+            : 'store can own this once registered; resets on restart, not shared across multiple instances.'
+          : 'Resets on restart, not shared across multiple instances; no alternative yet: a real gap.',
+      });
+    }
+
+    const egress = detectEgress(source);
+    if (egress) push(egress, {
+      category: 'manual-review', signal: 'outbound-network-call', routes: routesList, confidence: 'low',
+      reason: 'Direct outbound call (fetch/http(s).request/get) from app code.', capability: 'proxy',
+      note: 'proxy/signals centralizes egress but equivalence isn\'t verifiable; review by hand.',
+    });
+
+    const methodDispatch = detectMethodDispatch(source);
+    if (methodDispatch) push(methodDispatch, {
+      category: 'native-alternative', signal: 'method-dispatch', routes: routesList, confidence: 'medium',
+      reason: 'Hand-written request.method branching/switch dispatches per-method logic in code.', capability: 'methods',
+      note: 'Native routing already dispatches by method; declare one route per method instead of branching on request.method. See get_capability("methods").',
+    });
+
+    const rateLimit = detectRateLimit(source);
+    if (rateLimit) {
+      const declaredRoutes = [...info.routesWithThrottle].sort(), duplicate = declaredRoutes.length > 0;
+      push(rateLimit, {
+        category: duplicate ? 'manual-review' : 'native-alternative', signal: 'manual-rate-limit',
+        routes: duplicate ? declaredRoutes : routesList, confidence: 'medium', capability: 'policies.throttle',
+        reason: 'Hand-rolled request counting with a 429/Retry-After response: a rate-limit pattern.',
+        note: duplicate
+          ? 'policies.throttle is already declared for these routes; hand-rolled counting duplicates the host-enforced quota and needs a human decision to remove one.'
+          : 'policies.throttle is not declared for these routes; see get_capability("policies.throttle") for quota/window enforcement without application code.',
+      });
+    }
+
+    const securityHeaders = detectSecurityHeaders(source);
+    if (securityHeaders) {
+      const declaredRoutes = [...info.routesWithSecurity].sort(), duplicate = declaredRoutes.length > 0;
+      push(securityHeaders, {
+        category: duplicate ? 'manual-review' : 'native-alternative', signal: 'manual-security-headers',
+        routes: duplicate ? declaredRoutes : routesList, confidence: 'medium', capability: 'policies.security',
+        reason: 'Hand-set security response headers (two or more of X-Frame-Options, CSP, HSTS, X-Content-Type-Options, Referrer-Policy, Permissions-Policy).',
+        note: duplicate
+          ? 'policies.security is already declared for these routes; hand-set headers duplicate the host-enforced profile and need a human decision to remove one.'
+          : 'policies.security is not declared for these routes; see get_capability("policies.security") for header configuration without application code.',
+      });
+    }
+  }
+  return {format: 1, projectSha256, routeCount: routes.length, moduleCount: modules.size, observations, summary};
+}