fix(doctor): recommend 'bd prune' instead of nonexistent 'bd cleanup' (#5829)

* fix(doctor): recommend 'bd prune' instead of nonexistent 'bd cleanup'

The Large Database check, its agent enrichment, the stale-closed-issues
enrichment, the Dolt perf recommendations, and the doctor --fix advisory
all told users to run 'bd cleanup', which is not a root-level command in
this build (cleanup lives under 'bd admin cleanup'). The operator-facing
lifecycle command is 'bd prune', whose --older-than flag takes durations
like 90d and which previews by default (--force to delete) — a better fit
for advice the doctor explicitly refuses to auto-fix because it deletes
data.

Extract largeDatabaseWarning so the remedy string is pinned by a test,
and pin the two enrichments' command lists likewise.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* docs(messaging): replace stale ephemeral cleanup commands

Update the remaining live messaging examples to use the current wisp-scoped bd purge command and duration syntax.

Agent-Signature: Codex-unknown-model-unknown-reasoning on behalf of Klas Hesselman

---------

Co-authored-by: Klas Hesselman <211416696+swedeinasia-flow@users.noreply.github.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
swedeinasia-flow 2026-08-20 20:30:47 +08:00 • committed by GitHub
commit 857723a17a
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
7 changed files with 67 additions and 15 deletions

View file

@ -216,7 +216,7 @@ func enrichLargeDatabase(dc DoctorCheck) agentEnrichment {
explanation: fmt.Sprintf("The database has accumulated many closed issues: %s. This may cause performance degradation in list/search operations. Pruning is optional and destructive.", dc.Message),
observed: dc.Message,
expected: "Closed issue count below configured threshold",
commands: []string{"bd cleanup --older-than 90"},
commands: []string{"bd prune --older-than 90d"},
sourceFiles: []string{"cmd/bd/doctor/database.go:CheckDatabaseSize"},
}
}
@ -521,7 +521,7 @@ func enrichStaleClosedIssues(dc DoctorCheck) agentEnrichment {
explanation: fmt.Sprintf("Stale closed issues: %s. Old closed issues can be pruned to reduce database size and improve query performance.", dc.Message),
observed: dc.Message + "\n" + dc.Detail,
expected: "Closed issues are within acceptable age/count thresholds",
commands: []string{"bd cleanup --older-than 90"},
commands: []string{"bd prune --older-than 90d"},
sourceFiles: []string{"cmd/bd/doctor/maintenance.go:CheckStaleClosedIssues"},
}
}

View file

@ -37,3 +37,29 @@ func TestEnrichFreshClone_WithSyncRemoteMentionsBootstrapAndFallback(t *testing.
t.Fatalf("expected sync.remote fallback command, got %#v", enrichment.commands)
}
}
// TestPruneEnrichmentsRecommendRealCommand pins the agent-facing pruning
// advice to a command that exists: these enrichments used to suggest
// 'bd cleanup', which is not a root-level command in this build (cleanup
// lives under 'bd admin cleanup'). 'bd prune --older-than 90d' previews by
// default, matching the "optional and destructive" framing.
func TestPruneEnrichmentsRecommendRealCommand(t *testing.T) {
enrichments := map[string]agentEnrichment{
"Large Database": enrichLargeDatabase(DoctorCheck{Message: "6000 closed issues (threshold: 5000)"}),
"Stale Closed Issues": enrichStaleClosedIssues(DoctorCheck{Message: "5000 stale closed issues"}),
}
for name, enrichment := range enrichments {
if len(enrichment.commands) == 0 {
t.Errorf("%s enrichment has no commands", name)
continue
}
for _, cmd := range enrichment.commands {
if strings.Contains(cmd, "bd cleanup") {
t.Errorf("%s enrichment recommends nonexistent 'bd cleanup': %q", name, cmd)
}
}
if !strings.HasPrefix(enrichment.commands[0], "bd prune") {
t.Errorf("%s enrichment should recommend 'bd prune', got %#v", name, enrichment.commands)
}
}
}

View file

