# Codewalk District

Multi-agent workspace for orchestrating multiple Claude Code agents.

## Database

Schema is defined in `src/db/schema.ts` using drizzle-orm. Migrations are managed by drizzle-kit.

See [docs/database-migrations.md](docs/database-migrations.md) for the full migration workflow, rules, and commands.

Key rule: **never use raw SQL for schema initialization.** Always use `drizzle-kit generate` and the migration system.

## Logging

Structured logging via pino. See [docs/logging.md](docs/logging.md) for full details.

Key rule: use `createModuleLogger()` from `src/logger/index.ts` for backend logging. Keep `console.log` for CLI user-facing output only.

## Build

After completing any change to server-side code (`src/**`), rebuild and re-link the `cw` binary:

```sh
npm run build && npm link
```

## Testing

### Unit Tests

```sh
npm test
```

### E2E Tests (Real CLI)

Real provider integration tests call actual CLI tools and incur API costs. They are **skipped by default**.

```sh
# Claude tests (~$0.50, ~3 min)
REAL_CLAUDE_TESTS=1 npm test -- src/test/integration/real-providers/ --test-timeout=300000

# Codex tests only
REAL_CODEX_TESTS=1 npm test -- src/test/integration/real-providers/codex-manager.test.ts --test-timeout=300000

# Both providers
REAL_CLAUDE_TESTS=1 REAL_CODEX_TESTS=1 npm test -- src/test/integration/real-providers/ --test-timeout=300000
```

Test files in `src/test/integration/real-providers/`:
- `claude-manager.test.ts` - Spawn, output parsing, session resume
- `schema-retry.test.ts` - Schema validation, JSON extraction, retry logic
- `crash-recovery.test.ts` - Server restart simulation
- `codex-manager.test.ts` - Codex provider tests