#!/usr/bin/env tsx /** * Codegen: emit a plain-data lookup `COLLECTION_ARRAY_METHODS` — for every * COLLECTION-mode capability, the set of its array-returning (non-subscription) * method names (the methods the hub fans across providers via `concatCollection` * and the child-side dispatcher must gracefully skip when a provider omits them). * * WHY THIS EXISTS (runner footprint, D28): the addon-runner needs ONLY this * predicate — "is (cap, method) a collection array method?" — to reproduce the * hub's graceful-skip in `child-cap-dispatch`. Previously it imported * `ALL_CAPABILITY_DEFINITIONS` + `isCollectionArrayMethod` from the root barrel, * which eagerly constructs the Zod schema graph of all ~266 caps (+~144MB RSS * PER forked runner). This static map carries the ANSWER (cap name → method * names), computed at codegen time by running the REAL predicate, so the runner * imports plain data (zero Zod, a few KB) via the lightweight `@camstack/types/addon` * entry instead of the schema barrel. * * Authoritative: the map is derived by executing the real * `isCollectionArrayMethod` over `ALL_CAPABILITY_DEFINITIONS` — never * hand-maintained — so it cannot drift from the cap definitions. * * Output: `packages/types/src/generated/collection-array-methods.ts` * * Run manually: npx tsx scripts/generate-collection-array-methods.ts */ import * as fs from 'node:fs' import * as path from 'node:path' import { fileURLToPath } from 'node:url' import { isCollectionArrayMethod } from '../packages/types/src/capabilities/cap-router-predicates.ts' import { expandCapMethods } from '../packages/types/src/capabilities/capability-definition.ts' import { ALL_CAPABILITY_DEFINITIONS } from '../packages/types/src/generated/capability-router-map.ts' import { writeIfChanged } from './codegen-write.ts' const __dirname = path.dirname(fileURLToPath(import.meta.url)) const ROOT = path.resolve(__dirname, '..') const OUTPUT = path.join(ROOT, 'packages/types/src/generated/collection-array-methods.ts') function quote(s: string): string { return JSON.stringify(s) } async function main(): Promise { const rows: Array<{ cap: string; methods: string[] }> = [] for (const def of ALL_CAPABILITY_DEFINITIONS) { if (def.mode !== 'collection') continue const methodNames = Object.keys(expandCapMethods(def)) .filter((m) => isCollectionArrayMethod(def, m)) .sort() if (methodNames.length > 0) rows.push({ cap: def.name, methods: methodNames }) } rows.sort((a, b) => a.cap.localeCompare(b.cap)) // A method a provider may legitimately NOT implement. Same reason the array // table exists: the absence is only observable on the CHILD (a UDS proxy // fabricates a callable for every property), and the child must not import // the schema barrel to find out. const optionalRows: Array<{ cap: string; methods: string[] }> = [] for (const def of ALL_CAPABILITY_DEFINITIONS) { const expanded = expandCapMethods(def) const methodNames = Object.keys(expanded) .filter((m) => { const schema: unknown = expanded[m] return ( typeof schema === 'object' && schema !== null && (schema as { providerOptional?: unknown }).providerOptional === true ) }) .sort() if (methodNames.length > 0) optionalRows.push({ cap: def.name, methods: methodNames }) } optionalRows.sort((a, b) => a.cap.localeCompare(b.cap)) const totalOptional = optionalRows.reduce((n, r) => n + r.methods.length, 0) const optionalEntries = optionalRows .map((r) => ` ${quote(r.cap)}: [${r.methods.map(quote).join(', ')}],`) .join('\n') const totalMethods = rows.reduce((n, r) => n + r.methods.length, 0) const entries = rows .map((r) => ` ${quote(r.cap)}: [${r.methods.map(quote).join(', ')}],`) .join('\n') const banner = `/** * AUTO-GENERATED by scripts/generate-collection-array-methods.ts — DO NOT EDIT. * * For every COLLECTION-mode capability, the array-returning (non-subscription) * method names the hub fans across providers. The addon-runner uses this to * reproduce the hub's graceful "provider skips an unimplemented collection * method" behaviour (see child-cap-dispatch) WITHOUT importing the schema * barrel (\`ALL_CAPABILITY_DEFINITIONS\`), which would cost ~144MB RSS per * forked runner. See docs/decisions/adr-0028.md. * * Coverage: ${rows.length} collection caps, ${totalMethods} array methods. */ ` const body = `export const COLLECTION_ARRAY_METHODS: Readonly> = Object.freeze({ ${entries} } as const) /** * True when \`method\` on cap \`capName\` is a COLLECTION cap's array-returning * (non-subscription) method — the schema-free runner-side equivalent of * \`isCollectionArrayMethod(capDefsByName.get(capName), method)\`. */ export function isCollectionArrayMethodName(capName: string, method: string): boolean { const methods = COLLECTION_ARRAY_METHODS[capName] return methods !== undefined && methods.includes(method) } /** * Per capability, the methods declared \`optionalMethod\` — the ones whose * ABSENCE on a provider is a fact about that provider, not a bug. * * Coverage: ${optionalRows.length} caps, ${totalOptional} methods. */ export const PROVIDER_OPTIONAL_METHODS: Readonly> = Object.freeze({ ${optionalEntries} } as const) /** * True when \`method\` on cap \`capName\` is declared \`optionalMethod\`. * * \`providerOptional\` used to be a TYPE-only flag: it made the method optional * on \`InferProvider\` and nothing read it at runtime, so a source that * honestly did not implement one produced \`INTERNAL_SERVER_ERROR\` — the same * signature as a method somebody forgot. Measured on the live hub 2026-09-24: * \`videoclips.getPlaybackOptions\` at the recorder's \`analytics\` source, a * time WINDOW with no file behind it, threw on every player open. */ export function isProviderOptionalMethodName(capName: string, method: string): boolean { const methods = PROVIDER_OPTIONAL_METHODS[capName] return methods !== undefined && methods.includes(method) } ` fs.mkdirSync(path.dirname(OUTPUT), { recursive: true }) writeIfChanged(OUTPUT, banner + body) // eslint-disable-next-line no-console console.log( `Wrote ${rows.length} collection caps / ${totalMethods} array methods, ` + `${optionalRows.length} caps / ${totalOptional} provider-optional methods → ${path.relative(ROOT, OUTPUT)}`, ) } main().catch((err: unknown) => { // eslint-disable-next-line no-console console.error(err) process.exit(1) })