diff --git a/.claude/agents/architect.md b/.claude/agents/architect.md new file mode 100644 index 000000000..50af22b84 --- /dev/null +++ b/.claude/agents/architect.md @@ -0,0 +1,21 @@ +--- +name: architect +description: Design and planning. Component deep dives, architectural evaluation, implementation and refactoring plans, and design proposals, persisted to docs/planning/. +tools: Read, Grep, Glob, Bash, Skill, mcp__workerd__compat-date-at, mcp__workerd__next-capnp-ordinal, Agent, Write, Edit, WebFetch, WebSearch +--- + +Your instructions are maintained for opencode in `.opencode/agent/architect.md`, relative to the +repository root. Before doing anything else, read that file and adopt everything after its YAML +frontmatter as your instructions. The frontmatter configures opencode only; ignore it. + +When following those instructions in Claude Code: + +- Tools named `compat-date-at` and `next-capnp-ordinal` are the `workerd` MCP server's tools of + the same names. +- Skills are loaded with the Skill tool. +- An `explore` subagent is the `Explore` agent. Claude Code subagents cannot start other agents, + so when you are running as a subagent, explore directly. +- Use Write and Edit only under `docs/planning/`. Bash is not restricted to the read-only + commands the frontmatter lists, but you must keep to them. +- Where the instructions say to switch to Build mode, tell the user to continue in a normal + Claude Code session. diff --git a/.claude/agents/code-review.md b/.claude/agents/code-review.md new file mode 100644 index 000000000..46f0bb876 --- /dev/null +++ b/.claude/agents/code-review.md @@ -0,0 +1,22 @@ +--- +name: code-review +description: Code review of local changes and GitHub pull requests. Works the safety, API, and style checklists, fans out to per-axis reviewers, and reports findings without changing code. Use for PR reviews, safety and security audits, and pre-submit checks. +tools: Read, Grep, Glob, Bash, Skill, mcp__workerd__compat-date-at, mcp__workerd__next-capnp-ordinal, Agent, Write, WebFetch, WebSearch +--- + +Your instructions are maintained for opencode in `.opencode/agent/code-review.md`, relative to the +repository root. Before doing anything else, read that file and adopt everything after its YAML +frontmatter as your instructions. The frontmatter configures opencode only; ignore it. + +When following those instructions in Claude Code: + +- Tools named `compat-date-at` and `next-capnp-ordinal` are the `workerd` MCP server's tools of + the same names. +- Skills are loaded with the Skill tool. +- An `explore` subagent is the `Explore` agent; `review-safety`, `review-api`, and `review-style` + are agents of the same names. Claude Code subagents cannot start other agents, so when you are + running as a subagent, skip the fan-out and work the checklists yourself. +- Use Write only for scratch files under `/tmp/opencode/`. Bash is not restricted to the + read-only commands the frontmatter lists, but you must keep to them. +- Where the instructions say to switch to Build mode, tell the user to continue in a normal + Claude Code session. diff --git a/.claude/agents/review-api.md b/.claude/agents/review-api.md new file mode 100644 index 000000000..9df624e2b --- /dev/null +++ b/.claude/agents/review-api.md @@ -0,0 +1,17 @@ +--- +name: review-api +description: Single-axis review of performance, API design, backward compatibility, security and standards compliance for a diff or component. Returns findings only, in the shared finding format. Invoked by the code-review agent's review fan-out; not useful on its own. +tools: Read, Grep, Glob, Bash, Skill, mcp__workerd__compat-date-at, mcp__workerd__next-capnp-ordinal +--- + +Your instructions are maintained for opencode in `.opencode/agent/review-api.md`, relative to the +repository root. Before doing anything else, read that file and adopt everything after its YAML +frontmatter as your instructions. The frontmatter configures opencode only; ignore it. + +When following those instructions in Claude Code: + +- Tools named `compat-date-at` and `next-capnp-ordinal` are the `workerd` MCP server's tools of + the same names. +- Skills are loaded with the Skill tool. +- Bash is not restricted to the read-only commands the frontmatter lists, but you must keep to + them. diff --git a/.claude/agents/review-safety.md b/.claude/agents/review-safety.md new file mode 100644 index 000000000..9cfdda8a0 --- /dev/null +++ b/.claude/agents/review-safety.md @@ -0,0 +1,17 @@ +--- +name: review-safety +description: Single-axis memory-safety and thread-safety review of C++ and Rust in a diff or component, including unsafe blocks and CXX bridges. Returns findings only, in the shared finding format. Invoked by the code-review agent's review fan-out; not useful on its own. +tools: Read, Grep, Glob, Bash, Skill, mcp__workerd__compat-date-at, mcp__workerd__next-capnp-ordinal +--- + +Your instructions are maintained for opencode in `.opencode/agent/review-safety.md`, relative to the +repository root. Before doing anything else, read that file and adopt everything after its YAML +frontmatter as your instructions. The frontmatter configures opencode only; ignore it. + +When following those instructions in Claude Code: + +- Tools named `compat-date-at` and `next-capnp-ordinal` are the `workerd` MCP server's tools of + the same names. +- Skills are loaded with the Skill tool. +- Bash is not restricted to the read-only commands the frontmatter lists, but you must keep to + them. diff --git a/.claude/agents/review-style.md b/.claude/agents/review-style.md new file mode 100644 index 000000000..eb36a8e47 --- /dev/null +++ b/.claude/agents/review-style.md @@ -0,0 +1,17 @@ +--- +name: review-style +description: Single-axis style and coding-convention review of a diff or component, dispatching to the KJ/C++, Rust or TypeScript guide by file type. Returns findings only, in the shared finding format. Invoked by the code-review agent's review fan-out; not useful on its own. +tools: Read, Grep, Glob, Bash, Skill, mcp__workerd__compat-date-at, mcp__workerd__next-capnp-ordinal +--- + +Your instructions are maintained for opencode in `.opencode/agent/review-style.md`, relative to the +repository root. Before doing anything else, read that file and adopt everything after its YAML +frontmatter as your instructions. The frontmatter configures opencode only; ignore it. + +When following those instructions in Claude Code: + +- Tools named `compat-date-at` and `next-capnp-ordinal` are the `workerd` MCP server's tools of + the same names. +- Skills are loaded with the Skill tool. +- Bash is not restricted to the read-only commands the frontmatter lists, but you must keep to + them. diff --git a/.claude/commands b/.claude/commands new file mode 120000 index 000000000..8f0a3d838 --- /dev/null +++ b/.claude/commands @@ -0,0 +1 @@ +../.opencode/commands \ No newline at end of file diff --git a/.claude/skills b/.claude/skills new file mode 120000 index 000000000..e5da19da9 --- /dev/null +++ b/.claude/skills @@ -0,0 +1 @@ +../.opencode/skills \ No newline at end of file diff --git a/.gitignore b/.gitignore index d89d37f4f..8c62cb2cd 100644 --- a/.gitignore +++ b/.gitignore @@ -37,7 +37,12 @@ package-lock.json coverage perf.data -.claude +# Claude Code: track the shared project config, which reuses the opencode agents, commands, +# skills, and tools under .opencode/; ignore everything else, such as settings.local.json. +.claude/* +!.claude/agents/ +!.claude/commands +!.claude/skills # opencode auto-generates package.json, bun.lock, and .gitignore inside .opencode/ # at startup to install plugin dependencies. These are runtime artifacts that should diff --git a/.mcp.json b/.mcp.json new file mode 100644 index 000000000..d68529486 --- /dev/null +++ b/.mcp.json @@ -0,0 +1,11 @@ +{ + "mcpServers": { + "workerd": { + "command": "sh", + "args": [ + "-c", + "exec node --disable-warning=MODULE_TYPELESS_PACKAGE_JSON \"$(git rev-parse --show-toplevel)/.opencode/lib/mcp-server.ts\"" + ] + } + } +} diff --git a/.opencode/tools/capnp.ts b/.opencode/lib/capnp.ts similarity index 53% rename from .opencode/tools/capnp.ts rename to .opencode/lib/capnp.ts index bf11105b1..63c34ae44 100644 --- a/.opencode/tools/capnp.ts +++ b/.opencode/lib/capnp.ts @@ -1,7 +1,12 @@ // Shared helper for running capnpc-capnp on .capnp schema files. // Used by next-capnp-ordinal and compat-date-at tools. -import path from 'path'; +import { execFile } from 'node:child_process'; +import { access, constants, realpath } from 'node:fs/promises'; +import path from 'node:path'; +import { promisify } from 'node:util'; + +const execFileAsync = promisify(execFile); /** * Run capnpc-capnp on a .capnp file and return the canonical text output. @@ -9,7 +14,7 @@ import path from 'path'; * Automatically locates the bazel-built capnp tools, building them if needed. * Includes standard import paths for workerd's capnp files. * - * @param root - Project root directory (ctx.worktree or ctx.directory) + * @param root - Project root directory (the workerd checkout) * @param filePath - Absolute path to the .capnp file * @returns The canonical schema text, or an error string prefixed with "Error:" */ @@ -25,19 +30,22 @@ export async function runCapnpcCapnp( root, 'bazel-bin/external/+http+capnp-cpp/src/capnp/capnpc-capnp' ); - const importPath = path.join( - root, - 'bazel-workerd/external/+http+capnp-cpp/src' - ); // Check tools exist, build if needed try { - await Bun.$`test -x ${capnp} && test -x ${capnpcCapnp}`.quiet(); + await access(capnp, constants.X_OK); + await access(capnpcCapnp, constants.X_OK); } catch { try { - await Bun.$`bazel build @capnp-cpp//src/capnp:capnp_tool @capnp-cpp//src/capnp:capnpc-capnp` - .cwd(root) - .quiet(); + await execFileAsync( + 'bazel', + [ + 'build', + '@capnp-cpp//src/capnp:capnp_tool', + '@capnp-cpp//src/capnp:capnpc-capnp', + ], + { cwd: root, maxBuffer: 64 * 1024 * 1024 } + ); } catch { return { error: @@ -46,6 +54,20 @@ export async function runCapnpcCapnp( } } + // The execroot's convenience symlink is named after the checkout directory (`bazel-workerd`, + // or `bazel-` in a worktree), so reach the execroot through `bazel-out` instead. + let execroot: string; + try { + execroot = path.dirname(await realpath(path.join(root, 'bazel-out'))); + } catch { + return { + error: + 'Could not locate the bazel execroot: the bazel-out symlink in the project root is ' + + 'missing. Run a bazel build (without --symlink_prefix or --experimental_convenience_symlinks=ignore) first.', + }; + } + const importPath = path.join(execroot, 'external/+http+capnp-cpp/src'); + const fileDir = path.dirname(filePath); const importArgs = [ '--no-standard-import', @@ -57,9 +79,12 @@ export async function runCapnpcCapnp( ]; try { - return await Bun.$`${capnp} compile ${importArgs} -o${capnpcCapnp} ${filePath}` - .cwd(root) - .text(); + const { stdout } = await execFileAsync( + capnp, + ['compile', ...importArgs, `-o${capnpcCapnp}`, filePath], + { cwd: root, maxBuffer: 64 * 1024 * 1024 } + ); + return stdout; } catch (e: any) { return { error: `capnpc-capnp failed:\n${e.stderr || e.message}` }; } diff --git a/.opencode/lib/compat-date-at.ts b/.opencode/lib/compat-date-at.ts new file mode 100644 index 000000000..2b71f9fc6 --- /dev/null +++ b/.opencode/lib/compat-date-at.ts @@ -0,0 +1,229 @@ +import { runCapnpcCapnp, resolveCapnpPath } from './capnp.ts'; +import type { ToolDef } from './tool-def.ts'; + +export const compatDateAt: ToolDef<{ date?: string; flag?: string }> = { + name: 'compat-date-at', + description: + 'List which compatibility flags are active or inactive at a given date. ' + + 'Parses compatibility-date.capnp via the capnp compiler. Useful for understanding ' + + 'what behavior a worker gets at a specific compat date, debugging test variant ' + + 'failures (@, @all-compat-flags, @all-autogates), and writing .wd-test configs.', + args: { + date: { + optional: true, + description: + 'Compatibility date (YYYY-MM-DD). Omit to list all flags with their enable dates.', + }, + flag: { + optional: true, + description: + 'Filter by flag name substring (matches enable flag, disable flag, or field name)', + }, + }, + async run(root, args) { + const flags = await parseCompatFlags(root); + if (typeof flags === 'string') return flags; + + let filtered = flags; + + if (args.flag) { + const q = args.flag.toLowerCase(); + filtered = flags.filter( + (f) => + f.fieldName.toLowerCase().includes(q) || + f.enableFlag?.toLowerCase().includes(q) || + f.disableFlag?.toLowerCase().includes(q) + ); + if (filtered.length === 0) { + return `No flags matching '${args.flag}'. There are ${flags.length} total flags.`; + } + } + + if (!args.date) { + return formatAllFlags(filtered); + } + + if (!/^\d{4}-\d{2}-\d{2}$/.test(args.date)) { + return `Invalid date format: '${args.date}'. Use YYYY-MM-DD.`; + } + + return formatAtDate(filtered, args.date); + }, +}; + +// --- Types --- + +interface CompatFlag { + fieldName: string; + ordinal: number; + enableFlag: string | null; + disableFlag: string | null; + enableDate: string | null; + enableAllDates: boolean; + experimental: boolean; + neededByFl: boolean; + impliedBy: string | null; + obsolete: boolean; +} + +// --- Parsing --- + +const COMPAT_CAPNP = 'src/workerd/io/compatibility-date.capnp'; + +async function parseCompatFlags(root: string): Promise { + const filePath = resolveCapnpPath(root, COMPAT_CAPNP); + const result = await runCapnpcCapnp(root, filePath); + if (typeof result !== 'string') return result.error; + + const flags: CompatFlag[] = []; + + for (const line of result.split('\n')) { + const m = line.match(/^\s+(\w+)\s+@(\d+)\s+:Bool/); + if (!m) continue; + + const fieldName = m[1]; + const ordinal = parseInt(m[2], 10); + + flags.push({ + fieldName, + ordinal, + enableFlag: extractAnno(line, 'compatEnableFlag'), + disableFlag: extractAnno(line, 'compatDisableFlag'), + enableDate: extractAnno(line, 'compatEnableDate'), + enableAllDates: line.includes('$compatEnableAllDates('), + experimental: line.includes('$experimental('), + neededByFl: line.includes('$neededByFl('), + impliedBy: extractRawAnno(line, 'impliedByAfterDate'), + obsolete: fieldName.startsWith('obsolete'), + }); + } + + return flags; +} + +function extractAnno(line: string, name: string): string | null { + const m = line.match(new RegExp(`\\$${name}\\("([^"]*)"\\)`)); + return m ? m[1] : null; +} + +function extractRawAnno(line: string, name: string): string | null { + const m = line.match(new RegExp(`\\$${name}\\(([^)]+)\\)`)); + return m ? m[1] : null; +} + +// --- Formatting --- + +function formatAllFlags(flags: CompatFlag[]): string { + const active = flags.filter((f) => !f.obsolete); + const obsolete = flags.filter((f) => f.obsolete); + + const dated = active + .filter((f) => f.enableDate || f.enableAllDates) + .sort((a, b) => (a.enableDate || '').localeCompare(b.enableDate || '')); + const experimental = active.filter( + (f) => f.experimental && !f.enableDate && !f.enableAllDates + ); + const noDate = active.filter( + (f) => !f.experimental && !f.enableDate && !f.enableAllDates + ); + + let out = `## All Compatibility Flags (${active.length} active, ${obsolete.length} obsolete)\n\n`; + + if (dated.length > 0) { + out += `### Date-gated (${dated.length})\n\n`; + for (const f of dated) { + const d = f.enableAllDates ? 'ALL DATES' : f.enableDate; + const extra: string[] = []; + if (f.neededByFl) extra.push('FL'); + if (f.experimental) extra.push('experimental'); + if (f.impliedBy) extra.push(`implied by ${f.impliedBy}`); + const suffix = extra.length > 0 ? ` (${extra.join(', ')})` : ''; + out += `- **${d}**: \`${f.enableFlag || f.fieldName}\`${suffix}\n`; + } + } + + if (noDate.length > 0) { + out += `\n### Opt-in only — no default date (${noDate.length})\n\n`; + for (const f of noDate) { + const extra: string[] = []; + if (f.impliedBy) extra.push(`implied by ${f.impliedBy}`); + const suffix = extra.length > 0 ? ` (${extra.join(', ')})` : ''; + out += `- \`${f.enableFlag || f.fieldName}\`${suffix}\n`; + } + } + + if (experimental.length > 0) { + out += `\n### Experimental — requires --experimental (${experimental.length})\n\n`; + for (const f of experimental) { + out += `- \`${f.enableFlag || f.fieldName}\`\n`; + } + } + + return out; +} + +function formatAtDate(flags: CompatFlag[], date: string): string { + const active = flags.filter((f) => !f.obsolete); + + const enabled: CompatFlag[] = []; + const notYetEnabled: CompatFlag[] = []; + const optInOnly: CompatFlag[] = []; + const experimental: CompatFlag[] = []; + + for (const f of active) { + if (f.enableAllDates) { + enabled.push(f); + } else if (f.enableDate) { + if (f.enableDate <= date) { + enabled.push(f); + } else { + notYetEnabled.push(f); + } + } else if (f.experimental) { + experimental.push(f); + } else { + optInOnly.push(f); + } + } + + let out = `## Flags at compatibility date "${date}"\n\n`; + out += `- **${enabled.length}** enabled by default\n`; + out += `- **${notYetEnabled.length}** not yet enabled (future date)\n`; + out += `- **${optInOnly.length}** opt-in only (no date set)\n`; + out += `- **${experimental.length}** experimental\n\n`; + + if (enabled.length > 0) { + out += `### Enabled by default (${enabled.length})\n\n`; + for (const f of enabled.sort((a, b) => + (a.enableDate || '').localeCompare(b.enableDate || '') + )) { + const d = f.enableAllDates ? 'all' : f.enableDate; + out += `- \`${f.enableFlag || f.fieldName}\` (since ${d})\n`; + } + } + + if (notYetEnabled.length > 0) { + out += `\n### Not yet enabled — date is after "${date}" (${notYetEnabled.length})\n\n`; + for (const f of notYetEnabled.sort((a, b) => + (a.enableDate || '').localeCompare(b.enableDate || '') + )) { + out += `- \`${f.enableFlag || f.fieldName}\` (${f.enableDate})\n`; + } + } + + if (optInOnly.length > 0) { + out += `\n### Opt-in only (${optInOnly.length})\n\n`; + for (const f of optInOnly) { + out += `- \`${f.enableFlag || f.fieldName}\`\n`; + } + } + + if (experimental.length > 0) { + out += `\n### Experimental (${experimental.length})\n\n`; + for (const f of experimental) { + out += `- \`${f.enableFlag || f.fieldName}\`\n`; + } + } + + return out; +} diff --git a/.opencode/lib/mcp-server.ts b/.opencode/lib/mcp-server.ts new file mode 100644 index 000000000..7b3ae5d25 --- /dev/null +++ b/.opencode/lib/mcp-server.ts @@ -0,0 +1,114 @@ +#!/usr/bin/env node +// Minimal stdio MCP server exposing the tools in this directory to Claude Code, which registers +// it in `/.mcp.json`. opencode loads the same tools natively from `.opencode/tools/`. +// +// Speaks newline-delimited JSON-RPC 2.0 and implements only what a tools-only server needs: +// `initialize`, `ping`, `tools/list`, and `tools/call`. It has no dependencies, so it runs on a +// fresh checkout with Node 22.18 or later (for TypeScript type stripping). + +import path from 'node:path'; +import { createInterface } from 'node:readline'; +import { compatDateAt } from './compat-date-at.ts'; +import { nextCapnpOrdinal } from './next-capnp-ordinal.ts'; +import { toJsonSchema, type ToolDef } from './tool-def.ts'; + +const TOOLS: ToolDef[] = [compatDateAt, nextCapnpOrdinal]; +const ROOT = path.resolve(import.meta.dirname, '../..'); + +type Id = string | number | null; + +function send(message: object): void { + process.stdout.write(JSON.stringify({ jsonrpc: '2.0', ...message }) + '\n'); +} + +async function handle(method: string, params: any): Promise { + switch (method) { + case 'initialize': + return { + protocolVersion: params?.protocolVersion ?? '2025-06-18', + capabilities: { tools: {} }, + serverInfo: { name: 'workerd', version: '1.0.0' }, + }; + case 'ping': + return {}; + case 'tools/list': + return { + tools: TOOLS.map((def) => ({ + name: def.name, + description: def.description, + inputSchema: toJsonSchema(def), + })), + }; + case 'tools/call': { + const def = TOOLS.find((t) => t.name === params?.name); + if (!def) throw new RpcError(-32602, `Unknown tool: ${params?.name}`); + const args = params.arguments ?? {}; + const problem = checkArgs(def, args); + if (problem) { + return { content: [{ type: 'text', text: problem }], isError: true }; + } + try { + const text = await def.run(ROOT, args); + return { content: [{ type: 'text', text }] }; + } catch (e: any) { + return { + content: [{ type: 'text', text: String(e?.stack ?? e) }], + isError: true, + }; + } + } + default: + throw new RpcError(-32601, `Method not found: ${method}`); + } +} + +// Checks `args` against the tool's declared arguments, returning a message for the model if they +// don't match. opencode gets the same check from the zod schema built by `toOpencodeTool`. +function checkArgs(def: ToolDef, args: unknown): string | undefined { + if (typeof args !== 'object' || args === null || Array.isArray(args)) { + return `Error: arguments to ${def.name} must be an object.`; + } + const values = args as Record; + for (const [name, arg] of Object.entries(def.args)) { + const value = values[name]; + if (value === undefined) { + if (!arg.optional) { + return `Error: ${def.name} requires the '${name}' argument.`; + } + } else if (typeof value !== 'string') { + return `Error: the '${name}' argument to ${def.name} must be a string.`; + } + } + return undefined; +} + +class RpcError extends Error { + code: number; + constructor(code: number, message: string) { + super(message); + this.code = code; + } +} + +async function dispatch(line: string): Promise { + let id: Id = null; + try { + const request = JSON.parse(line); + // Notifications (no id) need no response; this server ignores them all. + if (request.id === undefined) return; + id = request.id; + send({ id, result: await handle(request.method, request.params) }); + } catch (e: any) { + const code = + e instanceof RpcError + ? e.code + : e instanceof SyntaxError + ? -32700 + : -32603; + send({ id, error: { code, message: String(e?.message ?? e) } }); + } +} + +for await (const line of createInterface({ input: process.stdin })) { + if (line.trim()) void dispatch(line); +} diff --git a/.opencode/lib/next-capnp-ordinal.ts b/.opencode/lib/next-capnp-ordinal.ts new file mode 100644 index 000000000..fd5c14306 --- /dev/null +++ b/.opencode/lib/next-capnp-ordinal.ts @@ -0,0 +1,228 @@ +import path from 'node:path'; +import { runCapnpcCapnp, resolveCapnpPath } from './capnp.ts'; +import type { ToolDef } from './tool-def.ts'; + +export const nextCapnpOrdinal: ToolDef<{ file: string; struct?: string }> = { + name: 'next-capnp-ordinal', + description: + "Find the next available field ordinal (@N) in a Cap'n Proto struct. " + + 'Uses the capnp compiler (capnpc-capnp) to parse the schema canonically. ' + + 'Use before adding new fields to .capnp files (especially compatibility-date.capnp) ' + + 'to avoid ordinal collisions.', + args: { + file: { + description: + 'Path to .capnp file (absolute, or relative to project root)', + }, + struct: { + optional: true, + description: + "Struct name (e.g., 'CompatibilityFlags'). Omit to list all structs.", + }, + }, + async run(root, args) { + const filePath = resolveCapnpPath(root, args.file); + + const result = await runCapnpcCapnp(root, filePath); + if (typeof result !== 'string') return result.error; + + const structs = parseCapnpOutput(result); + + if (!args.struct) { + return listStructs(structs, filePath); + } + + // Support dotted names like "Worker.Module" + const target = + structs.find((s) => s.qualifiedName === args.struct) || + structs.find((s) => s.name === args.struct); + + if (!target) { + const available = structs.map((s) => s.qualifiedName).join(', '); + return `Struct '${args.struct}' not found in ${path.basename(filePath)}\n\nAvailable: ${available}`; + } + + return formatResult(target, filePath); + }, +}; + +// --- Output parsing --- + +interface FieldInfo { + name: string; + ordinal: number; + type: string; + annotations: string[]; + raw: string; +} + +interface StructInfo { + name: string; + qualifiedName: string; + fields: FieldInfo[]; + declaredAnnotations: string[]; +} + +function parseCapnpOutput(output: string): StructInfo[] { + const lines = output.split('\n'); + const allStructs: StructInfo[] = []; + + const nameStack: string[] = []; + let currentStruct: StructInfo | null = null; + + let depth = 0; + const structDepths: number[] = []; + + for (const line of lines) { + const opens = (line.match(/\{/g) || []).length; + const closes = (line.match(/\}/g) || []).length; + + // Check for struct opening + const structMatch = line.match(/struct\s+(\w+)\s+@0x[\da-fA-F]+\s*\{/); + if (structMatch) { + if (currentStruct) { + allStructs.push(currentStruct); + } + + const name = structMatch[1]; + nameStack.push(name); + structDepths.push(depth); + + currentStruct = { + name, + qualifiedName: nameStack.join('.'), + fields: [], + declaredAnnotations: [], + }; + + depth += opens; + continue; + } + + depth += opens; + + // Field declarations: " fieldName @N :Type ..." + const fieldMatch = line.match(/^\s+(\w+)\s+@(\d+)\s+:(\S+)/); + if (fieldMatch && currentStruct) { + const annotations: string[] = []; + const annoRe = /\$(\w+)\(([^)]*)\)/g; + let m; + while ((m = annoRe.exec(line)) !== null) { + annotations.push(`$${m[1]}(${m[2]})`); + } + + const raw = line + .trim() + .replace(/\s+#\s.*$/, '') + .replace(/;$/, ''); + + currentStruct.fields.push({ + name: fieldMatch[1], + ordinal: parseInt(fieldMatch[2], 10), + type: fieldMatch[3].replace(/[;,]$/, ''), + annotations, + raw, + }); + } + + // Annotation declarations inside a struct + const annoDecl = line.match(/^\s+annotation\s+(\w+)\s+@0x/); + if (annoDecl && currentStruct) { + currentStruct.declaredAnnotations.push(annoDecl[1]); + } + + depth -= closes; + + // Check if we've closed a struct + while ( + structDepths.length > 0 && + depth <= structDepths[structDepths.length - 1] + ) { + if (currentStruct) { + allStructs.push(currentStruct); + currentStruct = null; + } + structDepths.pop(); + nameStack.pop(); + + if (nameStack.length > 0) { + const parentName = nameStack.join('.'); + const parentIdx = allStructs.findIndex( + (s) => s.qualifiedName === parentName + ); + if (parentIdx >= 0) { + currentStruct = allStructs[parentIdx]; + allStructs.splice(parentIdx, 1); + } + } + } + } + + if (currentStruct) { + allStructs.push(currentStruct); + } + + return allStructs; +} + +// --- Formatting --- + +function listStructs(structs: StructInfo[], filePath: string): string { + if (structs.length === 0) { + return `No structs found in ${path.basename(filePath)}`; + } + let result = `## Structs in ${path.basename(filePath)}\n\n`; + for (const s of structs) { + if (s.fields.length === 0) { + result += `- **${s.qualifiedName}**: no fields\n`; + } else { + const max = Math.max(...s.fields.map((f) => f.ordinal)); + result += `- **${s.qualifiedName}**: ${s.fields.length} fields, highest @${max}, next @${max + 1}\n`; + } + } + return result; +} + +function formatResult(target: StructInfo, filePath: string): string { + if (target.fields.length === 0) { + return `Struct '${target.qualifiedName}' in ${path.basename(filePath)} has no fields.`; + } + + const sorted = [...target.fields].sort((a, b) => a.ordinal - b.ordinal); + const maxOrdinal = sorted[sorted.length - 1].ordinal; + const nextOrdinal = maxOrdinal + 1; + + const used = new Set(target.fields.map((f) => f.ordinal)); + const gaps: number[] = []; + for (let i = 0; i <= maxOrdinal; i++) { + if (!used.has(i)) gaps.push(i); + } + + const lastFields = sorted.slice(-5); + + let out = `## ${target.qualifiedName} in ${path.basename(filePath)}\n\n`; + out += `**Next available ordinal: @${nextOrdinal}**\n\n`; + out += `- Total fields: ${target.fields.length}\n`; + out += `- Highest ordinal: @${maxOrdinal} (\`${sorted[sorted.length - 1].name}\`)\n`; + + if (gaps.length > 0) { + out += `- Gaps: ${gaps.map((g) => `@${g}`).join(', ')}\n`; + out += ` (Likely obsolete -- do NOT reuse)\n`; + } + + if (target.declaredAnnotations.length > 0) { + out += `- Annotations: ${target.declaredAnnotations.join(', ')}\n`; + } + + out += `\n### Last ${lastFields.length} fields\n\n`; + for (const f of lastFields) { + out += `- \`${f.raw}\`\n`; + } + + out += `\n### Usage\n\n`; + out += '```capnp\n'; + out += ` yourNewField @${nextOrdinal} :Bool\n`; + out += '```\n'; + + return out; +} diff --git a/.opencode/lib/tool-def.ts b/.opencode/lib/tool-def.ts new file mode 100644 index 000000000..d523b1903 --- /dev/null +++ b/.opencode/lib/tool-def.ts @@ -0,0 +1,54 @@ +// Agent-neutral definitions of the project's custom tools. +// +// Each tool is defined once, as a ToolDef, and exposed to two harnesses: +// - opencode, through the thin wrappers in `.opencode/tools/` (see `toOpencodeTool`); +// - Claude Code, through the MCP server in `mcp-server.ts`, registered in `/.mcp.json`. +// +// Files in this directory must run unmodified under both Bun (opencode) and Node (the MCP +// server), so they use only `node:` modules and erasable TypeScript syntax, and do not import +// `@opencode-ai/plugin`. + +export interface ToolArg { + description: string; + optional?: boolean; +} + +export interface ToolDef> { + // Tool name, as registered with the harness. + name: string; + description: string; + // All arguments are strings. + args: { [K in keyof Args]-?: ToolArg }; + // `root` is the workerd checkout. The result is the text shown to the model; failures are + // reported as text too, not thrown. + run(root: string, args: Args): Promise; +} + +// The JSON Schema for a tool's arguments, as MCP's `inputSchema` expects. +export function toJsonSchema(def: ToolDef): object { + const properties: Record = {}; + const required: string[] = []; + for (const [name, arg] of Object.entries(def.args)) { + properties[name] = { type: 'string', description: arg.description }; + if (!arg.optional) required.push(name); + } + return { type: 'object', properties, required }; +} + +// Builds an opencode tool from a ToolDef. Takes the plugin's `tool` function as a parameter so +// that this file does not import `@opencode-ai/plugin`, which only opencode installs. +export function toOpencodeTool(tool: any, def: ToolDef): unknown { + const args: Record = {}; + for (const [name, arg] of Object.entries(def.args)) { + const schema = tool.schema.string(); + args[name] = (arg.optional ? schema.optional() : schema).describe( + arg.description + ); + } + return tool({ + description: def.description, + args, + execute: (args: any, ctx: any) => + def.run(ctx.worktree || ctx.directory, args), + }); +} diff --git a/.opencode/tools/compat-date-at.ts b/.opencode/tools/compat-date-at.ts index 3157735fb..ddfed4166 100644 --- a/.opencode/tools/compat-date-at.ts +++ b/.opencode/tools/compat-date-at.ts @@ -1,232 +1,6 @@ +// The implementation is shared with Claude Code; see ../lib/tool-def.ts. import { tool } from '@opencode-ai/plugin'; -import path from 'path'; -import { runCapnpcCapnp, resolveCapnpPath } from './capnp.ts'; +import { toOpencodeTool } from '../lib/tool-def.ts'; +import { compatDateAt } from '../lib/compat-date-at.ts'; -export default tool({ - description: - 'List which compatibility flags are active or inactive at a given date. ' + - 'Parses compatibility-date.capnp via the capnp compiler. Useful for understanding ' + - 'what behavior a worker gets at a specific compat date, debugging test variant ' + - 'failures (@, @all-compat-flags, @all-autogates), and writing .wd-test configs.', - args: { - date: tool.schema - .string() - .optional() - .describe( - 'Compatibility date (YYYY-MM-DD). Omit to list all flags with their enable dates.' - ), - flag: tool.schema - .string() - .optional() - .describe( - 'Filter by flag name substring (matches enable flag, disable flag, or field name)' - ), - }, - async execute(args, ctx) { - const root = ctx.worktree || ctx.directory; - const flags = await parseCompatFlags(root); - if (typeof flags === 'string') return flags; - - let filtered = flags; - - if (args.flag) { - const q = args.flag.toLowerCase(); - filtered = flags.filter( - (f) => - f.fieldName.toLowerCase().includes(q) || - f.enableFlag?.toLowerCase().includes(q) || - f.disableFlag?.toLowerCase().includes(q) - ); - if (filtered.length === 0) { - return `No flags matching '${args.flag}'. There are ${flags.length} total flags.`; - } - } - - if (!args.date) { - return formatAllFlags(filtered); - } - - if (!/^\d{4}-\d{2}-\d{2}$/.test(args.date)) { - return `Invalid date format: '${args.date}'. Use YYYY-MM-DD.`; - } - - return formatAtDate(filtered, args.date); - }, -}); - -// --- Types --- - -interface CompatFlag { - fieldName: string; - ordinal: number; - enableFlag: string | null; - disableFlag: string | null; - enableDate: string | null; - enableAllDates: boolean; - experimental: boolean; - neededByFl: boolean; - impliedBy: string | null; - obsolete: boolean; -} - -// --- Parsing --- - -const COMPAT_CAPNP = 'src/workerd/io/compatibility-date.capnp'; - -async function parseCompatFlags(root: string): Promise { - const filePath = resolveCapnpPath(root, COMPAT_CAPNP); - const result = await runCapnpcCapnp(root, filePath); - if (typeof result !== 'string') return result.error; - - const flags: CompatFlag[] = []; - - for (const line of result.split('\n')) { - const m = line.match(/^\s+(\w+)\s+@(\d+)\s+:Bool/); - if (!m) continue; - - const fieldName = m[1]; - const ordinal = parseInt(m[2], 10); - - flags.push({ - fieldName, - ordinal, - enableFlag: extractAnno(line, 'compatEnableFlag'), - disableFlag: extractAnno(line, 'compatDisableFlag'), - enableDate: extractAnno(line, 'compatEnableDate'), - enableAllDates: line.includes('$compatEnableAllDates('), - experimental: line.includes('$experimental('), - neededByFl: line.includes('$neededByFl('), - impliedBy: extractRawAnno(line, 'impliedByAfterDate'), - obsolete: fieldName.startsWith('obsolete'), - }); - } - - return flags; -} - -function extractAnno(line: string, name: string): string | null { - const m = line.match(new RegExp(`\\$${name}\\("([^"]*)"\\)`)); - return m ? m[1] : null; -} - -function extractRawAnno(line: string, name: string): string | null { - const m = line.match(new RegExp(`\\$${name}\\(([^)]+)\\)`)); - return m ? m[1] : null; -} - -// --- Formatting --- - -function formatAllFlags(flags: CompatFlag[]): string { - const active = flags.filter((f) => !f.obsolete); - const obsolete = flags.filter((f) => f.obsolete); - - const dated = active - .filter((f) => f.enableDate || f.enableAllDates) - .sort((a, b) => (a.enableDate || '').localeCompare(b.enableDate || '')); - const experimental = active.filter( - (f) => f.experimental && !f.enableDate && !f.enableAllDates - ); - const noDate = active.filter( - (f) => !f.experimental && !f.enableDate && !f.enableAllDates - ); - - let out = `## All Compatibility Flags (${active.length} active, ${obsolete.length} obsolete)\n\n`; - - if (dated.length > 0) { - out += `### Date-gated (${dated.length})\n\n`; - for (const f of dated) { - const d = f.enableAllDates ? 'ALL DATES' : f.enableDate; - const extra: string[] = []; - if (f.neededByFl) extra.push('FL'); - if (f.experimental) extra.push('experimental'); - if (f.impliedBy) extra.push(`implied by ${f.impliedBy}`); - const suffix = extra.length > 0 ? ` (${extra.join(', ')})` : ''; - out += `- **${d}**: \`${f.enableFlag || f.fieldName}\`${suffix}\n`; - } - } - - if (noDate.length > 0) { - out += `\n### Opt-in only — no default date (${noDate.length})\n\n`; - for (const f of noDate) { - const extra: string[] = []; - if (f.impliedBy) extra.push(`implied by ${f.impliedBy}`); - const suffix = extra.length > 0 ? ` (${extra.join(', ')})` : ''; - out += `- \`${f.enableFlag || f.fieldName}\`${suffix}\n`; - } - } - - if (experimental.length > 0) { - out += `\n### Experimental — requires --experimental (${experimental.length})\n\n`; - for (const f of experimental) { - out += `- \`${f.enableFlag || f.fieldName}\`\n`; - } - } - - return out; -} - -function formatAtDate(flags: CompatFlag[], date: string): string { - const active = flags.filter((f) => !f.obsolete); - - const enabled: CompatFlag[] = []; - const notYetEnabled: CompatFlag[] = []; - const optInOnly: CompatFlag[] = []; - const experimental: CompatFlag[] = []; - - for (const f of active) { - if (f.enableAllDates) { - enabled.push(f); - } else if (f.enableDate) { - if (f.enableDate <= date) { - enabled.push(f); - } else { - notYetEnabled.push(f); - } - } else if (f.experimental) { - experimental.push(f); - } else { - optInOnly.push(f); - } - } - - let out = `## Flags at compatibility date "${date}"\n\n`; - out += `- **${enabled.length}** enabled by default\n`; - out += `- **${notYetEnabled.length}** not yet enabled (future date)\n`; - out += `- **${optInOnly.length}** opt-in only (no date set)\n`; - out += `- **${experimental.length}** experimental\n\n`; - - if (enabled.length > 0) { - out += `### Enabled by default (${enabled.length})\n\n`; - for (const f of enabled.sort((a, b) => - (a.enableDate || '').localeCompare(b.enableDate || '') - )) { - const d = f.enableAllDates ? 'all' : f.enableDate; - out += `- \`${f.enableFlag || f.fieldName}\` (since ${d})\n`; - } - } - - if (notYetEnabled.length > 0) { - out += `\n### Not yet enabled — date is after "${date}" (${notYetEnabled.length})\n\n`; - for (const f of notYetEnabled.sort((a, b) => - (a.enableDate || '').localeCompare(b.enableDate || '') - )) { - out += `- \`${f.enableFlag || f.fieldName}\` (${f.enableDate})\n`; - } - } - - if (optInOnly.length > 0) { - out += `\n### Opt-in only (${optInOnly.length})\n\n`; - for (const f of optInOnly) { - out += `- \`${f.enableFlag || f.fieldName}\`\n`; - } - } - - if (experimental.length > 0) { - out += `\n### Experimental (${experimental.length})\n\n`; - for (const f of experimental) { - out += `- \`${f.enableFlag || f.fieldName}\`\n`; - } - } - - return out; -} +export default toOpencodeTool(tool, compatDateAt); diff --git a/.opencode/tools/next-capnp-ordinal.ts b/.opencode/tools/next-capnp-ordinal.ts index 56f93721d..07250988a 100644 --- a/.opencode/tools/next-capnp-ordinal.ts +++ b/.opencode/tools/next-capnp-ordinal.ts @@ -1,228 +1,6 @@ +// The implementation is shared with Claude Code; see ../lib/tool-def.ts. import { tool } from '@opencode-ai/plugin'; -import path from 'path'; -import { runCapnpcCapnp, resolveCapnpPath } from './capnp.ts'; +import { toOpencodeTool } from '../lib/tool-def.ts'; +import { nextCapnpOrdinal } from '../lib/next-capnp-ordinal.ts'; -export default tool({ - description: - "Find the next available field ordinal (@N) in a Cap'n Proto struct. " + - 'Uses the capnp compiler (capnpc-capnp) to parse the schema canonically. ' + - 'Use before adding new fields to .capnp files (especially compatibility-date.capnp) ' + - 'to avoid ordinal collisions.', - args: { - file: tool.schema - .string() - .describe('Path to .capnp file (absolute, or relative to project root)'), - struct: tool.schema - .string() - .optional() - .describe( - "Struct name (e.g., 'CompatibilityFlags'). Omit to list all structs." - ), - }, - async execute(args, ctx) { - const root = ctx.worktree || ctx.directory; - const filePath = resolveCapnpPath(root, args.file); - - const result = await runCapnpcCapnp(root, filePath); - if (typeof result !== 'string') return result.error; - - const structs = parseCapnpOutput(result); - - if (!args.struct) { - return listStructs(structs, filePath); - } - - // Support dotted names like "Worker.Module" - const target = - structs.find((s) => s.qualifiedName === args.struct) || - structs.find((s) => s.name === args.struct); - - if (!target) { - const available = structs.map((s) => s.qualifiedName).join(', '); - return `Struct '${args.struct}' not found in ${path.basename(filePath)}\n\nAvailable: ${available}`; - } - - return formatResult(target, filePath); - }, -}); - -// --- Output parsing --- - -interface FieldInfo { - name: string; - ordinal: number; - type: string; - annotations: string[]; - raw: string; -} - -interface StructInfo { - name: string; - qualifiedName: string; - fields: FieldInfo[]; - declaredAnnotations: string[]; -} - -function parseCapnpOutput(output: string): StructInfo[] { - const lines = output.split('\n'); - const allStructs: StructInfo[] = []; - - const nameStack: string[] = []; - let currentStruct: StructInfo | null = null; - - let depth = 0; - const structDepths: number[] = []; - - for (const line of lines) { - const opens = (line.match(/\{/g) || []).length; - const closes = (line.match(/\}/g) || []).length; - - // Check for struct opening - const structMatch = line.match(/struct\s+(\w+)\s+@0x[\da-fA-F]+\s*\{/); - if (structMatch) { - if (currentStruct) { - allStructs.push(currentStruct); - } - - const name = structMatch[1]; - nameStack.push(name); - structDepths.push(depth); - - currentStruct = { - name, - qualifiedName: nameStack.join('.'), - fields: [], - declaredAnnotations: [], - }; - - depth += opens; - continue; - } - - depth += opens; - - // Field declarations: " fieldName @N :Type ..." - const fieldMatch = line.match(/^\s+(\w+)\s+@(\d+)\s+:(\S+)/); - if (fieldMatch && currentStruct) { - const annotations: string[] = []; - const annoRe = /\$(\w+)\(([^)]*)\)/g; - let m; - while ((m = annoRe.exec(line)) !== null) { - annotations.push(`$${m[1]}(${m[2]})`); - } - - const raw = line - .trim() - .replace(/\s+#\s.*$/, '') - .replace(/;$/, ''); - - currentStruct.fields.push({ - name: fieldMatch[1], - ordinal: parseInt(fieldMatch[2], 10), - type: fieldMatch[3].replace(/[;,]$/, ''), - annotations, - raw, - }); - } - - // Annotation declarations inside a struct - const annoDecl = line.match(/^\s+annotation\s+(\w+)\s+@0x/); - if (annoDecl && currentStruct) { - currentStruct.declaredAnnotations.push(annoDecl[1]); - } - - depth -= closes; - - // Check if we've closed a struct - while ( - structDepths.length > 0 && - depth <= structDepths[structDepths.length - 1] - ) { - if (currentStruct) { - allStructs.push(currentStruct); - currentStruct = null; - } - structDepths.pop(); - nameStack.pop(); - - if (nameStack.length > 0) { - const parentName = nameStack.join('.'); - const parentIdx = allStructs.findIndex( - (s) => s.qualifiedName === parentName - ); - if (parentIdx >= 0) { - currentStruct = allStructs[parentIdx]; - allStructs.splice(parentIdx, 1); - } - } - } - } - - if (currentStruct) { - allStructs.push(currentStruct); - } - - return allStructs; -} - -// --- Formatting --- - -function listStructs(structs: StructInfo[], filePath: string): string { - if (structs.length === 0) { - return `No structs found in ${path.basename(filePath)}`; - } - let result = `## Structs in ${path.basename(filePath)}\n\n`; - for (const s of structs) { - if (s.fields.length === 0) { - result += `- **${s.qualifiedName}**: no fields\n`; - } else { - const max = Math.max(...s.fields.map((f) => f.ordinal)); - result += `- **${s.qualifiedName}**: ${s.fields.length} fields, highest @${max}, next @${max + 1}\n`; - } - } - return result; -} - -function formatResult(target: StructInfo, filePath: string): string { - if (target.fields.length === 0) { - return `Struct '${target.qualifiedName}' in ${path.basename(filePath)} has no fields.`; - } - - const sorted = [...target.fields].sort((a, b) => a.ordinal - b.ordinal); - const maxOrdinal = sorted[sorted.length - 1].ordinal; - const nextOrdinal = maxOrdinal + 1; - - const used = new Set(target.fields.map((f) => f.ordinal)); - const gaps: number[] = []; - for (let i = 0; i <= maxOrdinal; i++) { - if (!used.has(i)) gaps.push(i); - } - - const lastFields = sorted.slice(-5); - - let out = `## ${target.qualifiedName} in ${path.basename(filePath)}\n\n`; - out += `**Next available ordinal: @${nextOrdinal}**\n\n`; - out += `- Total fields: ${target.fields.length}\n`; - out += `- Highest ordinal: @${maxOrdinal} (\`${sorted[sorted.length - 1].name}\`)\n`; - - if (gaps.length > 0) { - out += `- Gaps: ${gaps.map((g) => `@${g}`).join(', ')}\n`; - out += ` (Likely obsolete -- do NOT reuse)\n`; - } - - if (target.declaredAnnotations.length > 0) { - out += `- Annotations: ${target.declaredAnnotations.join(', ')}\n`; - } - - out += `\n### Last ${lastFields.length} fields\n\n`; - for (const f of lastFields) { - out += `- \`${f.raw}\`\n`; - } - - out += `\n### Usage\n\n`; - out += '```capnp\n'; - out += ` yourNewField @${nextOrdinal} :Bool\n`; - out += '```\n'; - - return out; -} +export default toOpencodeTool(tool, nextCapnpOrdinal); diff --git a/AGENTS.md b/AGENTS.md index f4b564e85..40f740dd9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -12,6 +12,10 @@ Subdirectory `AGENTS.md` files provide component-specific context (key classes, - If checked out as a submodule, be aware that there is additional documentation and context in the root of that repository that is not present here. Look for the `../../README.md`, `../../AGENTS.md`, and other markdown files in the root of the parent repository. +- Custom tools (`next-capnp-ordinal`, `compat-date-at`) are defined in `.opencode/lib/`. opencode + loads them natively; Claude Code reaches them through the `workerd` MCP server registered in + `.mcp.json`, which needs Node 22.18 or later on `PATH` (for TypeScript type stripping). With an + older Node, the server fails to start and the tools are missing. ## Project Overview