@jimhoyd/urlcode 0.4.8 → 0.5.0

package/dist/extensions.js

@@ -176,6 +176,8 @@ export async function loadExtensionHooks                  (config
                   
                                                                                                                                                         
                           
+                                                                                                                                        
+                               
      
                                                                                                                                    
                                                                                                                                       
@@ -204,6 +206,8 @@ export async function loadExtensionHooks                  (config
                                                                    
                                                                                                                             
                                                                                       
+                                                                                                                                                                             
+                              
                                                                                                              
                        
                                                                                                                    

package/dist/functions.js

@@ -30,7 +30,8 @@ import { assert, ConfigError, HttpError } from './errors.js';
 
 // The worker protocol. Only JSON-shaped data and byte buffers cross it.
                                                                                                                                             
-                                                                                         
+/** `route.pattern` is the route key that matched, so one module can serve several routes without reading `request.url`. */
+                                                                                                                      
                                         
                                                                    
                                                         

package/dist/index.js

@@ -44,3 +44,5 @@ export {initProject, addRedirect} from './authoring.js';
 export {initProjectWith} from './init-with.js';
 export {collectDependencySet,renderPackageManifest,installSteps} from './project-dependencies.js';
                                                                                    
+export {installBundle,loadExtensionBundle,readBundleLock,parseBundleCatalog} from './extension-bundles.js';
+                                                                                                              

package/dist/init-with.js

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

package/dist/interchange.js

@@ -166,7 +166,7 @@ export async function exportRoutes(options                    )
     keys(record(options.document),['version','routes']);validateDocument(options.document);
     if(Object.keys(options.document.routes).length>100000)throw new Error('Input exceeds 100,000 routes');
     for(const [path,config]of Object.entries(options.document.routes)) {
-      try{keys(record(config),['redirect']);if(!config.redirect)throw new Error('Only redirects can be exported');keys(record(config.redirect),['url','status']);rows.push(row({path,url:config.redirect.url,status:config.redirect.status??302},rows.length+1));}
+      try{keys(record(config),['redirect']);if(!config.redirect)throw new Error('Only redirects can be exported');if(path.includes('*')||config.redirect.url.startsWith('/'))throw new Error('Suffix wildcards and root-relative destinations have no provider equivalent');keys(record(config.redirect),['url','status']);rows.push(row({path,url:config.redirect.url,status:config.redirect.status??302},rows.length+1));}
       catch{diagnostics.push({severity:'error',code:'runtime-required',source,path,message:'Only literal redirects with default methods and no extra behavior can be exported'});}
     }
     rows.sort((a,b)=>a.path<b.path?-1:a.path>b.path?1:0);

package/dist/match.js

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

package/dist/mcp.js

@@ -98,7 +98,7 @@ export async function serveMcp(options           )               {
   if(message.method==='initialize') {
    if(initialized){await error(id,-32600,'Already initialized');return;}
    if(typeof params.protocolVersion!=='string'||!object(params.capabilities)||!object(params.clientInfo)||typeof params.clientInfo.name!=='string'||typeof params.clientInfo.version!=='string'){await error(id,-32602,'Invalid initialize params');return;}
-   initialized=true;await send({jsonrpc:'2.0',id,result:{protocolVersion,capabilities:{tools:{}},serverInfo:{name:'urlcode',version:'0.4.8'}}});return;
+   initialized=true;await send({jsonrpc:'2.0',id,result:{protocolVersion,capabilities:{tools:{}},serverInfo:{name:'urlcode',version:'0.5.0'}}});return;
   }
   if(message.method==='ping'){await send({jsonrpc:'2.0',id,result:{}});return;}
   if(!ready){await error(id,-32002,'Initialize first');return;}

package/dist/readiness.js

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

package/dist/router.js

@@ -73,7 +73,10 @@ export async function compileRoutes(loaded                , bindings
     const parts = segments(pattern);
     assert(!pattern.startsWith('/_urlcode'), 'The /_urlcode prefix is reserved for runtime operations');
     const names = parts.map(parameterName).filter((name)                 => Boolean(name));
-    assert(!pattern.includes('*') || ((config.static || config.extension) && pattern.endsWith('/*') && parts.filter(p => p.includes('*')).length === 1 && parts.at(-1) === '*' && !names.length), 'Only static or extension routes support a terminal /* wildcard');
+    // `/prefix/**` is the redirect-only suffix wildcard: a literal prefix, one terminal `**`, no path parameters.
+    const wildcardRedirect = Boolean(config.redirect) && pattern.endsWith('/**');
+    if (wildcardRedirect) assert(pattern !== '/**' && pattern.indexOf('*') === pattern.length - 2 && parts.at(-1) === '**' && !names.length && !config.conditional, 'A /** wildcard redirect needs a literal prefix, one terminal **, no path parameters and no conditional');
+    assert(wildcardRedirect || !pattern.includes('*') || ((config.static || config.extension) && pattern.endsWith('/*') && parts.filter(p => p.includes('*')).length === 1 && parts.at(-1) === '*' && !names.length), 'Only static or extension routes support a terminal /* wildcard; a redirect uses a terminal /** instead');
     assert(!config.static || pattern.endsWith('/*'), 'Static routes require a terminal /* wildcard');
     if (config.page || config.download || config.static) assert((config.methods || methodsDefault).every(m => methodsDefault.includes(m)), 'Asset routes support only GET and HEAD');
     assert(new Set(names).size === names.length, 'Duplicate path parameter');
@@ -167,14 +170,21 @@ export async function compileRoutes(loaded                , bindings
     if (declaredRedirect) {
       const value = declaredRedirect.url;
       assert(!/[\u0000-\u0020\u007f\\]/u.test(value), 'Redirect URL contains unsafe characters');
+      // A root-relative destination (`/profiles/{id}`) stays on this site: a single leading slash, so never `//host`, and no dot segments.
+      const relative = value.startsWith('/') && !value.startsWith('//');
       let dest     ;
-      try { dest = new URL(value); } catch { assert(false, 'Redirect URL must be absolute HTTP(S)'); }
-      assert(['http:', 'https:'].includes(dest.protocol) && !dest.username && !dest.password, 'Redirect must use HTTP(S) without credentials');
-      const authority = value.match(/^https?:\/\/([^/?#]+)/i)?.[1];
-      assert(authority && !/[{}]/.test(authority) && !/[{}]/.test(dest.search + dest.hash), 'Redirect placeholders are allowed only in path segments');
+      try { dest = new URL(value, relative ? 'https://relative.invalid' : undefined); } catch { assert(false, 'Redirect URL must be an absolute HTTP(S) URL or a root-relative path'); }
+      if (relative) assert(dest.origin === 'https://relative.invalid' && !value.split(/[?#]/, 1)[0] .split('/').some(part => part === '.' || part === '..'), 'Root-relative redirect must be a plain path without dot segments');
+      else {
+        assert(['http:', 'https:'].includes(dest.protocol) && !dest.username && !dest.password, 'Redirect must use HTTP(S) without credentials');
+        const authority = value.match(/^https?:\/\/([^/?#]+)/i)?.[1];
+        assert(authority && !/[{}]/.test(authority), 'Redirect placeholders are allowed only in path segments');
+      }
+      assert(!/[{}]/.test(dest.search + dest.hash), 'Redirect placeholders are allowed only in path segments');
       const placeholders = [...value.matchAll(/\{([^}]+)\}/g)].map(m => m[1] );
-      assert(placeholders.every(n => token.test(n) && names.includes(n)), 'Redirect placeholder must reference a declared path input');
-      assert(!/[{}]/.test(value.replace(/\{[A-Za-z_][A-Za-z0-9_]*\}/g, '')), 'Invalid redirect placeholder');
+      assert(placeholders.every(n => (n === '**' && wildcardRedirect) || (token.test(n) && names.includes(n))), 'Redirect placeholder must reference a declared path input');
+      assert(placeholders.filter(n => n === '**').length <= 1, '{**} may appear once in a redirect destination');
+      assert(!/[{}]/.test(value.replace(/\{(?:[A-Za-z_][A-Za-z0-9_]*|\*\*)\}/g, '')), 'Invalid redirect placeholder');
       const query = declaredRedirect.query || {};
       const reserved = new Set(dest.searchParams.keys());
       for (const [key, ref] of Object.entries(query.map || {})) {
@@ -195,7 +205,8 @@ export async function compileRoutes(loaded                , bindings
       route.function = { ...declaredFunction, source, export: declaredFunction.export || 'default' };
       for (const ref of Object.values(declaredFunction.args || {})) referenceCheck(ref, route, true);
     }
-    if (config.static || config.extension) { route.prefix = pattern.slice(0, -1); mounts.push(route); }
+    if (wildcardRedirect) { route.prefix = pattern.slice(0, -2); route.wildcard = true; mounts.push(route); }
+    else if (config.static || config.extension) { route.prefix = pattern.slice(0, -1); mounts.push(route); }
     else if (!names.length) exact.set(pattern, route);
     else {
       assert(dynamic.length < 1000, 'Maximum 1000 parameterized routes per snapshot');
@@ -215,6 +226,7 @@ export async function compileRoutes(loaded                , bindings
     byLength.get(route.parts.length) .push(route);
   }
   for(const mount of mounts.filter(route=>route.extension)){const base=mount.parts.slice(0,-1);for(const candidate of [...exact.values(),...dynamic,...mounts]){if(candidate===mount)continue;const parts=candidate.parts;const shared=Math.min(base.length,parts.length-(candidate.prefix?1:0));const compatible=base.slice(0,shared).every((part,index)=>part===parts[index]||parameterName(parts[index] ));assert(!compatible||(!candidate.prefix&&parts.length<base.length),'Extension mount overlaps another route');}}
+  assert(new Set(mounts.map(mount => mount.prefix)).size === mounts.length, 'A /** wildcard redirect cannot share its prefix with a static or extension mount');
   mounts.sort((a,b) => b.prefix .length - a.prefix .length);
   assert(performance.now()<deadline, 'Route compilation deadline exceeded');
   return { exact, byLength, mounts, modules: [...modules.keys()], count: exact.size + dynamic.length + mounts.length };

package/dist/runtime.js

@@ -299,6 +299,7 @@ export async function createRuntime(project        , rawOptions
         }
         if (native && !route.middleware.length) return await finishResponse(native);
         context.args = Object.fromEntries(Object.entries(route.function?.args || {}).map(([key, ref]) => [key, resolveValue(ref, context)]));
+        context.route = { pattern: route.pattern };
         // Uniform for `function` and `middleware` alike: a route dispatches
         // through the sandboxed worker pool only when it declares
         // `sandbox: true`; every other route runs trusted, in-process

package/dist/types/agents-guide.d.ts

@@ -5,8 +5,13 @@ export declare const mcpConfigFile = ".mcp.json";
 /**
  * Renders `.mcp.json` registering the read-only `urlcode mcp` server for the project at `project`, relative
  * to the file. `--allow-authoring` is deliberately absent: the operator adds it by hand when they want it.
+ * `local` is for a project whose package.json pins the runtime: the server is then launched through `npx --no`,
+ * which uses the installed copy and refuses to fetch anything (a bare `urlcode` is not on PATH for a local-only install,
+ * and `npx urlcode` would resolve an unrelated registry package). Without a pin the bare command is kept for global installs.
  */
-export declare function renderMcpConfig(project?: string): string;
+export declare function renderMcpConfig(project?: string, { local }?: {
+    local?: boolean;
+}): string;
 /**
  * The application-level AGENTS.md written by `urlcode init`. Built from the
  * installed runtime's capability catalog, so it names only the handlers,

package/dist/types/authoring.d.ts

@@ -6,7 +6,7 @@ export interface InitOptions {
      */
     manifest?: DependencySet | undefined;
     /** `default` (function, middleware, redirect) or `page`: urlcode.yaml, public/index.html, a README and fixtures only. */
-    template?: 'default' | 'page' | undefined;
+    template?: 'default' | 'page' | 'redirects' | undefined;
 }
 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/context.d.ts

@@ -79,11 +79,23 @@ export interface TaskShape {
 }
 /** Established by running `urlcode validate` and `urlcode test` on each shape; test/context.test.ts compiles every `yaml` entry so this cannot drift from the runtime. */
 export declare const redirectShapes: TaskShape[];
+/** A complete, paste-ready project skeleton: every supported shape merged into one urlcode.yaml, plus the start script. */
+export interface TaskStarter {
+    file: string;
+    yaml: string;
+    /** Files the yaml references that must exist, with minimal content. */
+    companions: Record<string, string>;
+    packageScripts: Record<string, string>;
+    note: string;
+}
+/** Merges every supported shape's YAML; test/context-task.test.ts compiles the result, so it cannot drift from the runtime. */
+export declare function redirectStarter(): TaskStarter;
 export interface TaskContext {
     urlcode: string;
     schema: '1';
     task: ContextTask;
     shapes?: TaskShape[];
+    starter?: TaskStarter;
     project?: {
         entry: string;
         routes: number;

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

@@ -30,6 +30,19 @@ export interface ExtensionLock {
 }
 /** Parse an untrusted catalog only after its GitHub attestation was verified by the caller. */
 export declare function parseCatalog(bytes: Uint8Array, requestedTag: string): Catalog;
+export interface TarFile {
+    path: string;
+    bytes: Uint8Array;
+}
+export interface ArchiveLimits {
+    archive: number;
+    expanded: number;
+    files: number;
+    file: number;
+    label: string;
+}
+/** A minimal tar reader: only regular files are accepted, before any write occurs. */
+export declare function readBoundedTgz(source: Uint8Array, limits: ArchiveLimits): TarFile[];
 export declare function extractArtifact(bytes: Uint8Array, entry: ArtifactEntry, destination: string): Promise<void>;
 export declare function readLock(project: string): Promise<ExtensionLock>;
 export declare function writeLock(project: string, lock: ExtensionLock): Promise<void>;

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

@@ -0,0 +1,49 @@
+/** Verified, executable first-party bundles. Unlike extension artifacts, these are trusted operator code. */
+export declare const BUNDLE_REPOSITORY = "jimhoyd-com/urlcode";
+export declare const BUNDLE_WORKFLOW = "jimhoyd-com/urlcode/.github/workflows/extension-bundles.yml";
+export interface BundleEntry {
+    name: string;
+    version: string;
+    asset: string;
+    sha256: string;
+    entry: string;
+}
+export interface BundleCatalog {
+    format: 1;
+    tag: string;
+    commit: string;
+    coreVersion: string;
+    bundles: BundleEntry[];
+    revoked: {
+        sha256: string;
+        reason: string;
+    }[];
+}
+export interface LockedBundle extends BundleEntry {
+    catalog: {
+        tag: string;
+        commit: string;
+    };
+    coreVersion: string;
+}
+export interface BundleLock {
+    format: 1;
+    bundles: LockedBundle[];
+}
+export interface BundleTransport {
+    release(tag: string): Promise<{
+        name: string;
+        url: string;
+    }[]>;
+    download(url: string): Promise<Uint8Array>;
+    attest(path: string, release: string): Promise<void>;
+}
+/** Parse only a catalog whose attestation was already verified against the requested immutable tag. */
+export declare function parseBundleCatalog(bytes: Uint8Array, requested: string): BundleCatalog;
+export declare function extractBundle(bytes: Uint8Array, item: Pick<LockedBundle, 'name' | 'version' | 'entry' | 'sha256' | 'coreVersion'>, destination: string): Promise<void>;
+export declare function bundleCachePath(project: string, sha256: string): string;
+export declare function readBundleLock(project: string): Promise<BundleLock>;
+export declare const githubBundleTransport: BundleTransport;
+export declare function installBundle(project: string, release: string, bundleName: string, transport?: BundleTransport): Promise<BundleLock>;
+/** Explicit host-only loader. It never reads project YAML, downloads, updates, or discovers code. */
+export declare function loadExtensionBundle(project: string, bundleName: string): Promise<Record<string, unknown>>;

package/dist/types/extensions.d.ts

@@ -185,6 +185,8 @@ export interface ScaffoldRequest {
     hostFile: string;
     /** Every extension name being scaffolded together, including this one, in a canonical (sorted) order that is independent of the `--with` spelling. */
     names: readonly string[];
+    /** `npm` resolves extension packages from the operator's install; `bundle` resolves only already-verified, locked release bundles. */
+    distribution?: 'npm' | 'bundle';
     /**
      * Operator acknowledgements from repeated `--ack <extension>:<id>` flags, sorted and de-duplicated; empty when none. Core treats
      * them as opaque strings and never invents one. An extension reads only the ones qualified with its own name. To require one, throw
@@ -224,6 +226,8 @@ export interface ScaffoldResult {
     hostSetup: string[];
     hostEntries: string[];
     hostClose?: string[];
+    /** Named exports core may bind from this extension's already-verified executable bundle. Required for bundle distribution; never a project-controlled module reference. */
+    hostBundleExports?: string[];
     /** Files written relative to `directory` with their modes; never inside the project, never overwriting. */
     files: ScaffoldFile[];
     /** Markdown appended to README.md under a heading core adds; the numbered steps merged in the resolved order. */

package/dist/types/functions.d.ts

@@ -36,8 +36,12 @@ export interface FunctionWorkerData {
     dependencies: Record<string, string[]>;
     entries: [string, string][];
 }
+/** `route.pattern` is the route key that matched, so one module can serve several routes without reading `request.url`. */
 export type FunctionContext = RequestContext & {
     args?: Record<string, ParameterValue>;
+    route?: {
+        pattern: string;
+    };
 };
 export interface FunctionWorkerRequest {
     id: string;

package/dist/types/index.d.ts

@@ -40,3 +40,5 @@ export { initProject, addRedirect } from './authoring.ts';
 export { initProjectWith } from './init-with.ts';
 export { collectDependencySet, renderPackageManifest, installSteps } from './project-dependencies.ts';
 export type { ScaffoldRequest, ScaffoldResult, ScaffoldFile } from './extensions.ts';
+export { installBundle, loadExtensionBundle, readBundleLock, parseBundleCatalog } from './extension-bundles.ts';
+export type { BundleCatalog, BundleEntry, BundleLock, LockedBundle, BundleTransport } from './extension-bundles.ts';

package/dist/types/init-with.d.ts

@@ -1,5 +1,6 @@
 import type { ScaffoldResult } from './extensions.ts';
 import type { DependencyPin } from './project-dependencies.ts';
+import { type BundleTransport } from './extension-bundles.ts';
 export interface InitWithOptions {
     cwd?: string | undefined;
     /** Default true: record exact pins for core, the named extensions and their declared peers. */
@@ -8,6 +9,10 @@ export interface InitWithOptions {
     pins?: ReadonlyMap<string, string> | undefined;
     /** `--ack <extension>:<id>`, repeatable: opaque qualified acknowledgements handed to every scaffold. Core refuses one that no scaffold consumed. */
     acknowledgements?: readonly string[] | undefined;
+    /** Immutable signed release used instead of resolving executable extension packages from npm. */
+    bundleRelease?: string | undefined;
+    /** Test-only transport injection; production uses GitHub attestation verification. */
+    bundleTransport?: BundleTransport | undefined;
 }
 export interface InitWithResult {
     directory: string;
@@ -30,4 +35,4 @@ export declare function orderScaffolds(results: readonly ScaffoldResult[]): Scaf
  * `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 declare function initProjectWith(destination: string, requested: readonly string[], { cwd, manifest, pins, acknowledgements }?: InitWithOptions): Promise<InitWithResult>;
+export declare function initProjectWith(destination: string, requested: readonly string[], { cwd, manifest, pins, acknowledgements, bundleRelease, bundleTransport }?: InitWithOptions): Promise<InitWithResult>;

package/dist/types/match.d.ts

@@ -37,6 +37,7 @@ export interface MatchableRoute {
     pattern: string;
     parts: string[];
     prefix?: string;
+    wildcard?: boolean;
     extension?: string;
     parameters: CompiledParameter[];
     env: Record<string, string>;

package/dist/types/types.d.ts

@@ -264,6 +264,7 @@ export interface CompiledRoute extends Omit<RouteConfig, 'methods' | 'parameters
     reply?: Reply;
     expiresAt?: number;
     prefix?: string;
+    wildcard?: boolean;
     middleware: CompiledMiddleware[];
     function?: CompiledFunction;
     respond?: RespondSpec;