@jimhoyd/urlcode 0.4.1 → 0.4.2

package/.claude/skills/urlcode-authoring/SKILL.md

@@ -30,6 +30,11 @@ Start with `urlcode context --project <dir> --budget 4000`, then retrieve the
 capability, schema fragment, recipe or example relevant to the change. Use the
 read-only MCP equivalents when available. `llms.txt` is the index; read the
 matching task guide from `docs/` when a query needs more explanation.
+When the project has an operator host file, inspect `urlcode extensions
+--project <dir> --host-file <absolute-file> --json` (MCP: `get_extensions`)
+before writing extension configuration or project hooks. The report is the
+machine-readable source for config/policy schemas and hook names, purposes and
+input/output schemas.
 `docs/SPECIFICATION.md` and `schemas/urlcode.schema.json` resolve contract
 questions. Archived plans are historical, not valid YAML guidance.
 
@@ -49,6 +54,11 @@ questions. Archived plans are historical, not valid YAML guidance.
 - Create every referenced module, page and asset **before** validating. All
   source paths resolve from the project root. Trusted modules can import Node built-ins and npm packages;
   only `sandbox: true` modules are restricted to the relative snapshotted graph.
+- Customize installed extensions in this order: declarative configuration;
+  `urlcode-ui` copy, theme, template and CSS overrides; a hook declared by the
+  extension; a new extension only when the installed contract cannot express
+  the behavior. Extension hooks run trusted in-process and reject `sandbox:
+  true` in contract v1.
 - Write exact response fixtures for success and failure, covering every active
   method, middleware behavior, HEAD, and any range or cache semantics.
 - Follow `docs/BEST-PRACTICES.md` for layout and readability as the project grows.

