@jimhoyd/urlcode 0.4.7 → 0.5.0

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

@@ -2,12 +2,13 @@ import {realpath} from 'node:fs/promises';
                                                    
 import {once} from 'node:events';
 import {Ajv} from 'ajv';
-import {inspectProject,validateProject,explainRoute,getCapabilities,getCapability,getSchemaFragment,previewImport,previewExport,listRecipes,showRecipe,searchRecipes,searchExamples,describeExtensions,buildContext} from './tooling.js';
+import {inspectProject,validateProject,explainRoute,getCapabilities,getCapability,getSchemaFragment,previewImport,previewExport,listRecipes,showRecipe,searchRecipes,searchExamples,describeExtensions,buildContext,buildTaskContext} from './tooling.js';
 import {loadOperatorHost} from './operator-host.js';
 import {buildManifest} from './manifest.js';
                                                         
 import {authoringDefinitions,callAuthoringTool} from './mcp-authoring.js';
 import {listSkills,getSkill,searchDocs,getExample,validateYaml,explainError} from './agent-context.js';
+import {describeArtifactCache,readArtifactMember} from './extension-artifacts.js';
 const protocolVersion='2025-11-25';
 const maxBytes=1048576;
 const text={type:'string',maxLength:8192};
@@ -32,7 +33,9 @@ const definitions=[
  {name:'get_example',description:'Return the README and urlcode.yaml from one bundled runnable example.',properties:{name:{type:'string',maxLength:64}},required:['name']},
  {name:'validate_yaml',description:'Validate supplied URLCode YAML syntax and schema only. It never reads includes, source files, bindings or a project directory.',properties:{yaml:{type:'string',maxLength:524288}},required:['yaml']},
  {name:'explain_error',description:'Give deterministic next-step guidance for supplied URLCode validation output.',properties:{error:{type:'string',maxLength:8192}},required:['error']},
- {name:'get_context',description:'Emit the compact project context an authoring agent needs: versions, project summary, constraints, target support and exact commands, derived from the compiled project. Optional token budget drops sections in a fixed order.',properties:{target:text,budget:{type:'integer',minimum:1}}},
+ {name:'get_extension_artifacts',description:'Validate and list the project\'s locked declarative extension artifacts and their allowlisted files. Artifacts are inert data and do not activate extension code.',properties:{}},
+ {name:'get_extension_artifact',description:'Read one bounded JSON or Markdown file from a verified cached declarative extension artifact. The artifact name and member path must exist in the project lock/cache.',properties:{name:{type:'string',maxLength:64},path:{type:'string',maxLength:128}},required:['name','path']},
+ {name:'get_context',description:'Emit the compact project context an authoring agent needs: versions, project summary, constraints, target support and exact commands, derived from the compiled project. Pass `task: "redirects"` for a bounded, redirect-focused call instead (supported/gap shapes, exact YAML, this project\'s redirects). Optional token budget drops sections in a fixed order.',properties:{target:text,task:{enum:['redirects']},budget:{type:'integer',minimum:1}}},
 ];
 // Only the operator's own --host-file exposes registered extension contracts; no tool argument can name one.
 const hostDefinition={name:'get_extensions',description:'List operator-registered extension contracts, schemas, hooks, and supported project-owned customization surfaces with fast checks; use these before generating replacement framework code. Activates nothing.',properties:{}};
@@ -76,8 +79,12 @@ export async function serveMcp(options           )               {
    case 'get_example':return getExample(args.name          );
    case 'validate_yaml':return validateYaml(args.yaml          );
    case 'explain_error':return explainError(args.error          );
+   case 'get_extension_artifacts':return describeArtifactCache(project);
+   case 'get_extension_artifact':return readArtifactMember(project,args.name          ,args.path          );
    case 'get_extensions':return describeExtensions(project,host.extensions??[]);
-   case 'get_context':return buildContext(project,{projectFlag:'.',...(typeof args.target==='string'?{target:args.target}:{}),...(typeof args.budget==='number'?{budget:args.budget}:{})});
+   case 'get_context':return typeof args.task==='string'
+    ?buildTaskContext(project,args.task,{...(typeof args.budget==='number'?{budget:args.budget}:{})})
+    :buildContext(project,{projectFlag:'.',...(typeof args.target==='string'?{target:args.target}:{}),...(typeof args.budget==='number'?{budget:args.budget}:{})});
    default:if(authoring)return callAuthoringTool(project,name,args,options.origin);throw new Error('Unknown tool');
   }
  };
@@ -91,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.7'}}});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/site.js

