@jimhoyd/urlcode 0.3.0 → 0.4.0-alpha.2

package/dist/function-worker.js

@@ -83,6 +83,7 @@ port.on('message', async ({id,source,name,request,context,maxBytes,timeoutMs,cha
     if (output === undefined || Buffer.byteLength(output) > maxBytes * 6 + 65536) throw new Error('Output limit');
     const value = JSON.parse(output)                               ; // trust boundary: guest JSON, checked below
     if (!value || !Number.isInteger(value.status) || value.status < 200 || value.status > 599 || typeof value.body !== 'string' || !Array.isArray(value.headers) || value.headers.length > 256) throw new Error('Invalid response');
+    if (value.contentLength !== undefined && (!Number.isInteger(value.contentLength) || value.contentLength < 0)) throw new Error('Invalid response');
     if (value.nativeBody) {
       if (!native || value.status !== native.status || value.body !== '') throw new Error('Invalid native response');
       // Preserve native status and metadata (validators, ranges, redirect Location).
@@ -100,6 +101,7 @@ port.on('message', async ({id,source,name,request,context,maxBytes,timeoutMs,cha
       bytes += Buffer.byteLength(pair[0]) + Buffer.byteLength(pair[1]) + 4;
     }
     if (bytes > 16384) throw new Error('Header limit');
-    post({id,status:value.status,headers:value.headers,body,nativeBody:value.nativeBody === true});
+    post({id,status:value.status,headers:value.headers,body,nativeBody:value.nativeBody === true,
+      ...(typeof value.contentLength === 'number' ? {contentLength:value.contentLength} : {})});
   } catch { post({id,error:true}); }
 });

package/dist/functions.js

@@ -1,7 +1,7 @@
 import { Worker } from 'node:worker_threads';
 import { randomUUID } from 'node:crypto';
-import { collectFunctionSources, routeFunctions } from './function-sources.js';
-                                                                            
+import { collectSourcesFor, routeFunctions } from './function-sources.js';
+                                                                                                
 import { assert, ConfigError, HttpError } from './errors.js';
                                                                     
                                                                  
@@ -9,10 +9,24 @@ import { assert, ConfigError, HttpError } from './errors.js';
                                                           
                                                                                
                                                                                 
-                                      
+/** A module entry point the sandbox must load: an absolute source file path
+ * (already resolved and validated, e.g. via `functionFile()`) plus which
+ * export of it needs to be reachable. The same shape a `FunctionDefinition`
+ * already uses for `function`/`middleware` routes. */
+                                              
+/** What one `SandboxPool.execute()` call invokes: the same `{source, export}`
+ * shape as a `SandboxEntry`, naming one of the pool's declared entries. */
+                                               
+/** `entry` runs last (the route's `function`/handler); `chain` runs first, in
+ * order, each with `(request, context, next)` — the same wrap/middleware
+ * semantics `__invokePipeline` already gives sandboxed routes. Neither is
+ * required: an empty invocation with a `native` reply just returns it. */
+                                                                                                             
+                                     
                                                                                                   
                                                                                          
  
+                                                     
 
 // The worker protocol. Only JSON-shaped data and byte buffers cross it.
                                                                                                                                             
@@ -26,27 +40,43 @@ import { assert, ConfigError, HttpError } from './errors.js';
                                                                               
                                    
                                             
-                                                                                                
+                                                                                                                        
                                 
 
                                                                                                                                    
                                                                           
 
-export class FunctionPool {
-  root                    ; routes                 ; preparedSnapshot                             ; snapshot                             ;
+// The generalized sandbox primitive: the pool of worker threads, each running
+// the same function-worker.ts (QuickJS engine setup, dependency-closure module
+// allowlisting, memory/stack limits, deadline enforcement via both the
+// interrupt handler and outer worker termination, response-shape validation),
+// driven by an explicit list of `{source, export}` entries rather than
+// anything route/YAML-shaped. This is the ONE place that owns worker
+// spawning/QuickJS setup/deadline enforcement; `FunctionPool` below is a thin
+// route-shaped wrapper over it, not a second copy of the mechanics. Exported
+// publicly (as `@jimhoyd/urlcode/sandbox`, see src/sandbox.ts) for an
+// extension package that needs to run PROJECT code — a hook a project's own
+// config names — through the same trusted/sandboxed dispatch selection route
+// dispatch gets, when that hook declares `sandbox: true`
+// (docs/EXTENSIONS.md#project-level-lifecycle-hooks). There is no "trusted"
+// mode here: an extension wanting trusted execution just calls the project's
+// function directly via `import()` (already possible via
+// `ExtensionActivation.root`); this primitive is only ever the sandboxed path.
+export class SandboxPool {
+  root                    ; entries                ; preparedSnapshot                             ; snapshot                             ;
   restarts                     ; restartTimers                     ; log       ; timeoutMs        ; maxBytes        ;
   modules                      ; size        ; slots                      ; closed         ;
-  constructor(routes                 , { root, snapshot, workers = 2, timeoutMs = 5000, maxBytes = 1048576, log = () => {} }                      = {}) {
+  constructor(entries                , { root, snapshot, workers = 2, timeoutMs = 5000, maxBytes = 1048576, log = () => {} }                     = {}) {
     assert(Number.isInteger(workers) && workers >= 1 && workers <= 32, 'Workers must be 1–32');
     assert(Number.isInteger(timeoutMs) && timeoutMs >= 10 && timeoutMs <= 60000, 'Function timeout must be 10–60000 ms');
     assert(Number.isInteger(maxBytes) && maxBytes >= 1 && maxBytes <= 16777216, 'Response limit must be 1–16777216 bytes');
-    this.root = root; this.routes = routes; this.preparedSnapshot = snapshot;
+    this.root = root; this.entries = entries; this.preparedSnapshot = snapshot;
     // Consecutive replacement attempts per slot; cleared by a completed invocation.
     this.restarts = new Map(); this.restartTimers = new Set();
     this.log = log;
     this.timeoutMs = timeoutMs; this.maxBytes = maxBytes;
     const modules = new Map                     ();
-    for (const definition of routes.flatMap(routeFunctions)) {
+    for (const definition of entries) {
       const { source, export: name } = definition;
       let names = modules.get(source);
       if (!names) { names = new Set(); modules.set(source, names); }
@@ -58,7 +88,7 @@ export class FunctionPool {
   }
   async start()                {
     let snapshot = this.preparedSnapshot;
-    if (!snapshot && this.size) { assert(this.root !== undefined, 'Function pool requires a project root'); snapshot = await collectFunctionSources(this.routes,this.root); }
+    if (!snapshot && this.size) { assert(this.root !== undefined, 'Function pool requires a project root'); snapshot = await collectSourcesFor(this.entries,this.root); }
     snapshot ??= {sources:{},dependencies:{},entries:[],names:new Map()};
     this.snapshot = snapshot;
     try { await Promise.all(Array.from({ length: this.size }, (_, i) => this.spawn(i))); }
@@ -138,11 +168,18 @@ export class FunctionPool {
     timer.unref(); this.restartTimers.add(timer);
   }
   get healthy()          { return !this.closed && this.slots.length === this.size && this.slots.every(slot => slot?.ready); }
-  execute(route               , request                     , context                 , native                           )                          {
+  /** `invocation.entry` runs last (chain-wrapped), `invocation.chain` first, in
+   * declared order — the same `__invokePipeline` wrap/middleware discipline
+   * (`next()` callable at most once) the sandboxed route path already
+   * enforces; there is no second dispatch mechanism for this. Every entry and
+   * chain source named here must already be one of this pool's declared
+   * `entries` (constructor), or the worker's own module allowlist denies it. */
+  execute(invocation                   , request                     , context                 , native                           )                          {
     const slot = this.slots.find(s => s?.ready && !s.pending);
     const snapshot = this.snapshot;
     if (this.closed || !slot || !snapshot) return Promise.reject(new HttpError(503, 'Function capacity unavailable'));
     const id = randomUUID();
+    const { entry, chain = [] } = invocation;
     return new Promise((resolve, reject) => {
       const timer = setTimeout(() => {
         slot.pending = null; slot.ready = false;
@@ -154,8 +191,8 @@ export class FunctionPool {
         if (message.nativeBody && native) resolve({...message,body:native.body,...(native.contentLength === undefined ? {} : {contentLength:native.contentLength})});
         else resolve(message);
       }, reject };
-      const message                        = { id, source: route.function ? snapshot.names.get(route.function.source) : undefined, name: route.function?.export,
-        chain: (route.middleware || []).map(item => ({source:snapshot.names.get(item.source),name:item.export})),
+      const message                        = { id, source: entry ? snapshot.names.get(entry.source) : undefined, name: entry?.export,
+        chain: chain.map(item => ({source:snapshot.names.get(item.source),name:item.export})),
         native: native ? {status:native.status,headers:native.headers} : undefined,
         request, context, maxBytes: this.maxBytes, timeoutMs:this.timeoutMs + 100 };
       slot.worker.postMessage(message);
@@ -172,3 +209,37 @@ export class FunctionPool {
     await Promise.all(this.slots.map(s => s?.worker.terminate()));
   }
 }
+// Thin, route-shaped wrapper over `SandboxPool`: every existing internal
+// caller (route-level `function`/`middleware` dispatch, `src/runtime.ts`)
+// keeps working exactly as before, translating `FunctionRoute[]`/`FunctionRoute`
+// into the generalized `{source, export}` entries/target shape at the edge,
+// never duplicating worker spawning, module allowlisting or deadline
+// enforcement — that all still lives in the wrapped `SandboxPool`. Composition
+// rather than inheritance because `execute()`'s route-shaped and
+// entries-shaped parameters are genuinely different, incompatible types; the
+// fields/methods below the constructor exist only so the (unchanged) test
+// suite and `src/runtime.ts` keep reaching the wrapped pool's own state
+// exactly as they did before this file had two classes.
+export class FunctionPool {
+  routes                 ;         pool             ;
+  constructor(routes                 , options                      = {}) {
+    this.routes = routes;
+    this.pool = new SandboxPool(routes.flatMap(routeFunctions), options);
+  }
+  async start()                { await this.pool.start(); return this; }
+  execute(route               , request                     , context                 , native                           )                          {
+    return this.pool.execute({ entry: route.function, chain: route.middleware }, request, context, native);
+  }
+  scheduleRespawn(index        )       { this.pool.scheduleRespawn(index); }
+  close()                { return this.pool.close(); }
+  get healthy()          { return this.pool.healthy; }
+  get restarts()                      { return this.pool.restarts; }
+  get restartTimers()                      { return this.pool.restartTimers; }
+  get slots()                       { return this.pool.slots; }
+  get size()         { return this.pool.size; }
+  get closed()          { return this.pool.closed; }
+  get snapshot()                              { return this.pool.snapshot; }
+  get log()        { return this.pool.log; }
+  get timeoutMs()         { return this.pool.timeoutMs; }
+  get maxBytes()         { return this.pool.maxBytes; }
+}

package/dist/guest-api.js

@@ -5,7 +5,7 @@
 /** The request the guest receives (stringified as JSON in the worker). */
                                                                                                                           
 /** What the guest returns as JSON text; the worker enforces this shape before trusting it. */
-                                                                                                                   
+                                                                                                                                           
 // Runs only inside QuickJS/WASM. No native host functions or objects are exposed.
 // This is the documented text/JSON subset, not a complete Fetch implementation.
 export const guestBootstrap = String.raw`
@@ -13,6 +13,24 @@ export const guestBootstrap = String.raw`
   const NativeJSON = JSON;
   const stringify = JSON.stringify.bind(JSON);
   const now = Date.now.bind(Date);
+  // The guest has no TextEncoder/Buffer; this counts the UTF-8 bytes a
+  // Response's text would occupy on the wire (matching Buffer.byteLength on
+  // the host side, including its handling of lone surrogates as U+FFFD),
+  // without pulling any Node capability into the sandbox (#144).
+  function byteLength(text) {
+    let bytes = 0;
+    for (let i = 0; i < text.length; i++) {
+      const code = text.charCodeAt(i);
+      if (code >= 0xd800 && code <= 0xdbff) {
+        const next = text.charCodeAt(i + 1);
+        if (next >= 0xdc00 && next <= 0xdfff) { bytes += 4; i++; continue; }
+        bytes += 3; continue;
+      }
+      if (code >= 0xdc00 && code <= 0xdfff) { bytes += 3; continue; }
+      bytes += code < 0x80 ? 1 : code < 0x800 ? 2 : 3;
+    }
+    return bytes;
+  }
   const timers = new Map(); let next = 1;
   globalThis.setTimeout = (fn, delay = 0) => {
     if (typeof fn !== 'function' || timers.size >= 128) throw new Error('Timer limit');
@@ -94,8 +112,14 @@ export const guestBootstrap = String.raw`
       const response = await dispatch(0);
       if (violated || !(response instanceof Response)) throw new TypeError('Invalid middleware response');
       const nativeBody = response === nativeResponse;
+      const isHead = input.request.method === 'HEAD';
+      // The real length is already known "for free": _text is a fully
+      // materialized string at construction time, no stream read needed
+      // (#144, mirroring #139's fix for the trusted path). Only the
+      // transmitted bytes are suppressed for HEAD, never the length.
       globalThis.__output = stringify({status:response.status,headers:response.headers._pairs,
-        body:nativeBody || input.request.method === 'HEAD' ? '' : response._text,nativeBody});
+        body:nativeBody || isHead ? '' : response._text,nativeBody,
+        ...(isHead && !nativeBody ? {contentLength:byteLength(response._text)} : {})});
       globalThis.__state = 'done';
     } catch { globalThis.__state = 'failed'; }
   };
@@ -106,7 +130,9 @@ export const guestBootstrap = String.raw`
       const response = await handler(new Request(input.request.url, input.request), input.context);
       if (!(response instanceof Response)) throw new TypeError('Return a Response');
       const headers = response.headers._pairs;
-      globalThis.__output = stringify({status:response.status,headers,body: input.request.method === 'HEAD' ? '' : response._text});
+      const isHead = input.request.method === 'HEAD';
+      globalThis.__output = stringify({status:response.status,headers,body: isHead ? '' : response._text,
+        ...(isHead ? {contentLength:byteLength(response._text)} : {})});
       globalThis.__state = 'done';
     } catch { globalThis.__state = 'failed'; }
   };

package/dist/index.js

@@ -1,11 +1,45 @@
 export { createRuntime } from './runtime.js';
-                                                                                                                                                        
+                                                                                                                          
 export { startServer } from './server.js';
                                                          
 export { loadDocument, validateDocument, parseYaml } from './config.js';
-export {openLinkStore} from './link-store.js';
-                                                                          
-export {startLinkApi} from './link-api.js';
-                                                           
-                                                                                        
 export { events as observabilityEvents, validateObservers, createObserverSink, createMetrics, renderPrometheus } from './observability.js';
+
+export { getCapabilities, routeCapabilities, analyzeProjectCapabilities, analyzeCompiledCapabilities, assertTargetCompatibility, normalizeCapabilityTarget } from './capabilities.js';
+export { capabilityDetails } from './capabilities.js';
+                                                                                                                                                                                                                  
+
+export { importRoutes, exportRoutes } from './interchange.js';
+                                                                                                                                                              
+
+export {listRecipes, searchRecipes, showRecipe, addRecipe} from './recipes.js';
+                                                                                             
+export {listExamples, searchExamples} from './examples.js';
+                                                                                                    
+                                                                             
+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} from './tooling.js';
+                                                                                                                                                                                                                                                                                                        
+export {buildManifest, renderManifest, MANIFEST_SCHEMA_VERSION} from './manifest.js';
+                                                                                             
+export {serveMcp} from './mcp.js';
+                                         
+export {providerConformanceCases, runProviderConformance, verifyProviderDeployment} from './provider-verification.js';
+                                                                                                                                                                                               
+export {normalizeMatch, assertDisjointMatches, matchesRoute} from './conditions.js';
+                                                                  
+
+export {buildCloudflare} from './build-cloudflare.js';
+                                                                                                                        
+export {buildStatic} from './build-static.js';
+                                                                                                                                                                            
+export {runProjectTests} from './project-tests.js';
+                                                                              
+export {scaffoldProject} from './scaffold.js';
+                                                                                    
+export {initProject, addRedirect} from './authoring.js';
+export {initProjectWith} from './init-with.js';
+                                                                                   

package/dist/init-with.js

@@ -0,0 +1,165 @@
+import { mkdir, open, readFile, rm, unlink, lstat } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { basename, dirname, join, relative, resolve, sep } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { parseDocument, stringify } from 'yaml';
+import { initProject } from './authoring.js';
+import { mcpConfigFile, renderMcpConfig } from './agents-guide.js';
+import { loadDocument, parseYaml, validateDocument } from './config.js';
+import { inspectExtensionRevision } from './extensions.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 namePattern = /^[a-z][a-z0-9-]{0,63}$/;
+                                                             
+                                                                                                                                                          
+
+export function parseWithNames(value        )           {
+  const names = value.split(',').map(name => name.trim());
+  assert(names.length > 0 && names.every(name => namePattern.test(name)), 'Use --with name[,name] where each name is a lowercase extension package suffix such as auth');
+  assert(new Set(names).size === names.length, 'Duplicate --with names');
+  return names;
+}
+export 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);
+
+/**
+ * Resolves the extension package from the invoking directory (Node's package resolution with the default
+ * conditions), imports it, and calls its `scaffold` export. Nothing is bundled; core never imports these packages
+ * at build time. Refuses a missing package or a package without `scaffold` before anything is written.
+ */
+export async function loadScaffold(name        , request                 , cwd        )                          {
+  const pkg = packageName(name);
+  let entry        ;
+  try { entry = createRequire(join(cwd, 'package.json')).resolve(pkg); }
+  catch (error) {
+    if (isCode(error, 'MODULE_NOT_FOUND')) throw new ConfigError(`Extension package ${pkg} is not installed in ${cwd}; run: npm install ${pkg}`);
+    throw error;
+  }
+  const module = await import(pathToFileURL(entry).href)                           ;
+  const scaffold = module.scaffold;
+  if (typeof scaffold !== 'function') throw new ConfigError(`${pkg} does not export scaffold; upgrade it to a release that supports urlcode init --with, or add ${name} by hand following its README`);
+  let result         ;
+  try { result = await (scaffold                                         )(request); }
+  catch (error) { throw new ConfigError(`${pkg} scaffold refused: ${error instanceof Error ? error.message : String(error)}`); }
+  assert(record(result) && result.name === name, `${pkg} scaffold must return a result named ${name}`);
+  assert(record(result.extensions) && record(result.routes), `${pkg} scaffold must return extensions and routes objects`);
+  assert(strings(result.hostImports) && strings(result.hostSetup) && strings(result.hostEntries) && (result.hostClose === undefined || strings(result.hostClose)), `${pkg} scaffold must return host fragments as string arrays`);
+  assert(strings(result.nextSteps) && typeof result.readme === 'string', `${pkg} scaffold must return readme text and nextSteps strings`);
+  assert(result.env === undefined || (record(result.env) && Object.values(result.env).every(item => typeof item === 'string')), `${pkg} scaffold env must map names to descriptions`);
+  assert(Array.isArray(result.files) && result.files.every((file         ) => record(file) && typeof file.path === 'string' && (typeof file.content === 'string' || file.content instanceof Uint8Array) && (file.mode === undefined || (Number.isInteger(file.mode) && (file.mode          ) >= 0 && (file.mode          ) <= 0o777))), `${pkg} scaffold files must carry a path, content and an optional mode`);
+  return result                             ;
+}
+
+function filePath(root        , path        )         {
+  assert(typeof path === 'string' && path.length > 0 && path.length <= 1024 && !path.includes('\0'), 'Invalid scaffold file path');
+  const target = resolve(root, path), rel = relative(root, target);
+  assert(!path.startsWith('/') && rel === path.split('/').join(sep) && rel.length > 0 && !rel.startsWith('..'), `Scaffold file path must stay inside the site directory: ${path}`);
+  assert(rel !== PROJECT_DIRECTORY && !rel.startsWith(PROJECT_DIRECTORY + sep), `Scaffold files must stay outside the route project: ${path}`);
+  return target;
+}
+/** Creates the file exclusively: nothing generated is ever overwritten. */
+async function write(target        , content                     , mode = 0o644)                {
+  await mkdir(dirname(target), { recursive: true, mode: 0o700 });
+  const file = await open(target, 'wx', mode);
+  try { await file.writeFile(content); await file.sync(); } finally { await file.close(); }
+}
+export 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('');
+  for (const result of results) if (result.hostSetup.length) lines.push(...result.hostSetup);
+  lines.push('export default {', '  extensions: [');
+  for (const result of results) for (const entry of result.hostEntries) lines.push(`    ${entry},`);
+  lines.push('  ],', '  async close() {');
+  // Later extensions may depend on earlier setup, so release in reverse order.
+  for (const result of [...results].reverse()) for (const statement of result.hostClose ?? []) lines.push(`    ${statement}`);
+  lines.push('  },', '};');
+  return lines.join('\n') + '\n';
+}
+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);
+  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(), '');
+  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.`, '');
+  return parts.join('\n');
+}
+
+/**
+ * `urlcode init <directory> --with a,b`: the starter under `app/`, every extension's fragments merged into one
+ * `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() }                  = {})                          {
+  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 };
+  const results                   = [];
+  const wipe = ()       => { for (const result of results) for (const file of result.files) if (file.content instanceof Uint8Array) file.content.fill(0); };
+  try {
+    for (const name of names) results.push(await loadScaffold(name, request, cwd));
+    // Cross-result conflicts are refused before the destination exists.
+    const extensions                          = Object.create(null)                           , routes                          = Object.create(null)                           , env                         = {};
+    const owners = new Map                ();
+    for (const result of results) {
+      for (const [key, value] of Object.entries(result.extensions)) { assert(!Object.hasOwn(extensions, key), `Extension ${key} is declared by both ${owners.get('e:' + key)} and ${result.name}`); owners.set('e:' + key, result.name); extensions[key] = value; }
+      for (const [key, value] of Object.entries(result.routes)) { assert(!Object.hasOwn(routes, key), `Route ${key} is added by both ${owners.get('r:' + key)} and ${result.name}`); owners.set('r:' + key, result.name); routes[key] = value; }
+      for (const [key, value] of Object.entries(result.env ?? {})) { assert(!Object.hasOwn(env, key) || env[key] === value, `Environment variable ${key} is described differently by ${result.name}`); env[key] = value; }
+      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); }
+    }
+    await mkdir(dirname(directory), { recursive: true });
+    await mkdir(directory, { mode: 0o700 }); // refuses an existing destination
+    try {
+      await initProject(project);
+      const starter = await readFile(join(project, 'README.md'), 'utf8');
+      await unlink(join(project, 'README.md')); // its content moves into the site README
+      await unlink(join(project, mcpConfigFile)); // re-registered at the site root, pointing at app/
+      // Refuse routes or extensions the starter already declares, including in its included files.
+      const loaded = await loadDocument(project);
+      for (const key of Object.keys(routes)) assert(!Object.hasOwn(loaded.routes, key), `Route ${key} from ${owners.get('r:' + key)} already exists in the starter`);
+      for (const key of Object.keys(extensions)) assert(!Object.hasOwn(loaded.document.extensions ?? {}, key), `Extension ${key} from ${owners.get('e:' + key)} already exists in the starter`);
+      const yamlFile = join(project, 'urlcode.yaml'), original = await readFile(yamlFile, 'utf8');
+      const doc = parseDocument(original);
+      // Extensions are declared in the entry file; their routes go into a last include so the starter's own routes
+      // stay first in the loaded order and the entry file stays small.
+      doc.set('extensions', { ...loaded.document.extensions, ...extensions });
+      doc.addIn(['includes'], ROUTES_FILE);
+      const fragment = stringify({ version: '1', routes });
+      validateDocument(doc.toJS()); validateDocument(parseYaml(fragment));
+      await write(join(project, ROUTES_FILE), `# Routes added by urlcode init --with ${names.join(',')}. Mounts are exclusive to the named extension.\n${fragment}`);
+      await rm(yamlFile); await write(yamlFile, String(doc));
+      await loadDocument(project);
+      const projectSha256 = await inspectExtensionRevision(project);
+      const written = new Set        ();
+      for (const result of results) for (const file of result.files) {
+        const target = filePath(directory, file.path);
+        assert(!written.has(target), `Scaffold file ${file.path} is written by more than one extension`);
+        // Parent directories are created; existing files or symlinks anywhere on the path are refused.
+        let probe = dirname(target);
+        while (probe !== directory && probe.startsWith(directory)) { try { assert(!(await lstat(probe)).isSymbolicLink(), `Scaffold path passes through a symlink: ${file.path}`); } catch (error) { if (!isCode(error, 'ENOENT')) throw error; } probe = dirname(probe); }
+        await write(target, file.content, file.mode ?? 0o644); written.add(target);
+      }
+      await write(hostFile, renderHost(names, results), 0o600);
+      await write(join(directory, 'README.md'), renderReadme(directory, names, results, starter, env, projectSha256));
+      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) };
+    } catch (error) { await rm(directory, { recursive: true, force: true }); throw error; }
+  } finally { wipe(); }
+}

package/dist/interchange-cli.js

@@ -0,0 +1,42 @@
+import { open, unlink } from 'node:fs/promises';
+import { extname } from 'node:path';
+import { loadDocument } from './config.js';
+import { importRoutes, exportRoutes } from './interchange.js';
+                                                                            
+import { assert } from './errors.js';
+                                                                                                                                                                                                                                
+export async function readConversionInput(file       )                 {
+  const handle=await open(file,'r');
+  try {
+    const stat=await handle.stat();assert(stat.isFile()&&stat.size<=32*1024*1024,'Conversion input must be a regular file of at most 32 MiB');
+    const buffer=Buffer.alloc(stat.size+1);let size=0;
+    while(size<buffer.length){const result=await handle.read(buffer,size,buffer.length-size,null);if(!result.bytesRead)break;size+=result.bytesRead;}
+    assert(size<=stat.size,'Conversion source grew during read');
+    return new TextDecoder('utf-8',{fatal:true}).decode(buffer.subarray(0,size));
+  } finally {await handle.close();}
+}
+export async function runInterchange(command                  ,args         ,options                      )                                                 {
+  assert(!options.report||options.report==='json','Use --report json');
+  const explicit=args.length===2?args[0]:undefined;
+  const file=args.length===2?args[1]:args[0];
+  assert(command==='import'?!!file&&args.length<=2:args.length===0,'Invalid conversion arguments');
+  const format=(options.format??(command==='export'?options.target:explicit??extname(file ).slice(1)))                     ;
+  let report                 ;
+  if(command==='import') report=await importRoutes({format,text:await readConversionInput(file ),source:file ,acceptProviderDifferences:options.acceptProviderDifferences===true});
+  else {
+    const loaded=await loadDocument(options.project);
+    const {includes:_includes,...document}=loaded.document;
+    report=await exportRoutes({format,document:{...document,routes:loaded.routes},source:options.project,acceptProviderDifferences:options.acceptProviderDifferences===true});
+  }
+  if(report.ok&&options.out&&!options.dryRun) {
+    const handle=await open(options.out,'wx',0o600);
+    try {await handle.writeFile(report.output );await handle.sync();}
+    catch(error){await handle.close();await unlink(options.out);throw error;}
+    await handle.close();
+  }
+  // Acknowledged non-lossless conversion always carries a report, even when
+  // output is written to a file; warnings cannot disappear into raw stdout.
+  const text=options.report==='json'||options.dryRun||options.out||!report.ok||!report.lossless
+    ? JSON.stringify(report)+'\n' : report.output ;
+  return {report,text};
+}