node9-proxy: Instructions file for Claude Code

Node9 Proxy — Claude Code Rules

PR Checklist (required before every commit)

Before committing or opening a PR, verify all of the following:

• New behavior has a test that fails without the change
• npm test passes (455+ tests)
• npm run typecheck passes
• npm run lint passes (catches require() imports, unused vars, etc.)
• npm run format:check passes (run npm run format to fix)
• No console.log in hook or proxy code paths — use console.error (stdout must stay clean for JSON-RPC / MCP)
• Review your own diff before committing — run git diff and check for logical correctness issues that automated checks miss: missing return after res.end(), silent catch {} blocks swallowing errors, double event-listener registration, fall-through in route handlers

Test Rules

Every bug fix must ship with a regression test. Write the failing test first, then fix the code. This proves you understood the bug and prevents silent regressions.

Integration tests are required for:

• Any command that runs as a subprocess (check, log, proxy)
• Anything that touches stdout/stderr (protocol correctness)
• Any file write (audit.log, hook-debug.log, snapshot)
• Any behavior that depends on cwd or HOME

Use spawnSync against dist/cli.js (see src/__tests__/check.integration.test.ts for the pattern). Always assert result.error and result.status — a silent spawn failure must not pass tests.

Unit tests with mocked fs/getConfig are not sufficient for hook commands or the proxy. They cannot catch protocol bugs, filesystem path bugs, or exit code bugs.

Code Rules

Audit writes must happen before config loads. In hook commands, fs.appendFileSync(auditLog, ...) must come before any getConfig() call. A config failure must never silently skip the audit entry.

Validate external path inputs before filesystem use. Any cwd, file_path, or similar value from hook payloads must be validated (path.isAbsolute()) before being passed to getConfig(), path.join(), or fs calls. Use payload.cwd || undefined for empty-string guard, then path.isAbsolute() for traversal guard.