@@ -1,4 +1,4 @@
-import { stat, readdir, lstat } from 'node:fs/promises';
+import { stat, readdir, lstat, readFile } from 'node:fs/promises';
 import { join, extname } from 'node:path';
 import { assert, ConfigError } from './errors.js';
 import { safeFile } from './config.js';
@@ -233,3 +233,21 @@ export async function applySite(loaded                , options              = {
   for (const [path, route] of Object.entries(generated)) loaded.routes[path] = route;
   return generated;
 }
+
+// The Worker has no filesystem and no asset binding, so the one not-found page
+// is read here and carried inline as a respond route at /404.html. The page is
+// bounded and static: no templating, no request data. It is text/html; the
+// artifact is JSON, which does the escaping, and a body that is not valid
+// UTF-8 is refused rather than silently altered.
+export const notFoundInlineLimit = 65536;
+export async function inlineNotFound(loaded                )                   {
+  const site = loaded.document.site, path = generatedPaths.notFound;
+  const route = loaded.routes[path];
+  if (!site?.notFound || route?.generated !== 'site.notFound') return false;
+  const file = await safeFile(loaded.root, route.page?.file);
+  assert((await stat(file)).size <= notFoundInlineLimit, `site.notFound exceeds ${notFoundInlineLimit} bytes; the Cloudflare Worker carries it inline, so keep the page under 64 KiB`);
+  let text        ;
+  try { text = new TextDecoder('utf-8', { fatal: true }).decode(await readFile(file)); } catch { throw new ConfigError('site.notFound must be valid UTF-8 to be carried inline in the Worker'); }
+  loaded.routes[path] = { respond: { text }, response: { headers: { 'Content-Type': 'text/html; charset=utf-8', 'Cache-Control': 'no-store' } }, description: route.description ?? 'generated by site.notFound', generated: 'site.notFound' };
+  return true;
+}

package/dist/tooling.js

@@ -21,8 +21,8 @@ export {getCapability} from './capability-query.js';
 export {getSchemaFragment,schemaPathNames} from './schema-query.js';
                                                       
 export {listRecipes,showRecipe,searchRecipes,listExamples,searchExamples};
-export {buildContext,renderContext,estimateTokens,documentationTokens} from './context.js';
-                                                                               
+export {buildContext,renderContext,estimateTokens,documentationTokens,buildTaskContext,renderTaskContext,contextTasks} from './context.js';
+                                                                                                                 
                                                                                                                                                  
 /** `extensions` are operator registrations from a host file; explain reports whether each requirement has a provider. Nothing is activated. */
                                                                                                                                      

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/cloudflare.d.ts

@@ -39,6 +39,7 @@ export interface Artifact {
     policies?: {
         security: SecurityConfig;
     };
+    notFound?: true;
 }
 export type Validator = (value: unknown) => boolean;
 export type Validators = Record<string, Validator | undefined>;

package/dist/types/context.d.ts

@@ -64,3 +64,59 @@ export declare function renderContext(context: ProjectContext): string;
 export declare function buildContext(project: string, options?: ContextOptions): Promise<ProjectContext>;
 /** Estimated size of the shipped offline documentation bundle, for comparison with an emitted context. */
 export declare function documentationTokens(): Promise<number>;
+/** Tasks `--task` / MCP `get_context` accept. Each is fixed guidance plus the project's own facts for that task. */
+export declare const contextTasks: readonly ["redirects"];
+export type ContextTask = typeof contextTasks[number];
+export interface TaskShape {
+    need: string;
+    support: 'supported' | 'gap';
+    /** Exact YAML to merge into urlcode.yaml (`routes` entries or `site`); absent for a gap. */
+    yaml?: Record<string, unknown>;
+    /** The rule that applies, or the exact validation error a gap produces. */
+    note?: string;
+    /** For a gap: the tested declarative alternative. */
+    workaround?: string;
+}
+/** 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;
+        redirects: {
+            path: string;
+            status: number;
+            url: string;
+        }[];
+        site: string[];
+    };
+    recipe?: string;
+    commands?: Record<string, string>;
+    omitted?: string[];
+}
+export declare function renderTaskContext(context: TaskContext): string;
+/**
+ * One bounded call for a task: fixed guidance plus this project's facts for that task. Same compiler as buildContext;
+ * a directory without urlcode.yaml still gets the guidance, any other load failure propagates.
+ */
+export declare function buildTaskContext(project: string, task: string, options?: {
+    budget?: number | undefined;
+    hostFile?: string | undefined;
+    projectFlag?: string | undefined;
+}): Promise<TaskContext>;