@jimhoyd/urlcode 0.5.0 → 0.5.5

package/dist/extension-transport.js

@@ -0,0 +1,41 @@
+import { createHash } from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { readdir, rename, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { ConfigError, assert } from './errors.js';
+
+/** Shared GitHub release/cache/lockfile plumbing for extension-artifacts.ts and extension-bundles.ts. No opinion on what content is allowed or executable; that trust boundary stays local to each caller (#441). */
+
+                                                    
+export const isRecord=(v        )                   =>v !== null && typeof v==='object' && !Array.isArray(v);
+export const digestHex=(bytes           )       =>createHash('sha256').update(bytes).digest('hex');
+export function textField(value        , what       )        { assert(typeof value==='string' && value.length>0 && value.length<256,`Invalid ${what}`); return value; }
+export function exactKeys(value              , expected                  , what       )      { const actual=Object.keys(value).sort(); assert(JSON.stringify(actual)===JSON.stringify([...expected].sort()),`${what} has unknown or missing fields`); }
+const capitalize=(value       )       =>value.charAt(0).toUpperCase()+value.slice(1);
+
+/** Sorted, recursive listing of an extension cache directory; refuses links and special files. */
+export async function listCachedFiles(root       , itemLabel       , prefix='')                   { const found         =[]; for(const item of await readdir(join(root,prefix),{withFileTypes:true})) { const path=prefix?`${prefix}/${item.name}`:item.name; assert(item.isDirectory()||item.isFile(),`${capitalize(itemLabel)} cache contains a link or special file`); if(item.isDirectory()) found.push(...await listCachedFiles(root,itemLabel,path)); else found.push(path); } return found.sort(); }
+
+/** Atomic write-then-rename for a JSON lockfile, refusing to clobber a concurrent writer. */
+export async function writeLockAtomic(path       , temporary       , data        )               { await writeFile(temporary,JSON.stringify(data,null,2)+'\n',{flag:'wx'}); try { await rename(temporary,path); } finally { await rm(temporary,{force:true}); } }
+
+                                                          
+                                                                                                                                                                             
+                                                                                                                                                           
+
+/** A transport that accepts only GitHub Release asset URLs and verifies every downloaded subject. */
+export function createGithubTransport(config                      )                 {
+  const {repository,workflow,tagPattern,exampleTag,maxAssetSize,itemLabel}=config, releaseLabel=`${itemLabel} release`;
+  const releaseUrl=(tagName       )       =>`https://api.github.com/repos/${repository}/releases/tags/${encodeURIComponent(tagName)}`;
+  function downloadUrl(value       )     { const url=new URL(value); assert(url.protocol==='https:'&&(url.hostname==='github.com'||url.hostname.endsWith('.githubusercontent.com')),`${capitalize(releaseLabel)} redirect left GitHub`); return url; }
+  async function download(value       )                     { let url=downloadUrl(value); for(let redirects=0;redirects<=3;redirects++) { const response=await fetch(url,{redirect:'manual'}); if(response.status>=300&&response.status<400) { const location=response.headers.get('location'); assert(location&&redirects<3,`${capitalize(releaseLabel)} asset has an invalid redirect`); url=downloadUrl(new URL(location,url).href); continue; } assert(response.ok&&response.body,`Could not download ${releaseLabel} asset`); const length=response.headers.get('content-length'); assert(length===null||(/^\d+$/.test(length)&&Number(length)<=maxAssetSize),`${capitalize(releaseLabel)} asset exceeds the size limit`); const chunks             =[]; let size=0; for await(const chunk of response.body) { size+=chunk.byteLength; assert(size<=maxAssetSize,`${capitalize(releaseLabel)} asset exceeds the size limit`); chunks.push(chunk); } const body=new Uint8Array(size); let offset=0; for(const chunk of chunks) { body.set(chunk,offset); offset+=chunk.byteLength; } return body; } throw new ConfigError(`${capitalize(releaseLabel)} asset redirected too many times`); }
+  return {
+    async release(tagName) { assert(tagPattern.test(tagName),`Use an immutable ${releaseLabel} tag such as ${exampleTag}`); const response=await fetch(releaseUrl(tagName),{headers:{accept:'application/vnd.github+json'}}); assert(response.ok,`Could not fetch ${releaseLabel} ${tagName}`); const raw        =await response.json(); assert(isRecord(raw)&&Array.isArray(raw.assets),`${capitalize(releaseLabel)} has no asset inventory`); const seen=new Set        (); return raw.assets.map(item=>{ assert(isRecord(item)&&typeof item.name==='string'&&typeof item.browser_download_url==='string'&&!seen.has(item.name),`Invalid or duplicate ${releaseLabel} asset`); seen.add(item.name); const url=new URL(item.browser_download_url); assert(url.protocol==='https:'&&url.hostname==='github.com'&&url.pathname.startsWith(`/${repository}/releases/download/`),`${capitalize(releaseLabel)} asset is not a GitHub download`); return {name:item.name,url:url.href}; }); },
+    download,
+    async attest(path,release) { assert(tagPattern.test(release),`Invalid ${itemLabel} release tag`); await new Promise      ((resolveVerify,reject)=>{ const child=spawn('gh',['attestation','verify',path,'--repo',repository,'--signer-workflow',workflow,'--source-ref',`refs/tags/${release}`,'--deny-self-hosted-runners'],{stdio:'ignore'}); child.on('error',()=>reject(new ConfigError(`GitHub CLI with attestation support is required to verify ${itemLabel}s`))); child.on('exit',code=>code===0?resolveVerify():reject(new ConfigError(`GitHub attestation verification refused the ${itemLabel}`))); }); },
+  };
+}
+
+/** Downloads one named release asset and has the transport attest it before returning its bytes. */
+export async function verifiedReleaseAsset(assets               , asset       , release       , transport                , itemLabel       , tempPrefix       )                     { const found=assets.filter(item=>item.name===asset); assert(found.length===1,`${capitalize(itemLabel)} release is missing or repeats ${asset}`); const bytes=await transport.download(found[0] .url); const temporary=join(tmpdir(),`${tempPrefix}-${process.pid}-${Math.random().toString(16).slice(2)}`); await writeFile(temporary,bytes,{flag:'wx'}); try { await transport.attest(temporary,release); return bytes; } finally { await rm(temporary,{force:true}); } }

package/dist/feature-plan.js

@@ -0,0 +1,99 @@
+import {buildContext,estimateTokens} from './context.js';
+import {getCapabilities,normalizeCapabilityTarget} from './capabilities.js';
+                                                                       
+import {listRecipes} from './recipes.js';
+import {describeArtifactCache} from './extension-artifacts.js';
+                                                      
+
+/** The planner is deliberately a small, local projection. It never treats goal
+ * text as instructions, opens a host, or reads extension/project source. */
+export const featurePlanMaxBytes=32768;
+export const featurePlanMaxGoalLength=512;
+                                                                                                          
+                              
+                                                                                                    
+                                                                                                                                            
+                                                                                                                                                                                                                     
+                                                                                                                                                                                    
+ 
+
+const stop=new Set(['a','an','and','the','with','for','to','of','in','on','that','my','i','want','need','from']);
+function terms(goal       )          {
+ const words=goal.toLowerCase().split(/[^a-z0-9.-]+/).filter(word=>word.length>1&&!stop.has(word));
+ return [...new Set(words)].slice(0,16);
+}
+const recipeTerms                                 ={
+ 'contact-form':['contact','form','message','submit','submission','email'],
+ 'authenticated-json-api':['auth','authenticated','account','sign','signed','private','protected'],
+ 'store-crud':['store','persist','persisted','persistence','durable','database','crud','record','records','submission','submissions'],
+};
+const extensionReason                      ={
+ ui:'Presentation is an operator-installed extension; its registered authoring surfaces govern project-owned UI customization.',
+ auth:'Authentication is an operator-installed extension; its registration and revision pin, not project YAML, select the executable package and grants.',
+ store:'Durable state is an operator-installed extension; its data directory and revision pin remain operator-owned.',
+ forms:'Form workflow is available only through the already-registered forms extension contract; the project cannot select or install it.',
+};
+const outline                                         ={
+ 'contact-form':{kind:'contact endpoint',note:'The bundled recipe establishes one POST JSON endpoint with bounded validation and a revision-pinned signal; it does not provide a browser form flow.'},
+ 'authenticated-json-api':{kind:'protected endpoint',note:'The bundled recipe protects a function route through the auth extension policy; the project declares the requirement but never loads the package.'},
+ 'store-crud':{kind:'durable collection',note:'The bundled recipe declares a collection and an extension mount; CRUD behavior belongs to the registered store extension, not a generated handler.'},
+};
+function selectedRecipes(goalTerms         , recipes                                        ) {
+ const mapped=recipes.filter(recipe=>{
+  const known=recipeTerms[recipe.name]??[];
+  return known.some(term=>goalTerms.includes(term));
+ });
+ return (mapped.length?mapped:recipes.filter(recipe=>recipe.tags.some(tag=>goalTerms.includes(tag.toLowerCase())))).slice(0,4);
+}
+
+/**
+ * Plans only from the current compiled project, package-owned catalogs, locked
+ * inert artifacts, and registrations passed by the already-opened operator
+ * session. It intentionally has no filesystem path, host-file, binding, or
+ * execution argument.
+ */
+export async function planFeature(project       ,goal       ,options                   ={})                      {
+ if(typeof goal!=='string'||goal.length<1||goal.length>featurePlanMaxGoalLength)throw new Error(`Feature goal must be 1 to ${featurePlanMaxGoalLength} characters`);
+ const goalTerms=terms(goal),target=normalizeCapabilityTarget(options.target??'self-hosted');
+ const context=await buildContext(project,{target,projectFlag:'.'}), recipes=selectedRecipes(goalTerms,await listRecipes());
+ const capabilities=[...new Set(recipes.flatMap(recipe=>recipe.capabilities??[]).filter((name)                       =>typeof name==='string'))].sort();
+ const catalog=getCapabilities(target), rows=new Map(catalog.capabilities.map(row=>[row.capability,row]));
+ const registrations=new Map((options.extensions??[]).map(extension=>[extension.name,extension]));
+ const wanted=new Set        ();
+ for(const recipe of recipes) for(const service of recipe.services??[]) {
+  const match=/\b(ui|auth|store) extension\b/i.exec(service.name); if(match)wanted.add(match[1] .toLowerCase());
+ }
+ // These nouns request composition, not a project-controlled package choice.
+ if(goalTerms.some(term=>['form','contact','screen','page','ui'].includes(term)))wanted.add('ui');
+ // A forms capability is discoverable only from an operator registration. Do
+ // not turn a goal noun into an implied package choice or YAML declaration.
+ if(goalTerms.some(term=>['form','flow','workflow','multistep','multi-step','wizard'].includes(term))&&registrations.has('forms'))wanted.add('forms');
+ if(goalTerms.some(term=>['auth','authenticated','account','sign','signed','private','protected'].includes(term)))wanted.add('auth');
+ if(goalTerms.some(term=>['store','persist','persisted','persistence','durable','database','crud','record','records','submission','submissions'].includes(term)))wanted.add('store');
+ let artifacts                                                               =[];
+ try {artifacts=(await describeArtifactCache(project)).artifacts;} catch {/* no lock is an ordinary absence, never a reason to read elsewhere */}
+ const declared=new Set(context.project.extensions);
+ const required=[...wanted].sort().map(name=>{
+  const registration=registrations.get(name), artifact=artifacts.find(item=>item.name===name);
+  const supported=target!=='static'&&registration?.targets.includes(target==='self-hosted'?'node':target);
+  return {name,reason:extensionReason[name]??'This feature needs an operator-registered extension contract.',declared:declared.has(name),registered:Boolean(registration),target:registration?(supported?'supported':'refused'):'unknown',artifact:artifact?.status??'none'}         ;
+ });
+ const unsupported                           =[];
+ if(goalTerms.some(term=>['flow','workflow','multistep','multi-step','wizard'].includes(term))&&!registrations.has('forms'))unsupported.push({requirement:'Declarative form flow',reason:'No already-registered forms extension contract is available, and no bundled core capability or recipe declares multi-step form state, transitions, or submission orchestration. Keep that application behavior focused, or define it as an extension boundary.'});
+ if(goalTerms.some(term=>['idempotent','idempotency'].includes(term)))unsupported.push({requirement:'Idempotent mutation',reason:'The core capability catalog has no idempotent mutation primitive. Require an installed extension contract that exposes it, or keep the idempotency key and mutation logic in application code.'});
+ for(const capability of capabilities){const row=rows.get(capability);if(row?.targets[target]?.support==='refused')unsupported.push({requirement:capability,reason:row.targets[target] .reason});}
+ for(const extension of required)if(extension.target==='refused')unsupported.push({requirement:`${extension.name} extension on ${target}`,reason:'The already-registered extension does not declare support for this target.'});
+ const applicationCode                               =[];
+ if(recipes.some(recipe=>recipe.name==='contact-form'))applicationCode.push({requirement:'Product-specific form presentation and submission rules',reason:'The contact recipe covers a bounded JSON endpoint and optional signal only; it does not generate browser UI or business workflow code.'});
+ if(!recipes.length)applicationCode.push({requirement:'Feature-specific behavior',reason:'No bundled declarative recipe matched the bounded goal terms. Check capability and extension contracts before writing focused application code.'});
+ const plan                                    ={
+  format:1,goalTerms,target,project:{routes:context.project.routes,extensions:context.project.extensions},
+  applicable:{capabilities:capabilities.map(name=>{const decision=rows.get(name)?.targets[target];return {name,support:decision?.support??'unknown',reason:decision?.reason??'Not in this revision\'s capability catalog'};}),recipes:recipes.map(recipe=>({name:recipe.name,description:recipe.description,matched:(recipeTerms[recipe.name]??[]).filter(term=>goalTerms.includes(term)).slice(0,4)}))},
+  extensions:{required,ordering:{status:'operator-resolved',names:[...wanted].sort(),note:'Extension package selection, prerequisites, and canonical activation order are resolved by the operator-approved init/host composition. This read-only plan neither loads a bundle nor turns project YAML into an operator decision.'}},
+  outline:recipes.map(recipe=>outline[recipe.name]??{kind:recipe.name,note:'Use the bundled recipe metadata as the known contract.'}),applicationCode,unsupported,
+  next:['get_context','search_recipes','get_capability','get_extensions','get_extension_artifacts'].filter((name,index,all)=>all.indexOf(name)===index),
+ };
+ const estimatedTokens=estimateTokens(JSON.stringify(plan)); const result={...plan,estimatedTokens};
+ if(Buffer.byteLength(JSON.stringify(result))>featurePlanMaxBytes)throw new Error('Feature plan exceeds output limit');
+ return result;
+}

package/dist/index.js

@@ -21,8 +21,8 @@ export {buildTypeScriptProject} from './typescript-authoring.js';
                                                                      
 export {importBulkProject} from './bulk.js';
                                                                           
-export {inspectProject, validateProject, explainRoute, explainProject, previewImport, previewExport, getCapability, getSchemaFragment, schemaPathNames, inspectExtensions, describeExtensions, buildContext, renderContext, estimateTokens, documentationTokens, buildTaskContext, renderTaskContext, contextTasks} from './tooling.js';
-                                                                                                                                                                                                                                                                                                                                             
+export {inspectProject, validateProject, explainRoute, explainProject, previewImport, previewExport, getCapability, getSchemaFragment, schemaPathNames, inspectExtensions, describeExtensions, buildContext, renderContext, estimateTokens, documentationTokens, buildTaskContext, renderTaskContext, contextTasks, planFeature, featurePlanMaxBytes, featurePlanMaxGoalLength} from './tooling.js';
+                                                                                                                                                                                                                                                                                                                                                                              
 export {buildManifest, renderManifest, MANIFEST_SCHEMA_VERSION} from './manifest.js';
                                                                                              
 export {serveMcp} from './mcp.js';

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.5.0'}}});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/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};
+}

