@jimhoyd/urlcode 0.3.0 → 0.4.0-alpha.1

package/dist/capabilities.js

@@ -0,0 +1,208 @@
+import { hasExtensionPolicy } from './extensions.js';
+import { ConfigError } from './errors.js';
+import { effectivePolicies, registry } from './policies.js';
+                                                                                                                                                                                          
+
+export const capabilityTargets = ['self-hosted', 'cloudflare', 'aws', 'vercel']         ;
+                                                                
+                                                                          
+export const capabilityNames = ['extension','policies.extensions','proxy', 'signals', 'conditional', 'conditions', 'redirect', 'respond', 'page', 'static', 'download', 'function', 'middleware', 'link', 'dynamicLinks', 'parameters', 'methods', 'enabled', 'expires', 'request.body', 'response.headers', 'bindings', 'policies.agents', 'policies.security', 'policies.cache', 'policies.compression', 'policies.throttle']         ;
+                                                            
+                                                                                  
+                                                                                                              
+                                      
+                                                                                                                        
+                                             
+ 
+                                    
+            
+                                                                                         
+                                                                                                                 
+ 
+
+export function normalizeCapabilityTarget(target        )                   {
+  if (target === 'node') return 'self-hosted';
+  if ((capabilityTargets                     ).includes(target)) return target                    ;
+  throw new ConfigError('Unknown capability target; use self-hosted, cloudflare, aws or vercel');
+}
+const internalTarget = (target                  )             => target === 'self-hosted' ? 'node' : target;
+const deployment = (target                  )                                    => target === 'self-hosted' ? 'local-runtime' : 'unverified';
+const policyNames = Object.keys(registry)                ;
+
+// Policy modules remain the authority for configuration-dependent support.
+function decision(capability                , target                  , policies                    )                     {
+  if(capability==='extension'||capability==='policies.extensions')return target==='cloudflare'?{support:'refused',reason:'Operator extensions have no Worker artifact lowering'}:{support:'native',reason:'Requires an operator registry and exact revision pin at activation'};
+  const policy = policyNames.find(name => capability === `policies.${name}`);
+  if (policy) {
+    if (policy === 'throttle' && !policies && (target === 'aws' || target === 'vercel')) {
+      return { support: 'conditional', reason: 'Only partition: route is implemented; counters are per instance' };
+    }
+    const module               = registry[policy];
+    const support                    = (module.targets(policies?.[policy])                                              )[internalTarget(target)] ?? 'unknown';
+    return { support, reason: support === 'refused' ? `${capability} cannot be compiled or enforced by this target`
+      : support === 'delegated' ? 'Delegated to the provider; exact compression settings and deployment behavior are unverified'
+      : support === 'unknown' ? 'No implementation evidence for this target'
+      : 'Implemented by the existing policy module; configuration validation still applies' };
+  }
+  if (target !== 'self-hosted') {
+    const reason = ['proxy','signals'].includes(capability) ? 'bounded egress currently requires the self-hosted Node lifecycle'
+      : target === 'cloudflare' && ['conditional','conditions'].includes(capability) ? 'conditional routing has no Worker artifact lowering yet'
+      : capability === 'function' ? 'isolated functions need worker threads and the WASM engine'
+      : capability === 'middleware' ? 'declares middleware that needs the sandbox'
+      : capability === 'link' || capability === 'dynamicLinks' ? 'stored live links need a durable writable store'
+      : target === 'cloudflare' && ['page', 'static', 'download'].includes(capability) ? 'assets need a static-asset binding'
+      : target === 'cloudflare' && capability === 'bindings' ? 'env and secret bindings would have to be baked into the artifact'
+      : undefined;
+    if (reason) return { support: 'refused', reason };
+  }
+  return { support: target === 'cloudflare' ? 'compiled' : 'native', reason: target === 'self-hosted'
+    ? 'Implemented and tested in the local runtime'
+    : 'Implemented with local adapter tests; provider deployment unverified; transport normalization limits apply' };
+}
+
+/** Catalog, not a claim that every configuration or provider deployment works. */
+export function getCapabilities(target         )                    {
+  const selected = target === undefined ? [...capabilityTargets] : [normalizeCapabilityTarget(target)];
+  return { format: 1, targets: selected.map(target => ({ target, deployment: deployment(target) })),
+    capabilities: capabilityNames.map(capability => ({ capability,
+      targets: Object.fromEntries(selected.map(target => [target, decision(capability, target)])) })) };
+}
+
+/** A safe projection shared by declaration preflight and the existing compiled IR. No values escape. */
+export function routeCapabilities(route                             , document                 )                   {
+  const result                   = [];
+  if(route.extension)result.push('extension');
+  if(hasExtensionPolicy(document,route))result.push('policies.extensions');
+  if(route.proxy)result.push('proxy');
+  if(route.signals?.length)result.push('signals');
+  if (route.match) result.push('conditions');
+  if (route.conditional) {
+    result.push('conditional');
+    for (const branch of [...route.conditional.cases, ...(route.conditional.fallback ? [route.conditional.fallback] : [])]) {
+      if (branch.redirect && !result.includes('redirect')) result.push('redirect');
+      if (branch.respond && !result.includes('respond')) result.push('respond');
+    }
+  }
+  for (const name of ['redirect', 'respond', 'page', 'static', 'download', 'function', 'link']         ) if (route[name]) result.push(name);
+  if (route.middleware?.length) result.push('middleware');
+  if (route.parameters?.length) result.push('parameters');
+  // Defaults are still semantics required by every route.
+  result.push('methods', 'enabled');
+  if (route.expires) result.push('expires');
+  if (route.request?.body) result.push('request.body');
+  if (Object.keys(route.response?.headers ?? {}).length) result.push('response.headers');
+  if (Object.keys(route.env ?? {}).length || Object.keys(route.secrets ?? {}).length) result.push('bindings');
+  const policies = effectivePolicies(document, route);
+  for (const name of policyNames) if (policies[name]) result.push(`policies.${name}`);
+  return result;
+}
+
+function analyze(document                 , routes                                                          , requestedTarget        )                      {
+  const target = normalizeCapabilityTarget(requestedTarget);
+  const requirements                          = [];
+  if (Object.keys(document.extensions??{}).length) requirements.push({path:'(project)',capability:'extension',...decision('extension',target)});
+  if (document.dynamicLinks) requirements.push({ path: '(project)', capability: 'dynamicLinks', ...decision('dynamicLinks', target) });
+  for (const [path, route] of routes) {
+    const policies = effectivePolicies(document, route);
+    for (const capability of routeCapabilities(route, document)) requirements.push({ path, capability, ...decision(capability, target, policies) });
+  }
+  const issues = requirements.filter(item => item.support === 'refused' || item.support === 'unknown' || item.support === 'conditional');
+  return { target, deployment: deployment(target), compatible: issues.length === 0, requirements, issues };
+}
+
+/** Preflight only: call after schema validation/site expansion, before resolving bindings. */
+export function analyzeProjectCapabilities(loaded                , target        )                      {
+  return analyze(loaded.document, Object.entries(loaded.routes), target);
+}
+
+/** Analyze normalized route semantics without exporting validators, resources or resolved secrets. */
+export function analyzeCompiledCapabilities(document                 , compiled                    , target        )                      {
+  function* entries()                                              {
+    for (const route of compiled.exact.values()) yield [route.pattern, route];
+    for (const bucket of compiled.byLength.values()) for (const route of bucket) yield [route.pattern, route];
+    for (const route of compiled.mounts) yield [route.pattern, route];
+  }
+  return analyze(document, entries(), target);
+}
+
+export function assertTargetCompatibility(report                     )       {
+  if (report.compatible) return;
+  throw new ConfigError(`Cannot activate/build project for ${report.target}:\n` + report.issues.map(issue =>
+    `${issue.path}\n  capability: ${issue.capability}\n  unsupported by target: ${report.target}\n  ${issue.reason}`).join('\n'));
+}
+
+export function formatCapabilities(catalog                   )         {
+  return ['Capability'.padEnd(24) + catalog.targets.map(({ target }) => target.padEnd(16)).join(''),
+    ...catalog.capabilities.map(row => row.capability.padEnd(24) + catalog.targets.map(({ target }) => (row.targets[target]?.support ?? 'unknown').padEnd(16)).join('')),
+    '', 'Provider deployments: unverified. native/compiled describe local implementation tests.',
+    'conditional requires configuration analysis; delegated relies on the provider (unverified).',
+    'See docs/CAPABILITIES.md for transport limits and programmatic project analysis.', ''].join('\n');
+}
+
+                                                                                                                            
+                                   
+                       
+                  
+                                                                                                       
+                   
+                        
+                                                                                     
+                   
+ 
+const policyDetail = (name        , summary        , constraints          )                   => ({ kind: 'policy', summary, schema: [`policies.${name}`], constraints:
+  ['Route policies merge over project/profile policies; `false` removes one', ...constraints], grants: [] });
+/** Static facts about each catalog entry. Per-target support stays in `decision`; recipe and cookbook usage is scanned by `getCapability`. */
+export const capabilityDetails                                           = {
+  extension: { kind: 'project', summary: 'Route delegated to a versioned logical extension declared under top-level `extensions`.', schema: ['extension', 'extensions'],
+    constraints: ['Extension names match ^[a-z][a-z0-9-]{0,63}$; at most 16 project extensions', 'Each declaration needs `version: "1"` and a `config` object', 'Never loads project code; the registry is operator host code'],
+    grants: ['Operator extension registry loaded with --host-file, pinned to the exact project revision'] },
+  'policies.extensions': { kind: 'policy', summary: 'Extension-provided policy attached through `policies.extensions`.', schema: ['policies.extensions'],
+    constraints: ['Names must reference declared top-level `extensions`', 'Refused on Cloudflare: no Worker artifact lowering'], grants: ['Operator extension registry loaded with --host-file'] },
+  proxy: { kind: 'egress', summary: 'Bounded HTTPS proxy to one declared upstream URL.', schema: ['proxy'],
+    constraints: ['`url` at most 8192 characters; headers at most 32, string values at most 4096 characters or `{secret}` references', 'Forwarded query keys and request headers are explicit allowlists (at most 32 each)', 'Self-hosted only: bounded egress requires the Node lifecycle'],
+    grants: ['External operator policy (--policy) with a revision-pinned exact-origin grant for the route', 'Secret bindings referenced by headers must be granted separately'] },
+  signals: { kind: 'egress', summary: 'Fire-and-forget HTTPS notifications after a route reply.', schema: ['signals'],
+    constraints: ['1 to 8 signals per route; each `url` at most 8192 characters with at most 32 headers', 'Self-hosted only: bounded egress requires the Node lifecycle'],
+    grants: ['External operator policy (--policy) with a revision-pinned exact-origin grant per signal destination'] },
+  conditional: { kind: 'routing', summary: 'Disjoint request-condition cases selecting a redirect or respond reply.', schema: ['conditional'],
+    constraints: ['1 to 16 cases plus an optional fallback; cases must be disjoint', 'Each case replies with `redirect` or `respond`, never a handler needing assets or code', 'Refused on Cloudflare until artifact lowering exists'], grants: [] },
+  conditions: { kind: 'routing', summary: 'Route-level `match` on query, headers or cookies.', schema: ['match'],
+    constraints: ['At least one of query, headers, cookies; at most 16 entries each with values up to 1024 characters', 'Refused on Cloudflare until artifact lowering exists'], grants: [] },
+  redirect: { kind: 'handler', summary: 'HTTP redirect to a URL template with optional query passing or mapping.', schema: ['redirect'],
+    constraints: ['`url` required, at most 8192 characters', 'status one of 301, 302, 303, 307, 308', '`query.pass` is `false` or an explicit list; `query.map` maps from path, query or header inputs'], grants: [] },
+  respond: { kind: 'handler', summary: 'Static text or JSON reply with a status code.', schema: ['respond'],
+    constraints: ['status 200 to 599', '`text` at most 1 MiB; `text` and `json` are mutually exclusive'], grants: [] },
+  page: { kind: 'handler', summary: 'Serve one HTML file from the project.', schema: ['page'],
+    constraints: ['`file` required, project-relative, 1 to 1024 characters', 'Fixed `cacheControl` choices; `contentType` must be a media type', 'Refused on Cloudflare: assets need a static-asset binding'], grants: [] },
+  static: { kind: 'handler', summary: 'Serve a project directory as a static mount.', schema: ['static'],
+    constraints: ['`directory` required, project-relative, 1 to 1024 characters; `index` must be a .html name', 'Refused on Cloudflare: assets need a static-asset binding'], grants: [] },
+  download: { kind: 'handler', summary: 'Serve a project file as an attachment.', schema: ['download'],
+    constraints: ['`file` required, project-relative, 1 to 1024 characters; `filename` at most 255 characters', 'Refused on Cloudflare: assets need a static-asset binding'], grants: [] },
+  function: { kind: 'handler', summary: 'Sandboxed project function producing the reply.', schema: ['function'],
+    constraints: ['`source` at most 1024 characters, project-relative; `export` defaults to the default export', '`args` are literals, `{from: path|query|header}` inputs or `{env}` references', 'Self-hosted only: needs worker threads and the WASM engine; no network or filesystem in the guest'], grants: [] },
+  middleware: { kind: 'middleware', summary: 'Sandboxed modules run before the handler.', schema: ['middleware'],
+    constraints: ['At most 16 entries, each with a project-relative `source` and optional `export`', 'Self-hosted only: needs the sandbox'], grants: [] },
+  link: { kind: 'handler', summary: 'Live stored short link resolved from an operator collection.', schema: ['link', 'dynamicLinks'],
+    constraints: ['`collection` matches ^[A-Za-z][A-Za-z0-9_-]{0,63}$; `code` comes from a path parameter', 'Entry urlcode.yaml must set `dynamicLinks: true`', 'Self-hosted only: needs a durable writable store'],
+    grants: ['--link-store collection=/absolute/file binding owned by the operator'] },
+  dynamicLinks: { kind: 'project', summary: 'Entry-point opt-in for live stored-link routes.', schema: ['dynamicLinks'],
+    constraints: ['Entry urlcode.yaml only; ignored defaults to false', 'Does not enable guest storage or management access'], grants: ['--link-store binding when any link route is declared'] },
+  parameters: { kind: 'request', summary: 'Validated path, query and header inputs.', schema: ['parameters'],
+    constraints: ['Names match ^[A-Za-z_][A-Za-z0-9_-]*$ and `in` is path, query or header', 'Schema types: string, integer, number, boolean, array; length bounds up to 8192'], grants: [] },
+  methods: { kind: 'routing', summary: 'Allowed HTTP methods; defaults to GET and HEAD.', schema: ['methods'],
+    constraints: ['Unique subset of GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS with at least one entry'], grants: [] },
+  enabled: { kind: 'routing', summary: 'Route on/off switch; disabled routes are still validated.', schema: ['enabled'], constraints: ['Boolean; defaults to true'], grants: [] },
+  expires: { kind: 'routing', summary: 'Timestamp after which the route stops matching.', schema: ['expires'], constraints: ['UTC timestamp YYYY-MM-DDTHH:MM:SS[.mmm]Z; expired routes are still validated'], grants: [] },
+  'request.body': { kind: 'request', summary: 'Request body admission limits and format.', schema: ['request.body'],
+    constraints: ['`maxBytes` 0 to 1048576; up to 16 lowercase `contentTypes`', '`format` text or json'], grants: [] },
+  'response.headers': { kind: 'request', summary: 'Static response headers added to the reply.', schema: ['response.headers'],
+    constraints: ['At most 64 headers; values up to 4096 characters or lists of at most 16', 'Cloudflare coalesces duplicate headers'], grants: [] },
+  bindings: { kind: 'binding', summary: 'Route `env` literals/references and `secrets` references.', schema: ['env', 'secrets'],
+    constraints: ['Names match ^[A-Za-z_][A-Za-z0-9_]*$', '`env` entries are `{value}` literals or `{env}` references; `secrets` entries are `{secret}` references', 'Refused on Cloudflare: bindings would be baked into the artifact'],
+    grants: ['External operator policy (--policy) granting each referenced env/secret name; values never enter the project'] },
+  'policies.agents': policyDetail('agents', 'Agent allow/deny rules by bundled list name.', ['List names come from the bundled agent lists']),
+  'policies.security': policyDetail('security', 'Security response headers.', ['Fixed header set with validated values']),
+  'policies.cache': policyDetail('cache', 'Host cache strategy for route replies.', ['Refused on Cloudflare: no cache enforcement in the artifact']),
+  'policies.compression': policyDetail('compression', 'Response compression.', ['Delegated on AWS, Vercel and Cloudflare; exact settings are unverified']),
+  'policies.throttle': policyDetail('throttle', 'Per-instance request quota per window.', ['`quota` and `window` are required', 'Only `partition: route` is implemented on serverless targets; `client` is refused there; counters are per instance']),
+};

