From cbf84cb1c007dfcb2beb7d64f795e1ba8b76ed17 Mon Sep 17 00:00:00 2001 From: Karel Bourgois Date: Thu, 3 Sep 2026 02:34:05 +0200 Subject: [PATCH] =?UTF-8?q?fix(cli):=20`bd=20list=20--wisp-type`=20cannot?= =?UTF-8?q?=20match=20a=20row=20=E2=80=94=20register=20the=20plane=20knob?= =?UTF-8?q?=20it=20needs=20(#6098)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `bd list --wisp-type heartbeat` returns an empty listing for EVERY input, and `bd list` exposes no flag that changes that. ListRequest.WispType is a predicate, not a plane selector — its own doc says so, and RunReaderListWispTypeNarrowsTheAdmittedPlaneRatherThanAdmittingIt pins it. That contract is right and this does not touch it. The doc also names the way out: The combination that answers with rows is IncludeEphemeral (or IncludeInfra) plus this, and it is lawful rather than refused. `bd list` registers neither `--include-ephemeral` nor `--all-types`. So of the two combinations the doc names, the CLI can express only IncludeInfra — which admits the plane AND lifts the infra-type exclusions AND changes the template treatment, three decisions a caller who wanted one classification did not ask for. The narrow knob the doc names FIRST has no flag at all. That is the whole defect: the API composes correctly, and the CLI is missing the other half of the pair. ## What this does 1. Registers `--include-ephemeral` on `bd list`, wired to `ListRequest.IncludeEphemeral` — the plane knob alone, off by default, so the default listing is byte-identical. 2. Refuses `--wisp-type` when no plane is admitted, with the fix in the hint, instead of printing an empty listing. The refusal is at the CLI layer ONLY. At the API layer the combination stays lawful and still composes to an empty page: that is the pinned contract, and a programmatic caller composing filters may legitimately land on it. A human typing `--wisp-type heartbeat` cannot have meant "prove to me that durable rows carry no classification", so the CLI is where the guess is safe to make. An explicit `--type` is deliberately left alone: an infra type routes to the plane by itself, so the request may well be satisfiable, and this layer cannot tell which types those are without loading the workspace's infra vocabulary. Refusing there would reject lawful, answerable requests. ## Verification --- PASS: TestListRegistersIncludeEphemeral --- PASS: TestGatherListInput_WispTypeWithoutAPlaneIsRefused --- PASS: TestGatherListInput_WispTypeWithAPlaneIsAccepted (3 subtests) --- PASS: TestGatherListInput_IncludeEphemeralReachesTheRequest The pair discriminates rather than being trivially green: a guard that refused every `--wisp-type` would pass the refusal test and fail all three acceptance subtests, one per route that admits the plane. `ok github.com/steveyegge/beads/cmd/bd`, `ok github.com/steveyegge/beads/internal/workapi`, `go build ./...` and `go vet` clean. `internal/workapi/list.go` and the golden corpus are untouched. docs/CLI_REFERENCE.md is not regenerated here: the docs pipeline builds from the release tag in docs/cli-docs.pin (v1.2.2), not from this checkout, so the new flag appears at the next release bump. Claude-Session: https://claude.ai/code/session_01X1jMLQTSrCwtzFRS1xeUC6 --- cmd/bd/list.go | 8 ++ cmd/bd/list_input.go | 23 ++++ cmd/bd/list_wisp_type_reachability_test.go | 130 +++++++++++++++++++++ 3 files changed, 161 insertions(+) create mode 100644 cmd/bd/list_wisp_type_reachability_test.go diff --git a/cmd/bd/list.go b/cmd/bd/list.go index c5e70ef59..d1c105be8 100644 --- a/cmd/bd/list.go +++ b/cmd/bd/list.go @@ -470,6 +470,14 @@ func init() { // Infra type filtering: exclude agent/role/message by default listCmd.Flags().Bool("include-infra", false, "Include infrastructure beads (agent/role/message) in output") + // Ephemeral plane: the wisps table is suppressed by default. This is the + // PLANE knob on its own — ListRequest.IncludeEphemeral — as distinct from + // --include-infra, which admits the plane AND lifts the infra-type + // exclusions above. Without it the plane is reachable from the CLI only + // through --include-infra's wider bundle, which leaves --wisp-type below + // with no narrow way to match anything. + listCmd.Flags().Bool("include-ephemeral", false, "Include ephemeral wisp-plane rows in output (normally hidden)") + // Explicit type exclusion listCmd.Flags().StringSlice("exclude-type", nil, "Exclude issue types from results (comma-separated or repeatable, e.g., --exclude-type=convoy,epic)") diff --git a/cmd/bd/list_input.go b/cmd/bd/list_input.go index 58c039d78..7d12e7c63 100644 --- a/cmd/bd/list_input.go +++ b/cmd/bd/list_input.go @@ -134,6 +134,7 @@ func gatherListInput(cmd *cobra.Command) (listInput, error) { in.IncludeTemplates, _ = cmd.Flags().GetBool("include-templates") in.IncludeGates, _ = cmd.Flags().GetBool("include-gates") in.IncludeInfra, _ = cmd.Flags().GetBool("include-infra") + in.IncludeEphemeral, _ = cmd.Flags().GetBool("include-ephemeral") in.ExcludeTypes, _ = cmd.Flags().GetStringSlice("exclude-type") in.ParentID, _ = cmd.Flags().GetString("parent") @@ -158,6 +159,28 @@ func gatherListInput(cmd *cobra.Command) (listInput, error) { return in, HandleError("invalid wisp-type %q (must be %s)", s, types.ValidWispTypeNames()) } in.WispType = &wt + + // wisp_type is a PREDICATE, not a plane selector (see + // issueops.ListRequest.WispType): it narrows whatever the rest of the + // request admitted. On a default listing that is the durable rows, + // which carry no classification — so this request cannot match a row + // for ANY input, and would report an empty listing rather than the + // unread plane that actually holds the answer. + // + // The request stays LAWFUL at the API layer, where composing to empty + // is the pinned contract. Refusing it belongs HERE, at the CLI, where + // the only thing a human can have meant is the combination that + // answers with rows. + // + // An explicit --type is left alone: an infra type routes to the plane + // by itself, so the request may be satisfiable and this cannot tell + // without the workspace's infra vocabulary, which this layer does not + // load. + if !in.IncludeEphemeral && !in.IncludeInfra && in.IssueType == "" { + return in, HandleErrorWithHint( + fmt.Sprintf("--wisp-type %s cannot match anything here: it filters the wisp_type column, and this listing admits only durable rows, which never carry one", s), + "add --include-ephemeral to admit the ephemeral plane (or --include-infra, which admits it as part of a wider bundle)") + } } in.DeferredFlag, _ = cmd.Flags().GetBool("deferred") diff --git a/cmd/bd/list_wisp_type_reachability_test.go b/cmd/bd/list_wisp_type_reachability_test.go new file mode 100644 index 000000000..20111859c --- /dev/null +++ b/cmd/bd/list_wisp_type_reachability_test.go @@ -0,0 +1,130 @@ +package main + +import ( + "strings" + "testing" + + "github.com/spf13/cobra" +) + +// newWispTypeInputCmd carries only the flags the --wisp-type reachability +// check reads. gatherListInput reads many others, but GetString / GetBool on +// an unregistered flag return zero values, so this stays minimal — the same +// shape as newListInputTestCmd. +func newWispTypeInputCmd() *cobra.Command { + cmd := &cobra.Command{Use: "list"} + f := cmd.Flags() + f.String("wisp-type", "", "") + f.Bool("include-ephemeral", false, "") + f.Bool("include-infra", false, "") + f.StringP("type", "t", "", "") + return cmd +} + +// TestListRegistersIncludeEphemeral pins the flag the guard below points at. +// +// It is the load-bearing half of this change: ListRequest.IncludeEphemeral is +// the plane knob its own doc names as the combination that answers with rows, +// and `bd list` did not register a flag for it. Without this the advice the +// guard prints names a flag that does not exist, which is worse than the +// silence it replaces. +func TestListRegistersIncludeEphemeral(t *testing.T) { + if listCmd.Flags().Lookup("include-ephemeral") == nil { + t.Fatal("bd list must register --include-ephemeral: it is the only narrow way to admit the wisp plane, and --wisp-type's error message tells callers to use it") + } +} + +// TestGatherListInput_WispTypeWithoutAPlaneIsRefused covers the request that +// cannot match a row for ANY input: wisp_type narrows whatever the rest of the +// request admitted, and a default listing admits only durable rows, which +// carry no classification. +// +// The API layer keeps composing this to an empty page — that is its pinned +// contract, and this does not touch it. The refusal is here, where the only +// thing a human can have meant is the combination that returns rows. +func TestGatherListInput_WispTypeWithoutAPlaneIsRefused(t *testing.T) { + defer func(prev bool) { jsonOutput = prev }(jsonOutput) + jsonOutput = false + + cmd := newWispTypeInputCmd() + if err := cmd.Flags().Set("wisp-type", "heartbeat"); err != nil { + t.Fatalf("set wisp-type: %v", err) + } + var err error + stderr := captureStderr(t, func() { _, err = gatherListInput(cmd) }) + if err == nil { + t.Fatal("--wisp-type with no plane knob cannot match any row and must be refused, got nil error") + } + // The message has to carry the way out, or it is just a different silence. + if !strings.Contains(stderr, "--include-ephemeral") { + t.Errorf("the refusal must name the flag that makes the request answerable; got:\n%s", stderr) + } +} + +// TestGatherListInput_WispTypeWithAPlaneIsAccepted is the discriminating half: +// a guard that refused everything would pass the test above on its own. Each +// case here admits the plane by a different route, and all must survive. +func TestGatherListInput_WispTypeWithAPlaneIsAccepted(t *testing.T) { + defer func(prev bool) { jsonOutput = prev }(jsonOutput) + jsonOutput = false + + for _, tc := range []struct { + name string + flag string + val string + }{ + {"the narrow plane knob", "include-ephemeral", "true"}, + {"the wider bundle that also admits it", "include-infra", "true"}, + // An explicit type is left alone: an infra type routes to the plane by + // itself, and this layer cannot tell which types those are without the + // workspace's infra vocabulary. Refusing here would reject a lawful, + // answerable request. + {"an explicit type, which may itself be infra", "type", "agent"}, + } { + t.Run(tc.name, func(t *testing.T) { + cmd := newWispTypeInputCmd() + if err := cmd.Flags().Set("wisp-type", "heartbeat"); err != nil { + t.Fatalf("set wisp-type: %v", err) + } + if err := cmd.Flags().Set(tc.flag, tc.val); err != nil { + t.Fatalf("set %s: %v", tc.flag, err) + } + in, err := gatherListInput(cmd) + if err != nil { + t.Fatalf("--wisp-type with --%s must be accepted, got: %v", tc.flag, err) + } + if in.WispType == nil || string(*in.WispType) != "heartbeat" { + t.Errorf("WispType must survive onto the request, got %v", in.WispType) + } + }) + } +} + +// TestGatherListInput_IncludeEphemeralReachesTheRequest confirms the new flag +// is wired through rather than merely registered — a flag that parses but is +// never read would leave the plane just as unreachable. +func TestGatherListInput_IncludeEphemeralReachesTheRequest(t *testing.T) { + defer func(prev bool) { jsonOutput = prev }(jsonOutput) + jsonOutput = false + + cmd := newWispTypeInputCmd() + if err := cmd.Flags().Set("include-ephemeral", "true"); err != nil { + t.Fatalf("set include-ephemeral: %v", err) + } + in, err := gatherListInput(cmd) + if err != nil { + t.Fatalf("gatherListInput: %v", err) + } + if !in.IncludeEphemeral { + t.Error("--include-ephemeral must set ListRequest.IncludeEphemeral, got false") + } + + // And the default stays off, so the durable-only listing is unchanged. + bare, err := gatherListInput(newWispTypeInputCmd()) + if err != nil { + t.Fatalf("gatherListInput (bare): %v", err) + } + if bare.IncludeEphemeral { + t.Error("IncludeEphemeral must default to false; the default listing is durable-only") + } +}