package/dist/router.js

@@ -140,8 +140,21 @@ export async function compileRoutes(loaded                , bindings
     }
     assert(names.every(name => route.parameters.some(p => p.in === 'path' && p.name === name)), 'Every path placeholder requires an input declaration');
     for (const [alias, ref] of Object.entries(config.env || {})) {
-      if (ref.env) assert(permissions.projectSha256 === projectSha256 && permissions.routes?.[pattern]?.env?.includes(ref.env), 'Environment binding denied by operator policy');
-      const value = own(ref, 'value') ? ref.value : bindings[ref.env ];
+      // `env` always requires an operator grant for that route/name. A missing grant is not
+      // fatal when a `default` is declared: the binding just degrades to its literal default
+      // and never reads the host (issue #258). With no `default`, a missing grant still fails
+      // route compilation, as before. `value`-only bindings are plain literals and never
+      // consult the grant or the host environment.
+      let value                    ;
+      if (ref.env) {
+        const granted = permissions.projectSha256 === projectSha256 && permissions.routes?.[pattern]?.env?.includes(ref.env);
+        assert(granted || ref.default !== undefined, 'Environment binding denied by operator policy');
+        const hostValue = bindings[ref.env];
+        const hostSet = ref.default !== undefined ? typeof hostValue === 'string' && hostValue.length > 0 : hostValue !== undefined;
+        value = granted ? (hostSet ? hostValue : ref.default) : ref.default;
+      } else {
+        value = ref.value;
+      }
       assert(typeof value === 'string', 'Missing required environment binding');
       route.env[alias] = value;
     }