package/dist/capability-query.js

@@ -0,0 +1,72 @@
+import {readdirSync,readFileSync,statSync} from 'node:fs';
+import {fileURLToPath} from 'node:url';
+import {parse} from 'yaml';
+import {capabilityDetails,capabilityNames,capabilityTargets,formatCapabilities,getCapabilities,routeCapabilities} from './capabilities.js';
+                                                                                                           
+import {ConfigError} from './errors.js';
+import {getSchemaFragment} from './schema-query.js';
+                                                      
+                                                            
+
+                                                              
+                                                           
+                               
+                                   
+                                                      
+                                                    
+                            
+                             
+ 
+const root=(...parts         )=>fileURLToPath(new URL('../'+parts.join('/'),import.meta.url));
+const object=(value        )                                =>value!==null&&typeof value==='object'&&!Array.isArray(value);
+function yamlFiles(directory       )          {
+  const out         =[];
+  for(const entry of readdirSync(directory,{withFileTypes:true}).sort((a,b)=>a.name.localeCompare(b.name))) {
+    if(entry.name.startsWith('.')||entry.name==='node_modules')continue;
+    const file=directory+'/'+entry.name;
+    if(entry.isDirectory())out.push(...yamlFiles(file));else if(/\.ya?ml$/.test(entry.name))out.push(file);
+  }
+  return out;
+}
+/** Bundled examples are fixed package content; they are read as data and never validated or activated here. */
+function usage(base       ,files         ,name               )                   {
+  const result                  =[];
+  for(const file of files) {
+    let document        ;try{document=parse(readFileSync(file,'utf8'));}catch{continue;}
+    if(!object(document))continue;
+    const routes         =[];
+    if(name==='dynamicLinks'&&document.dynamicLinks===true)routes.push('(project)');
+    if(name==='extension'&&object(document.extensions)&&Object.keys(document.extensions).length)routes.push('(project)');
+    for(const [path,route] of Object.entries(object(document.routes)?document.routes:{})) {
+      if(!object(route))continue;
+      try{if(routeCapabilities(route               ,document                              ).includes(name))routes.push(path);}catch{/* unparsable example route: not a use */}
+    }
+    if(routes.length)result.push({file:file.slice(base.length+1),routes});
+  }
+  return result;
+}
+export function capabilityNameList()                           {return capabilityNames;}
+/** One catalog entry with its schema fragments and bundled usage. No project, credentials or network are read. */
+export function getCapability(name       )                 {
+  if(typeof name!=='string'||!(capabilityNames                     ).includes(name))throw new ConfigError('Unknown capability; valid names: '+capabilityNames.join(', '));
+  const capability=name                  ,detail=capabilityDetails[capability];
+  const catalog=getCapabilities();
+  const targets=Object.fromEntries(capabilityTargets.map(target=>[target,catalog.capabilities.find(row=>row.capability===capability) .targets[target] ]))                                               ;
+  const refused=capabilityTargets.flatMap(target=>targets[target].support==='refused'?[{target,reason:targets[target].reason}]:[]);
+  const recipesRoot=root('recipes'),cookbookRoot=root('examples','cookbook');
+  const recipes=usage(recipesRoot,readdirSync(recipesRoot,{withFileTypes:true}).filter(entry=>entry.isDirectory()).map(entry=>recipesRoot+'/'+entry.name+'/urlcode.yaml').filter(file=>{try{return statSync(file).isFile();}catch{return false;}}),capability);
+  const cookbook=usage(cookbookRoot,yamlFiles(cookbookRoot),capability);
+  return {format:1,name:capability,...detail,schemaFragments:detail.schema.map(getSchemaFragment),targets,refused,recipes,cookbook};
+}
+export function formatCapability(entry                )        {
+  const list=(items         )=>items.length?items.map(item=>'  - '+item):['  (none)'];
+  const usageLines=(items                  )=>items.length?items.map(item=>`  - ${item.file}: ${item.routes.join(', ')}`):['  (none)'];
+  return [`${entry.name} (${entry.kind})`,entry.summary,'','Schema: '+entry.schema.join(', ')+'  (urlcode schema <path>)',
+    ...entry.schemaFragments.map(fragment=>`  ${fragment.pointer}\n`+JSON.stringify(fragment.schema,null,2).split('\n').map(line=>'    '+line).join('\n')),
+    '','Constraints:',...list(entry.constraints),'','Required grants:',...list(entry.grants),'','Targets:',
+    ...capabilityTargets.map(target=>`  ${target.padEnd(12)}${entry.targets[target].support.padEnd(12)}${entry.targets[target].reason}`),
+    '','Unsupported:',...(entry.refused.length?entry.refused.map(item=>`  - ${item.target}: ${item.reason}`):['  (none)']),
+    '','Recipes:',...usageLines(entry.recipes),'','Cookbook routes:',...usageLines(entry.cookbook),
+    '','Provider deployments: unverified; see docs/CAPABILITIES.md.',''].join('\n');
+}
+export {formatCapabilities};

