// Generates the orca-plugin-authoring skill references from the plugin source of truth. // `--write` rewrites them; the default (`--check`) fails when one is stale. import { readFile, writeFile } from 'node:fs/promises' import path from 'node:path' import process from 'node:process' import { readTypingsModule } from '../../plugin-authoring/generated-contracts/plugin-authoring-typings-outline.mjs' import { loadRepoTypeScriptModules, REPO_ROOT } from '../../plugin-authoring/generated-contracts/plugin-schema-module-loader.mjs' const GUIDE = 'orca-plugin-authoring' const REFERENCE_DIR = ['skill-guides', GUIDE, 'references'] const GENERATED_NOTE = '' const TYPINGS = { // The `orca` module is split by size; `orca plugin types` joins these into one file. components: [ 'resources/plugins/declarative/orca.d.ts', 'resources/plugins/declarative/orca-components.d.ts', 'resources/plugins/declarative/orca-components-layout.d.ts', 'resources/plugins/declarative/orca-components-data.d.ts' ], // Merges into module 'orca': shell, files, on, the worker bridge and plugin data. services: 'resources/plugins/types/orca-services.d.ts', frame: 'resources/plugins/types/orca-frame.d.ts', worker: 'resources/plugins/types/orca-worker.d.ts', testing: 'resources/plugins/types/orca-testing.d.ts' } const SURFACES = ['worker', 'panel', 'editor'] const LONG_ENUM = 8 function loadSources() { return loadRepoTypeScriptModules({ catalog: 'src/shared/plugins/declarative/plugin-declarative-catalog.ts', limits: 'src/shared/plugins/declarative/plugin-declarative-limits.ts', hostApi: 'src/shared/plugins/workers/plugin-host-api.ts', hostMajor: 'src/shared/plugins/workers/plugin-host-api-major.ts', hostDoc: 'src/shared/plugins/workers/plugin-host-api-reference-doc.ts', typeText: 'src/shared/plugins/workers/plugin-schema-type-text.ts', events: 'src/shared/plugins/events/plugin-events.ts', eventContribution: 'src/shared/plugins/contributions/plugin-event-contribution.ts', hooks: 'src/shared/plugins/events/plugin-hook-payloads.ts', hookContribution: 'src/shared/plugins/contributions/plugin-hook-contribution.ts', capabilities: 'src/shared/plugins/capabilities/plugin-capabilities.ts', schema: 'src/shared/plugins/manifest/plugin-json-schema.ts', fieldDocs: 'src/shared/plugins/manifest/plugin-schema-field-docs.ts', cli: 'src/cli/specs/plugin.ts', cliView: 'src/cli/specs/plugin-view.ts', themeTokens: 'src/shared/plugins/artifacts/plugin-theme-token-reference-doc.ts' }) } async function readTypings(repoRoot) { const read = (file) => readFile(path.join(repoRoot, ...file.split('/')), 'utf8') const components = (await Promise.all(TYPINGS.components.map(read))).join('\n') return { components: readTypingsModule(components, TYPINGS.components[0], 'orca'), services: readTypingsModule(await read(TYPINGS.services), TYPINGS.services, 'orca'), frame: readTypingsModule(await read(TYPINGS.frame), TYPINGS.frame, 'orca/frame'), worker: readTypingsModule(await read(TYPINGS.worker), TYPINGS.worker, 'orca/worker'), testing: readTypingsModule(await read(TYPINGS.testing), TYPINGS.testing, 'orca/testing') } } const code = (text) => `\`${text}\`` const withSummary = (line, text) => (text ? `${line}: ${text}` : line) const bullet = (member) => `- ${withSummary(code(member.text), member.summary)}` function document(title, intro, sections) { const lines = [`# ${title}`, '', GENERATED_NOTE, '', ...intro, ...sections.flat()] return `${lines.join('\n').trimEnd()}\n` } function childrenLabel(policy, catalog) { const labels = { none: 'none', text: 'text', inline: `text, ${[...catalog.PLUGIN_DECLARATIVE_INLINE_COMPONENTS].join(', ')}`, items: 'ListItem only', tabs: 'Tab only', any: 'any' } if (!labels[policy]) { throw new Error(`No reference label for component child policy ${policy}`) } return labels[policy] } function renderComponents({ catalog, limits }, { components, services }) { const vocabulary = ['Gap', 'Align', 'Tone', 'Size', 'Variant', 'Press'].map( (name) => `- ${code(name)}: ${code(components.typeText(name))}` ) const icons = components.unionLiterals('IconName') const entries = catalog.PLUGIN_DECLARATIVE_COMPONENT_NAMES.map((name) => { const propsType = components.componentProps(name) if (!propsType) { throw new Error(`orca.d.ts does not export component ${name}`) } const props = components.literalMembers(propsType).map((member) => member.text) const children = childrenLabel(catalog.PLUGIN_DECLARATIVE_CATALOG[name].children, catalog) return `- ${code(name)} (children: ${children}): ${props.length > 0 ? code(props.join('; ')) : 'no props'}` }) const runtime = [ ...[...components.functions, ...services.functions].map((fn) => ({ ...fn, text: fn.text.replace(/^function /u, '') })), ...['host', 'api', 'env', 'ui'].flatMap((name) => components.value(name)), ...['shell', 'files', 'plugin', 'storage', 'settings', 'secrets'].flatMap((name) => services.value(name) ) ].map(bullet) const typeLine = (module, name) => `- ${withSummary(code(module.typeDeclaration(name)), module.typeSummary(name))}` const types = [ ...['PersistScope', 'AtomOptions', 'PanelContext', 'PanelSetup', 'HostError'].map((name) => typeLine(components, name) ), ...[ 'PluginRequestOptions', 'PluginBridgeApi', 'DataChange', 'StorageApi', 'SettingsApi', 'SecretsApi' ].map((name) => typeLine(services, name)) ] const limit = limits.PLUGIN_DECLARATIVE_LIMITS return document( 'Components panel API', [ 'Everything a components panel (`"ui": "components"`) imports comes from `orca`. Components are JSX tags only; props are semantic (no `className`, `style` or lowercase DOM tags). Event props are functions. An unknown prop or enum value is dropped with a warning; an unknown component draws a placeholder.', '' ], [ ['## Prop vocabulary', '', ...vocabulary], [`- ${code('IconName')}: ${icons.join(', ')}. Any other name draws a fallback glyph.`, ''], ['## Components', '', ...entries, ''], ['## Runtime', '', ...runtime, ''], [ '## Panel ↔ worker contract', '', "Declare requests and worker posts once with declaration merging, in a file both the panel and the worker include: `declare module 'orca' { interface PluginRequests { 'todos.list': { input: { done?: boolean }; output: Todo[] } } interface PluginPanelEvents { 'todos.changed': { count: number } } }`. Declared names are typed end to end (`plugin.request`, `plugin.on`, the worker's `orca.panels.handle` and `orca.panels.post`, and `orca/testing`'s `requests` and `panel.post`); any other name carries JSON.", '' ], ['## Types', '', ...types, ''], [ '## Limits', '', `A render is refused, keeping the last good one, past ${limit.maxNodes} nodes, depth ${limit.maxDepth}, ${limit.maxTreeBytes / 1024} KiB of data, ${limit.maxTextLength / 1024} KiB per text, ${limit.maxLabelLength / 1024} KiB per label prop, ${limit.maxPropsPerNode} props per node or ${limit.maxSelectOptions} Select options.` ] ] ) } function renderTesting({ testing }) { const members = (name) => testing.literalMembers(name, { flatten: false }).map((member) => bullet(member)) return document( 'Test kit (`orca/testing`)', [ '`ORCA plugin test` runs `*.test.ts(x)` files in Node with `orca` and `orca/testing` resolved to what this Orca ships, and plugin sources (panels and the worker `main`) loaded as Orca loads them. Every act resolves once the panel or worker has settled: `await` it and never add sleeps.', '' ], [ ['## Functions', '', ...testing.functions.map(bullet), ''], ['## `TestPanel` (from `mount`)', '', ...members('TestPanel'), ''], ['## `TestWorker` (from `mountWorker`)', '', ...members('TestWorker'), ''], ['## `MockHost` (from `mockHost`)', '', ...members('MockHost'), ''], ['## `MockEditorHost` (from `mockEditorHost`)', '', ...members('MockEditorHost'), ''], [ '## Options', '', ...[ 'MountOptions', 'MountWorkerOptions', 'MockHostOptions', 'MockEditorHostOptions', 'CheckScenario' ].map((name) => `- ${code(testing.typeDeclaration(name))}`) ] ] ) } function hostVersion({ hostMajor }, minor) { return `${hostMajor.PLUGIN_HOST_API_MAJOR}.${minor}` } function signature({ typeText }, spec) { const { REFERENCE_TYPE_TEXT, zodTypeText } = typeText const omittable = spec.params.safeParse(undefined).success return `(params${omittable ? '?' : ''}: ${zodTypeText(spec.params, 'input', REFERENCE_TYPE_TEXT)}) => ${zodTypeText(spec.result, 'output', REFERENCE_TYPE_TEXT)}` } /** Each hook's event, what `next` may change and what stops the chain. */ function hookLines({ hooks, hookContribution, typeText }) { const { REFERENCE_TYPE_TEXT, zodTypeText } = typeText const type = (schema) => code(zodTypeText(schema, 'output', REFERENCE_TYPE_TEXT)) return hookContribution.PLUGIN_HOOK_NAMES.map((name) => { const spec = hooks.PLUGIN_HOOK_SPECS[name] const changes = spec.mutable.length > 0 ? spec.mutable.map(code).join(', ') : 'nothing' const stops = spec.result === null ? 'nothing (observe only)' : type(spec.result) return `- ${code(name)} (since ${hookContribution.PLUGIN_HOOK_SINCE[name]}): ${spec.summary}\n event ${type(spec.payload)}; \`next\` may change ${changes}; stop with ${stops}` }) } function renderHostApi(sources, { frame, worker }) { const { hostApi, hostDoc, capabilities } = sources const names = hostApi.PLUGIN_HOST_METHOD_NAMES const methodsFor = (surface) => hostApi.pluginHostMethodsFor(surface).map(code).join(', ') const methods = names.map((name) => { const spec = hostApi.PLUGIN_HOST_API[name] const facts = [ spec.capability ? `capability ${code(spec.capability)}` : 'no capability', spec.surfaces.join(', '), `since ${hostVersion(sources, spec.since)}`, ...(spec.deprecatedSince === undefined ? [] : [`deprecated ${hostVersion(sources, spec.deprecatedSince)}`]), ...(spec.userActivation ? ['needs a user gesture'] : []) ] return `- ${code(name)} (${facts.join('; ')}): ${spec.summary}\n ${code(signature(sources, spec))}` }) const surfaceNotes = { worker: 'Worker (`trusted-worker`, `main`): `orca` passed to `activate(orca)`', panel: 'Panel: global `orca` in an HTML panel; `host` imported from `orca` in a components panel', editor: 'Custom editor: global `orca` in the editor frame' } return document( 'Host API by surface', [ `Host API ${hostVersion(sources, hostApi.PLUGIN_HOST_API_MINOR)} (\`"pluginApi": 1\`). Call \`host.call(method, params, { signal })\`; a surface not listed for a method gets \`not_permitted\`. Params are strict: a field this Orca does not know is refused with \`invalid_params\`, so check \`host.has(method)\` or \`api.minor\` before using a method newer than your \`engines.orca\` floor. Each call also needs the manifest capability and the user's approval.`, '' ], [ [ '## Methods per surface', '', ...SURFACES.map((s) => `- ${surfaceNotes[s]}: ${methodsFor(s)}`), '' ], ["## Worker API (`import type { OrcaWorkerApi } from 'orca/worker'`)", ''], [...worker.literalMembers('OrcaWorkerApi').map(bullet), ''], ['## Frame API (global `orca`, also `window.orca`, in HTML panels and custom editors)', ''], frame.literalMembers('OrcaFrameApi').map(bullet), [ ...frame .literalMembers('EditorDocumentApi') .map((m) => bullet({ ...m, text: `document.${m.text}` })), '' ], [ '## Theme variables in frames', '', "HTML panels and custom editors get these CSS variables from Orca's active theme, plus a `light` or `dark` class on ``. A theme change updates them in place and emits `theme` (`orca.on('theme', ...)`); the frame is not reloaded. Style from them, not fixed colours.", '', ...sources.themeTokens.pluginFrameThemeVariables().map(({ variable, paints }) => { // Name the frame's own variables, not the app theme tokens behind them. const role = paints.replace(/`--([\w-]+)`/g, '`--orca-$1`') return `- ${code(variable)}${role ? `: ${role}` : ''}` }), '' ], ['## Methods', '', ...methods, ''], [ '## Hooks', '', `List each in \`contributes.hooks\` (\`{ "event", "onError"? }\`; \`main\` and \`trusted-worker\`) and handle it with \`orca.hooks.on(event, (event, next) => ...)\`. Return \`next(event)\` (or nothing) to go on, or the stop result. Plugins run in turn, ${sources.hooks.PLUGIN_HOOK_DEFAULT_DEADLINE_MS / 1000} s each; a throw, timeout or crash passes unless the entry says \`"onError": "deny"\`. Decide first: an awaited call before you return (a notification, say) can fail or time out and turn your deny into a pass.`, '', ...hookLines(sources), '' ], [ '## Capabilities', '', ...capabilities.PLUGIN_CAPABILITY_KINDS.map( (kind) => `- ${code(kind)} (since ${capabilities.PLUGIN_CAPABILITY_SINCE[kind]}): ${capabilities.PLUGIN_CAPABILITY_DESCRIPTIONS[kind]}` ), '' ], [ '## Errors', '', 'A failed call rejects with an `Error` carrying `code`, `message`, `retryable` and, for `rate_limited`, `retryAfterMs`. Treat an unknown code as `action_failed`.', '', ...Object.entries(hostDoc.PLUGIN_HOST_ERROR_CODE_MEANINGS).map( ([errorCode, meaning]) => `- ${code(errorCode)}: ${meaning}` ) ] ] ) } function renderEvents({ events, eventContribution, typeText }, { services, frame }) { const { REFERENCE_TYPE_TEXT, zodTypeText } = typeText const workerEvents = eventContribution.PLUGIN_EVENT_NAMES.map( (name) => `- ${code(name)} (${eventContribution.PLUGIN_EVENT_CAPABILITY[name] ? `capability ${code(eventContribution.PLUGIN_EVENT_CAPABILITY[name])}` : 'no capability'}; since ${eventContribution.PLUGIN_EVENT_SINCE[name]}): ${events.PLUGIN_EVENT_SUMMARIES[name]}\n ${code(zodTypeText(events.PLUGIN_EVENT_PAYLOAD_SCHEMAS[name], 'output', REFERENCE_TYPE_TEXT))}` ) return document( 'Events', [], [ [ '## Worker events', '', 'List each in `contributes.events` (`{ "on": "" }`), with `main`, the `trusted-worker` profile and the capability shown; then `orca.events.on(event, handler)` in `activate(orca)` returns `{ dispose() }`. Payloads:', '', ...workerEvents, '' ], [ '## Frame events (`orca.on(event, handler)` in HTML panels and custom editors)', '', ...frame.literalMembers('FrameEvents', { flatten: false }).map(bullet), '' ], [ '## Components panel events (`on(event, handler)` from `orca`)', '', ...services.literalMembers('OrcaEvents', { flatten: false }).map(bullet), '- Every worker event above, with the same payload and capability; a panel needs no `contributes.events` entry, it subscribes while it is open. HTML panels get them on `orca.on` too.' ] ] ) } function typeLabel(schema) { if (schema.$ref) { return schema.$ref.replace('#/$defs/', '') } if (schema.const !== undefined) { return JSON.stringify(schema.const) } if (schema.enum) { return schema.enum.length > LONG_ENUM ? `one of ${schema.enum.join(', ')}` : schema.enum.map((value) => JSON.stringify(value)).join(' | ') } if (schema.type === 'array' && schema.items && !Array.isArray(schema.items)) { return `${typeLabel(schema.items)}[]` } if (schema.anyOf) { return [...new Set(schema.anyOf.map(typeLabel))].join(' | ') } return Array.isArray(schema.type) ? schema.type.join(' | ') : (schema.type ?? 'any') } function fieldLines(schema, pathRules, prefix = '') { const required = new Set(schema.required ?? []) return Object.entries(schema.properties ?? {}).flatMap(([key, field]) => { const since = field['x-orca-since'] ? `, since ${field['x-orca-since']}` : '' const facts = `${typeLabel(field)}${required.has(key) ? ', required' : ''}${since}` const description = (field.description ?? '').replace(` ${pathRules}`, '') const line = `- ${code(`${prefix}${key}`)} (${facts}): ${description}` return field.type === 'object' && field.properties ? [line, ...fieldLines(field, pathRules, `${prefix}${key}.`)] : [line] }) } function renderManifest({ schema, fieldDocs }) { const manifest = schema.pluginManifestJsonSchema() const pathRules = fieldDocs.PLUGIN_PATH_RUNTIME_RULES const lines = (fields) => fieldLines(fields, pathRules) const reserved = (field) => (field.description ?? '').startsWith('Reserved for ') const top = { ...manifest, properties: Object.fromEntries( Object.entries(manifest.properties).filter(([key]) => key !== 'contributes') ) } const contributes = manifest.properties.contributes const open = Object.entries(contributes.properties).filter(([, field]) => !reserved(field)) const closed = Object.keys(contributes.properties).filter((key) => reserved(contributes.properties[key]) ) return document( 'orca-plugin.json fields', [ `\`Since\` is the first Orca release that reads a field: raise \`engines.orca\` to the newest one you use. Orca refuses unknown keys at every level. File paths are ${pathRules.replace(/^Relative/u, 'relative')}`, '' ], [ ['## Top level', '', ...lines(top), ''], [ '## Contribution points (`contributes`)', '', ...lines({ properties: Object.fromEntries(open) }), '' ], [`Reserved (must stay empty arrays): ${closed.map(code).join(', ')}.`, ''], ...Object.entries(manifest.$defs ?? {}).map(([name, fragment]) => [ `## ${name}`, '', fragment.description, '', ...lines(fragment), '' ]) ] ) } function renderCli({ cli, cliView }) { const specs = [ ...cli.PLUGIN_AUTHORING_COMMAND_SPECS, ...cli.PLUGIN_RUNTIME_COMMAND_SPECS, ...cliView.PLUGIN_VIEW_COMMAND_SPECS ] const exitCodes = specs .flatMap((spec) => spec.notes ?? []) .find((note) => note.startsWith('Exit codes')) // Why: commands whose exit codes differ (such as check's plugin_check_failed) would otherwise be invisible here. const otherExitCodes = specs.flatMap((spec) => (spec.notes ?? []) .filter((note) => note.startsWith('Exit codes') && note !== exitCodes) .map((note) => `\`${spec.path.join(' ')}\`: ${note.replace(/^Exit codes: /u, '')}`) ) return document( 'Plugin CLI commands', [ [ '`ORCA` is the Orca executable you resolved. Every command takes `--json`; branch on `error.code`.', exitCodes, ...otherExitCodes.map((note) => `Except ${note}`), "Run `ORCA --help` for a command's notes." ] .filter(Boolean) .join(' '), '' ], [specs.map((spec) => `- ${code(spec.usage.replace(/^orca /u, 'ORCA '))}: ${spec.summary}`)] ) } /** Every reference this generator owns, as `{ path, content }`. */ export async function buildPluginAuthoringReferences(repoRoot = REPO_ROOT) { const sources = loadSources() const typings = await readTypings(repoRoot) const files = { 'cli.md': renderCli(sources), 'components.md': renderComponents(sources, typings), 'events.md': renderEvents(sources, typings), 'host-api.md': renderHostApi(sources, typings), 'manifest.md': renderManifest(sources), 'testing.md': renderTesting(typings) } return Object.entries(files).map(([name, content]) => ({ path: path.join(repoRoot, ...REFERENCE_DIR, name), content })) } export async function findStalePluginAuthoringReferences(artifacts, repoRoot = REPO_ROOT) { const stale = [] for (const artifact of artifacts) { const current = await readFile(artifact.path, 'utf8').catch(() => null) if (current?.replace(/\r\n/g, '\n') !== artifact.content) { stale.push(path.relative(repoRoot, artifact.path).split(path.sep).join('/')) } } return stale } async function main() { const artifacts = await buildPluginAuthoringReferences() if (process.argv.includes('--write')) { await Promise.all(artifacts.map((artifact) => writeFile(artifact.path, artifact.content))) return } const stale = await findStalePluginAuthoringReferences(artifacts) if (stale.length > 0) { throw new Error( `Plugin authoring skill references are stale:\n${stale.join('\n')}\nRun pnpm generate:plugin-authoring-skill-references.` ) } } if (process.argv[1] && path.resolve(process.argv[1]) === import.meta.filename) { main().catch((error) => { console.error(error instanceof Error ? error.message : error) process.exitCode = 1 }) }