@jimhoyd/urlcode 0.3.0 → 0.4.0-alpha.1

package/dist/cli.js

@@ -1,23 +1,36 @@
 #!/usr/bin/env node
+import { getCapabilities, formatCapabilities } from './capabilities.js';
+import { getCapability, formatCapability } from './capability-query.js';
+import { getSchemaFragment } from './schema-query.js';
+import { stringify as stringifyYaml } from 'yaml';
 import { auditProject, benchmarkProject } from './readiness.js';
                                                         
 import { parseArgs } from 'node:util';
 import { createRuntime } from './runtime.js';
+import { loadOperatorHost } from './operator-host.js';
+                                                       
 import { startServer } from './server.js';
                                                  
 import {scaffoldProject} from './scaffold.js';
 import { initProject, addRedirect } from './authoring.js';
+import { initProjectWith, parseWithNames } from './init-with.js';
 import { runProjectTests } from './project-tests.js';
+import { verifyDeployment, failLevels } from './verify-deployment.js';
+                                                     
 import { loadOperatorPolicy, prepareFunctionSnapshot, requestedPermissions } from './policy.js';
 import { loadDocument } from './config.js';
+import { describeExtensions } from './tooling.js';
+                                                        
 import {parseLinkBinding,runLinkCommand,linkPoolOptions} from './link-cli.js';
 import { ConfigError, HttpError } from './errors.js';
 import {supportsConcurrentWal} from './sqlite-version.js';
 import { registry as policyRegistry } from './policies.js';
 import { loadComplianceRules, profileNames as complianceProfiles } from './compliance.js';
+import { parseRouteSnapshot, diffRoutes, renderRouteDiff } from './route-diff.js';
+import { readFile } from 'node:fs/promises';
 
