jjbrunton
633bb0ec04
Split monolithic chat service into modular structure with Matrix client support, extract web server into per-resource route modules, introduce bootstrap/main-loop separation, and add comprehensive vitest coverage across services, repositories, and utilities. Adds project docs and CLAUDE.md agent instructions.
49 lines
2.7 KiB
Markdown
49 lines
2.7 KiB
Markdown
# 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`.
|