#!/usr/bin/env tsx /** * Codegen: emit the capability FACTS two addons read at runtime, as plain data * on `@camstack/types/addon` — so neither imports `ALL_CAPABILITY_DEFINITIONS`. * * WHY THIS EXISTS (addon footprint, D28): an addon bundles `@camstack/types`. * Reaching `ALL_CAPABILITY_DEFINITIONS` from addon server code inlines the Zod * schema graph of every capability (~11,000 builder calls) and evaluates it at * load: +~100 MB of private heap in each runner that holds the addon * (`addon-post-analysis` x2 runners, `addon-osd-manager`). The facts they need * are tiny: * * - `CAP_ADVANCE_FIELDS` cap name -> the numeric state field whose strict * advance derives the cap's one-shot event (read from each cap's own * `events[*].fromState: { field, on: 'advance' }`). Consumer: the sensor * transition gate (`addon-post-analysis`). * - `CAP_STATE_LEAVES` cap name -> the bindable scalar leaves of its * runtime state (`stateLeavesOf` in `scripts/lib/cap-state-leaves.ts`, * Zod introspection run here so no runner pays for it). * * - `CAP_METHOD_TIMEOUTS_MS` cap name -> method -> the declared `timeoutMs`. * A forked addon's outbound `ctx.api` call is bounded on the CHILD's socket, * which has no cap definitions; without this table every call it makes ends * at the 60 s socket default whatever the method declared. * * All are computed by running the REAL code over `ALL_CAPABILITY_DEFINITIONS` * here, so they cannot drift from the cap definitions; * `packages/types/src/__tests__/addon-cap-facts.spec.ts` proves equality. * * Output: `packages/types/src/generated/addon-cap-facts.ts` * * Run manually: npx tsx scripts/generate-addon-cap-facts.ts */ import * as path from 'node:path' import { fileURLToPath } from 'node:url' import { ALL_CAPABILITY_DEFINITIONS } from '../packages/types/src/generated/capability-router-map.ts' import { stateLeavesOf } from './lib/cap-state-leaves.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/addon-cap-facts.ts') function main(): void { const advance: Array = [] const leaves: Array = [] const timeouts: Array = [] let leafCount = 0 const names = [...ALL_CAPABILITY_DEFINITIONS] .map((def) => def.name) .sort((a, b) => a.localeCompare(b)) for (const def of [...ALL_CAPABILITY_DEFINITIONS].sort((a, b) => a.name.localeCompare(b.name))) { const field = Object.values(def.events ?? {}).find((event) => event.fromState?.on === 'advance') ?.fromState?.field if (field !== undefined) advance.push([def.name, field]) const declared = Object.entries(def.methods ?? {}) .filter(([, m]) => typeof m.timeoutMs === 'number') .sort(([a], [b]) => a.localeCompare(b)) .map(([name, m]) => `${JSON.stringify(name)}: ${m.timeoutMs}`) if (declared.length > 0) timeouts.push([def.name, `{ ${declared.join(', ')} }`]) const found = stateLeavesOf(def) if (found.length === 0) continue leafCount += found.length const rows = found.map((leaf) => JSON.stringify({ path: leaf.path, valueType: leaf.valueType, ...(leaf.enumValues !== undefined ? { enumValues: leaf.enumValues } : {}), }), ) leaves.push([def.name, `[${rows.join(', ')}]`]) } const content = `/** * AUTO-GENERATED by scripts/generate-addon-cap-facts.ts — DO NOT EDIT. * * Schema-free capability facts for addon server code, so an addon never imports * \`ALL_CAPABILITY_DEFINITIONS\` (the whole Zod schema graph, ~+100 MB heap per * runner). See docs/decisions/adr-0028.md. * * Coverage: ${advance.length} advance-derived caps, ${leaves.length} caps with ${leafCount} state leaves, ${timeouts.length} caps with a declared method timeout. */ /** A bindable scalar in a capability's runtime state. */ export interface CapStateLeaf { /** Dot path inside the cap's state slice. */ readonly path: string readonly valueType: 'number' | 'boolean' | 'string' | 'enum' readonly enumValues?: readonly string[] } /** cap name -> the numeric state field whose strict advance IS the cap's one-shot event. */ export const CAP_ADVANCE_FIELDS: Readonly> = Object.freeze({ ${advance.map(([cap, field]) => ` ${JSON.stringify(cap)}: ${JSON.stringify(field)},`).join('\n')} }) /** Every capability name, so addon code can check a name without the schema graph. */ export const CAP_NAMES: readonly string[] = Object.freeze([ ${names.map((name) => ` ${JSON.stringify(name)},`).join('\n')} ]) /** cap name -> the bindable leaves of its runtime state (absent: none). */ export const CAP_STATE_LEAVES: Readonly> = Object.freeze({ ${leaves.map(([cap, rows]) => ` ${JSON.stringify(cap)}: ${rows},`).join('\n')} }) /** cap name -> method -> the \`timeoutMs\` its definition declares (absent: the transport default). */ export const CAP_METHOD_TIMEOUTS_MS: Readonly< Record>> > = Object.freeze({ ${timeouts.map(([cap, rows]) => ` ${JSON.stringify(cap)}: ${rows},`).join('\n')} }) ` writeIfChanged(OUTPUT, content) // eslint-disable-next-line no-console console.log( `Wrote ${advance.length} advance caps, ${leaves.length} caps / ${leafCount} state leaves → ${path.relative(ROOT, OUTPUT)}`, ) } main()