RedditBot/CLAUDE.md

RedditBot — agent instructions

Test-first workflow (MANDATORY)

This applies to every code-changing task in this repo. Sub-agents inherit it.

1. Before implementation — establish the baseline

Run the full test suite first:

npm test

Note the count of passing / failing tests. Do not start implementing until you have this baseline. If something is already failing, surface it to the user before touching it — don't silently inherit pre-existing failures into your scope.

2. During implementation — update tests alongside code

• When you change a function's behavior, update or add the test for it in the same change.
• When you change a function's signature, fix the call sites in tests in the same change.
• When you introduce a new module, add a test for it in tests/<name>.test.ts.
• If a test fails because the test is wrong (stale assertion, ESM mocking issue, real env leaking in), fix the test. If it fails because the code is wrong, fix the code.
• Never delete a test to make it pass. Either fix the assertion to reflect intended behavior, or fix the code.

3. Before reporting done — confirm green

Re-run the full suite:

npm test
npx tsc --noEmit

Both must be clean before you say the task is done. If either is failing, either fix it or explicitly call out the regression in your final message — do not report success and leave a broken suite.

If tests pass count went down vs. the baseline you took in step 1, that is a regression. Treat it as a blocker.

Why this matters

The test suite is the only automated safety net for this project (no CI yet, no integration tests). Drift here means real bugs ship. Past incident: a refactor went out with 129 pre-existing test failures undetected — they had been broken for weeks because nobody re-ran the suite.

Project notes for agents

• Runtime: TypeScript with module: NodeNext. Imports use .js extensions even for .ts files.
• Tests: vitest, globals: false so describe/it/expect/beforeEach/afterEach must be imported explicitly.
• The OpenRouter, MediaService, ProcessorService, RateLimiter, and MonitorService constructors accept optional last parameters for test-injectable dependencies (mock clients, temp dirs, fake fetchers, shortened timing). Use them rather than vi.mock() of ESM modules — the namespace-mocking pattern fails under NodeNext.
• Shadow-DOM scraping for chat.reddit.com lives in src/services/chat/scrapers.ts as typed page.evaluate functions. The myUsername parameter is threaded through from config.reddit.username.
• Some .env vars (notably OPENROUTER_API_KEY) are auto-loaded via dotenv.config() at module import. Tests that touch loadConfig must snapshot+clear these in beforeEach and restore in afterEach.