package/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "Claude plugins published from the URLCode repository.",
-    "version": "0.4.1"
+    "version": "0.4.2"
   },
   "plugins": [
     {

package/CONTRIBUTING.md

@@ -79,6 +79,42 @@ A behavior change that a reader depends on is not finished until the matching
 page in `docs/` is updated. Put both in the **same** pull request so review can
 see both halves and neither can land alone.
 
+### Maintain existing pages first
+
+Before creating a page, search the docs and update the existing home for the
+reader's task. A new page needs a distinct purpose and a link from the relevant
+guide or index. Routine task summaries and verification transcripts belong in
+the pull request, not a new permanent report.
+
+Keep each kind of information in its authoritative home:
+
+| Information | Home |
+|---|---|
+| Implemented behavior and accepted fields | Specification, topic contracts and generated schema reference |
+| How to accomplish a task | The existing guide or executable recipe |
+| Current versions and publication state | Manifests and the commands in [version alignment](docs/VERSION-ALIGNMENT.md) |
+| Actionable bugs and proposed work | GitHub issues; the roadmap links to priorities rather than copying task lists |
+| Unresolved design choices | [Open decisions](docs/OPEN-DECISIONS.md), linked to the relevant issue |
+| Security and operational evidence | Dated, scoped evidence records and the readiness register |
+| Completed or superseded plans | [Archive](docs/archive/README.md), with a link to the current owner of any remaining work |
+
+Link to these sources instead of copying changing status or entire explanations.
+Examples and brief task-specific explanations are useful; a second maintained
+version table or backlog is not. Do not treat archiving a plan as closing its
+unperformed security or deployment checks.
+
+When a decision is implemented, update the reader-facing guide and remove its
+obsolete next steps. Preserve useful rationale and evidence with an explicit
+status; do not leave historical proposals presenting themselves as current
+instructions. Avoid moving files only for tidiness: existing links and anchors
+are part of the documentation interface.
+
+Run `npm run check:docs` after documentation changes. It checks local links,
+retired repository references, guidance claims and generated resources. These
+checks cannot prove prose is current: review the affected facts against code
+and evidence too. Reviewers should ask which page owns the changed information
+and whether this PR introduced a competing explanation.
+
 `urlcode-docs` was deleted on 2026-09-19. It held its own copy of most of these
 pages and had drifted from them; the content that was ahead has been brought
 across, and the repository was retired rather than reconciled page by page.

package/ROADMAP.md

@@ -7,7 +7,7 @@ principles; [the specification](docs/SPECIFICATION.md) owns implemented behavior
 
 ## What works now
 
-The source at `db375bf` provides declarative routing, responses, assets, policies,
+The current source provides declarative routing, responses, assets, policies,
 conditions, proxy/signals, trusted Node functions and middleware, and opt-in
 `sandbox: true` isolation. Target support differs: use `urlcode capabilities`
 before promising a deployment. Stored short links have no supported package.
@@ -22,19 +22,19 @@ not future phases. See [the framework](docs/FRAMEWORK.md).
 
 ## Next work
 
-Auth, admin and UI are workspace packages here, and all three have been released
-from this repository; that migration is
-[done](docs/OPEN-DECISIONS.md#done-the-monorepo-migration-is-complete) and its
-plan is [archived](docs/archive/2026-09-19/SPIKE-MONOREPO.md). The separate
-middleware package was withdrawn rather than migrated —
-`@jimhoyd/urlcode-middleware` is unpublished and its repository deleted — so
-there is nothing to move in and nothing to fold into core afterward.
+Auth, admin and UI are workspace packages here, released from this repository;
+the migration is [done](docs/archive/2026-09-20/OPEN-DECISIONS-COMPLETED.md) and
+its plan is [archived](docs/archive/2026-09-19/SPIKE-MONOREPO.md). The separate
+middleware package was withdrawn rather than migrated
+([the decision](docs/OPEN-DECISIONS.md#accepted-middleware-withdrawn-rather-than-consolidated)).
+Versions and channels are in [version alignment](docs/VERSION-ALIGNMENT.md) and
+`npm run release:status`, not in this page.
 
 1. **Make the existing product coherent.** Keep docs, examples, generated LLM
    resources, installed skills and the standalone template consistent with their
    runtime version. Resolve the [open decisions](docs/OPEN-DECISIONS.md).
-   [Issue 168](https://github.com/jimhoyd-com/urlcode/issues/168) tracks checking
-   schema-invalid documentation examples beyond the existing prose checks.
+   Schema-invalid YAML examples in Markdown are now checked
+   (`scripts/check-guidance-claims.ts`; issue 168 is closed).
    [Issue 174](https://github.com/jimhoyd-com/urlcode/issues/174) retains the
    extension-schema retrieval proposal.
 2. **Measure the agent experience.** The benchmark harness and authoring evals
@@ -47,8 +47,12 @@ there is nothing to move in and nothing to fold into core afterward.
    independent security review, deployed recovery/soak tests and real provider
    verification remain distinct from source implementation and local tests.
    [Issue 58](https://github.com/jimhoyd-com/urlcode/issues/58) and
-   [release readiness](docs/RELEASE-READINESS.md) retain those gates. Live
-   Google/Apple/SES checks remain explicitly deferred.
+   [release readiness](docs/RELEASE-READINESS.md) retain those gates; a stable
+   release or green CI does not close them. Live Google/Apple/SES checks remain
+   explicitly deferred. [Issue 185](https://github.com/jimhoyd-com/urlcode/issues/185)
+   (CI lane measurement and release-train validation) and
+   [issue 202](https://github.com/jimhoyd-com/urlcode/issues/202) (Windows auth
+   worker startup timeout) are also still open.
 4. **Choose expansion from evidence.** Collections and a business application
    suite are proposals, not available features. Decide scope before implementing
    them. Per-route Lambda compilation is **decided against**: projects using

package/dist/BUILD-MANIFEST.json

@@ -14,7 +14,7 @@
     "dist/capabilities.js": "28dba05b3851b8b12b3c1b809af87b732f84d601c737afe9225abe429886e691",
     "dist/capability-query.js": "9f68bc94901451d7b9ecdd3aee8c3376dca7f0b890e31d8205306cf8120dea86",
     "dist/catalog.js": "c378ef9bfd63b940790f6975f7db54557c2459722b65a7c170b97df24184bc52",
-    "dist/cli.js": "45b8adaae66a46e7b05067f1ced488b9dd7ccff8d15ba71e858459d76f5ddbb8",
+    "dist/cli.js": "76d3741fa476ff20c9dae2daff56bc5c51701c7fdd61ac924ed0f3e2809928ca",
     "dist/client-address.js": "9d0d01466aab23124330605c5a0e0f981f87c897858acfad909f546a63df165b",
     "dist/cloudflare.js": "17b43b0a6b6a0ef8a893415c989e4ae3976d97cc966adbf897b785f9adc472e3",
     "dist/compliance-rules/baseline.js": "6296dea6bcb9f9bb80ed6ed5ab2f456e7f74e6de2be5d2d98ca8c983fb4df3ab",
@@ -32,7 +32,7 @@
     "dist/examples.js": "89ae2b764a688fe52acfb9b94d3d262d7742401ebd0ef10c9ebfc76edfa5631c",
     "dist/explain-cli.js": "f0f8f3b5046430d03c6abb629b38651c9c734b03456040735ce9d7e582b2bcd5",
     "dist/explain.js": "7fb632036cc68280701dd512c74d27d6e0f97b4848e9024b284d7c5393b35eb5",
-    "dist/extensions.js": "0506ec6289fa0582399d8c6d27727ffeb629bd442264248c921c63cc5b46ff01",
+    "dist/extensions.js": "07ae8888a5944372ee452b58fb0b6de226b0bc6ed73c5d5a198c1788e1a55fd6",
     "dist/function-sources.js": "16fad4abc81c7ee07b6cbcef2d23a9fc50e97a17cb4dde1db53469bbb555c96f",
     "dist/function-worker.js": "35771790ada4e1b36d447d4967a5e6cf0b543f32944e4c904f5fbf8998e824a5",
     "dist/functions.js": "0f09d1bd27eb655ceb5900a4a5e2b760d2028b02cb637a6a89a4eb5940828008",
@@ -48,7 +48,7 @@
     "dist/manifest.js": "83eed0d59621039ef364cf6e7b54c5bd47e0d8cf0a5abe7b07344bfc1db56ed8",
     "dist/match.js": "53ebcc2cda529a8d07fb83f8cb69a1446036ffc1641af3c4bd45a55851bded28",
     "dist/mcp-authoring.js": "1183a56c5decb99ecb67a5da7bd91d1b494bc17a2965051aa63c4a7e291462b5",
-    "dist/mcp.js": "484c03cdf81f94116ec973feb70754298f8b1d5b3b42561969f8cce26b3c97c2",
+    "dist/mcp.js": "4b818de2567ae8fb03adf3e5984931672ee2b469bc7ae9586388552846dae15e",
     "dist/observability.js": "f4b1ab496f051fe3ef2ed36b2b2e469c63a8940700e2df852e6ff2d9cccdd5ae",
     "dist/operator-host.js": "e3dac9d43a83beb775202b4ab9eeeba7ac63cebfc5dcc669be38d825be587bd0",
     "dist/plugins.js": "a61aa933cd9e1b41020b86fae78aa3a7f45f5313124aa11b50cb57898722385e",
@@ -58,13 +58,13 @@
     "dist/policies/security.js": "2b3bfdf82140156fea4b162adc28ee43ccd85c402fb200680dbb8d8706417420",
     "dist/policies/throttle.js": "bbb0cb1c24cf70d0a1ac32fc0618efb6c44e5b5d42564842f9c585ff7e501603",
     "dist/policies.js": "3750a7032ec7326aa544f4808683ad9eb91d4f2c5afe79904420cd8a355710a9",
-    "dist/policy.js": "33c527008fafe4af18243ba668d069517c20659150f9f1d1a5a1d076e8724f89",
+    "dist/policy.js": "2da95b3f1f77249b1e9f399a06b88909b68594fdbc958176075e91ff23104a7c",
     "dist/prerender.js": "6210999e848ab86c87f265943960ef63716896da7a40e248221a6a30425c56b8",
     "dist/project-dependencies.js": "b43a8f3125f62d38f0e71237b7813a785ef0613a83fcdec3fa8314f33758a534",
     "dist/project-tests.js": "445eaa139d2f1a2534369cfdeef081ef518de03218a467e7c5c2059caf840270",
     "dist/provider-verification.js": "ffcf9f05e8cb5f71ea46a97e279e8a613fdfdf9435ab02bd57af11e2680a9107",
     "dist/proxy.js": "34107e59ac0dbbea090efa3cf5badf3226c5302ba25e8f8ff9b2b5596ed80e50",
-    "dist/readiness.js": "90b54bc0cf60dd155d05789a1aad767bd67483d5fa6064ae8b1143f8cf9e06b2",
+    "dist/readiness.js": "28b1ade5addbc3c7427fe6a52b93850001904187c0e03c1552cbb77d8fb8572d",
     "dist/recipes.js": "11853f23e63c3c65c5bed03a278cde0349d28c9fa23266c9907a2df318bb5fc3",
     "dist/route-diff.js": "8d71d50d332ffaaed588656bd32aa36763260d1ad87bb62d7ea1c8fb23383969",
     "dist/router.js": "cf831025d5ed6778d1d6a0e541177799794e76766c82084ded81d3e87317ca1e",
@@ -75,7 +75,7 @@
     "dist/server.js": "d878bc8f0d6a05f8fd25997cace3150e2ff4d44ee9c8f4b5530e29601e164be1",
     "dist/signals.js": "b55e54efc8fb6703e08f2a1e808ec8e011bda67738db8ceadf1b248f695795be",
     "dist/site.js": "c40a06a6f9e2d6d3bea94727783c115fed4309bb0190787f58434eed64cbde84",
-    "dist/tooling.js": "7409db98422325cd4181d073d645ea57debca0e54cb151123474b85f4d4ed7dc",
+    "dist/tooling.js": "191d88eda3bf174f7000fa34995c940f3cf7e9ceafeb4b813e16eb0006767055",
     "dist/trusted-functions.js": "f3800c75f45ce90faf85ba6664398ad9031c5a9ac51d5ce42bdcff08a497d48e",
     "dist/types.js": "2fe7664dbb5695ec72114197abde72de4031df9c3b211740eacefa68e9b21844",
     "dist/typescript-authoring.js": "2e98498a15bdbb76f36fbee84afb7c42ca95bbf80a2e6dd4040147f3b1642a29",

package/dist/cli.js

@@ -28,7 +28,7 @@ import { loadComplianceRules, profileNames as complianceProfiles } from './compl
 import { parseRouteSnapshot, diffRoutes, renderRouteDiff } from './route-diff.js';
 import { readFile } from 'node:fs/promises';
 
-const usage = `URLCode 0.4.1 — local/self-hosted runtime
+const usage = `URLCode 0.4.2 — local/self-hosted runtime
   urlcode init <directory> [--with ui,auth,admin] [--manifest|--no-manifest] [--pin @scope/pkg=specifier]
     # --with: layered site from installed @jimhoyd/urlcode-<name> packages, with a package.json pinning them exactly; name ui first
     # --manifest: also pin the runtime for a route-only project; --no-manifest: --with without a package.json
@@ -135,6 +135,7 @@ function formatExtensions(report                     )         {
   if (!report.declared.length) lines.push('Declared: (none)');
   for (const item of report.extensions) lines.push(`Registered: ${item.name} (contract ${item.version}; targets ${item.targets.join(', ') || '(none)'}; ${item.declared ? 'declared' : 'not declared'}; revision ${item.revisionPinned ? 'pinned' : 'NOT pinned'})`,
     `  mounts: ${item.mounts.join(', ') || '(none)'}`, `  policy routes: ${item.policyRoutes.join(', ') || '(none)'}`, `  credential headers: ${item.credentialHeaders.join(', ') || '(none)'}`,
+    `  hooks: ${item.hooks.length ? item.hooks.map(hook => `${String((hook                   ).name)} (${String((hook                   ).kind)})`).join(', ') : '(none)'}`,
     `  configuration schema: ${JSON.stringify(item.schema)}`, `  policy schema: ${item.policySchema ? JSON.stringify(item.policySchema) : '(none)'}`);
   lines.push(report.note);
   return lines.join('\n') + '\n';

package/dist/extensions.js

@@ -1,6 +1,8 @@
 import Ajv from 'ajv/dist/2020.js';
+import { randomUUID } from 'node:crypto';
+import { pathToFileURL } from 'node:url';
 import { assert, HttpError } from './errors.js';
-import { loadDocument } from './config.js';
+import { functionFile, loadDocument } from './config.js';
 import { prepareFunctionSnapshot } from './policy.js';
 import { validateHeaderName, validateHeaderValue } from './header-validation.js';
                                                         
@@ -52,9 +54,76 @@ import { validateHeaderName, validateHeaderValue } from './header-validation.js'
  * vary on credentials. Everything else under the mount stays no-store.
  */
                                                            
+                                                                                                                  
+                                                              
+                                                
+/** Machine-readable contract for one project hook an extension exposes. */
+                                        
+              
+                         
+                     
+                     
+                       
+ 
+                                                                                                      
+/** Shared schema for project hook references. Omission means trusted execution. */
+export const extensionHookReferenceSchema={
+  oneOf:[
+    {type:'string',minLength:1,maxLength:1024},
+    {type:'object',additionalProperties:false,required:['source'],properties:{
+      source:{type:'string',minLength:1,maxLength:1024},
+      export:{type:'string',pattern:'^[A-Za-z_][A-Za-z0-9_]*$'},
+      sandbox:{type:'boolean'},
+      sandboxReason:{type:'string',minLength:1,maxLength:512},
+    }},
+  ],
+}         ;
+/** Builds the strict `config.hooks` schema from an extension's declared hook names. */
+export function extensionHooksSchema(contracts                                 )        {
+  return {type:'object',additionalProperties:false,properties:Object.fromEntries(contracts.map(contract=>[contract.name,extensionHookReferenceSchema]))};
+}
+/**
+ * Loads project hooks once per activation. Project hooks are trusted first-party
+ * code by default, matching function/middleware routes. Sandboxed arbitrary-value
+ * hooks are not part of contract v1 and are refused rather than run trusted.
+ */
+export async function loadExtensionHooks                  (config                                           ,contracts                                 ,context                                 )                                  {
+  const known=new Map(contracts.map(contract=>[contract.name,contract]));
+  const hooks                                        =Object.create(null)                                           ;
+  if(config===undefined)return hooks                           ;
+  assert(config&&typeof config==='object'&&!Array.isArray(config),'Extension hooks must be an object');
+  const epoch=randomUUID();
+  for(const [name,raw] of Object.entries(config)){
+    const contract=known.get(name);assert(contract,`Unknown extension hook: ${name}`);
+    assert(typeof raw==='string'||raw&&typeof raw==='object'&&!Array.isArray(raw),`Invalid extension hook: ${name}`);
+    const reference                       =typeof raw==='string'?{source:raw}:raw                          ;
+    if(reference.sandbox===true)throw new Error(`hook ${name}: sandbox: true is not supported for extension hooks; hooks run trusted by default`);
+    const exportName=reference.export??'default';
+    let modulePath       ;
+    try{modulePath=await functionFile(context.root,reference.source);}
+    catch(error){throw new Error(`hook ${name}: failed to load module "${reference.source}"`,{cause:error});}
+    let module                       ;
+    try{module=await import(pathToFileURL(modulePath).href+'?urlcode-extension-hook-epoch='+epoch)                          ;}
+    catch(error){throw new Error(`hook ${name}: failed to load module "${reference.source}"`,{cause:error});}
+    const fn=module[exportName];
+    if(typeof fn!=='function')throw new Error(`hook ${name}: export "${exportName}" in "${reference.source}" is not a function`);
+    const ajv=new Ajv.default({strict:false,allErrors:false});
+    const validateInput=ajv.compile(contract.inputSchema);
+    const validateOutput=contract.outputSchema?ajv.compile(contract.outputSchema):undefined;
+    hooks[name]=(input        )        =>{
+      assert(validateInput(input),`Invalid extension hook input: ${name}`);
+      const validate=(output        )        =>{if(validateOutput)assert(validateOutput(output),`Invalid extension hook output: ${name}`);return output;};
+      const output=(fn                            )(input);
+      return output instanceof Promise?output.then(validate):validate(output);
+    };
+  }
+  return hooks                           ;
+}
                                    
                                                                        
                                                                                                               
+                                                                                 
+                                          
      
                                                                                    
                                                                         
@@ -105,6 +174,7 @@ import { validateHeaderName, validateHeaderValue } from './header-validation.js'
                                                                                                  
                                                                                                                              
 const namePattern=/^[a-z][a-z0-9-]{0,63}$/;
+const hookNamePattern=/^[a-z][A-Za-z0-9]{0,63}$/;
 const cacheHeaders=new Set(['cache-control','cdn-cache-control','vercel-cdn-cache-control','surrogate-control']);
 const segmentPattern=/^[A-Za-z0-9_-][A-Za-z0-9._-]{0,63}$/;
 export const immutableCacheControl='public, max-age=31536000, immutable';
@@ -153,6 +223,13 @@ export function prepareExtensions(document                ,routes
     assert(registration.version==='1'&&typeof registration.activate==='function','Invalid extension version or activation hook');
     assert(Array.isArray(registration.targets)&&registration.targets.every(target=>['node','aws','vercel'].includes(target)),'Extension targets must be node, aws or vercel');
     assert(typeof registration.projectSha256==='string'&&/^[a-f0-9]{64}$/.test(registration.projectSha256),'Extension requires an explicit operator revision pin');
+    const hookNames=new Set        ();
+    for(const hook of registration.hooks??[]){
+      assert(hook&&typeof hook==='object'&&hookNamePattern.test(hook.name)&&!hookNames.has(hook.name),'Invalid extension hook contract');
+      assert(['filter','action'].includes(hook.kind)&&typeof hook.description==='string'&&hook.description.length>=1&&hook.description.length<=512,'Invalid extension hook contract');
+      assert(hook.inputSchema&&typeof hook.inputSchema==='object'&&(!hook.outputSchema||typeof hook.outputSchema==='object'),'Invalid extension hook contract');
+      hookNames.add(hook.name);
+    }
     provided.set(registration.name,registration);
   }
   const declarations=document.extensions??{};

package/dist/mcp.js

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

package/dist/policy.js

@@ -32,6 +32,22 @@ export async function prepareFunctionSnapshot(loaded                )
     if (route.sandbox) { for (const definition of [...middleware, ...(fn ? [fn] : [])]) sandboxed.push({pattern,function:definition}); }
     else trusted.push({middleware, function: fn});
   }
+  // Extension hooks are a core primitive even though their names and payloads
+  // belong to each extension. Include every declared entry module in the
+  // reviewed project revision, so editing trusted hook code invalidates the
+  // operator's extension pin just like editing a trusted route function.
+  for(const [extension,declaration] of Object.entries(loaded.document.extensions??{})){
+    const hooks=declaration.config.hooks;
+    if(hooks===undefined)continue;
+    assert(hooks&&typeof hooks==='object'&&!Array.isArray(hooks),`Extension ${extension} hooks must be an object`);
+    for(const [name,raw] of Object.entries(hooks                          )){
+      assert(typeof raw==='string'||raw&&typeof raw==='object'&&!Array.isArray(raw),`Invalid extension hook: ${extension}.${name}`);
+      const reference=typeof raw==='string'?{source:raw}:raw                                     ;
+      assert(typeof reference.source==='string',`Invalid extension hook: ${extension}.${name}`);
+      assert(reference.export===undefined||typeof reference.export==='string',`Invalid extension hook: ${extension}.${name}`);
+      trusted.push({function:await resolveOne({source:reference.source,...(reference.export===undefined?{}:{export:reference.export          })})});
+    }
+  }
   const collected = await collectFunctionSources(sandboxed,loaded.root);
   const trustedSources = await collectTrustedSources(trusted,loaded.root);
   // The hash operator grants pin to still covers trusted routes' own source, so

package/dist/readiness.js

@@ -37,6 +37,9 @@ import { runCompliance } from './compliance.js';
                                                                                                                                         
                               
                                     
+                                                                         
+                                                                                               
+                            
                                                                                                                        
                                                                                                                                     
                                                                                                                                                             
@@ -188,7 +191,8 @@ export async function auditProject(app              , {expectRoutes,log=()=>{},c
   const advisories=plan.inventory.flatMap(route=>(route.advisories??[]).map(message=>({route:route.path,message})));
   // The per-route capability table: which policies apply and whether this
   // host enforces, compiles or delegates each one. Refusals never get here.
-  return {elapsedMs:performance.now()-began,ready:countMatches && !failed && !uncovered.length && counts.active>0,counts,expectedRoutes:expectRoutes ?? null,countMatches,checks:cases.length,passed,failed,coveredRouteMethods:covered.size,unassertedCases,uncovered,policies:plan.policies ?? {},compliance:compliance?await runCompliance(app,compliance):null,advisories};
+  const notReadyReasons=[...(counts.active>0?[]:['no-active-routes']),...(countMatches?[]:['route-count-mismatch']),...(failed?['failed-checks']:[]),...(uncovered.length?['uncovered-route-methods']:[])];
+  return {elapsedMs:performance.now()-began,ready:!notReadyReasons.length,notReadyReasons,counts,expectedRoutes:expectRoutes ?? null,countMatches,checks:cases.length,passed,failed,coveredRouteMethods:covered.size,unassertedCases,uncovered,policies:plan.policies ?? {},compliance:compliance?await runCompliance(app,compliance):null,advisories};
 }
 export async function benchmarkProject(app              ,{requests=1000,concurrency=2,maxP95Ms,seconds=30,warmup=0,target}                  ={})                           {
   assert(Number.isInteger(requests)&&requests>=1&&requests<=100000,'Requests must be 1–100000');

package/dist/tooling.js

@@ -68,7 +68,7 @@ export async function previewImport(options                    ) {return importR
 export async function previewExport(project       ,format                  ,acceptProviderDifferences=false) {const loaded=await loadDocument(project);const {includes:_includes,...document}=loaded.document;return exportRoutes({format,document:{...document,routes:loaded.routes},acceptProviderDifferences});}
                                       
                                                               
-                                                                                                                                                                                                            
+                                                                                                                                                                                                                           
                                                                                                   
  
 /** Reports registered extension contracts against the project's declarations. Never activates an extension. */
@@ -84,6 +84,7 @@ export async function describeExtensions(project       ,registrations
   name:String(registration.name),version:String(registration.version),targets:Array.isArray(registration.targets)?registration.targets.map(String):[],
   credentialHeaders:Array.isArray(registration.credentialHeaders)?registration.credentialHeaders.map(String):[],
   schema:structuredClone(registration.schema??{}),policySchema:registration.policySchema?structuredClone(registration.policySchema):null,
+  hooks:structuredClone(registration.hooks??[])            ,
   declared:Object.hasOwn(loaded.document.extensions??{},registration.name),revisionPinned:registration.projectSha256===projectSha256,
   mounts:mountsOf(registration.name),policyRoutes:policyRoutesOf(registration.name),
  }));

package/dist/types/extensions.d.ts

@@ -66,6 +66,62 @@ export interface ExtensionInstance {
 export interface ExtensionImmutableAssets {
     prefix: string;
 }
+export interface ExtensionHookReference {
+    source: string;
+    export?: string;
+    sandbox?: boolean;
+    sandboxReason?: string;
+}
+export type ExtensionHookConfig = string | ExtensionHookReference;
+export type ExtensionHookKind = 'filter' | 'action';
+/** Machine-readable contract for one project hook an extension exposes. */
+export interface ExtensionHookContract {
+    name: string;
+    kind: ExtensionHookKind;
+    description: string;
+    inputSchema: object;
+    outputSchema?: object;
+}
+export type LoadedExtensionHooks<T extends string = string> = Partial<Record<T, (input: unknown) => unknown>>;
+/** Shared schema for project hook references. Omission means trusted execution. */
+export declare const extensionHookReferenceSchema: {
+    readonly oneOf: readonly [{
+        readonly type: "string";
+        readonly minLength: 1;
+        readonly maxLength: 1024;
+    }, {
+        readonly type: "object";
+        readonly additionalProperties: false;
+        readonly required: readonly ["source"];
+        readonly properties: {
+            readonly source: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly maxLength: 1024;
+            };
+            readonly export: {
+                readonly type: "string";
+                readonly pattern: "^[A-Za-z_][A-Za-z0-9_]*$";
+            };
+            readonly sandbox: {
+                readonly type: "boolean";
+            };
+            readonly sandboxReason: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly maxLength: 512;
+            };
+        };
+    }];
+};
+/** Builds the strict `config.hooks` schema from an extension's declared hook names. */
+export declare function extensionHooksSchema(contracts: readonly ExtensionHookContract[]): object;
+/**
+ * Loads project hooks once per activation. Project hooks are trusted first-party
+ * code by default, matching function/middleware routes. Sandboxed arbitrary-value
+ * hooks are not part of contract v1 and are refused rather than run trusted.
+ */
+export declare function loadExtensionHooks<T extends string>(config: Readonly<Record<string, unknown>> | undefined, contracts: readonly ExtensionHookContract[], context: Pick<ExtensionActivation, 'root'>): Promise<LoadedExtensionHooks<T>>;
 export interface RuntimeExtension {
     name: string;
     version: '1';
@@ -75,6 +131,8 @@ export interface RuntimeExtension {
     policySchema?: object;
     credentialHeaders?: string[];
     immutableAssets?: ExtensionImmutableAssets;
+    /** Project customization points, exposed by CLI/MCP for authors and agents. */
+    hooks?: readonly ExtensionHookContract[];
     /**
      * Reviewed, operator-declared cache sensitivity for `policies.extensions.<name>`
      * routes (never for an `extension:` mount, which is always treated as

package/dist/types/readiness.d.ts

@@ -57,6 +57,9 @@ export interface AuditOptions {
 export interface AuditReport {
     elapsedMs: number;
     ready: boolean;
+    /** Empty when `ready`; otherwise one stable code per failed condition:
+     * `no-active-routes`, `route-count-mismatch`, `failed-checks`, `uncovered-route-methods`. */
+    notReadyReasons: string[];
     counts: {
         configured: number;
         active: number;

package/dist/types/tooling.d.ts

@@ -93,6 +93,7 @@ export interface ExtensionInspection {
         credentialHeaders: string[];
         schema: object;
         policySchema: object | null;
+        hooks: object[];
         declared: boolean;
         revisionPinned: boolean;
         mounts: string[];

package/docs/AI-AUTHORING.md

@@ -273,9 +273,10 @@ either `true` or `false`) or `sandbox: true` is enough to silence it.
 
 The same judgment call applies to a project-level lifecycle hook an
 extension invokes (`onSignUp`, `beforeRegister` and the like) — it is
-first-party project code with the same trusted-by-default rule and the same
-`sandbox: true` opt-in as any `function`/`middleware` route, no special
-case. See [EXTENSIONS.md](EXTENSIONS.md#project-level-lifecycle-hooks).
+first-party project code with the same trusted-by-default rule as a
+`function`/`middleware` route. Extension hook contract v1 is trusted-only;
+`sandbox: true` is rejected rather than silently ignored. See
+[EXTENSIONS.md](EXTENSIONS.md#project-level-lifecycle-hooks).
 
 Guest TypeScript needs `build-typescript --project SOURCE --out NEW_DIRECTORY`
 before serving. Only the emitted `.js`/`.mjs` executes, in QuickJS for a
@@ -294,7 +295,7 @@ origin grants pinned to the project revision. These are self-hosted features;
 providers refuse them. Signals are bounded best effort with drops, no retries
 or persistence. Never turn a user request into an implicit network grant.
 
-Before using a feature, ask `urlcode capabilities <name>` for its constraints, grants and target support and `urlcode schema <path>` for only that YAML fragment (MCP: `get_capability`, `get_schema`), instead of guessing.
+Before using a feature, ask `urlcode capabilities <name>` for its constraints, grants and target support and `urlcode schema <path>` for only that YAML fragment (MCP: `get_capability`, `get_schema`), instead of guessing. For an installed extension, use `urlcode extensions --host-file ... --json` or MCP `get_extensions`; its hook contracts include the accepted names, purpose and input/output schemas. Prefer extension configuration and UI copy/templates/theme/CSS, then a declared project hook, and only then a new extension or fork.
 The [tooling SDK and stdio MCP](TOOLING.md) inspect, validate, explain and preview
 without guest execution, environment reads or writes. Run `urlcode explain /route`
 to check effective methods, policies and cache outcome, and `urlcode manifest`

package/docs/COMPOSING-A-SITE.md

@@ -200,15 +200,24 @@ extensions:
         onSignUp: ./hooks/on-signup.mjs
 ```
 
-`hooks` is not a core schema key. It is each package's own config, validated
-by that package's schema before `activate()`, which is why `get_extensions` is
-the place to check what a given version accepts.
+`hooks` remains each package's own config, but core supplies the reference
+schema, trusted loader and machine-readable hook contract. `get_extensions`
+reports those contracts, so an agent can discover accepted names, purpose and
+input/output shapes without guessing from prose.
 
 Hooks are first-party project code and run **trusted and in-process**, the
 same default `function` and `middleware` routes have
-([FUNCTION-SECURITY.md](FUNCTION-SECURITY.md)). Neither package implements
-sandboxed hook execution yet; `sandbox: true` on a hook is rejected loudly at
-activation rather than accepted and silently run trusted.
+([FUNCTION-SECURITY.md](FUNCTION-SECURITY.md)). Extension hook contract v1 is
+trusted-only; `sandbox: true` is rejected loudly at activation.
+
+### `@jimhoyd/urlcode-ui`
+
+| Hook | Input | Returns | Called |
+|---|---|---|---|
+| `transformView` | `{template, view}` | the view object to render | Synchronously before each public `ui.kit.render()` or `ui.kit.page()` call. Use it only when theme, copy, templates and CSS cannot express the change. |
+
+For example, `transformView: ./hooks/ui-view.mjs` can add project-computed
+navigation or labels to an auth/admin view without editing either package.
 
 ### `@jimhoyd/urlcode-auth`
 

package/docs/CONTAINER-PROMOTION.md

@@ -0,0 +1,74 @@
+# Container image promotion (design, issue #233)
+
+Status: design plus an inert helper. Nothing described under "Proposed" is
+implemented, and no workflow was changed. This does not authorize enabling
+`PUBLISH_CONTAINER`, publishing, or changing any existing tag. The point is
+supply-chain integrity (tested bytes are shipped bytes), not speed: the sampled
+CI image build took about 12 seconds, so build caching is deliberately out of scope.
+
+## Current behavior (read from the workflows at 67a6996)
+
+- `ci.yml` job `container` (a required check) runs `docker build -t urlcode:test .`
+  and smoke-tests it. That image is discarded; no digest is recorded.
+- `candidate.yml` builds and signs the npm archives, SBOM and manifests. It builds no
+  image. `manifest.json` and the exact-file-set check in `validateCandidate` know nothing
+  about images.
+- `release.yml`, only when `vars.PUBLISH_CONTAINER == 'true'`, runs a fresh
+  `docker build` of the tagged commit with `revision`/`version` labels and pushes
+  `:VERSION` and the channel tag.
+- On retry, if `:VERSION` already exists it is accepted after checking only the
+  `revision` label. A label is asserted by whoever built the image, so a differently
+  built image with the same label passes. Bytes are not compared.
+- Channel monotonicity is enforced by reading the `version` label of the existing
+  channel tag (semver `gte`). That guard is sound and should be kept.
+- A rebuild is not byte-reproducible (it runs `npm ci`, embeds timestamps), so the image
+  the release publishes is never the image CI tested, even for the same commit.
+
+Not verified: live GHCR contents, package visibility/permissions, whether
+`PUBLISH_CONTAINER` is set, and whether any image was ever pushed.
+
+## Proposed path (not implemented)
+
+1. Candidate build. In `candidate.yml`, build the image once from the exact commit
+   (`docker buildx build --output type=oci,dest=candidate/image.oci.tar` with the
+   revision/version labels), run the same three smoke tests as `ci.yml` against that
+   archive, and record `image: { digest, sourceCommit, version }` in `manifest.json`.
+   Add `image.oci.tar` to the attested subjects so the existing `attestation verify` and
+   the manifest SHA-256 pinned in the annotated tag cover the image as well.
+2. Manifest schema. Add the archive to the expected file set in `validateCandidate`
+   and validate the record with `candidateImage()` from `scripts/release-image.ts`.
+   Because the tag pins the manifest hash, the digest is immutable once tagged.
+3. Promotion. `release.yml` verifies the bundle (already done by `restore`), then copies
+   the archive to the registry preserving the manifest digest (`skopeo copy` or
+   `crane push` of the OCI layout; not `docker load` then `docker push`, which can
+   change digests under some storage drivers) and pushes `:VERSION` and the channel tag
+   as pointers to that digest. It never runs `docker build`.
+4. Retry identity. If `:VERSION` exists, resolve its digest with
+   `docker buildx imagetools inspect` and require `assertPromotedImage()` to pass. A
+   rebuilt image with matching labels but different bytes is refused. Channel tags keep
+   the existing `assertChannel` check via `assertImageChannel()`.
+5. Attestation. Optionally attest the image digest with `actions/attest` using
+   `push-to-registry`; this needs `packages: write` and its GHCR behavior is unverified.
+6. Self-hosting. The `Dockerfile` and `docker build` remain the documented way to build
+   from source. CI's `container` check stays as is to preserve the required check name.
+
+## What the inert helper proves
+
+`scripts/release-image.ts` and `test/release-image.test.ts` are pure functions and unit
+tests. They pin the invariant (promoted digest equals tested digest; labels match;
+channel never regresses; a same-label different-bytes image is rejected). No workflow
+imports them, so the release path is unchanged.
+
+## Could not establish
+
+- Whether GHCR preserves the OCI digest through `skopeo`/`crane` from the runner, and
+  whether the org's package settings permit it.
+- Behavior of image attestation and OIDC for GHCR.
+- Whether a candidate-built OCI archive fits comfortably within the artifact size and
+  90-day retention model; recovery from GitHub release assets would need the archive
+  attached there too.
+- Any real run: none was dispatched.
+
+A first implementation should be a separate reviewed PR that lands the candidate-side
+build behind an operator-controlled input, and leaves the publisher change until one
+candidate has been produced and inspected.