package/dist/catalog.js

@@ -0,0 +1,105 @@
+import {readFile} from 'node:fs/promises';
+import {fileURLToPath} from 'node:url';
+import Ajv from 'ajv/dist/2020.js';
+import {loadDocument,parseYaml} from './config.js';
+import {applySite} from './site.js';
+import {analyzeProjectCapabilities,capabilityTargets} from './capabilities.js';
+                                                                       
+import {readAuthoringFile,authoringPath} from './authoring-files.js';
+import {assert} from './errors.js';
+
+/**
+ * The metadata shape shared by recipes/NAME/recipe.yaml and examples/NAME/example.yaml
+ * (schemas/recipe.schema.json). The catalog entries are fixed package data: names
+ * come from a list in code, never from a directory scan, a registry or an argument.
+ */
+                                                                         
+                                                           
+                                  
+                                                                                              
+                                                                                             
+                                                                                                   
+                                                                                
+                                                                       
+ 
+/** The fields the capability preflight determines; `npm run check` refuses hand-written values that differ. */
+                                                                                                                                    
+                                                                                                    
+
+const schemaFile=fileURLToPath(new URL('../schemas/recipe.schema.json',import.meta.url));
+                                                                                                      
+let validator                     ;
+async function validate()                     {
+  if(!validator){
+    const schema         =JSON.parse(await readFile(schemaFile,'utf8'));
+    validator=new Ajv.default({allErrors:false,strict:true,strictRequired:false}).compile(schema          )             ;
+  }
+  return validator;
+}
+export const metadataFiles={recipe:'recipe.yaml',example:'example.yaml'}         ;
+/** Reads and schema-validates one metadata file; the id must equal the directory name, and file lists stay authoring-safe paths. */
+export async function readMetadata(root        ,id        ,file                              )                           {
+  const text=(await readAuthoringFile(root,file,65536)).toString('utf8');
+  const value         =parseYaml(text),valid=await validate();
+  const first=valid(value)?undefined:valid.errors?.[0];
+  assert(!first,`${id}/${file} does not match schemas/recipe.schema.json: ${first?.instancePath||'/'} ${first?.message??''}`);
+  const metadata=value                   ;
+  assert(metadata.id===id,`${id}/${file} declares id ${metadata.id}`);
+  for(const path of metadata.files){try{authoringPath(path);}catch{assert(false,`${id}/${file} lists ${path}, which is not an authoring-safe path`);}}
+  return metadata;
+}
+const strength                              ={compatible:0,conditional:1,unknown:2,refused:3};
+/** Preflight only: loads the project, expands site routes and asks the capability analysis for every target. No bindings, code or activation. */
+export async function deriveMetadata(root        )                           {
+  const loaded=await loadDocument(root);await applySite(loaded,{});
+  const capabilities=new Set                ();
+  const targets={}                                          ;
+  for(const target of capabilityTargets){
+    const report=analyzeProjectCapabilities(loaded,target);
+    let verdict               ='compatible';
+    for(const issue of report.issues){const support=issue.support                 ;if(strength[support]>strength[verdict])verdict=support;}
+    targets[target]=verdict;
+    if(target==='self-hosted')for(const requirement of report.requirements)capabilities.add(requirement.capability);
+  }
+  return {capabilities:[...capabilities].sort(),targets,routes:Object.keys(loaded.routes).length};
+}
+/** Reports where hand-written derived fields disagree with the preflight; empty means consistent. */
+export function derivedDifferences(metadata                 ,derived                 )           {
+  const problems          =[];
+  const same=(a         ,b         )=>JSON.stringify(a)===JSON.stringify(b);
+  if(!same(metadata.capabilities??[],derived.capabilities))problems.push(`capabilities should be [${derived.capabilities.join(', ')}]`);
+  for(const target of capabilityTargets)if(metadata.targets?.[target]!==derived.targets[target])problems.push(`targets.${target} should be ${derived.targets[target]}`);
+  if(metadata.routes!==derived.routes)problems.push(`routes should be ${derived.routes}`);
+  return problems;
+}
+const stopWords=new Set(['a','an','and','the','with','for','to','of','in','on','that','my','i','want','need']);
+export function searchTerms(text        )           {
+  assert(typeof text==='string' && text.length<=256,'Search text must be at most 256 characters');
+  const words=text.toLowerCase().split(/[^a-z0-9.-]+/).filter(Boolean);
+  const terms=[...new Set(words.filter(word=>!stopWords.has(word)||words.length===1))];
+  assert(terms.length>0 && terms.length<=16,'Provide one to sixteen search words');
+  return terms;
+}
+/**
+ * Local search over id, description, tags and capabilities: every term must match
+ * somewhere; the score prefers whole-tag and id hits over description substrings.
+ * Ties keep catalog order, so the smallest entry wins when a caller sorts by size first.
+ */
+export function searchMetadata                           (entries              ,text        ,extraText                      =()=>[])                 {
+  const terms=searchTerms(text),hits                =[];
+  for(const entry of entries){
+    const tags=entry.tags.map(tag=>tag.toLowerCase()),capabilities=(entry.capabilities??[]).map(name=>name.toLowerCase());
+    const id=entry.id.toLowerCase(),description=entry.description.toLowerCase(),extra=extraText(entry).map(value=>value.toLowerCase());
+    let score=0;const matched          =[];
+    for(const term of terms){
+      let best=0;
+      if(id===term || tags.includes(term) || capabilities.includes(term))best=4;
+      else if(id.includes(term) || tags.some(tag=>tag.includes(term)) || capabilities.some(name=>name.includes(term)))best=2;
+      else if(description.includes(term) || extra.some(value=>value.includes(term)))best=1;
+      if(best===0){score=0;break;}
+      score+=best;matched.push(term);
+    }
+    if(score>0)hits.push({entry,score,matched});
+  }
+  return hits.sort((a,b)=>b.score-a.score);
+}