fix(show): explain that "not found" may mean deleted, not never-existed (#5802)

* fix(show): explain that "not found" may mean deleted, not never-existed (ga-m6inyb)

bd delete and wisp purge both remove a row (and its events) from the
live tables with no trace left behind, so `bd show` on a deleted or
purged id is byte-for-byte identical to one that never existed —
confirmed live (Gas Town HQ Dolt server) against two real archived-wisp
ids, and against dolt_history_wisps (always empty for wisps by design,
per the dolt_ignore comments throughout internal/storage/dolt).

An earlier draft of this fix tried to auto-detect the distinction via
bd's own commit history (store.History), but that scan has a
documented multi-second-to-timeout cost even on a healthy production
database (reproduced live: `bd history` timed out with "row read wait
bigger than connection timeout" on both a real archived wisp and a
made-up id on the same server) — wiring it into show's default
not-found path would regress the common typo case to fix a rarer one.
Wisps never have history at all regardless, so it wouldn't have
resolved the reported case either way.

Instead, the not-found message now says plainly that the id may have
existed and been removed, and points at `bd history <id>` as the
(separate, opt-in) way to check further — additive only: the JSON
"error" field text is unchanged, the new context lands in a "hint"
field; the direct-mode text path keeps "Issue %s not found" as its
first line and adds the hint as a second line.

Also found, filed separately, not fixed here: `make ci-pr-lint`
surfaces 2 pre-existing gosec findings in darwin/nonlinux-only files
that the Linux CI runner never lints (no darwin cross-lint pass,
unlike the existing Windows one) — confirmed present on a clean
origin/main checkout, unrelated to this change.

* fix(show): update contract-pinning tests for the new not-found hint (CI)

CI on PR #5802 caught 4 test corpora this change needed to update but I
missed locally (my earlier local run only matched tests named
TestShow*; these pin the SAME code path — reportIssueLookupFailure and
show.go's JSON not-found branch — under different names):

- cmd/bd/proxied_lookup_failure_test.go: TestProxiedLookupReportsMissingIssue
  (show / show --refs / show --children / reopen rows) and
  TestReportIssueLookupFailure both assert exact stderr text by design
  ("Their lines here are unchanged, and that is the point" — the
  file's own doc comment). Updated the 4 affected wantNotFound values
  to include the new hint, computed via showNotFoundHint() rather than
  duplicated as a literal, so the two can't drift independently.

- cmd/bd/protocol/testdata/corpus/{flat,envelope}/error.json and their
  manifest.json SHA-256 entries: the committed golden-file corpus for
  `bd show <missing> --json`. `make corpus-regen` needs Docker
  (unavailable here) to regenerate for real, so I independently
  reimplemented corpus.go's exact marshalCanonical encoding (same
  json.Encoder settings: SetEscapeHTML(false), 2-space indent) in a
  standalone program and confirmed both edited files are byte-for-byte
  identical to what that encoder produces, before hand-computing and
  writing the new SHA-256 manifest entries.

Two more matches from a repo-wide grep for the old exact string
(linear_test.go, update_claim_proxied_test.go) needed no change:
linear_test.go's is an unrelated subsystem's own literal message, and
update_claim_proxied_test.go asserts via strings.Contains, which the
purely-additive hint doesn't break.

Local verification (same commands as before, still Docker-less):
go build ./..., go vet ./cmd/bd/..., go vet -tags=integration, make
ci-pr-lint (2 pre-existing unrelated darwin-only gosec findings only),
and the full previously-failing test names plus a broader NotFound|
LookupFailure|Claim sweep — all green.

* docs(changelog): add [Unreleased] entry for the show not-found hint (ga-m6inyb)

Addresses reviewer bee-ghosttrack's second ask on PR #5802: "this adds a
line to one of bd's most common outputs and a new JSON field" needs a
CHANGELOG entry. Filed under Fixed, since the underlying bead is a bug
(archived and never-existed issues were indistinguishable via bd show).

Also documents, per the reviewer's first ask, that the direct-mode
single-ID not-found path's first line is not purely additive: it
changes from "Error fetching <id>: ..." to "Issue <id> not found" to
match the wording the other not-found paths already used.

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

---------

Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
Co-authored-by: Steve Yegge <steve.yegge@gmail.com>
This commit is contained in:
Athos Bernardes 2026-08-20 12:11:39 -03:00 • committed by GitHub
commit d871b5c54a
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
10 changed files with 191 additions and 15 deletions

View file

@ -140,6 +140,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
and never POST. Once the backlog has decayed empty, spawns stop entirely; a
machine that never enabled telemetry has no queue directory and never forks.
- **`bd show` on a deleted or purged issue no longer prints text identical to
an ID that never existed** (ga-m6inyb). `bd delete` and wisp `purge` both
remove a row (and its `events`) from the live tables with no trace left
behind, so "not found" was collapsing two states that call for opposite
responses — archived (success) and never-existed (possibly lost data) —
into one observable. This had a real cost: a gate-reviewer session showed
a legitimate issue successfully, hit an unrelated mysql i/o timeout on a
retry moments later, got the identical "not found" text for the same ID,
and reasonably concluded data had been lost — when the issue had simply
been archived in between. `bd show` on a missing ID now adds a second
line — `Hint: this ID may have never existed, or may reference a
deleted/purged record with no trace left in the live database — try 'bd
history <id>'` — pointing at the existing, opt-in `bd history <id>` for
anyone who wants to check further on a non-wisp issue (wisps are never
committed to history, purged or not, so there is no signal left to
recover for them). JSON output gains an additive `hint` field; the
existing `error` text is unchanged. **Direct-mode text output changes for
one path**: the single-ID not-found branch's first line changes from
`Error fetching <id>: no issue found matching "<id>"` to `Issue <id> not
found`, matching the wording the multi-ID and proxied-mode paths already
used (those two are unchanged aside from gaining the new second `Hint:`
line).
- **Explicit commits now sweep the entire working set and report no-ops
honestly.** In server mode, `bd vc commit` and `bd dolt commit` previously
routed through the config-excluding automatic-commit path, so out-of-band

View file

@ -1,6 +1,7 @@
{
"data": {
"error": "no issues found matching the provided IDs"
"error": "no issues found matching the provided IDs",
"hint": "some IDs may reference deleted/purged records with no trace left in the live database — try 'bd history <id>' to check"
},
"schema_version": 1
}

View file

@ -1,4 +1,5 @@
{
"error": "no issues found matching the provided IDs",
"hint": "some IDs may reference deleted/purged records with no trace left in the live database — try 'bd history <id>' to check",
"schema_version": 1
}

View file

@ -45,7 +45,7 @@
},
"envelope/error": {
"cmd": "bd show nonexistent-xyz-corpus --json",
"sha256": "f79e391ae3a508ae0ee6a7f63bd3708ac2140a8bcd9e6394a38992105c1c58de"
"sha256": "17d5eafb5a0147e81dca583ea572191a705ba793f5619c27d597705c299dcddd"
},
"envelope/list": {
"cmd": "bd list --all --json",
@ -113,7 +113,7 @@
},
"flat/error": {
"cmd": "bd show nonexistent-xyz-corpus --json",
"sha256": "29b5ecbc5404159e3a1e6a195aea7f2b444ba25b006108eb3c3d86e84e9eb531"
"sha256": "7d31206f17d193611086a67460f751f323b93ae4d8297861e680a2d4b444e116"
},
"flat/list": {
"cmd": "bd list --all --json",

View file

@ -192,7 +192,10 @@ var proxiedLookupCommands = []struct {
},
// show reports per id and keeps going, so its line has no "Error: "
// prefix; the non-zero exit comes from the empty result at the end.
wantNotFound: "Issue bd-missing not found",
// The second line is the ga-m6inyb hint: reportIssueLookupFailure
// no longer implies an absent id definitely never existed, since a
// deleted/purged one is observationally identical.
wantNotFound: "Issue " + stubMissingID + " not found\nHint: " + showNotFoundHint(stubMissingID),
wantHardErr: "Error fetching bd-missing: connection reset by peer",
},
{
@ -200,7 +203,7 @@ var proxiedLookupCommands = []struct {
run: func(ctx context.Context) error {
return runShowProxiedServer(showViewCmd("refs"), ctx, []string{stubMissingID})
},
wantNotFound: "Issue bd-missing not found",
wantNotFound: "Issue " + stubMissingID + " not found\nHint: " + showNotFoundHint(stubMissingID),
wantHardErr: "Error resolving bd-missing: connection reset by peer",
exitsZero: true,
},
@ -209,7 +212,7 @@ var proxiedLookupCommands = []struct {
run: func(ctx context.Context) error {
return runShowProxiedServer(showViewCmd("children"), ctx, []string{stubMissingID})
},
wantNotFound: "Issue bd-missing not found",
wantNotFound: "Issue " + stubMissingID + " not found\nHint: " + showNotFoundHint(stubMissingID),
wantHardErr: "Error resolving bd-missing: connection reset by peer",
exitsZero: true,
},
@ -238,7 +241,7 @@ var proxiedLookupCommands = []struct {
run: func(ctx context.Context) error {
return runReopenProxiedServer(&cobra.Command{}, ctx, []string{stubMissingID})
},
wantNotFound: "Issue bd-missing not found",
wantNotFound: "Issue " + stubMissingID + " not found\nHint: " + showNotFoundHint(stubMissingID),
wantHardErr: "Error resolving bd-missing: connection reset by peer",
},
{
@ -418,7 +421,8 @@ func TestReportIssueLookupFailure(t *testing.T) {
t.Run("absent id names the issue", func(t *testing.T) {
err := fmt.Errorf("%w: issue bd-gone", storage.ErrNotFound)
stderr := captureStderrDuring(t, func() { reportIssueLookupFailure("fetching", "bd-gone", err) })
if got, want := strings.TrimSpace(stderr), "Issue bd-gone not found"; got != want {
want := "Issue bd-gone not found\nHint: " + showNotFoundHint("bd-gone")
if got := strings.TrimSpace(stderr); got != want {
t.Errorf("stderr = %q, want %q", got, want)
}
})

View file

@ -14,6 +14,18 @@ import (
"github.com/steveyegge/beads/issueops"
)
// showNotFoundHint explains that an unresolved issue ID is not proof the ID
// never existed: bd delete and wisp purge both remove a row (and its
// events) from the live tables with no trace left behind, so a deleted or
// purged ID looks identical to one that was never created. bd history can
// sometimes tell the two apart via Dolt's commit history, but that scan is
// real, sometimes-slow work (and wisps are never committed to history at
// all), so it's offered as a pointer rather than run automatically here
// (ga-m6inyb).
func showNotFoundHint(id string) string {
return fmt.Sprintf("this ID may have never existed, or may reference a deleted/purged record with no trace left in the live database — try 'bd history %s'", id)
}
var showCmd = &cobra.Command{
Use: "show [id...] [--id=<id>...] [--current]",
Aliases: []string{"view"},
@ -121,7 +133,12 @@ var showCmd = &cobra.Command{
if result != nil {
result.Close()
}
fmt.Fprintf(os.Stderr, "Error fetching %s: %v\n", id, err)
if isNotFoundErr(err) {
fmt.Fprintf(os.Stderr, "Issue %s not found\n", id)
fmt.Fprintf(os.Stderr, "Hint: %s\n", showNotFoundHint(id))
} else {
fmt.Fprintf(os.Stderr, "Error fetching %s: %v\n", id, err)
}
continue
}
if result == nil || result.Issue == nil {
@ -129,6 +146,7 @@ var showCmd = &cobra.Command{
result.Close()
}
fmt.Fprintf(os.Stderr, "Issue %s not found\n", id)
fmt.Fprintf(os.Stderr, "Hint: %s\n", showNotFoundHint(id))
continue
}
issue := result.Issue
@ -258,7 +276,8 @@ var showCmd = &cobra.Command{
return jerr
}
} else {
return HandleErrorRespectJSON("no issues found matching the provided IDs")
return HandleErrorWithHintRespectJSON("no issues found matching the provided IDs",
"some IDs may reference deleted/purged records with no trace left in the live database — try 'bd history <id>' to check")
}
} else if foundCount > 0 {
maybeShowTip(store)

View file

@ -0,0 +1,36 @@
package main
import (
"strings"
"testing"
)
// TestShowNotFoundHint_PointsAtHistoryAndAcknowledgesDeletion guards
// ga-m6inyb: bd show's "not found" message must stop implying an ID never
// existed (it may have existed and been deleted/purged, which leaves no
// trace in the live tables) and must tell the reader how to check further.
func TestShowNotFoundHint_PointsAtHistoryAndAcknowledgesDeletion(t *testing.T) {
hint := showNotFoundHint("bd-1234")
if !strings.Contains(hint, "bd history bd-1234") {
t.Errorf("expected hint to name the exact id in a 'bd history' pointer, got: %q", hint)
}
if !strings.Contains(hint, "deleted") && !strings.Contains(hint, "purged") {
t.Errorf("expected hint to acknowledge deletion/purge as a possibility, got: %q", hint)
}
if !strings.Contains(hint, "never existed") {
t.Errorf("expected hint to name 'never existed' as only ONE of the possibilities, got: %q", hint)
}
}
func TestShowNotFoundHint_IsIDSpecific(t *testing.T) {
a := showNotFoundHint("bd-aaa")
b := showNotFoundHint("bd-bbb")
if a == b {
t.Errorf("expected hint text to vary with id, got identical output: %q", a)
}
if !strings.Contains(a, "bd-aaa") || strings.Contains(a, "bd-bbb") {
t.Errorf("expected hint for bd-aaa to reference only its own id, got: %q", a)
}
}

View file

@ -53,8 +53,11 @@ func TestShowProxiedJSONMissingIDKeepsItsContract(t *testing.T) {
if err == nil {
t.Error("a batch that found nothing exited zero")
}
if got, want := strings.TrimSpace(stderr), "Issue "+stubMissingID+" not found"; got != want {
t.Errorf("stderr = %q, want %q", got, want)
if got, want := strings.SplitN(stderr, "\n", 2)[0], "Issue "+stubMissingID+" not found"; got != want {
t.Errorf("stderr first line = %q, want %q", got, want)
}
if !strings.Contains(stderr, "bd history "+stubMissingID) {
t.Errorf("expected stderr to hint at checking 'bd history %s', got: %q", stubMissingID, stderr)
}
if strings.Contains(stderr, stubRawNoRows) {
t.Errorf("stderr leaks the raw driver sentinel: %q", stderr)
@ -99,7 +102,10 @@ func TestShowProxiedTextRouteDoesNotOpenAReader(t *testing.T) {
if err == nil {
t.Error("a batch that found nothing exited zero")
}
if got, want := strings.TrimSpace(stderr), "Issue "+stubMissingID+" not found"; got != want {
t.Errorf("stderr = %q, want %q", got, want)
if got, want := strings.SplitN(stderr, "\n", 2)[0], "Issue "+stubMissingID+" not found"; got != want {
t.Errorf("stderr first line = %q, want %q", got, want)
}
if !strings.Contains(stderr, "bd history "+stubMissingID) {
t.Errorf("expected stderr to hint at checking 'bd history %s', got: %q", stubMissingID, stderr)
}
}

View file

@ -159,6 +159,7 @@ func proxiedGetComments(ctx context.Context, uw uow.UnitOfWork, id string, isWis
func reportIssueLookupFailure(verb, id string, err error) {
if errors.Is(err, storage.ErrNotFound) {
fmt.Fprintf(os.Stderr, "Issue %s not found\n", id)
fmt.Fprintf(os.Stderr, "Hint: %s\n", showNotFoundHint(id))
return
}
fmt.Fprintf(os.Stderr, "Error %s %s: %v\n", verb, id, err)
@ -468,7 +469,8 @@ func runShowProxiedDefault(ctx context.Context, uw uow.UnitOfWork, in *showProxi
if len(allDetails) > 0 {
_ = outputJSON(allDetails)
} else {
return HandleErrorRespectJSON("no issues found matching the provided IDs")
return HandleErrorWithHintRespectJSON("no issues found matching the provided IDs",
"some IDs may reference deleted/purged records with no trace left in the live database — try 'bd history <id>' to check")
}
} else if foundCount == 0 {
return SilentExit()

View file

@ -136,3 +136,87 @@ func TestShow_NotFoundJSON(t *testing.T) {
t.Errorf("expected non-empty 'error' field in JSON response, got: %s", stdout)
}
}
// TestShow_NotFoundHintExplainsAmbiguity guards ga-m6inyb: a never-existed ID
// and a deleted/purged ID currently print the identical "not found" text, so
// a reader has no way to know the two are different situations (deleted
// records leave no trace in the live table — see internal/storage/dolt
// "dolt_ignored" wisp comments and the tombstone-removal history). The fix
// is not to fabricate a distinction bd cannot safely compute (a history scan
// is real work with a documented multi-second-to-timeout cost even on a
// healthy production database), it's to stop the message from implying a
// certainty bd doesn't have, and point at the (separate, opt-in) tool that
// can dig further.
func TestShow_NotFoundHintExplainsAmbiguity(t *testing.T) {
tmpDir := setupCLITestDB(t)
_, stderr, err := runBDInProcessAllowError(t, tmpDir, "show", "test-nonexistent")
if err == nil {
t.Fatal("expected error for nonexistent issue, but command succeeded")
}
if !strings.Contains(stderr, "not found") {
t.Errorf("expected 'not found' preserved in stderr, got: %s", stderr)
}
if !strings.Contains(stderr, "bd history") {
t.Errorf("expected stderr to point at 'bd history' as the way to check further, got: %s", stderr)
}
if !strings.Contains(stderr, "deleted") && !strings.Contains(stderr, "purged") {
t.Errorf("expected stderr to acknowledge the ID could be a deleted/purged record, not just 'never existed', got: %s", stderr)
}
}
// TestShow_DeletedIssueGetsSameHonestNotFoundMessage proves the hint applies
// to a REAL deleted issue, not just a fabricated ID: bd delete physically
// removes the row (and its events) from the live tables, so bd show on it is
// observationally identical to an ID that never existed. The message must
// not claim otherwise.
func TestShow_DeletedIssueGetsSameHonestNotFoundMessage(t *testing.T) {
tmpDir := setupCLITestDB(t)
out := runBDInProcess(t, tmpDir, "create", "Will be deleted", "-p", "2", "--json")
jsonStart := strings.Index(out, "{")
if jsonStart < 0 {
t.Fatalf("no JSON found in create output: %s", out)
}
var issue map[string]interface{}
if err := json.Unmarshal([]byte(out[jsonStart:]), &issue); err != nil {
t.Fatalf("failed to parse create output: %v, output: %s", err, out)
}
id := issue["id"].(string)
runBDInProcess(t, tmpDir, "delete", id, "--force")
_, stderr, err := runBDInProcessAllowError(t, tmpDir, "show", id)
if err == nil {
t.Fatal("expected error for deleted issue, but command succeeded")
}
if !strings.Contains(stderr, "bd history") {
t.Errorf("expected stderr to point at 'bd history' for a deleted issue, got: %s", stderr)
}
}
// TestShow_NotFoundJSONIncludesHint checks the --json error envelope gets an
// additive "hint" field carrying the same honesty caveat, while leaving the
// existing "error" string untouched for any script matching on it today.
func TestShow_NotFoundJSONIncludesHint(t *testing.T) {
tmpDir := setupCLITestDB(t)
stdout, _, err := runBDInProcessAllowError(t, tmpDir, "show", "test-nonexistent", "--json")
if err == nil {
t.Fatal("expected error for nonexistent issue with --json, but command succeeded")
}
var errResp map[string]interface{}
if jsonErr := json.Unmarshal([]byte(stdout), &errResp); jsonErr != nil {
t.Fatalf("expected valid JSON error response, got parse error: %v\nStdout: %s", jsonErr, stdout)
}
if errField, _ := errResp["error"].(string); errField != "no issues found matching the provided IDs" {
t.Errorf("expected unchanged 'error' field text for backward compat, got: %q", errField)
}
hint, _ := errResp["hint"].(string)
if hint == "" {
t.Fatalf("expected non-empty 'hint' field explaining the ambiguity, got response: %s", stdout)
}
if !strings.Contains(hint, "bd history") {
t.Errorf("expected hint to point at 'bd history', got: %s", hint)
}
}