cursorrules

Claude IDE Bridge — Cursor Rules

Build

• Run npm run build for bridge, cd vscode-extension && npm run build && npm run package for extension.
• Run npx biome check . before every commit.
• Run npm test before every commit.
• Always rebuild bridge + extension + VSIX before testing changes.

Tool Pattern

• Create tools using createXxxTool(deps) returning { schema, handler }.
• Register every tool in src/tools/index.ts.
• Set extensionRequired: true if the tool needs the VS Code extension.
• Tool names must match /^[a-zA-Z0-9_]+$/.
• Use readOnlyHint: true in annotations for tools that do not modify state.
• Never throw from a tool handler — catch and return { content: [...], isError: true }.

Extension Handlers

• Create handlers as standalone async functions.
• Register in vscode-extension/src/handlers/index.ts.
• All ws.send() calls must use safeSend() or readyState check + try-catch.

Error Handling

• Tool execution errors: return isError: true in content blocks. See docs/adr/0004-tool-errors-as-content.md.
• Protocol errors: use ErrorCodes (JSON-RPC -32xxx). Never mix the two.
• Never use JSON-RPC error codes in tool handlers.

Input Validation

• All tool arguments are validated by AJV schemas at the transport layer.
• Use resolveFilePath() for any user-supplied path — blocks null bytes, symlinks, and workspace escapes.
• Use isValidRef() for git ref arguments — blocks leading-dash refs.
• Clipboard operations enforce 1MB cap via Buffer.byteLength.
• searchAndReplace rejects null bytes and --prefixed glob patterns.

Security

• runCommand only executes allowlisted commands. Interpreter commands (node, python, bash) are permanently blocked.
• sendHttpRequest blocks private/loopback IPs (SSRF). DNS pre-resolves hostnames. Host header overridden after user headers.
• Never include auth tokens, IPs, or domain names in source code or documentation.
• Lock files use O_EXCL creation (symlink attack prevention) and chmod 0o600.