CLI Rearchitect Story 2: db-status Migration PoC (Phase 0)

[grimlockbot]

Summary

Migrate the db-status command to use CommandContext as a proof-of-concept. Fix the singleton database import. Write integration tests.

Parent Epic: #172
Phase: 0
Priority: 2
Depends On: Story 1: Core Infrastructure Types

---

Agent Instructions

Before You Start

1. Read packages/cli/PROGRESS.md for status of prior stories in this chain
2. Read docs/CONTEXT.md for project bootstrap
3. Read the parent epic Epic: Rearchitect CLI as Agent-First Compiled Binary #172 for full architecture context
4. Read docs/CONVENTIONS.md and docs/TESTING.md for code standards
5. Run bun run check-types && bun run test to verify clean baseline

Task

Migrate the db-status command to use CommandContext as a proof-of-concept, demonstrating the pattern all other commands will follow.

1. createTestContext() helper:

   • Returns a CommandContext with captured stdout/stderr as string buffers
   • Allows inspection: testCtx.getStdout(), testCtx.getStderr()
   • Uses a no-op AbortController
   • Mock secrets provider that returns env vars

2. Migrate db-status:

   • Current: imports database singleton directly, uses console.log
   • Target: receives CommandContext, uses ctx.stdout.write(), gets db via lazy getDb()
   • Add error handling: connection failure → DatabaseError with suggestion
   • Add timeout handling: use ctx.signal for AbortController timeout

3. Integration tests:

   • Table-driven tests: success case, connection failure, timeout
   • Use createTestContext() to capture output
   • Assert exit codes and output content

TDD Approach (Mandatory)

1. Write the failing test FIRST
2. Implement the minimum code to make it pass
3. Refactor for clarity
4. Run validation: bun run check-types && bun run test
5. Repeat for each acceptance criterion

Files to Create/Modify

• packages/cli/src/commands/db-status.ts — Rewrite to accept CommandContext
• packages/cli/src/index.ts — Wire db-status to use createContext()
• packages/cli/tests/integration/commands/db-status.test.ts
• packages/cli/tests/helpers/test-context.ts — createTestContext() helper that captures stdout/stderr

Acceptance Criteria

• db-status uses CommandContext (no direct console.log or database singleton)
• db-status handles connection failure with DatabaseError + suggestion
• createTestContext() helper works for capturing command output
• Table-driven integration tests cover happy + error paths
• All new code has corresponding tests
• bun run check-types passes with zero errors
• bun run test passes with zero failures
• No regressions in existing tests

Progress Tracking

• Update packages/cli/PROGRESS.md after each major milestone within this story
• Format: ## Story 2: db-status Migration PoC\n- [x] completed step\n- [ ] pending step
• Commit progress regularly with descriptive messages: feat(cli): [what changed]

On Completion

1. Ensure all acceptance criteria are checked off
2. Run final validation: bun run check-types && bun run test
3. Write a completion summary at the bottom of packages/cli/PROGRESS.md
4. Commit with message: feat(cli): complete story 2 - db-status migration PoC

---

Ralph Loop Config

• Validation Command: bun run check-types && bun run test
• Priority: 2