@ -498,7 +498,7 @@ func isNoDbModeConfigured(beadsDir string) bool {
// CheckDatabaseSize warns when the database has accumulated many closed issues.
// This is purely informational - pruning is NEVER auto-fixed because it
// permanently deletes data. Users must explicitly run 'bd cleanup' to prune.
// permanently deletes data. Users must explicitly run 'bd prune' to prune.
//
// Config: doctor.suggest_pruning_issue_count (default: 5000, 0 = disabled)
//
@ -577,13 +577,7 @@ func checkDatabaseSizeWithStore(store *dolt.DoltStore) DoctorCheck {
}
if stats.ClosedIssues > threshold {
return DoctorCheck{
Name: "Large Database",
Status: StatusWarning,
Message: fmt.Sprintf("%d closed issues (threshold: %d)", stats.ClosedIssues, threshold),
Detail: "Large number of closed issues may impact performance",
Fix: "Consider running 'bd cleanup --older-than 90' to prune old closed issues",
}
return largeDatabaseWarning(stats.ClosedIssues, threshold)
}
return DoctorCheck{
@ -592,3 +586,17 @@ func checkDatabaseSizeWithStore(store *dolt.DoltStore) DoctorCheck {
Message: fmt.Sprintf("%d closed issues (threshold: %d)", stats.ClosedIssues, threshold),
}
}
// largeDatabaseWarning builds the over-threshold Large Database check. Split
// out so tests can pin the recommended remedy to a command that actually
// exists: 'bd prune' is the root-level lifecycle command ('cleanup' only
// exists as 'bd admin cleanup').
func largeDatabaseWarning(closedIssues, threshold int) DoctorCheck {
return DoctorCheck{
Name: "Large Database",
Status: StatusWarning,
Message: fmt.Sprintf("%d closed issues (threshold: %d)", closedIssues, threshold),
Detail: "Large number of closed issues may impact performance",
Fix: "Consider running 'bd prune --older-than 90d' to prune old closed issues (preview; add --force to delete)",
}
}

View file

@ -210,3 +210,21 @@ func setupDoctorBareParentWorktree(t *testing.T) (string, string) {
return bareDir, featureWorktreeDir
}
// TestLargeDatabaseWarningRecommendsRealCommand pins the Large Database
// remedy to a command that exists: the check used to recommend 'bd cleanup',
// which is not a root-level command in this build (cleanup lives under
// 'bd admin cleanup'); the operator-facing lifecycle command is 'bd prune'.
func TestLargeDatabaseWarningRecommendsRealCommand(t *testing.T) {
dc := largeDatabaseWarning(6000, 5000)
if dc.Status != StatusWarning {
t.Fatalf("expected StatusWarning, got %v", dc.Status)
}
if strings.Contains(dc.Fix, "bd cleanup") {
t.Fatalf("Large Database fix recommends nonexistent 'bd cleanup': %q", dc.Fix)
}
if !strings.Contains(dc.Fix, "bd prune") {
t.Fatalf("Large Database fix should recommend 'bd prune': %q", dc.Fix)
}
}

View file

@ -361,7 +361,7 @@ func assessDoltPerformance(metrics *DoltPerfMetrics) {
// Check database size
if metrics.TotalIssues > 5000 && metrics.ClosedIssues > 4000 {
recommendations = append(recommendations, "Many closed issues. Consider 'bd cleanup' to prune old issues.")
recommendations = append(recommendations, "Many closed issues. Consider 'bd prune --older-than 90d' to prune old issues.")
}
if len(warnings) == 0 {

View file

@ -363,7 +363,7 @@ func applyFixList(path string, fixes []doctorCheck) {
continue
case "Large Database":
// No auto-fix: pruning deletes data, must be user-controlled
fmt.Printf(" ⚠ Run 'bd cleanup --older-than 90' to prune old closed issues\n")
fmt.Printf(" ⚠ Run 'bd prune --older-than 90d' to preview prunable closed issues (add --force to delete)\n")
continue
case "Legacy MQ Files":
err = doctor.FixStaleMQFiles(path)

View file

@ -74,13 +74,13 @@ Messages marked `ephemeral: true` are transient - they can be bulk-deleted after
```bash
# Clean up closed ephemeral messages
bd cleanup --ephemeral --force
bd purge --force
# Preview what would be deleted
bd cleanup --ephemeral --dry-run
bd purge --dry-run
# Only delete ephemeral messages older than 7 days
bd cleanup --ephemeral --older-than 7 --force
bd purge --older-than 7d --force
```
Ephemeral messages are: