feat: add doctor command (#151)

[asphaltbuffet]

Closes #151

Implements the full doctor command across the storage, eventbus, app, and command layers.

What's included

internal/store — TruncateEntitiesTx (#157)

Transactional DELETE of all entities_current rows. Called exclusively by TruncateAndReplay during projection rebuilds.

internal/eventbus — TruncateAndReplay (#159)

Rebuilds entities_current from the full event log without writing new events. Uses a separate applyEventProjectionOnlyTx dispatch path to avoid growing the event log on reparent replay (see ADR-0009).

internal/app — doctor methods (#158, #160, #161)

• ValidateEventLog — checks each event for known type, unmarshalable payload, non-empty EntityID, and valid entity.created fields
• CheckProjectionConsistency — logical diff between event log and projection: phantom rows, missing rows, stale last_event_id
• TruncateAndReplay — thin delegation to bus.TruncateAndReplay

cmd/doctor — command layer (#162, #163)

Follows the established NewDefaultXxxCmd / NewXxxCmd(app interface) / buildXxxCmd / runXxx pattern.

Run order:

1. Config file validation + DB path resolution (always runs)
2. ValidateEventLog
3. CheckProjectionConsistency
4. --rebuild: TruncateAndReplay if clean, or with --force (-f)

Flags: --rebuild, --force / -f, --json

Key behaviours:

• All checks run unless infrastructure fails (DB can't be opened) — config issues don't block DB checks (ADR-0010)
• Exits non-zero when any issue found; prints OK when all clear
• --rebuild skipped when issues present unless --force is set; exit is still non-zero when issues were found regardless of rebuild outcome
• --json emits a single document: {"healthy": bool, "issue_count": int, "issues": [...], "rebuilt": int|omitted} (ADR-0011)

internal/cli — OutputWriter.Issue

New method rendering [kind] description in warning orange. Always shown regardless of quiet mode. JSON mode emits {"kind": ..., "description": ...}. Issue #192 tracks aligning config check to the same convention.

Docs

• ADR-0010: doctor check abort rule
• ADR-0011: doctor --json output shape
• CONTEXT.md: Healthy glossary entry

[asphaltbuffet]

Code review

Found 2 issues:

1. buildProjectionSets treats soft-deleted entities as hard-deleted, causing false-positive "phantom row" errors on every removed entity

EntityRemovedEvent is a soft-delete: handleEntityRemoved sets status = removed and leaves the row in entities_current. ListAllEntities returns all rows including removed ones. But buildProjectionSets excludes removed entities from expectedPresent, so checkProjectionRows flags every legitimately removed entity as a phantom projection row — reporting a broken projection on any healthy database that has ever had an entity removed.

wherehouse/internal/app/doctor.go

Lines 136 to 146 in 3494c24

	created[id] = true
	case inventory.EntityRemovedEvent:
	removed[id] = true
	}
	}
	expectedPresent := make(map[string]bool, len(created))
	for id := range created {
	if !removed[id] {
	expectedPresent[id] = true
	}

2. runConfigCheck has a stale doc comment claiming it returns bool; function actually returns []app.DoctorIssue

The comment at line 96 reads "Returns true if any config issues were found" — the function signature was changed to return a slice but this comment block was not updated. The duplicate comment block immediately below (lines 97–98) is the correct version.

wherehouse/cmd/doctor/doctor.go

Lines 95 to 99 in 3494c24

	// runConfigCheck validates config files and DB path resolution.
	// Returns true if any config issues were found.
	// runConfigCheck validates config files and DB path resolution.
	// Returns any config issues found.
	func runConfigCheck(out *cli.OutputWriter, cfg *config.Config) []app.DoctorIssue {

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}