-const usage = `URLCode 0.3.0 — local/self-hosted runtime
-  urlcode init <directory>
+const usage = `URLCode 0.4.0-alpha.1 — local/self-hosted runtime
+  urlcode init <directory> [--with auth,admin]  # --with: layered site from installed @jimhoyd/urlcode-<name> packages
   urlcode scaffold [--project directory] [--dry-run]
   urlcode validate [--project directory] [--local] [--origin https://links.example]  # origin: absolute URLs in site.* files
   urlcode dev [--project directory] [--port 3000] [--host 127.0.0.1]
@@ -30,33 +43,60 @@ const usage = `URLCode 0.3.0 — local/self-hosted runtime
   urlcode test [--project directory] [--origin https://links.example]
   urlcode build --target cloudflare [--project directory] [--out dist/cloudflare] [--origin https://links.example]
   urlcode routes [--project directory] [--origin https://links.example]
+    diff: [--compare previous-routes.json] [--format json|markdown]  # added/removed/changed routes against an earlier report; always exits 0
   urlcode audit [--project directory] [--expect-routes 2]
     compliance: [--compliance baseline|strict|privacy|none] [--compliance-rules /absolute/rules.mjs] [--compliance-ignore id,id]
                 [--compliance-warn] [--origin https://links.example] [--request-log minimal|detailed]  # declare the deployment under review
   urlcode benchmark [--project directory] [--requests 1000] [--concurrency 2] [--seconds 30] [--max-p95-ms 50]
     [--warmup 50] [--target https://links.example]  # target measures a running deployment, not a local snapshot
-  urlcode permissions [--project directory]  # inspect requested bindings; grants nothing
+  urlcode verify-deployment --target https://links.example [--project directory] [--origin https://links.example]
+    [--expect-routes 2] [--expect-metrics] [--timeout-ms 10000] [--fail-on high|medium|low|info|none]
+    [--compliance baseline|strict|privacy|none] [--compliance-rules ...] [--compliance-ignore id,id] [--compliance-warn]
+    # compares the running deployment's responses with what this project declares; never follows redirects, no --insecure
+  urlcode permissions [--project directory]  # inspect requested bindings and egress origins; grants nothing
+  urlcode explain [/route] [--project directory] [--target self-hosted|cloudflare|aws|vercel] [--host-file ...] [--json]
+    # effective methods, handler, middleware, inputs, policies, cache outcome, bindings and target support from the compiled configuration
+  urlcode manifest [--project directory] [--json]  # generated semantic manifest; build writes the same file as manifest.json
+  urlcode extensions [--project directory] [--host-file /absolute/operator/host.mjs] [--json]  # registered contracts and schemas; executes trusted host code, activates nothing
   urlcode links init|create|get|list|update|delete|export|import|api --store /absolute/links.sqlite [--collection links]
     create/update: --destination https://example.com [--code abc] [--status 302] [--enabled true] [--expires UTC]
     update/delete: --code abc --if-version N (update replaces all mutable fields)
     export: consistent NDJSON snapshot to stdout [--collection links] [--page-size 100]
     import: --input /absolute/export.ndjson restores into empty collections (versions are reassigned)
     api: --auth-file /operator/management.json (or legacy --token-file /operator/token) --port 3001 (separate authenticated server)
+  urlcode import [netlify|cloudflare|vercel|netlify-toml] <file> [--format csv|json|yaml] [--out new-file] [--dry-run] [--report json]
+  urlcode export --target netlify|cloudflare|vercel|netlify-toml|csv|json|yaml [--project directory] [--out new-file] [--report json]
+    conversion: [--accept-provider-differences]  # explicit non-lossless migration candidate; exact behavior requires runtime
+  urlcode recipes [list|search <text>|show <name>|add <name> --out new-directory] [--dry-run] [--json]
+  urlcode examples [list|search <text>] [--json]  # bundled runnable examples and the cookbook route index
+  urlcode build-typescript [--project directory] --out new-directory [--dry-run]
+  urlcode bulk-import csv|json|yaml <file> --out new-directory [--dry-run]
+  urlcode verify-provider --target self-hosted|aws|vercel|cloudflare --origin https://owned-fixture.example
+    [--timeout-ms 3000] [--release label] [--git-commit sha]  # explicitly invokes synthetic deployment probes
+  urlcode mcp [--project directory] [--allow-authoring] [--host-file ...]  # bounded stdio tooling; --allow-authoring adds project-confined authoring tools, host file adds get_extensions
+  urlcode capabilities [--target self-hosted|cloudflare|aws|vercel] [--json]
+  urlcode capabilities <name> [--json]  # one catalog entry: schema fragment, constraints, grants, targets, bundled uses
+  urlcode schema <path> [--json|--yaml]  # schema fragment for route, redirect, policies.cache, site.sitemap, ...
+  urlcode context [--project directory] [--target self-hosted|cloudflare|aws|vercel] [--budget 500] [--json] [--stats]
+    # compact facts for an authoring agent from the compiled project; --stats compares estimated tokens with the docs
   urlcode doctor
+  serve/dev/validate/test/routes/audit/benchmark/explain/context/extensions/mcp: --host-file /absolute/operator/host.mjs (trusted code outside project)
   serve/dev/validate/test/routes/audit/benchmark: --link-store links=/absolute/links.sqlite
   Store pool controls: --link-readers 2 (1–8), --link-read-limit 32, --link-write-limit 32 (1–32 each)
 Dev loads .env.local and watches; serve does neither. Functions run in WASM isolation; external bindings require --policy outside the project.
 `;
 const print = (value         )          => process.stdout.write(typeof value === 'string' ? value : JSON.stringify(value) + '\n');
 const options = {
-  project:{ type:'string', default:'.' },
+  json:{ type:'boolean' }, yaml:{ type:'boolean' }, report:{type:'string'}, 'accept-provider-differences':{type:'boolean'},
+  project:{ type:'string', default:'.' }, 'host-file':{type:'string'}, with:{type:'string'},
   port:{ type:'string' }, host:{ type:'string', default:'127.0.0.1' },
   'expect-routes':{type:'string'}, requests:{type:'string'}, concurrency:{type:'string'}, seconds:{type:'string'}, 'max-p95-ms':{type:'string'}, warmup:{type:'string'}, target:{type:'string'},
   'link-readers':{type:'string'}, 'link-read-limit':{type:'string'}, 'link-write-limit':{type:'string'},
   workers:{type:'string'}, 'function-timeout-ms':{type:'string'}, 'max-response-bytes':{type:'string'}, 'max-body-bytes':{type:'string'},
   'max-in-flight':{type:'string'}, 'max-in-flight-health':{type:'string'}, 'request-log':{type:'string'}, 'trust-request-id':{type:'boolean'}, 'trusted-proxies':{type:'string'}, metrics:{type:'boolean'},
   'link-store':{type:'string'}, store:{type:'string'}, collection:{type:'string'}, code:{type:'string'}, destination:{type:'string'}, status:{type:'string'}, enabled:{type:'string'}, expires:{type:'string'}, 'if-version':{type:'string'}, limit:{type:'string'}, after:{type:'string'}, 'token-file':{type:'string'}, 'auth-file':{type:'string'}, input:{type:'string'}, 'page-size':{type:'string'},
-  out:{type:'string'}, 'dry-run':{type:'boolean'}, compliance:{type:'string'}, 'compliance-rules':{type:'string'}, 'compliance-ignore':{type:'string'}, 'compliance-warn':{type:'boolean'}, policy:{ type:'string' }, origin:{ type:'string' }, alias:{ type:'string' }, local:{ type:'boolean' }, help:{ type:'boolean', short:'h' },
+  release:{type:'string'}, 'git-commit':{type:'string'}, 'timeout-ms':{type:'string'}, 'fail-on':{type:'string'}, 'expect-metrics':{type:'boolean'},
+  budget:{type:'string'}, stats:{type:'boolean'}, out:{type:'string'}, 'dry-run':{type:'boolean'}, compare:{type:'string'}, format:{type:'string'}, compliance:{type:'string'}, 'compliance-rules':{type:'string'}, 'compliance-ignore':{type:'string'}, 'compliance-warn':{type:'boolean'}, policy:{ type:'string' }, origin:{ type:'string' }, alias:{ type:'string' }, local:{ type:'boolean' }, 'allow-authoring':{ type:'boolean' }, help:{ type:'boolean', short:'h' },
 }         ;
                                                                                                           
                                                                                                                                                                                                                         
@@ -95,15 +135,62 @@ async function complianceOptions(values        )
   if(!['minimal','detailed'].includes(host.requestLog))throw new ConfigError('Use --request-log minimal or detailed');
   return {profile,ignore,origin:values.origin,host,rules:operator?.rules ?? [],disable:operator?.disable ?? [],override:operator?.override ?? {}};
 }