package/dist/tooling.js

@@ -23,7 +23,11 @@ export {getSchemaFragment,schemaPathNames} from './schema-query.js';
 export {listRecipes,showRecipe,searchRecipes,listExamples,searchExamples};
 export {buildContext,renderContext,estimateTokens,documentationTokens,buildTaskContext,renderTaskContext,contextTasks} from './context.js';
                                                                                                                  
+export {planFeature,featurePlanMaxBytes,featurePlanMaxGoalLength} from './feature-plan.js';
+                                                                      
                                                                                                                                                  
+export {reviewProject} from './review.js';
+                                                                                             
 /** `extensions` are operator registrations from a host file; explain reports whether each requirement has a provider. Nothing is activated. */
                                                                                                                                      
 function routesOf(table                                          )                 {return [...table.exact.values(),...[...table.byLength.values()].flat(),...table.mounts];}

package/dist/types/authoring.d.ts

@@ -8,5 +8,7 @@ export interface InitOptions {
     /** `default` (function, middleware, redirect) or `page`: urlcode.yaml, public/index.html, a README and fixtures only. */
     template?: 'default' | 'page' | 'redirects' | undefined;
 }
+/** Adds what the starter needs to an existing package.json and changes nothing else; a conflicting script is refused, never overwritten. */
+export declare function mergePackageJson(text: string, scripts: Record<string, string>, dependency: string, version: string): string;
 export declare function initProject(destination: string, { manifest, template }?: InitOptions): Promise<string>;
 export declare function addRedirect(project: string, destination: string, alias?: string | undefined): Promise<string>;

