4656627a59
Snapshots were stale since migration 0008. Generated a schema-derived snapshot at 0032 so drizzle-kit generate works again (zero diff on current schema.ts). Also fixed migration 0032 to use statement-breakpoint separator required by better-sqlite3. - Added 0032_snapshot.json derived from current schema.ts - Fixed 0032 SQL to use --> statement-breakpoint between statements - Updated CLAUDE.md and database-migrations.md with correct workflow
65 lines
3.8 KiB
Markdown
65 lines
3.8 KiB
Markdown
# Codewalkers
|
||
|
||
Multi-agent workspace for orchestrating multiple AI coding agents working in parallel on a shared codebase.
|
||
|
||
**Architecture**: [docs/architecture.md](docs/architecture.md) — system diagram, module map, entity relationships, tech stack.
|
||
|
||
## Quick Reference
|
||
|
||
| Module | Docs | Path |
|
||
|--------|------|------|
|
||
| Agent (lifecycle, providers, accounts) | [docs/agent.md](docs/agent.md) | `apps/server/agent/` |
|
||
| Database (schema, repositories) | [docs/database.md](docs/database.md) | `apps/server/db/` |
|
||
| Server & API (tRPC procedures) | [docs/server-api.md](docs/server-api.md) | `apps/server/server/`, `apps/server/trpc/`, `apps/server/coordination/` |
|
||
| Frontend (React UI) | [docs/frontend.md](docs/frontend.md) | `apps/web/` |
|
||
| CLI & Config | [docs/cli-config.md](docs/cli-config.md) | `apps/server/cli/`, `apps/server/config/` |
|
||
| Dispatch & Events | [docs/dispatch-events.md](docs/dispatch-events.md) | `apps/server/dispatch/`, `apps/server/events/` |
|
||
| Git, Process, Logging | [docs/git-process-logging.md](docs/git-process-logging.md) | `apps/server/git/`, `apps/server/process/`, `apps/server/logger/`, `apps/server/logging/` |
|
||
| Preview (Docker deployments) | [docs/preview.md](docs/preview.md) | `apps/server/preview/` |
|
||
| Testing | [docs/testing.md](docs/testing.md) | `apps/server/test/` |
|
||
| Database Migrations | [docs/database-migrations.md](docs/database-migrations.md) | `drizzle/` |
|
||
| Logging Guide | [docs/logging.md](docs/logging.md) | `apps/server/logger/` |
|
||
|
||
Pre-implementation design docs are archived in `docs/archive/`.
|
||
|
||
## Key Rules
|
||
|
||
- **Database migrations**: Edit `apps/server/db/schema.ts`, then run `npx drizzle-kit generate`. Multi-statement migrations need `--> statement-breakpoint` between statements. See [docs/database-migrations.md](docs/database-migrations.md).
|
||
- **Logging**: Use `createModuleLogger()` from `apps/server/logger/index.ts`. Keep `console.log` for CLI user-facing output only.
|
||
- **Hexagonal architecture**: Repository ports in `apps/server/db/repositories/*.ts`, Drizzle adapters in `apps/server/db/repositories/drizzle/*.ts`. All re-exported from `apps/server/db/index.ts`.
|
||
- **tRPC context**: Optional repos accessed via `require*Repository()` helpers in `apps/server/trpc/routers/_helpers.ts`.
|
||
|
||
## UI Patterns
|
||
|
||
- **Shift+click to skip confirmation**: Destructive actions (delete task, etc.) show a `window.confirm()` dialog on click. Holding Shift bypasses the dialog and executes immediately. Apply this pattern to all new destructive buttons.
|
||
|
||
## Build
|
||
|
||
```sh
|
||
npm run build && npm link
|
||
```
|
||
|
||
Run after any change to server-side code (`apps/server/**`).
|
||
|
||
## Testing
|
||
|
||
```sh
|
||
npm test # Unit + E2E tests (no API cost)
|
||
CW_CASSETTE_RECORD=1 npm test -- <test-file> # Record new cassettes locally
|
||
REAL_CLAUDE_TESTS=1 npm test -- apps/server/test/integration/real-providers/ --test-timeout=300000 # Real provider tests (~$0.50)
|
||
|
||
# Record full-flow cassettes (one-time, costs ~$2–5 in API credits):
|
||
CW_CASSETTE_RECORD=1 npm test -- apps/server/test/integration/full-flow/full-flow-cassette.test.ts --test-timeout=3600000
|
||
# Commit the generated apps/server/test/cassettes/<hash>.json files afterward.
|
||
# Subsequent runs replay from cassettes at no cost: npm test
|
||
```
|
||
|
||
See [docs/testing.md](docs/testing.md) for details, including the **cassette system** for pipeline integration tests that run without API costs.
|
||
|
||
## Documentation Maintenance
|
||
|
||
**After every code change, update the relevant docs/ file.** Documentation must stay in sync with implementation. When adding a new module, table, tRPC procedure, component, or CLI command, update the corresponding doc. When refactoring, update affected docs and remove stale information.
|
||
|
||
# Committing
|
||
|
||
After completing & verifying changes always commit the changes. |