+function formatExtensions(report                     )         {
+  const lines = [`Project revision: ${report.projectSha256}`];
+  for (const item of report.declared) lines.push(`Declared: ${item.name} (contract ${item.version}) ${item.registered ? 'registered' : report.hostLoaded ? 'NOT registered by the host file' : 'schemas need --host-file'}`, `  mounts: ${item.mounts.join(', ') || '(none)'}`, `  policy routes: ${item.policyRoutes.join(', ') || '(none)'}`);
+  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)'}`,
+    `  configuration schema: ${JSON.stringify(item.schema)}`, `  policy schema: ${item.policySchema ? JSON.stringify(item.policySchema) : '(none)'}`);
+  lines.push(report.note);
+  return lines.join('\n') + '\n';
+}
 const errorMessages                                     = { ERR_PARSE_ARGS_UNKNOWN_OPTION:'Unknown option; use --help', EEXIST:'Destination or edit lock already exists', ENOENT:'Required file or directory not found', EADDRINUSE:'Port is already in use', EACCES:'Permission denied' };
+let operatorHost               = {};
+let serving = false;
 try {
   const { values, positionals } = parseArgs({ allowPositionals:true, options });
   const [command, arg, ...extra] = positionals;
   values.port ??= command==='links' && arg==='api' ? '3001' : '3000';
   if (values.help || !command) print(usage);
   else {
-    if (extra.length || (!['init','add','links'].includes(command) && arg)) throw new ConfigError('Unexpected positional arguments');
-    if(command==='links'){await runLinkCommand(arg,values,print);}else{
+    if (values['host-file'] !== undefined) {
+      if (!['serve','dev','validate','test','routes','audit','benchmark','explain','context','extensions','mcp'].includes(command)) throw new ConfigError('--host-file is only supported by serve/dev/validate/test/routes/audit/benchmark/explain/context/extensions/mcp');
+      // The MCP server and context command load and release the host themselves.
+      if (command !== 'mcp' && command !== 'context') operatorHost = await loadOperatorHost(values['host-file'], values.project);
+    }
+    if (values.with !== undefined && command !== 'init') throw new ConfigError('--with is only supported by init');
+    if (values['allow-authoring'] && command !== 'mcp') throw new ConfigError('--allow-authoring is only supported by mcp');
+    const hostOptions = { extensions: operatorHost.extensions, plugins: operatorHost.plugins };
+    if ((!['import','recipes','recipe','examples','example','bulk-import'].includes(command) && extra.length) || (!['init','add','links','import','recipes','recipe','examples','example','bulk-import','explain','capabilities','schema'].includes(command) && arg)) throw new ConfigError('Unexpected positional arguments');
+
+    if(command==='import'||command==='export'){
+      const { runInterchange } = await import('./interchange-cli.js');
+      const converted = await runInterchange(command,positionals.slice(1),{project:values.project,target:values.target,format:values.format,out:values.out,report:values.report,dryRun:values['dry-run'],acceptProviderDifferences:values['accept-provider-differences']});
+      print(converted.text); if(!converted.report.ok)process.exitCode=1;
+    }else if(['recipes','recipe','examples','example','build-typescript','bulk-import','verify-provider','mcp'].includes(command)){
+      const {runEcosystemCommand}=await import('./ecosystem-cli.js');
+      await runEcosystemCommand(command,positionals.slice(1),values,print);
+    }else if(command==='explain'||command==='manifest'){
+      const {runExplainCommand}=await import('./explain-cli.js');
+      const exitCode=await runExplainCommand(command,arg,{project:values.project,target:values.target,origin:values.origin,json:values.json,extensions:operatorHost.extensions},print);
+      if(exitCode)process.exitCode=exitCode;
+    }else if(command==='capabilities'){
+      if(arg!==undefined){ if(values.target!==undefined)throw new ConfigError('--target applies to the full catalog, not one entry'); const entry=getCapability(arg); print(values.json ? entry : formatCapability(entry)); }
+      else { const catalog = getCapabilities(values.target); print(values.json ? catalog : formatCapabilities(catalog)); }
+    }else if(command==='schema'){
+      if(arg===undefined)throw new ConfigError('Use urlcode schema <path>');
+      const fragment=getSchemaFragment(arg);
+      print(values.yaml ? stringifyYaml(fragment.schema) : JSON.stringify(fragment.schema,null,2)+'\n');
+    }else if(command==='context'){
+      if (values.budget !== undefined && !/^\d{1,9}$/.test(values.budget)) throw new ConfigError('Invalid --budget');
+      const { buildContext, renderContext, estimateTokens, documentationTokens } = await import('./context.js');
+      const context = await buildContext(values.project, { target:values.target, hostFile:values['host-file'], ...(values.budget === undefined ? {} : { budget:Number(values.budget) }) });
+      const text = values.json ? JSON.stringify(context) + '\n' : renderContext(context);
+      print(text);
+      // Estimates only (characters / 4); a tokenizer is not a dependency. Stats go to stderr so stdout stays parseable.
+      if (values.stats) process.stderr.write(JSON.stringify({ event:'stats', estimate:'characters/4', documentationTokens:await documentationTokens(), contextTokens:estimateTokens(text) }) + '\n');
+    }else if(command==='links'){await runLinkCommand(arg,values,print);}else{
       const permissions = await loadOperatorPolicy(values.policy,values.project);
       const linkStore=parseLinkBinding(values['link-store'],linkPoolOptions(values));
       switch (command) {
@@ -117,12 +204,22 @@ try {
           const expected=number('expect-routes');
           if(expected!==undefined && !Number.isSafeInteger(expected))throw new ConfigError('Expected route count must be an integer');
           const compliance=command==='audit'?await complianceOptions(values):undefined;
+          const format=values.format ?? 'json';
+          if(!['json','markdown'].includes(format))throw new ConfigError('Use --format json or markdown');
+          if(values.format!==undefined && values.compare===undefined)throw new ConfigError('--format applies to routes --compare');
           const started=performance.now();
-          const app=await startServer({project:values.project,port:0,local:true,permissions,linkStore,origin:values.origin,log:()=>{}});
+          const app=await startServer({...hostOptions,project:values.project,port:0,local:true,permissions,linkStore,origin:values.origin,log:()=>{}});
           const startupMs=performance.now()-started;
           try {
             if(command==='routes') {
-              const plan=app.testPlan(); print({routes:plan.inventory.length,dynamicLinks:plan.dynamicLinks,inventory:plan.inventory,policies:plan.policies});
+              const plan=app.testPlan();
+              if(values.compare===undefined) print({routes:plan.inventory.length,dynamicLinks:plan.dynamicLinks,inventory:plan.inventory,policies:plan.policies});
+              else {
+                // The diff reports; it never judges, so the exit code stays 0.
+                const before=parseRouteSnapshot(JSON.parse(await readFile(values.compare,'utf8'))); // file boundary: an earlier `routes` report
+                const diff=diffRoutes(before,{inventory:plan.inventory,policies:plan.policies});
+                print(format==='markdown'?renderRouteDiff(diff):diff);
+              }
             } else if(command==='audit') {
               const report=await auditProject(app,{expectRoutes:expected,log:print,compliance});print(report);if(!report.ready)process.exitCode=1;
               if(report.compliance && !report.compliance.pass && !values['compliance-warn'])process.exitCode=1;
@@ -134,6 +231,34 @@ try {
           } finally {await app.close();}
           break;
         }
+        case 'verify-deployment': {
+          if (!values.target) throw new ConfigError('Provide --target https://host');
+          const integer = (key                                )                     => {
+            const value = values[key];
+            if (value === undefined) return undefined;
+            if (!/^\d{1,9}$/.test(value)) throw new ConfigError(`Invalid --${key}`);
+            return Number(value);
+          };
+          const failOn = values['fail-on'] ?? 'high';
+          const isFailOn = (value        )                  => (failLevels                     ).includes(value);
+          if (!isFailOn(failOn)) throw new ConfigError(`Use --fail-on ${failLevels.join('|')}`);
+          const report = await verifyDeployment(values.project, { target: values.target, origin: values.origin, expectRoutes: integer('expect-routes'), timeoutMs: integer('timeout-ms'),
+            expectMetrics: values['expect-metrics'], failOn, compliance: await complianceOptions(values), complianceWarn: values['compliance-warn'], permissions, linkStore, log: print });
+          print(report); if (!report.pass) process.exitCode = 1; break;
+        }
+        case 'verify-provider': {
+          const target=values.target;
+          if(target!=='self-hosted'&&target!=='aws'&&target!=='vercel'&&target!=='cloudflare')throw new ConfigError('Provide --target self-hosted|aws|vercel|cloudflare');
+          if(!values.origin)throw new ConfigError('Provide --origin https://owned-fixture.example');
+          if(values['timeout-ms']!==undefined&&!/^\d{1,5}$/.test(values['timeout-ms']))throw new ConfigError('Invalid --timeout-ms');
+          const {verifyProviderDeployment}=await import('./provider-verification.js');
+          const report=await verifyProviderDeployment(target,values.origin,{
+            ...(values['timeout-ms']===undefined?{}:{timeoutMs:Number(values['timeout-ms'])}),
+            ...(values.release===undefined?{}:{release:values.release}),
+            ...(values['git-commit']===undefined?{}:{gitCommit:values['git-commit']}),
+          });
+          print(report);if(!report.pass)process.exitCode=1;break;
+        }
         case 'build': {
           if (values.target !== 'cloudflare') throw new ConfigError('Use --target cloudflare');
           const { buildCloudflare } = await import('./build-cloudflare.js');
@@ -141,36 +266,46 @@ try {
         }
         case 'scaffold':
           print(await scaffoldProject(values.project,{dryRun:values['dry-run']}));break;
+        case 'extensions': {
+          const report = await describeExtensions(values.project, values['host-file'] === undefined ? undefined : operatorHost.extensions ?? []);
+          print(values.json ? report : formatExtensions(report)); break;
+        }
         case 'permissions': {
           const loaded = await loadDocument(values.project);
           print(requestedPermissions(loaded,await prepareFunctionSnapshot(loaded))); break;
         }
         case 'init':
           if (!arg) throw new ConfigError('Provide a new project directory');
-          await initProject(arg); print({ event:'created' }); break;
+          if (values.with === undefined) { await initProject(arg); print({ event:'created' }); break; }
+          {
+            const created = await initProjectWith(arg, parseWithNames(values.with));
+            print({ event:'created', ...created, review:`Review ${created.project}/urlcode.yaml and pin its revision explicitly (for example PROJECT_SHA256=${created.projectSha256}); re-review after any project change` });
+          }
+          break;
         case 'validate': {
-          const runtime = await createRuntime(values.project, { local:values.local, permissions, linkStore, origin:values.origin });
+          const runtime = await createRuntime(values.project, { ...hostOptions, local:values.local, permissions, linkStore, origin:values.origin });
           print({ event:'valid', dynamicLinks:runtime.testPlan().dynamicLinks, routes:runtime.count, version:runtime.version }); await runtime.close(); break;
         }
         case 'add':
           if (!arg) throw new ConfigError('Provide an HTTP(S) destination URL');
           print({ event:'added', path:await addRedirect(values.project,arg,values.alias) }); break;
         case 'test': {
-          const result = await runProjectTests(values.project, { log:print, permissions, linkStore, origin:values.origin });
+          const result = await runProjectTests(values.project, { ...hostOptions, log:print, permissions, linkStore, origin:values.origin });
           print(result); if (result.failed) process.exitCode = 1; break;
         }
         case 'doctor':
-          print({ node:process.version, sqlite:process.versions.sqlite, liveLinks:supportsConcurrentWal(process.versions.sqlite), platform:process.platform, architecture:process.arch, runtime:'node-process', functionSandbox:'quickjs-wasm', network:false, filesystem:false, providers:[], policies:Object.keys(policyRegistry), license:'Apache-2.0' }); break;
+          print({ node:process.version, sqlite:process.versions.sqlite, liveLinks:supportsConcurrentWal(process.versions.sqlite), platform:process.platform, architecture:process.arch, runtime:'node-process', functionSandbox:'quickjs-wasm', network:false, filesystem:false, guestNetwork:false, hostEgress:'revision-pinned-origin-grants', tooling:['recipes','examples','bulk-import','build-typescript','mcp','verify-provider'], providers:[], capabilityTargets:getCapabilities().targets, policies:Object.keys(policyRegistry), license:'Apache-2.0' }); break;
         case 'dev': case 'serve': {
           const port = Number(values.port);
           if (!/^\d+$/.test(values.port) || !Number.isInteger(port) || port < 0 || port > 65535) throw new ConfigError('Invalid port');
           if (command === 'serve' && values.local) throw new ConfigError('serve never reads local dotenv files');
-          const app = await startServer({ project:values.project, host:values.host, port,
+          const app = await startServer({ ...hostOptions, project:values.project, host:values.host, port,
             local:command === 'dev', watch:command === 'dev', origin:values.origin, permissions, linkStore,
             ...serverCapacity(values) });
           print({ event:'listening', address:app.address.address, port:app.address.port, mode:command, origin:app.origin });
+          serving = true;
           let stopping = false;
-          const stop = async () => { if (stopping) return; stopping = true; await app.close(); };
+          const stop = async () => { if (stopping) return; stopping = true; try { await app.close(); } finally { await operatorHost.close?.(); } };
           process.once('SIGINT',stop); process.once('SIGTERM',stop);
           break;
         }
@@ -182,4 +317,8 @@ try {
   const code = typeof error === 'object' && error !== null && 'code' in error && typeof error.code === 'string' ? error.code : undefined;
   const message = (error instanceof ConfigError || error instanceof HttpError) ? error.message : ((code !== undefined ? errorMessages[code] : undefined) || 'Operation failed; check project files, module dependencies and command options');
   process.stderr.write(JSON.stringify({ event:'error', message }) + '\n'); process.exitCode = 1;
+} finally {
+  if (!serving) {
+    try { await operatorHost.close?.(); } catch { process.stderr.write('Operator host cleanup failed\n'); process.exitCode = 1; }
+  }
 }

package/dist/client-address.js

@@ -57,7 +57,7 @@ function within(address        , { bytes, prefix }      )          {
   return true;
 }
 
-export function isTrustedProxy(address        , trusted        )          {
+function isTrustedProxy(address        , trusted        )          {
   return trusted.some(range => within(address, range));
 }
 

package/dist/compliance-rules/baseline.js

@@ -3,7 +3,7 @@ import { oshp, rfc9111, rfc9110, rfc6585, rfc9309, breach, management, active, f
 
 export const profile = 'baseline';
 
-export const securityHeaders            = {
+const securityHeaders            = {
   id: 'oshp/security-headers', title: 'Every active route carries a security headers profile', standard: oshp, severity: 'medium', appliesTo: 'route',
   check({ route, effective }) {
     if (!active(route) || effective.security) return [];
@@ -11,7 +11,7 @@ export const securityHeaders            = {
   },
 };
 
-export const hstsOrigin              = {
+const hstsOrigin              = {
   id: 'oshp/hsts-origin', title: 'HSTS is only reachable on an https origin', standard: { ...oshp, section: 'Strict-Transport-Security' }, severity: 'low', appliesTo: 'project',
   check({ plan, policies, origin }) {
     const emitting = plan.inventory.filter(route => active(route) && emittedSecurityHeaders(policies[route.path], plan.policies?.[route.path]).has('strict-transport-security'));
@@ -23,7 +23,7 @@ export const hstsOrigin              = {
   },
 };
 
-export const secretsCompression            = {
+const secretsCompression            = {
   id: 'breach/secrets-compression', title: 'Routes bound to secrets are never compressed', standard: breach, severity: 'high', appliesTo: 'route',
   check({ route, config, effective }) {
     if (!hasSecrets(config) || effective.compression?.allowWithSecrets !== true) return [];
@@ -31,7 +31,7 @@ export const secretsCompression            = {
   },
 };
 
-export const secretsNoStore            = {
+const secretsNoStore            = {
   id: 'rfc9111/secrets-no-store', title: 'Routes bound to secrets declare no-store or private caching', standard: { ...rfc9111, section: '5.2.2.5 no-store, 5.2.2.7 private' }, severity: 'medium', appliesTo: 'route',
   check({ route, config, effective }) {
     if (!hasSecrets(config)) return [];
@@ -47,7 +47,7 @@ export const secretsNoStore            = {
   },
 };
 
-export const cacheControlDeclared            = {
+const cacheControlDeclared            = {
   id: 'rfc9111/cache-control-declared', title: 'Every declared response states its Cache-Control', standard: rfc9111, severity: 'low', appliesTo: 'route',
   check({ route, config, effective }) {
     if (!active(route) || effective.cache) return [];
@@ -60,7 +60,7 @@ export const cacheControlDeclared            = {
   },
 };
 
-export const throttleFunctions            = {
+const throttleFunctions            = {
   id: 'rfc6585/throttle-functions', title: 'Function and middleware routes declare a request budget', standard: rfc6585, severity: 'medium', appliesTo: 'route',
   check({ route, effective }) {
     if (!active(route) || !functionLike(route) || effective.throttle) return [];
@@ -78,7 +78,7 @@ export const robots              = {
   },
 };
 
-export const expiredRoutes              = {
+const expiredRoutes              = {
   id: 'rfc9110/expired-routes', title: 'Expired routes still present in YAML', standard: { ...rfc9110, section: '15.5.11 410 Gone' }, severity: 'info', appliesTo: 'project',
   check({ plan }) {
     const expired = plan.inventory.filter(route => route.state === 'expired').map(route => route.path);
@@ -87,7 +87,7 @@ export const expiredRoutes              = {
   },
 };
 
-export const managementPrivate              = {
+const managementPrivate              = {
   id: 'ops/management-private', title: 'Management and probe listeners stay private', standard: management, severity: 'info', appliesTo: 'project',
   check({ document }) {
     if (document.dynamicLinks !== true) return [];

package/dist/compliance-rules/privacy.js

@@ -8,7 +8,7 @@ export const profile = 'privacy';
 // `host.includeCode`), because the runtime's log guarantees are settings of
 // the serving process, not of the project. An undeclared setting is reported
 // as unknown rather than assumed.
-export const requestLogMinimal              = {
+const requestLogMinimal              = {
   id: 'privacy/request-log-minimal', title: 'Request log records stay minimal', standard: monitoring, severity: 'medium', appliesTo: 'project',
   check({ host }) {
     if (host.requestLog === 'minimal') return [];
@@ -17,7 +17,7 @@ export const requestLogMinimal              = {
   },
 };
 
-export const linkEventsOff              = {
+const linkEventsOff              = {
   id: 'privacy/link-events-off', title: 'Link events stay off unless declared', standard: linkChannel, severity: 'medium', appliesTo: 'project',
   check({ document, host }) {
     if (document.dynamicLinks !== true || host.linkEvents === false) return [];
@@ -27,7 +27,7 @@ export const linkEventsOff              = {
   },
 };
 
-export const detailedParameters            = {
+const detailedParameters            = {
   id: 'privacy/detailed-log-parameters', title: 'No detailed logging on parameterised routes', standard: monitoring, severity: 'low', appliesTo: 'route',
   check({ route, config, host }) {
     if (host.requestLog !== 'detailed' || !active(route) || !((config.parameters?.length ?? 0) > 0)) return [];

package/dist/compliance-rules/strict.js

@@ -6,7 +6,7 @@ export const profile = 'strict';
 
 // The runtime caps a response at 16 KiB of headers; the security policy
 // bounds its own static headers at half of that so the handler keeps room.
-export const headerBudgetBytes = 8192;
+const headerBudgetBytes = 8192;
 
 export const csp            = {
   id: 'oshp/csp', title: 'Every active route emits a Content-Security-Policy', standard: { ...oshp, section: 'Content-Security-Policy' }, severity: 'medium', appliesTo: 'route',
@@ -16,7 +16,7 @@ export const csp            = {
   },
 };
 
-export const throttleAll            = {
+const throttleAll            = {
   id: 'rfc6585/throttle-all', title: 'Every active route declares a request budget', standard: rfc6585, severity: 'medium', appliesTo: 'route',
   check({ route, effective }) {
     if (!active(route) || functionLike(route) || effective.throttle) return [];
@@ -24,7 +24,7 @@ export const throttleAll            = {
   },
 };
 
-export const listsPinned            = {
+const listsPinned            = {
   id: 'agents/lists-pinned', title: 'Agent deny and allow lists are pinned to a revision', standard: agentLists, severity: 'low', appliesTo: 'route',
   check({ route, effective, policy }) {
     if (!active(route) || !effective.agents) return [];
@@ -39,7 +39,7 @@ export const listsPinned            = {
   },
 };
 
-export const redirectHttps            = {
+const redirectHttps            = {
   id: 'rfc9110/redirect-https', title: 'Redirect targets are https', standard: { ...rfc9110, section: '15.4 Redirection 3xx' }, severity: 'medium', appliesTo: 'route',
   check({ route, config }) {
     const url = config.redirect?.url;
@@ -48,7 +48,7 @@ export const redirectHttps            = {
   },
 };
 
-export const headerBudget            = {
+const headerBudget            = {
   id: 'http/header-budget', title: 'Declared response headers stay under the static budget', standard: { ...rfc9110, section: '5.4 Field Limits' }, severity: 'low', appliesTo: 'route',
   check({ route, config, effective, policy }) {
     if (!active(route)) return [];

package/dist/conditions.js

@@ -0,0 +1,88 @@
+import { assert, HttpError } from './errors.js';
+
+/** Bounded conjunction of exact string comparisons; no regex or implicit detection. */
+                             
+                                                                                                     
+                                 
+ 
+                                                                                                                                                                 
+const token = /^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/;
+export function normalizeMatch(match            )             {
+  assert(match && typeof match === 'object' && !Array.isArray(match), 'match must be an object');
+  assert(Object.keys(match).length > 0 && Object.keys(match).every(key => ['query','headers','cookies','host','method'].includes(key)), 'Unsupported or empty match');
+  const normalized             = {};
+  for (const group of ['query','headers','cookies']         ) if (match[group] !== undefined) {
+    assert(match[group] !== null && typeof match[group] === 'object' && !Array.isArray(match[group]), `match.${group} must be an object`);
+    const fields = Object.entries(match[group]);
+    assert(fields.length > 0 && fields.length <= 16, `match.${group} requires 1–16 entries`);
+    const values                        = Object.create(null)                         ;
+    for (const [name,value] of fields) {
+      const key = group === 'headers' ? name.toLowerCase() : name;
+      assert(token.test(key) && key.length <= 128 && !Object.hasOwn(values,key), `Invalid or duplicate match.${group} name`);
+      assert(typeof value === 'string' && value.length <= 1024 && !/[\u0000-\u001f\u007f]/.test(value), `Invalid match.${group} value`);
+      if (group === 'headers') assert(!['host','cookie','authorization','proxy-authorization','connection','transfer-encoding','content-length','keep-alive','proxy-authenticate','te','trailer','upgrade'].includes(key), 'Use match.host/cookies; credential and transport headers cannot be conditions');
+      if (group === 'cookies') assert(!/[;,\s"\\]/.test(value), 'Cookie conditions use unquoted wire values');
+      values[key] = value;
+    }
+    normalized[group] = values;
+  }
+  if (match.method !== undefined) {
+    assert(['GET','HEAD','POST','PUT','PATCH','DELETE','OPTIONS'].includes(match.method), 'Invalid match.method');
+    normalized.method = match.method;
+  }
+  if (match.host !== undefined) {
+    assert(typeof match.host === 'string' && match.host.length <= 255 && /^[a-z0-9.-]+(?::[0-9]{1,5})?$/i.test(match.host), 'match.host must be a literal host with optional port');
+    const url = new URL('https://' + match.host);
+    assert(url.host === match.host.toLowerCase(), 'match.host must be a canonical authority');
+    normalized.host = url.host;
+  }
+  assert(Object.keys(normalized).length > 0, 'Empty match');
+  return normalized;
+}
+function equalities(match            )                     {
+  const values = new Map               ();
+  for (const group of ['query','headers','cookies']         ) for (const [name,value] of Object.entries(match[group] ?? {})) values.set(`${group}:${name}`,value);
+  if (match.host) values.set('host',match.host);
+  if (match.method) values.set('method',match.method);
+  return values;
+}
+/** Cases must be disjoint: at least one shared fact must demand different values. */
+export function assertDisjointMatches(matches              )       {
+  assert(Array.isArray(matches) && matches.length >= 1 && matches.length <= 16, 'Conditional routes require 1–16 cases');
+  const facts = matches.map(normalizeMatch).map(equalities);
+  for (let i = 0; i < facts.length; i++) for (let j = i + 1; j < facts.length; j++) {
+    assert([...facts[i] ].some(([key,value]) => facts[j] .has(key) && facts[j] .get(key) !== value), `Conditional cases ${i + 1} and ${j + 1} overlap`);
+  }
+}
+export function matchesRoute(match            , request                  )          {
+  if (match.method && match.method !== request.method) return false;
+  // The operator's origin is authoritative, never forwarded/client Host text.
+  if (match.host && new URL(request.origin).host !== match.host) return false;
+  for (const [name,value] of Object.entries(match.query ?? {})) {
+    const actual = request.query.getAll(name);
+    if (actual.length > 1) throw new HttpError(400,'Duplicate condition query input');
+    if (actual.length !== 1 || actual[0] !== value) return false;
+  }
+  for (const [name,value] of Object.entries(match.headers ?? {})) {
+    if ((request.headerCounts?.[name] ?? 0) > 1) throw new HttpError(400,'Duplicate condition header input');
+    if (request.headers.get(name) !== value) return false;
+  }
+  if (match.cookies) {
+    const raw = request.headers.get('cookie') ?? '';
+    if (raw.length > 8192) throw new HttpError(400,'Cookie conditions exceed input limit');
+    const values = new Map                 ();
+    for (const part of raw.split(';')) {
+      const index = part.indexOf('=');
+      if (index < 0) continue;
+      const name = part.slice(0,index).trim(), value = part.slice(index + 1).trim();
+      if (!Object.hasOwn(match.cookies,name)) continue;
+      const entries = values.get(name) ?? []; entries.push(value); values.set(name,entries);
+    }
+    for (const [name,value] of Object.entries(match.cookies)) {
+      const actual = values.get(name) ?? [];
+      if (actual.length > 1) throw new HttpError(400,'Duplicate condition cookie input');
+      if (actual.length !== 1 || actual[0] !== value) return false;
+    }
+  }
+  return true;
+}