package/dist/types/explain.d.ts

@@ -76,6 +76,9 @@ export interface RouteExplanation {
             env: string;
         } | {
             literal: true;
+        } | {
+            env: string;
+            default: string;
         }>;
         secrets: Record<string, {
             secret: string;

package/dist/types/extension-artifacts.d.ts

@@ -1,3 +1,4 @@
+import { type ReleaseAsset } from './extension-transport.ts';
 /** Offline, declarative extension bundles. These are deliberately not Node packages. */
 export declare const ARTIFACT_REPOSITORY = "jimhoyd-com/urlcode";
 export declare const ARTIFACT_WORKFLOW = "jimhoyd-com/urlcode/.github/workflows/extension-artifacts.yml";
@@ -47,10 +48,7 @@ export declare function extractArtifact(bytes: Uint8Array, entry: ArtifactEntry,
 export declare function readLock(project: string): Promise<ExtensionLock>;
 export declare function writeLock(project: string, lock: ExtensionLock): Promise<void>;
 export declare function cachePath(project: string, sha256: string): string;
-export interface ReleaseAsset {
-    name: string;
-    url: string;
-}
+export type { ReleaseAsset };
 export interface ArtifactTransport {
     release(tag: string): Promise<ReleaseAsset[]>;
     download(url: string): Promise<Uint8Array>;

package/dist/types/extension-transport.d.ts

@@ -0,0 +1,31 @@
+/** Shared GitHub release/cache/lockfile plumbing for extension-artifacts.ts and extension-bundles.ts. No opinion on what content is allowed or executable; that trust boundary stays local to each caller (#441). */
+export type UnknownRecord = Record<string, unknown>;
+export declare const isRecord: (v: unknown) => v is UnknownRecord;
+export declare const digestHex: (bytes: Uint8Array) => string;
+export declare function textField(value: unknown, what: string): string;
+export declare function exactKeys(value: UnknownRecord, expected: readonly string[], what: string): void;
+/** Sorted, recursive listing of an extension cache directory; refuses links and special files. */
+export declare function listCachedFiles(root: string, itemLabel: string, prefix?: string): Promise<string[]>;
+/** Atomic write-then-rename for a JSON lockfile, refusing to clobber a concurrent writer. */
+export declare function writeLockAtomic(path: string, temporary: string, data: unknown): Promise<void>;
+export interface ReleaseAsset {
+    name: string;
+    url: string;
+}
+export interface GithubTransport {
+    release(tag: string): Promise<ReleaseAsset[]>;
+    download(url: string): Promise<Uint8Array>;
+    attest(path: string, release: string): Promise<void>;
+}
+export interface GithubTransportConfig {
+    repository: string;
+    workflow: string;
+    tagPattern: RegExp;
+    exampleTag: string;
+    maxAssetSize: number;
+    itemLabel: string;
+}
+/** A transport that accepts only GitHub Release asset URLs and verifies every downloaded subject. */
+export declare function createGithubTransport(config: GithubTransportConfig): GithubTransport;
+/** Downloads one named release asset and has the transport attest it before returning its bytes. */
+export declare function verifiedReleaseAsset(assets: ReleaseAsset[], asset: string, release: string, transport: GithubTransport, itemLabel: string, tempPrefix: string): Promise<Uint8Array>;

package/dist/types/feature-plan.d.ts

@@ -0,0 +1,67 @@
+import type { CapabilityName, CapabilityTarget } from './capabilities.ts';
+import type { RuntimeExtension } from './extensions.ts';
+/** The planner is deliberately a small, local projection. It never treats goal
+ * text as instructions, opens a host, or reads extension/project source. */
+export declare const featurePlanMaxBytes = 32768;
+export declare const featurePlanMaxGoalLength = 512;
+export interface FeaturePlanOptions {
+    target?: string;
+    extensions?: readonly RuntimeExtension[] | undefined;
+}
+export interface FeaturePlan {
+    format: 1;
+    goalTerms: string[];
+    target: CapabilityTarget;
+    project: {
+        routes: number;
+        extensions: string[];
+    };
+    applicable: {
+        capabilities: {
+            name: CapabilityName;
+            support: string;
+            reason: string;
+        }[];
+        recipes: {
+            name: string;
+            description: string;
+            matched: string[];
+        }[];
+    };
+    extensions: {
+        required: {
+            name: string;
+            reason: string;
+            declared: boolean;
+            registered: boolean;
+            target: string;
+            artifact: 'none' | 'cached' | 'missing' | 'invalid';
+        }[];
+        ordering: {
+            status: 'operator-resolved';
+            names: string[];
+            note: string;
+        };
+    };
+    outline: {
+        kind: string;
+        note: string;
+    }[];
+    applicationCode: {
+        requirement: string;
+        reason: string;
+    }[];
+    unsupported: {
+        requirement: string;
+        reason: string;
+    }[];
+    next: string[];
+    estimatedTokens: number;
+}
+/**
+ * Plans only from the current compiled project, package-owned catalogs, locked
+ * inert artifacts, and registrations passed by the already-opened operator
+ * session. It intentionally has no filesystem path, host-file, binding, or
+ * execution argument.
+ */
+export declare function planFeature(project: string, goal: string, options?: FeaturePlanOptions): Promise<FeaturePlan>;

package/dist/types/index.d.ts

@@ -18,8 +18,8 @@ export { buildTypeScriptProject } from './typescript-authoring.ts';
 export type { TypeScriptBuildReport } from './typescript-authoring.ts';
 export { importBulkProject } from './bulk.ts';
 export type { BulkFormat, BulkFilePlan, BulkImportReport } from './bulk.ts';
-export { inspectProject, validateProject, explainRoute, explainProject, previewImport, previewExport, getCapability, getSchemaFragment, schemaPathNames, inspectExtensions, describeExtensions, buildContext, renderContext, estimateTokens, documentationTokens, buildTaskContext, renderTaskContext, contextTasks } from './tooling.ts';
-export type { InspectOptions, RouteExplanation, RouteMiss, ExplainedHandler, ExplainedCache, ExplainedExtensionRequirement, ExtensionProvider, TargetSupport, CapabilityEntry, CapabilityUsage, SchemaFragment, ExtensionInspection, ContextOptions, ProjectContext, ContextSection, ContextTask, TaskContext, TaskShape } from './tooling.ts';
+export { inspectProject, validateProject, explainRoute, explainProject, previewImport, previewExport, getCapability, getSchemaFragment, schemaPathNames, inspectExtensions, describeExtensions, buildContext, renderContext, estimateTokens, documentationTokens, buildTaskContext, renderTaskContext, contextTasks, planFeature, featurePlanMaxBytes, featurePlanMaxGoalLength } from './tooling.ts';
+export type { InspectOptions, RouteExplanation, RouteMiss, ExplainedHandler, ExplainedCache, ExplainedExtensionRequirement, ExtensionProvider, TargetSupport, CapabilityEntry, CapabilityUsage, SchemaFragment, ExtensionInspection, ContextOptions, ProjectContext, ContextSection, ContextTask, TaskContext, TaskShape, FeaturePlan, FeaturePlanOptions } from './tooling.ts';
 export { buildManifest, renderManifest, MANIFEST_SCHEMA_VERSION } from './manifest.ts';
 export type { Manifest, ManifestRoute, ManifestModule, RecipeProvenance } from './manifest.ts';
 export { serveMcp } from './mcp.ts';