@jimhoyd/urlcode 0.4.0-alpha.2 → 0.4.1

package/dist/capability-query.js

@@ -44,7 +44,6 @@ function usage(base       ,files         ,name               )
   }
   return result;
 }
-export function capabilityNameList()                           {return capabilityNames;}
 /** One catalog entry with its schema fragments and bundled usage. No project, credentials or network are read. */
 export function getCapability(name       )                 {
   if(typeof name!=='string'||!(capabilityNames                     ).includes(name))throw new ConfigError('Unknown capability; valid names: '+capabilityNames.join(', '));

package/dist/catalog.js

@@ -36,7 +36,6 @@ async function validate()                     {
   }
   return validator;
 }
-export const metadataFiles={recipe:'recipe.yaml',example:'example.yaml'}         ;
 /** Reads and schema-validates one metadata file; the id must equal the directory name, and file lists stay authoring-safe paths. */
 export async function readMetadata(root        ,id        ,file                              )                           {
   const text=(await readAuthoringFile(root,file,65536)).toString('utf8');

package/dist/cli.js

@@ -14,6 +14,7 @@ import { startServer } from './server.js';
 import {scaffoldProject} from './scaffold.js';
 import { initProject, addRedirect } from './authoring.js';
 import { initProjectWith, parseWithNames } from './init-with.js';
+import { collectDependencySet, installSteps, parsePin } from './project-dependencies.js';
 import { runProjectTests } from './project-tests.js';
 import { verifyDeployment, failLevels } from './verify-deployment.js';
                                                      
@@ -27,8 +28,11 @@ import { loadComplianceRules, profileNames as complianceProfiles } from './compl
 import { parseRouteSnapshot, diffRoutes, renderRouteDiff } from './route-diff.js';
 import { readFile } from 'node:fs/promises';
 
-const usage = `URLCode 0.4.0-alpha.2 — local/self-hosted runtime
-  urlcode init <directory> [--with auth,admin]  # --with: layered site from installed @jimhoyd/urlcode-<name> packages
+const usage = `URLCode 0.4.1 — local/self-hosted runtime
+  urlcode init <directory> [--with ui,auth,admin] [--manifest|--no-manifest] [--pin @scope/pkg=specifier]
+    # --with: layered site from installed @jimhoyd/urlcode-<name> packages, with a package.json pinning them exactly; name ui first
+    # --manifest: also pin the runtime for a route-only project; --no-manifest: --with without a package.json
+    # --pin: record a local path or tarball instead of the registry version; repeatable. No install is ever run for you.
   urlcode scaffold [--project directory] [--dry-run]
   urlcode validate [--project directory] [--local] [--origin https://links.example]  # origin: absolute URLs in site.* files
   urlcode dev [--project directory] [--port 3000] [--host 127.0.0.1]
@@ -74,12 +78,13 @@ const usage = `URLCode 0.4.0-alpha.2 — local/self-hosted runtime
     # compact facts for an authoring agent from the compiled project; --stats compares estimated tokens with the docs
   urlcode doctor
   serve/dev/validate/test/routes/audit/benchmark/explain/context/extensions/mcp: --host-file /absolute/operator/host.mjs (trusted code outside project)
-Dev loads .env.local and watches; serve does neither. Functions run in WASM isolation; external bindings require --policy outside the project.
+Dev loads .env.local and watches; serve does neither. Functions run trusted and in-process by default; a route declaring sandbox: true runs in WASM isolation. External bindings require --policy outside the project.
 `;
 const print = (value         )          => process.stdout.write(typeof value === 'string' ? value : JSON.stringify(value) + '\n');
 const options = {
   json:{ type:'boolean' }, yaml:{ type:'boolean' }, report:{type:'string'}, 'accept-provider-differences':{type:'boolean'},
   project:{ type:'string', default:'.' }, 'host-file':{type:'string'}, with:{type:'string'},
+  manifest:{type:'boolean'}, 'no-manifest':{type:'boolean'}, pin:{type:'string', multiple:true},
   port:{ type:'string' }, host:{ type:'string', default:'127.0.0.1' },
   'expect-routes':{type:'string'}, requests:{type:'string'}, concurrency:{type:'string'}, seconds:{type:'string'}, 'max-p95-ms':{type:'string'}, warmup:{type:'string'}, target:{type:'string'},
   workers:{type:'string'}, 'function-timeout-ms':{type:'string'}, 'max-response-bytes':{type:'string'}, 'max-body-bytes':{type:'string'},
@@ -149,6 +154,8 @@ try {
       if (command !== 'mcp' && command !== 'context') operatorHost = await loadOperatorHost(values['host-file'], values.project);
     }
     if (values.with !== undefined && command !== 'init') throw new ConfigError('--with is only supported by init');
+    if ((values.manifest || values['no-manifest'] || values.pin !== undefined) && command !== 'init') throw new ConfigError('--manifest/--no-manifest/--pin are only supported by init');
+    if (values.manifest && values['no-manifest']) throw new ConfigError('Use either --manifest or --no-manifest');
     if (values['allow-authoring'] && command !== 'mcp') throw new ConfigError('--allow-authoring is only supported by mcp');
     const hostOptions = { extensions: operatorHost.extensions, plugins: operatorHost.plugins };
     if ((!['import','recipes','recipe','examples','example','bulk-import'].includes(command) && extra.length) || (!['init','add','import','recipes','recipe','examples','example','bulk-import','explain','capabilities','schema'].includes(command) && arg)) throw new ConfigError('Unexpected positional arguments');
@@ -266,14 +273,23 @@ try {
           const loaded = await loadDocument(values.project);
           print(requestedPermissions(loaded,await prepareFunctionSnapshot(loaded))); break;
         }
-        case 'init':
+        case 'init': {
           if (!arg) throw new ConfigError('Provide a new project directory');
-          if (values.with === undefined) { await initProject(arg); print({ event:'created' }); break; }
-          {
-            const created = await initProjectWith(arg, parseWithNames(values.with));
-            print({ event:'created', ...created, review:`Review ${created.project}/urlcode.yaml and pin its revision explicitly (for example PROJECT_SHA256=${created.projectSha256}); re-review after any project change` });
+          // Pins are opt-in for a route-only project (its runtime may be managed elsewhere) and the default for
+          // --with, which has just resolved the very packages the generated site depends on.
+          const wanted = values.with === undefined ? values.manifest === true : !values['no-manifest'];
+          const pins = new Map((values.pin ?? []).map(parsePin));
+          if (pins.size && !wanted) throw new ConfigError('--pin needs a manifest; drop --no-manifest or add --manifest');
+          if (values.with === undefined) {
+            const set = wanted ? await collectDependencySet([], [], { overrides: pins }) : undefined;
+            const created = await initProject(arg, { manifest: set });
+            print(set ? { event:'created', dependencies:set.pins, nextSteps:installSteps(created, set) } : { event:'created' });
+            break;
           }
+          const created = await initProjectWith(arg, parseWithNames(values.with), { manifest: wanted, pins });
+          print({ event:'created', ...created, review:`Review ${created.project}/urlcode.yaml and pin its revision explicitly (for example PROJECT_SHA256=${created.projectSha256}); re-review after any project change` });
           break;
+        }
         case 'validate': {
           const runtime = await createRuntime(values.project, { ...hostOptions, local:values.local, permissions, origin:values.origin });
           print({ event:'valid', routes:runtime.count, version:runtime.version }); await runtime.close(); break;
@@ -286,7 +302,7 @@ try {
           print(result); if (result.failed) process.exitCode = 1; break;
         }
         case 'doctor':
-          print({ node:process.version, platform:process.platform, architecture:process.arch, runtime:'node-process', functionSandbox:'quickjs-wasm', network:false, filesystem:false, guestNetwork:false, hostEgress:'revision-pinned-origin-grants', tooling:['recipes','examples','bulk-import','build-typescript','mcp','verify-provider'], providers:[], capabilityTargets:getCapabilities().targets, policies:Object.keys(policyRegistry), license:'Apache-2.0' }); break;
+          print({ node:process.version, platform:process.platform, architecture:process.arch, runtime:'node-process', functionDefault:'trusted-in-process', sandboxEngine:'quickjs-wasm', trustedFilesystem:true, trustedNetwork:true, sandboxedFilesystem:false, sandboxedNetwork:false, hostEgress:'revision-pinned-origin-grants', tooling:['recipes','examples','bulk-import','build-typescript','mcp','verify-provider'], providers:[], capabilityTargets:getCapabilities().targets, policies:Object.keys(policyRegistry), license:'Apache-2.0' }); break;
         case 'dev': case 'serve': {
           const port = Number(values.port);
           if (!/^\d+$/.test(values.port) || !Number.isInteger(port) || port < 0 || port > 65535) throw new ConfigError('Invalid port');

package/dist/config.js

@@ -74,7 +74,7 @@ function modulePath(pattern        , kind                           , file
  * a route-level `cache` becomes `policies.cache` (refused alongside a direct `policies.cache`).
  * Everything downstream (routes, audit, the compiled table) sees only the long form.
  */
-export function normalizeRoute(pattern        , route                                   )              {
+function normalizeRoute(pattern        , route                                   )              {
   const authored = route                       ;
   const needsFunction = typeof authored.function === 'string';
   const needsMiddleware = authored.middleware?.some(entry => typeof entry === 'string') ?? false;

package/dist/explain-cli.js

@@ -12,7 +12,7 @@ const targetsOf=(target                 )                   =>target===undefined
 function summary(explanation                 ,targets                   )        {
   const handler=explanation.handler,detail=handler.kind==='function'?`${handler.source          }#${handler.export          }`:handler.kind==='redirect'?`${handler.status          } ${handler.url          }`:handler.kind==='extension'?handler.name          :handler.kind==='page'||handler.kind==='download'?handler.file          :handler.kind==='static'?handler.directory          :handler.kind==='proxy'?handler.url          :handler.kind==='respond'?String(handler.status):'';
   const support=targets.map(target=>explanation.targets[target].compatible?target:`${target}:refused`).join(',');
-  return [explanation.path,explanation.methods.join(','),`${handler.kind}${detail?` ${detail}`:''}`,explanation.state,String(explanation.middleware.length),explanation.policies.names.join(',')||'-',explanation.cache.outcome,support].join('\t');
+  return [explanation.path,explanation.methods.join(','),`${handler.kind}${detail?` ${detail}`:''}`,explanation.state,explanation.sandbox?'sandboxed':'trusted',String(explanation.middleware.length),explanation.policies.names.join(',')||'-',explanation.cache.outcome,support].join('\t');
 }
 function detail(explanation                 ,targets                   )        {
   const lines         =[`route: ${explanation.path}`];
@@ -20,6 +20,8 @@ function detail(explanation                 ,targets                   )
   if(explanation.generated)lines.push(`generated: site.${explanation.generated}`);
   lines.push(`state: ${explanation.state}${explanation.expires?` (expires ${explanation.expires})`:''}`,`methods: ${explanation.methods.join(', ')}`,`handler: ${JSON.stringify(explanation.handler)}`);
   lines.push(`middleware: ${explanation.middleware.length?explanation.middleware.map(item=>`${item.source}#${item.export}`).join(' -> '):'none'}`);
+  // Route-level, so it is printed for a native handler with middleware too.
+  lines.push(`execution: ${explanation.sandbox?'sandboxed (QuickJS)':'trusted (in-process)'}${explanation.sandboxReason?`; ${explanation.sandboxReason}`:''}`);
   lines.push(`inputs: ${explanation.inputs.parameters.length?explanation.inputs.parameters.map(p=>`${p.in}:${p.name}${p.required?'':'?'}`).join(', '):'none'}${explanation.inputs.body?`; body ${JSON.stringify(explanation.inputs.body)}`:''}`);
   lines.push(`policies: ${explanation.policies.names.length?explanation.policies.names.join(', '):'none'}`);
   for(const [name,entry] of Object.entries(explanation.policies.inventory))lines.push(`  ${name}: ${JSON.stringify(entry)}`);
@@ -52,7 +54,7 @@ export async function runExplainCommand(command                     ,route
   if(route===undefined){
     const report=await explainProject(options.project,base);
     if(options.json){print(report);return 0;}
-    print(table([['route','methods','handler','state','mw','policies','cache','targets'],...report.routes.map(item=>summary(item,targets).split('\t'))]));return 0;
+    print(table([['route','methods','handler','state','execution','mw','policies','cache','targets'],...report.routes.map(item=>summary(item,targets).split('\t'))]));return 0;
   }
   if(!route.startsWith('/'))throw new ConfigError('Provide an absolute route path such as /docs');
   const explanation=await explainRoute(options.project,route,base);

package/dist/explain.js

@@ -29,6 +29,11 @@ const handlerNames=['extension','proxy','conditional','redirect','function','pag
                                    
                                                                                                                         
                                                                                                               
+                                                                                         
+                                                                                               
+                                                                                                 
+                                                                                  
+                                         
                                                                    
                                                                                                               
                        
@@ -52,7 +57,7 @@ function handlerOf(route              ,root       )                  {
       return {kind,cases:(route.conditionalRoutes?.cases??[]).map(item=>({match:item.match,...branch(item.route)})),...(route.conditionalRoutes?.fallback?{fallback:branch(route.conditionalRoutes.fallback)}:{})};
     }
     case 'redirect':return {kind,url:route.redirect .url,status:route.redirect .status??302,...(route.redirect .query?{query:route.redirect .query}:{})};
-    case 'function':return {kind,source:relativeSource(root,route.function .source),export:route.function .export,...(route.function .args?{args:route.function .args}:{}),sandbox:route.sandbox===true,...(route.sandboxReason?{sandboxReason:route.sandboxReason}:{})};
+    case 'function':return {kind,source:relativeSource(root,route.function .source),export:route.function .export,...(route.function .args?{args:route.function .args}:{})};
     case 'page':return {kind,file:route.page .file,...(route.page .contentType?{contentType:route.page .contentType}:{})};
     case 'static':return {kind,directory:route.static .directory,...(route.static .index?{index:route.static .index}:{})};
     case 'download':return {kind,file:route.download .file,...(route.download .filename?{filename:route.download .filename}:{}),...(route.download .contentType?{contentType:route.download .contentType}:{})};
@@ -89,7 +94,7 @@ function targetsOf(loaded               ,route              ,options
   }
   return result;
 }
-export function routeState(route              ,now       )            {return route.enabled===false?'disabled':route.expiresAt&&now>=route.expiresAt?'expired':'active';}
+function routeState(route              ,now       )            {return route.enabled===false?'disabled':route.expiresAt&&now>=route.expiresAt?'expired':'active';}
 /** Describe one compiled route. `chain` is the policy chain compiled for it, when the project declares policies. */
 export function explainCompiledRoute(loaded               ,route              ,chain                      ,options               ={})                  {
   const root=loaded.root,declared=loaded.routes[route.pattern];
@@ -110,6 +115,7 @@ export function explainCompiledRoute(loaded               ,route              ,c
     state:routeState(route,options.now??Date.now()),enabled:route.enabled!==false,...(route.expires?{expires:route.expires}:{}),
     methods:[...route.methods],conditional:Boolean(route.match||route.conditional),handler,
     middleware:route.middleware.map(item=>({source:relativeSource(root,item.source),export:item.export})),
+    sandbox:route.sandbox===true,...(route.sandboxReason?{sandboxReason:route.sandboxReason}:{}),
     inputs:{parameters:route.parameters.map(({name,in:location,required,schema})=>({name,in:location,required,schema})),...(route.request?.body?{body:route.request.body}:{})},
     policies:{names,inventory,extensions},
     cache:cacheOf(route,chain,extensionNames),

package/dist/extensions.js

@@ -63,7 +63,7 @@ import { validateHeaderName, validateHeaderValue } from './header-validation.js'
                                                                            
                                                                               
                                                                           
-                                                                             
+                                                  
                                                                        
                                                                        
                                                                          

package/dist/http-response.js

@@ -16,7 +16,7 @@ import { HttpError } from './errors.js';
  
 
 // Hop-by-hop and runtime-owned headers a handler must never set on the wire.
-export const forbiddenHeaders = new Set(['connection','keep-alive','transfer-encoding','content-length','upgrade','trailer','proxy-authenticate','proxy-authorization','te']);
+const forbiddenHeaders = new Set(['connection','keep-alive','transfer-encoding','content-length','upgrade','trailer','proxy-authenticate','proxy-authorization','te']);
 
 // One place decides what a URLCode response *is*, independent of how a host
 // delivers it. A Node server writes it to a socket; a Lambda returns it as

package/dist/index.js

@@ -42,4 +42,5 @@ export {scaffoldProject} from './scaffold.js';
                                                                                     
 export {initProject, addRedirect} from './authoring.js';
 export {initProjectWith} from './init-with.js';
+export {collectDependencySet,renderPackageManifest,installSteps} from './project-dependencies.js';
                                                                                    

package/dist/init-with.js

@@ -8,13 +8,21 @@ import { mcpConfigFile, renderMcpConfig } from './agents-guide.js';
 import { loadDocument, parseYaml, validateDocument } from './config.js';
 import { inspectExtensionRevision } from './extensions.js';
                                                                        
+import { collectDependencySet, installSteps, renderPackageManifest } from './project-dependencies.js';
+                                                                              
 import { ConfigError, assert } from './errors.js';
 
 /** Directory names inside the generated site. The route project lives under `app/`; everything else is operator-owned. */
-export const PROJECT_DIRECTORY = 'app', HOST_FILE = 'host.mjs', ROUTES_FILE = 'routes/extensions.yaml';
+const PROJECT_DIRECTORY = 'app', HOST_FILE = 'host.mjs', ROUTES_FILE = 'routes/extensions.yaml';
 const namePattern = /^[a-z][a-z0-9-]{0,63}$/;
-                                                             
-                                                                                                                                                          
+                                  
+                           
+                                                                                                 
+                                 
+                                                                                            
+                                                 
+ 
+                                                                                                                                                                                         
 
 export function parseWithNames(value        )           {
   const names = value.split(',').map(name => name.trim());
@@ -22,7 +30,7 @@ export function parseWithNames(value        )           {
   assert(new Set(names).size === names.length, 'Duplicate --with names');
   return names;
 }
-export const packageName = (name        )         => `@jimhoyd/urlcode-${name}`;
+const packageName = (name        )         => `@jimhoyd/urlcode-${name}`;
 const isCode = (error         , code        )          => error instanceof Error && 'code' in error && error.code === code;
 const strings = (value         )                    => Array.isArray(value) && value.every(item => typeof item === 'string');
 const record = (value         )                                   => value !== null && typeof value === 'object' && !Array.isArray(value);
@@ -32,7 +40,7 @@ const record = (value         )                                   => value !== n
  * conditions), imports it, and calls its `scaffold` export. Nothing is bundled; core never imports these packages
  * at build time. Refuses a missing package or a package without `scaffold` before anything is written.
  */
-export async function loadScaffold(name        , request                 , cwd        )                          {
+async function loadScaffold(name        , request                 , cwd        )                          {
   const pkg = packageName(name);
   let entry        ;
   try { entry = createRequire(join(cwd, 'package.json')).resolve(pkg); }
@@ -68,7 +76,7 @@ async function write(target        , content                     , mode = 0o644)
   const file = await open(target, 'wx', mode);
   try { await file.writeFile(content); await file.sync(); } finally { await file.close(); }
 }
-export function renderHost(names                   , results                           )         {
+function renderHost(names                   , results                           )         {
   const lines = [`// Generated by urlcode init --with ${names.join(',')}. Trusted operator code: keep it outside ${PROJECT_DIRECTORY}/ and review before serving.`];
   for (const result of results) lines.push(...result.hostImports);
   lines.push('');
@@ -85,12 +93,23 @@ function demote(markdown        )         {
   let fence = false;
   return markdown.split('\n').map(line => { if (/^\s*(?:```|~~~)/.test(line)) fence = !fence; return !fence && /^#{1,5} /.test(line) ? `#${line}` : line; }).join('\n');
 }
-export function renderReadme(directory        , names                   , results                           , starter        , env                        , projectSha256        )         {
-  const steps = results.flatMap(result => result.nextSteps);
+function renderDependencySection(directory        , set               )         {
+  const rows = set.pins.map(pin => `- \`${pin.name}\` ${pin.version} (${pin.role})${pin.specifier === pin.version ? '' : ` installed from \`${pin.specifier}\``}`);
+  const lines = ['## Dependencies', '',
+    '`package.json` pins the runtime, every extension named in `--with` and their declared peers to the exact versions that were installed when this site was generated. Those versions were checked against each package\'s own `peerDependencies` as one set.', '',
+    ...rows, '',
+    ...installSteps(directory, set).flatMap(step => [step, '']),
+    set.local ? 'At least one pin is a local path or tarball rather than a registry version: reproducing this install needs that path to exist, so keep it under your control or replace the specifier before publishing the site.' : 'The pins are registry versions; `npm install` resolves them without the network only if your cache or mirror already holds them.', '',
+    'There is no upgrade command. Changing a pinned version today means editing `package.json` yourself and re-running `npm install`; review the extension changelogs first.', ''];
+  return lines.join('\n');
+}
+function renderReadme(directory        , names                   , results                           , starter        , env                        , projectSha256        , set                            )         {
+  const steps = [...(set ? installSteps(directory, set) : []), ...results.flatMap(result => result.nextSteps)];
   const parts = [`# ${basename(directory)}`, '',
     `Created with \`urlcode init ${basename(directory)} --with ${names.join(',')}\`. \`${PROJECT_DIRECTORY}/\` is the route project (\`urlcode.yaml\`, functions, tests); \`${HOST_FILE}\` is the trusted operator host that wires the installed extension packages; operator modules and private data stay outside the project. Run every command with \`--project ${PROJECT_DIRECTORY} --host-file "$PWD/${HOST_FILE}"\`.`, '',
     '## Starter', '', `The starter files live in \`${PROJECT_DIRECTORY}/\`; add \`--project ${PROJECT_DIRECTORY}\` and the host file to the commands below.`, '', demote(starter).trim(), ''];
   for (const result of results) parts.push(`## Extension: ${result.name}`, '', result.readme.trim(), '');
+  if (set) parts.push(renderDependencySection(directory, set));
   parts.push('## Next steps', '', ...steps.map((step, index) => `${index + 1}. ${step}`), '');
   if (Object.keys(env).length) parts.push('## Environment', '', ...Object.entries(env).map(([key, text]) => `- \`${key}\`: ${text}`), '');
   parts.push('## Project revision', '', `\`${PROJECT_DIRECTORY}/urlcode.yaml\` currently has revision \`${projectSha256}\` (\`inspectExtensionRevision\`). Review the project, then pin exactly that value where the host expects it; any change to extension YAML, policies or mounts changes it and needs a new explicit review.`, '');
@@ -102,7 +121,7 @@ export function renderReadme(directory        , names                   , result
  * `urlcode.yaml`, one `host.mjs`, one `README.md` and the extensions' own files. All packages are resolved and
  * their scaffolds computed before anything is written, so a refusal leaves no directory behind.
  */
-export async function initProjectWith(destination        , names                   , { cwd = process.cwd() }                  = {})                          {
+export async function initProjectWith(destination        , names                   , { cwd = process.cwd(), manifest = true, pins }                  = {})                          {
   assert(names.length > 0, 'Provide at least one --with name');
   const directory = resolve(destination), project = join(directory, PROJECT_DIRECTORY), hostFile = join(directory, HOST_FILE);
   const request                  = { directory, project, hostFile, names };
@@ -120,6 +139,9 @@ export async function initProjectWith(destination        , names
       const seen = new Set        ();
       for (const file of result.files) { const path = filePath(directory, file.path); assert(!seen.has(path), `${result.name} scaffolds ${file.path} twice`); seen.add(path); }
     }
+    // Also resolved before the destination exists: an incompatible or incompletely installed set refuses with
+    // nothing written. It runs after the scaffold conflicts so a composition error is still reported as one.
+    const dependencies = manifest ? await collectDependencySet(names, names.map(packageName), { cwd, ...(pins === undefined ? {} : { overrides: pins }) }) : undefined;
     await mkdir(dirname(directory), { recursive: true });
     await mkdir(directory, { mode: 0o700 }); // refuses an existing destination
     try {
@@ -153,13 +175,16 @@ export async function initProjectWith(destination        , names
         await write(target, file.content, file.mode ?? 0o644); written.add(target);
       }
       await write(hostFile, renderHost(names, results), 0o600);
-      await write(join(directory, 'README.md'), renderReadme(directory, names, results, starter, env, projectSha256));
+      if (dependencies) await write(join(directory, 'package.json'), renderPackageManifest(directory, dependencies));
+      await write(join(directory, 'README.md'), renderReadme(directory, names, results, starter, env, projectSha256, dependencies));
       await write(join(directory, '.gitignore'), 'node_modules/\ndata/\n.env\n.env.*\n');
       // The read-only MCP server for agents opened at the site root; --host-file and --allow-authoring stay operator choices.
       await write(join(directory, mcpConfigFile), renderMcpConfig(PROJECT_DIRECTORY));
       // AGENTS.md: initProject writes the application-level file into app/ once it produces one (NEXT-STEPS 1.1);
       // nothing here overrides it. A site-level agent note would be assembled beside README.md at this point.
-      return { directory, project, hostFile, extensions: [...names], projectSha256, nextSteps: results.flatMap(result => result.nextSteps) };
+      return { directory, project, hostFile, extensions: [...names], projectSha256,
+        nextSteps: [...(dependencies ? installSteps(directory, dependencies) : []), ...results.flatMap(result => result.nextSteps)],
+        dependencies: dependencies?.pins ?? [] };
     } catch (error) { await rm(directory, { recursive: true, force: true }); throw error; }
   } finally { wipe(); }
 }

package/dist/manifest.js

@@ -15,9 +15,14 @@ import {explainCompiledRoute} from './explain.js';
 // checked in as a source of truth, and it is deterministic: the same project
 // yields the same bytes. Nothing in it is a binding value or source text.
 
-export const MANIFEST_SCHEMA_VERSION=2;
+// Bumped to 3 when `sandbox`/`sandboxReason` moved from the `function` handler
+// record to the route, so a middleware-only route reports its execution mode too.
+export const MANIFEST_SCHEMA_VERSION=3;
                                 
                                                                                                                                                
+                                                                                        
+                                                                  
+                                         
                                                                                                                                             
                                                                                                        
                                                                                                              
@@ -77,6 +82,7 @@ export async function buildManifest(project       ,options               ={})
     manifestRoutes.push({
       path:explanation.path,methods:explanation.methods,handler:explanation.handler,enabled:explanation.enabled,
       ...(explanation.expires?{expires:explanation.expires}:{}),...(explanation.generated?{generated:explanation.generated}:{}),...(explanation.description?{description:explanation.description}:{}),
+      sandbox:explanation.sandbox,...(explanation.sandboxReason?{sandboxReason:explanation.sandboxReason}:{}),
       middleware:explanation.middleware,parameters:explanation.inputs.parameters,...(explanation.inputs.body?{body:explanation.inputs.body}:{}),
       policies:explanation.policies.names,extensions,cache:explanation.cache,bindings:{env:routeEnv,secrets:routeSecrets},egress:explanation.egress,
       capabilities:explanation.capabilities,targets,
@@ -105,5 +111,5 @@ export async function buildManifest(project       ,options               ={})
 }
 /** The manifest as `build` writes it: two-space JSON with a trailing newline. */
 export function renderManifest(manifest         )        {return JSON.stringify(manifest,null,2)+'\n';}
-export const manifestFileName='manifest.json';
+const manifestFileName='manifest.json';
 export function manifestPath(out       )        {return join(out,manifestFileName);}

package/dist/mcp-authoring.js

@@ -17,8 +17,8 @@ import {assert} from './errors.js';
  * Authoring tools for `urlcode mcp --allow-authoring`. Every write lands inside
  * the operator-selected project root (after realpath), through the existing
  * authoring, recipe and scaffold paths. Nothing here reads bindings, creates
- * grants, deploys, or touches operator policy, compliance rules, host files or
- * link stores. The runners spawn the CLI against the same root only.
+ * grants, deploys, or touches operator policy, compliance rules or host files.
+ * The runners spawn the CLI against the same root only.
  */
 const text={type:'string',maxLength:1024};
 const handler={anyOf:[{type:'string',maxLength:2048},{type:'object'}]};
@@ -54,7 +54,7 @@ async function verdict(root       ,origin        ) {
  catch{return {valid:false         ,note:'Project does not validate; call run_validate for the CLI report.'};}
 }
 function object(value        )                                {return value!==null&&typeof value==='object'&&!Array.isArray(value);}
-function expandHandler(path       ,handler        )                        {
+function expandHandler(handler        )                        {
  if(object(handler))return handler;
  assert(typeof handler==='string','Handler must be a route object or a short form');
  if(/^https?:\/\//.test(handler))return {redirect:{url:handler}};
@@ -83,7 +83,7 @@ async function createRoute(root       ,args                       ,origin
  assert(file==='urlcode.yaml'||(loaded.document.includes??[]).includes(file),'file must be urlcode.yaml or an include listed in it');
  const target=await confinedPath(root,file);
  assert(!Object.hasOwn(loaded.routes,path),'Route already exists');
- const route={...expandHandler(path,args.handler)};
+ const route={...expandHandler(args.handler)};
  const middleware=expandMiddleware(args.middleware);if(middleware)route.middleware=middleware;
  const lockPath=join(root,'urlcode.yaml.lock'),lock=await open(lockPath,'wx',0o600);
  let temp                 ;

package/dist/mcp.js

@@ -78,7 +78,7 @@ export async function serveMcp(options           )               {
   if(message.method==='initialize') {
    if(initialized){await error(id,-32600,'Already initialized');return;}
    if(typeof params.protocolVersion!=='string'||!object(params.capabilities)||!object(params.clientInfo)||typeof params.clientInfo.name!=='string'||typeof params.clientInfo.version!=='string'){await error(id,-32602,'Invalid initialize params');return;}
-   initialized=true;await send({jsonrpc:'2.0',id,result:{protocolVersion,capabilities:{tools:{}},serverInfo:{name:'urlcode',version:'0.4.0-alpha.2'}}});return;
+   initialized=true;await send({jsonrpc:'2.0',id,result:{protocolVersion,capabilities:{tools:{}},serverInfo:{name:'urlcode',version:'0.4.1'}}});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/cache.js

@@ -198,7 +198,7 @@ function bodyOf(result               )         { return result.body ? (Buffer.is
 
 // Conditional requests for results the handler did not validate itself:
 // assets answer 304 before this phase, so only 200 results are examined.
-function revalidate(state            , req               , result               )                {
+function revalidate(req               , result               )                {
   if (result.status !== 200 || (req.method !== 'GET' && req.method !== 'HEAD')) return result;
   let headers = result.headers, etag = header(headers, 'etag');
   if (!etag) {
@@ -249,7 +249,7 @@ export function onResponse(state            , req               , result
   // refusal produced ahead of the handler keeps its own headers.
   if (flight || state.statuses.has(result.status)) headers = mergeVary(headers, state.vary);
   let out                = { ...result, headers };
-  if (state.strategy === 'revalidate') out = revalidate(state, req, out);
+  if (state.strategy === 'revalidate') out = revalidate(req, out);
   if (!flight) return out;
   // Store decision for the request that reached the handler; waiters are
   // released either way, with the entry or with nothing.

package/dist/policies.js

@@ -9,7 +9,9 @@ import { assert, ConfigError } from './errors.js';
                                                                                                                                                                                                                                                                
                                                                                                         
 
-// Host-side behavior declared in YAML and enforced outside the sandbox. Every
+// Host-side behavior declared in YAML and enforced in the host process, outside
+// 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):
 //

package/dist/prerender.js

@@ -102,6 +102,10 @@ async function planPasses(source        )                      {
   const cost = new Map                            ();
   for (const pattern of patterns) {
     const route = loaded.routes[pattern] ;
+    // Trusted routes use Node resolution, not the sandbox module collector.
+    // Applying guest import/size limits here would reject valid build-time Node
+    // code before the runtime can dispatch it through its declared trust mode.
+    if (route.sandbox !== true) { cost.set(pattern, []); continue; }
     const definitions = [];
     for (const definition of routeFunctions(route))
       definitions.push({function: {source: await functionFile(loaded.root, definition.source), export: definition.export || 'default'}});