@jimhoyd/urlcode 0.5.0 → 0.5.6

package/dist/extension-bundles.js

@@ -1,11 +1,10 @@
-import { createHash } from 'node:crypto';
-import { spawn } from 'node:child_process';
-import { lstat, mkdir, readFile, readdir, rename, rm, writeFile } from 'node:fs/promises';
+import { lstat, mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { dirname, join, relative, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { ConfigError, assert } from './errors.js';
 import { readBoundedTgz,              } from './extension-artifacts.js';
+import {                                    isRecord as record, digestHex as digest, textField, exactKeys as sharedExactKeys, listCachedFiles, writeLockAtomic, createGithubTransport, verifiedReleaseAsset,                   } from './extension-transport.js';
 
 /** Verified, executable first-party bundles. Unlike extension artifacts, these are trusted operator code. */
 export const BUNDLE_REPOSITORY='jimhoyd-com/urlcode';
@@ -17,11 +16,8 @@ const hex=/^[a-f0-9]{64}$/;
 const entry=/^node_modules\/@jimhoyd\/urlcode-[a-z][a-z0-9-]{0,63}\/dist\/[A-Za-z0-9._/-]+\.js$/;
 const safeEntry=(value       )        =>entry.test(value)&&value.split('/').every(segment=>segment!=='.'&&segment!=='..');
 const limits={archive:128*1024*1024,expanded:512*1024*1024,files:12000,file:32*1024*1024,label:'Extension bundle archive'};
-                                        
-const record=(value        )                     =>value!==null&&typeof value==='object'&&!Array.isArray(value);
-const digest=(bytes           )=>createHash('sha256').update(bytes).digest('hex');
-const text=(value        ,what       )       =>{assert(typeof value==='string'&&value.length>0&&value.length<256,`Invalid ${what} in extension bundle metadata`);return value;};
-const exact=(value            ,keys                  ,what       )     =>assert(JSON.stringify(Object.keys(value).sort())===JSON.stringify([...keys].sort()),`${what} has unknown or missing fields`);
+const text=(value        ,what       )       =>textField(value,`${what} in extension bundle metadata`);
+const exact=(value            ,keys                  ,what       )     =>sharedExactKeys(value,keys,what);
 
                                                                                                         
                                                                                                                                                            
@@ -53,17 +49,13 @@ function bundleManifest(files          )                {
 function validateFiles(files          ,item                                           ,coreVersion       )      {
   assert(files.length>1&&files.every(file=>file.path==='bundle.json'||file.path.startsWith('node_modules/')),'Extension bundle contains a file outside its frozen module tree');const manifest=bundleManifest(files);assert(manifest.coreVersion===coreVersion,'Extension bundle core version does not match its signed catalog');assert(manifest.bundles.some(value=>value.name===item.name&&value.version===item.version&&value.entry===item.entry),'Extension bundle manifest does not match its signed catalog entry');assert(files.some(file=>file.path===item.entry),'Extension bundle is missing its declared entry module');
 }
-async function diskFiles(root       ,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(),'Extension bundle cache contains a link or special file');if(item.isDirectory())found.push(...await diskFiles(root,path));else found.push(path);}return found.sort();}
-async function validateCached(root       ,item             )              {const archive=await readFile(join(root,'.bundle.tgz'));assert(digest(archive)===item.sha256,`Cached extension bundle ${item.name} does not match its lockfile`);const files=readBoundedTgz(archive,limits);validateFiles(files,item,item.coreVersion);const expected=['.bundle.tgz',...files.map(file=>file.path)].sort();assert(JSON.stringify(await diskFiles(root))===JSON.stringify(expected),`Cached extension bundle ${item.name} has unexpected files`);for(const file of files)assert(digest(await readFile(join(root,file.path)))===digest(file.bytes),`Cached extension bundle ${item.name} was modified`);}
+async function validateCached(root       ,item             )              {const archive=await readFile(join(root,'.bundle.tgz'));assert(digest(archive)===item.sha256,`Cached extension bundle ${item.name} does not match its lockfile`);const files=readBoundedTgz(archive,limits);validateFiles(files,item,item.coreVersion);const expected=['.bundle.tgz',...files.map(file=>file.path)].sort();assert(JSON.stringify(await listCachedFiles(root,'extension bundle'))===JSON.stringify(expected),`Cached extension bundle ${item.name} has unexpected files`);for(const file of files)assert(digest(await readFile(join(root,file.path)))===digest(file.bytes),`Cached extension bundle ${item.name} was modified`);}
 export async function extractBundle(bytes           ,item                                                                   ,destination       )              {assert(digest(bytes)===item.sha256,`Extension bundle ${item.name} does not match its signed SHA-256`);const files=readBoundedTgz(bytes,limits);validateFiles(files,item,item.coreVersion);const root=resolve(destination),temporary=join(tmpdir(),`urlcode-extension-bundle-${process.pid}-${Math.random().toString(16).slice(2)}`);await mkdir(temporary,{recursive:true});try{for(const file of files){const target=resolve(temporary,file.path),rel=relative(temporary,target);assert(rel&&!rel.startsWith('..'),'Unsafe extension bundle path');await mkdir(dirname(target),{recursive:true});await writeFile(target,file.bytes,{flag:'wx'});}await writeFile(join(temporary,'.bundle.tgz'),bytes,{flag:'wx'});await mkdir(dirname(root),{recursive:true});try{await rename(temporary,root);}catch{try{await validateCached(root,item                );return;}catch{throw new ConfigError(`Extension bundle cache entry ${item.sha256} already exists but is not identical`);}}}finally{await rm(temporary,{recursive:true,force:true});}}
 export function bundleCachePath(project       ,sha256       )       {assert(hex.test(sha256),'Invalid extension bundle digest');return join(project,'.urlcode','extension-bundles',sha256);}
 export async function readBundleLock(project       )                    {let raw        ;try{const path=join(project,'urlcode.extension-bundles.lock.json'),info=await lstat(path);assert(info.isFile()&&!info.isSymbolicLink()&&info.nlink===1,'Extension bundle lockfile must be an ordinary file');raw=JSON.parse(await readFile(path,'utf8'));}catch(error){if(error instanceof ConfigError)throw error;throw new ConfigError('No extension bundle lockfile; install a bundle first');}assert(record(raw)&&raw.format===1&&Array.isArray(raw.bundles),'Invalid extension bundle lockfile');exact(raw,['format','bundles'],'Extension bundle lockfile');const seen=new Set        (),bundles=raw.bundles.map(value=>{assert(record(value)&&record(value.catalog),'Invalid extension bundle lock entry');exact(value,['name','version','asset','sha256','entry','catalog','coreVersion'],'Extension bundle lock entry');exact(value.catalog,['tag','commit'],'Extension bundle lock catalog');const item={...parseEntry(value,'extension bundle lock entry',false),catalog:{tag:text(value.catalog.tag,'lock tag'),commit:text(value.catalog.commit,'lock commit')},coreVersion:text(value.coreVersion,'lock core version')};assert(tag.test(item.catalog.tag)&&/^[a-f0-9]{40}$/.test(item.catalog.commit)&&version.test(item.coreVersion)&&!seen.has(item.name),'Invalid or duplicate extension bundle lock entry');seen.add(item.name);return item;});return {format:1,bundles};}
-async function writeLock(project       ,lock           )              {const path=join(project,'urlcode.extension-bundles.lock.json'),temporary=join(project,`.urlcode.extension-bundles.lock.${process.pid}.${Math.random().toString(16).slice(2)}`);await writeFile(temporary,JSON.stringify(lock,null,2)+'\n',{flag:'wx'});try{await rename(temporary,path);}finally{await rm(temporary,{force:true});}}
-function releaseUrl(value       )       {return `https://api.github.com/repos/${BUNDLE_REPOSITORY}/releases/tags/${encodeURIComponent(value)}`;}
-function downloadUrl(value       )    {const url=new URL(value);assert(url.protocol==='https:'&&(url.hostname==='github.com'||url.hostname.endsWith('.githubusercontent.com')),'Extension bundle release 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,'Extension bundle release asset has an invalid redirect');url=downloadUrl(new URL(location,url).href);continue;}assert(response.ok&&response.body,'Could not download extension bundle release asset');const chunks             =[];let size=0;for await(const chunk of response.body){size+=chunk.byteLength;assert(size<=limits.archive,'Extension bundle release asset exceeds the size limit');chunks.push(chunk);}const result=new Uint8Array(size);let offset=0;for(const chunk of chunks){result.set(chunk,offset);offset+=chunk.byteLength;}return result;}throw new ConfigError('Extension bundle release asset redirected too many times');}
-export const githubBundleTransport                ={async release(value){assert(tag.test(value),'Use an immutable extension bundle release tag such as extension-bundles@v1.0.0');const response=await fetch(releaseUrl(value),{headers:{accept:'application/vnd.github+json'}});assert(response.ok,`Could not fetch extension bundle release ${value}`);const raw        =await response.json();assert(record(raw)&&Array.isArray(raw.assets),'Extension bundle release has no asset inventory');const seen=new Set        ();return raw.assets.map(asset=>{assert(record(asset)&&typeof asset.name==='string'&&typeof asset.browser_download_url==='string'&&!seen.has(asset.name),'Invalid or duplicate extension bundle release asset');seen.add(asset.name);const url=new URL(asset.browser_download_url);assert(url.protocol==='https:'&&url.hostname==='github.com'&&url.pathname.startsWith(`/${BUNDLE_REPOSITORY}/releases/download/`),'Extension bundle release asset is not a GitHub download');return {name:asset.name,url:url.href};});},download,async attest(path,release){assert(tag.test(release),'Invalid extension bundle release tag');await new Promise      ((accept,reject)=>{const child=spawn('gh',['attestation','verify',path,'--repo',BUNDLE_REPOSITORY,'--signer-workflow',BUNDLE_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 extension bundles')));child.on('exit',code=>code===0?accept():reject(new ConfigError('GitHub attestation verification refused the extension bundle')));});}};
-async function verified(assets                           ,asset       ,release       ,transport                )                    {const found=assets.filter(value=>value.name===asset);assert(found.length===1,`Extension bundle release is missing or repeats ${asset}`);const bytes=await transport.download(found[0] .url),temporary=join(tmpdir(),`urlcode-bundle-attest-${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});}}
+async function writeLock(project       ,lock           )              {const path=join(project,'urlcode.extension-bundles.lock.json'),temporary=join(project,`.urlcode.extension-bundles.lock.${process.pid}.${Math.random().toString(16).slice(2)}`);await writeLockAtomic(path,temporary,lock);}
+export const githubBundleTransport                =createGithubTransport({repository:BUNDLE_REPOSITORY,workflow:BUNDLE_WORKFLOW,tagPattern:tag,exampleTag:'extension-bundles@v1.0.0',maxAssetSize:limits.archive,itemLabel:'extension bundle'});
+async function verified(assets               ,asset       ,release       ,transport                )                    {return verifiedReleaseAsset(assets,asset,release,transport,'extension bundle','urlcode-bundle-attest');}
 export async function installBundle(project       ,release       ,bundleName       ,transport                =githubBundleTransport)                    {assert(name.test(bundleName),'Invalid extension bundle name');const assets=await transport.release(release),catalog=parseBundleCatalog(await verified(assets,'extension-bundles-catalog.json',release,transport),release),item=catalog.bundles.find(value=>value.name===bundleName);assert(item,`Extension bundle ${bundleName} is not in the signed catalog`);const revoked=catalog.revoked.find(value=>value.sha256===item.sha256);assert(!revoked,`Extension bundle ${bundleName} is revoked: ${revoked?.reason??'unknown reason'}`);const locked                                                                    ={...item,catalog:{tag:catalog.tag,commit:catalog.commit},coreVersion:catalog.coreVersion};await extractBundle(await verified(assets,item.asset,release,transport),locked,bundleCachePath(project,item.sha256));let prior                     ;try{prior=await readBundleLock(project);}catch{/* first install */}const bundles=(prior?.bundles??[]).filter(value=>value.name!==item.name);bundles.push(locked);bundles.sort((left,right)=>left.name.localeCompare(right.name));const lock={format:1         ,bundles};await writeLock(project,lock);return lock;}
 async function runningCoreVersion()                {const raw        =JSON.parse(await readFile(new URL('../package.json',import.meta.url),'utf8'));assert(record(raw)&&typeof raw.version==='string'&&version.test(raw.version),'Could not read the running core version');return raw.version;}
 /** Explicit host-only loader. It never reads project YAML, downloads, updates, or discovers code. */

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.6'}}});return;
   }
   if(message.method==='ping'){await send({jsonrpc:'2.0',id,result:{}});return;}
   if(!ready){await error(id,-32002,'Initialize first');return;}

package/dist/policies/agents.js

@@ -2,7 +2,7 @@ import { assert, ConfigError } from '../errors.js';
 import { lists as bundled } from '../../data/agents/index.js';
                                                          
 
-// User-Agent policy. Contract in src/policies.ts. This module also runs inside
+// User-Agent policy. Contract in packages/core/src/policies.ts. This module also runs inside
 // the Cloudflare Worker, so it has no Node imports and never touches the
 // filesystem: bundled lists arrive through the generated data/agents/index.js
 // and project-relative list files arrive already loaded (src/agent-lists.ts

package/dist/policies/security.js

@@ -43,7 +43,7 @@ export const profiles
 });
 
 // Headers the runtime or a handler owns; `set` may not claim them. Mirrors
-// the set in src/http-policy.ts (that file uses the Node Buffer global, so the
+// the set in packages/core/src/http-policy.ts (that file uses the Node Buffer global, so the
 // list is reproduced rather than imported).
 export const reservedHeaders = Object.freeze(new Set(['connection','keep-alive','transfer-encoding','content-length','upgrade','trailer','proxy-authenticate','proxy-authorization','te','location','allow','content-range','accept-ranges','etag','last-modified','content-encoding','x-request-id','x-content-type-options','content-type','set-cookie','cache-control','vary','ratelimit','ratelimit-policy','retry-after','age']));
 

package/dist/policies.js

@@ -13,7 +13,7 @@ import { assert, ConfigError } from './errors.js';
 // function/middleware execution entirely -- trusted routes and sandbox: true
 // routes alike. Every
 // module here follows one contract so a first-party policy and an operator
-// plugin share a code path (PolicyModule in src/types.ts):
+// plugin share a code path (PolicyModule in packages/core/src/types.ts):
 //
 //   name          the YAML key under `policies`
 //   phases        'request' | 'response' | both; fixed order below

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/scripts/operational-drills.js

@@ -4,7 +4,7 @@ import {mkdtemp,mkdir,writeFile,rm} from 'node:fs/promises';
 import {tmpdir} from 'node:os';
 import {join} from 'node:path';
 import {startServer} from '../server.js';
-                                             
+                                                           
 
 const seconds=Number(process.env.URLCODE_SOAK_SECONDS||5);
 assert(Number.isInteger(seconds)&&seconds>=1&&seconds<=3600,'Soak must be 1–3600 seconds');

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>;