From a006a3369fa1bb30a26d64e9bd904e4d375a413b Mon Sep 17 00:00:00 2001 From: matt wilkie Date: Sat, 13 Jun 2026 21:22:38 -0700 Subject: [PATCH] fix(cli): implement children pretty and defer reason Why: #4365 reports two documented CLI affordances that either fail or require a second command. children advertised --pretty but rejected it, and defer had no way to capture the reason at deferral time. What: add the children --pretty flag by delegating to list's existing tree renderer, add defer --reason by appending to notes during the status update, and refresh generated CLI docs. Agent-Signature: codex-unknown-model-unknown-reasoning on behalf of matt wilkie --- cmd/bd/children.go | 7 +++++ cmd/bd/defer.go | 24 +++++++++++++++++ cmd/bd/protocol/children_test.go | 26 +++++++++++++++++++ cmd/bd/protocol/defer_test.go | 26 +++++++++++++++++++ docs/CLI_REFERENCE.md | 12 +++++++-- website/docs/cli-reference/children.md | 8 +++++- website/docs/cli-reference/defer.md | 4 ++- website/static/llms-full.txt | 12 +++++++-- .../version-1.0.0/cli-reference/children.md | 8 +++++- .../version-1.0.0/cli-reference/defer.md | 4 ++- .../version-1.0.4/cli-reference/children.md | 8 +++++- .../version-1.0.4/cli-reference/defer.md | 4 ++- .../version-1.0.5/cli-reference/children.md | 8 +++++- .../version-1.0.5/cli-reference/defer.md | 4 ++- 14 files changed, 143 insertions(+), 12 deletions(-) create mode 100644 cmd/bd/protocol/children_test.go diff --git a/cmd/bd/children.go b/cmd/bd/children.go index 4af06dbc1..a3fada1d5 100644 --- a/cmd/bd/children.go +++ b/cmd/bd/children.go @@ -24,6 +24,7 @@ Examples: Args: cobra.ExactArgs(1), Run: func(cmd *cobra.Command, args []string) { parentID := args[0] + pretty, _ := cmd.Flags().GetBool("pretty") // Set the parent flag on listCmd, run it, then reset _ = listCmd.Flags().Set("parent", parentID) @@ -33,10 +34,16 @@ Examples: _ = listCmd.Flags().Set("status", "all") defer func() { _ = listCmd.Flags().Set("status", "") }() + if pretty { + _ = listCmd.Flags().Set("pretty", "true") + defer func() { _ = listCmd.Flags().Set("pretty", "false") }() + } + listCmd.Run(listCmd, []string{}) }, } func init() { + childrenCmd.Flags().Bool("pretty", false, "Show children in tree format") rootCmd.AddCommand(childrenCmd) } diff --git a/cmd/bd/defer.go b/cmd/bd/defer.go index 65c127b29..114acac72 100644 --- a/cmd/bd/defer.go +++ b/cmd/bd/defer.go @@ -3,6 +3,7 @@ package main import ( "fmt" "os" + "strings" "time" "github.com/spf13/cobra" @@ -27,6 +28,7 @@ Deferred issues don't show in 'bd ready' but remain visible in 'bd list'. Examples: bd defer bd-abc # Defer a single issue (status-based) bd defer bd-abc --until=tomorrow # Defer until specific time + bd defer bd-abc --reason="waiting on API access" bd defer bd-abc bd-def # Defer multiple issues`, Args: cobra.MinimumNArgs(1), Run: func(cmd *cobra.Command, args []string) { @@ -48,6 +50,11 @@ Examples: } deferUntil = &t } + reason, _ := cmd.Flags().GetString("reason") + reason = strings.TrimSpace(reason) + if cmd.Flags().Changed("reason") && reason == "" { + FatalError("reason cannot be empty") + } ctx := rootCtx @@ -79,6 +86,22 @@ Examples: if deferUntil != nil { updates["defer_until"] = *deferUntil } + if reason != "" { + issue, err := store.GetIssue(ctx, fullID) + if err != nil { + fmt.Fprintf(os.Stderr, "Error loading %s: %v\n", fullID, err) + continue + } + if issue == nil { + fmt.Fprintf(os.Stderr, "Issue %s not found\n", fullID) + continue + } + notes := issue.Notes + if notes != "" { + notes += "\n" + } + updates["notes"] = notes + reason + } if err := store.UpdateIssue(ctx, fullID, updates, actor); err != nil { fmt.Fprintf(os.Stderr, "Error deferring %s: %v\n", fullID, err) @@ -108,6 +131,7 @@ Examples: func init() { // Time-based scheduling flag (GH#820) deferCmd.Flags().String("until", "", "Defer until specific time (e.g., +1h, tomorrow, next monday)") + deferCmd.Flags().String("reason", "", "Record why this issue is being deferred (appended to notes)") deferCmd.ValidArgsFunction = issueIDCompletion rootCmd.AddCommand(deferCmd) } diff --git a/cmd/bd/protocol/children_test.go b/cmd/bd/protocol/children_test.go new file mode 100644 index 000000000..8c0710450 --- /dev/null +++ b/cmd/bd/protocol/children_test.go @@ -0,0 +1,26 @@ +package protocol + +import ( + "strings" + "testing" +) + +// TestProtocol_ChildrenPrettyRendersTree asserts that the documented +// `bd children --pretty` example is accepted and uses the tree renderer. +func TestProtocol_ChildrenPrettyRendersTree(t *testing.T) { + t.Parallel() + w := newWorkspace(t) + parent := w.create("--title", "Pretty parent", "--type", "epic") + child := w.create("--title", "Pretty child", "--type", "task", "--parent", parent) + + out := w.run("children", parent, "--pretty") + if !strings.Contains(out, parent) { + t.Fatalf("bd children --pretty output should include parent %s:\n%s", parent, out) + } + if !strings.Contains(out, child) { + t.Fatalf("bd children --pretty output should include child %s:\n%s", child, out) + } + if !strings.Contains(out, "Total:") { + t.Fatalf("bd children --pretty should use the tree renderer summary:\n%s", out) + } +} diff --git a/cmd/bd/protocol/defer_test.go b/cmd/bd/protocol/defer_test.go index a16b255c9..bea6dbafd 100644 --- a/cmd/bd/protocol/defer_test.go +++ b/cmd/bd/protocol/defer_test.go @@ -18,3 +18,29 @@ func TestProtocol_DeferPastDateWarns(t *testing.T) { t.Errorf("bd defer --until= should warn about past date:\n%s", out) } } + +// TestProtocol_DeferReasonAppendsNotes asserts that `bd defer --reason` +// records the audit context at the same time as the deferral. +func TestProtocol_DeferReasonAppendsNotes(t *testing.T) { + t.Parallel() + w := newWorkspace(t) + id := w.create("--title", "Reasoned defer", "--type", "task", "--notes", "existing context") + + w.run("defer", id, "--until=2099-12-31", "--reason", "blocked on external API availability") + + issue := w.showJSON(id) + assertField(t, issue, "status", "deferred") + assertField(t, issue, "notes", "existing context\nblocked on external API availability") +} + +// TestProtocol_DeferRejectsEmptyReason keeps whitespace-only reasons from +// creating ambiguous blank audit entries. +func TestProtocol_DeferRejectsEmptyReason(t *testing.T) { + t.Parallel() + w := newWorkspace(t) + id := w.create("--title", "Blank reason", "--type", "task") + + if _, err := w.tryRun("defer", id, "--reason", " "); err == nil { + t.Error("bd defer --reason with whitespace-only text should fail but exited 0") + } +} diff --git a/docs/CLI_REFERENCE.md b/docs/CLI_REFERENCE.md index 721aaa3c5..58fcb6eb3 100644 --- a/docs/CLI_REFERENCE.md +++ b/docs/CLI_REFERENCE.md @@ -337,7 +337,13 @@ Examples: bd children hq-abc123 --pretty # Show children in tree format ``` -bd children +bd children [flags] +``` + +**Flags:** + +``` + --pretty Show children in tree format ``` ### bd close @@ -5504,6 +5510,7 @@ Deferred issues don't show in 'bd ready' but remain visible in 'bd list'. Examples: bd defer bd-abc # Defer a single issue (status-based) bd defer bd-abc --until=tomorrow # Defer until specific time + bd defer bd-abc --reason="waiting on API access" bd defer bd-abc bd-def # Defer multiple issues ``` @@ -5513,7 +5520,8 @@ bd defer [id...] [flags] **Flags:** ``` - --until string Defer until specific time (e.g., +1h, tomorrow, next monday) + --reason string Record why this issue is being deferred (appended to notes) + --until string Defer until specific time (e.g., +1h, tomorrow, next monday) ``` ### bd formula diff --git a/website/docs/cli-reference/children.md b/website/docs/cli-reference/children.md index 1ed30f6c2..05a474bee 100644 --- a/website/docs/cli-reference/children.md +++ b/website/docs/cli-reference/children.md @@ -22,5 +22,11 @@ Examples: bd children hq-abc123 --pretty # Show children in tree format ``` -bd children +bd children [flags] +``` + +**Flags:** + +``` + --pretty Show children in tree format ``` diff --git a/website/docs/cli-reference/defer.md b/website/docs/cli-reference/defer.md index 476f4d8d6..41a8a6223 100644 --- a/website/docs/cli-reference/defer.md +++ b/website/docs/cli-reference/defer.md @@ -22,6 +22,7 @@ Deferred issues don't show in 'bd ready' but remain visible in 'bd list'. Examples: bd defer bd-abc # Defer a single issue (status-based) bd defer bd-abc --until=tomorrow # Defer until specific time + bd defer bd-abc --reason="waiting on API access" bd defer bd-abc bd-def # Defer multiple issues ``` @@ -31,5 +32,6 @@ bd defer [id...] [flags] **Flags:** ``` - --until string Defer until specific time (e.g., +1h, tomorrow, next monday) + --reason string Record why this issue is being deferred (appended to notes) + --until string Defer until specific time (e.g., +1h, tomorrow, next monday) ``` diff --git a/website/static/llms-full.txt b/website/static/llms-full.txt index 2ffa7e766..d58242b41 100644 --- a/website/static/llms-full.txt +++ b/website/static/llms-full.txt @@ -3520,7 +3520,13 @@ Examples: bd children hq-abc123 --pretty # Show children in tree format ``` -bd children +bd children [flags] +``` + +**Flags:** + +``` + --pretty Show children in tree format ``` @@ -4363,6 +4369,7 @@ Deferred issues don't show in 'bd ready' but remain visible in 'bd list'. Examples: bd defer bd-abc # Defer a single issue (status-based) bd defer bd-abc --until=tomorrow # Defer until specific time + bd defer bd-abc --reason="waiting on API access" bd defer bd-abc bd-def # Defer multiple issues ``` @@ -4372,7 +4379,8 @@ bd defer [id...] [flags] **Flags:** ``` - --until string Defer until specific time (e.g., +1h, tomorrow, next monday) + --reason string Record why this issue is being deferred (appended to notes) + --until string Defer until specific time (e.g., +1h, tomorrow, next monday) ``` diff --git a/website/versioned_docs/version-1.0.0/cli-reference/children.md b/website/versioned_docs/version-1.0.0/cli-reference/children.md index 1ed30f6c2..05a474bee 100644 --- a/website/versioned_docs/version-1.0.0/cli-reference/children.md +++ b/website/versioned_docs/version-1.0.0/cli-reference/children.md @@ -22,5 +22,11 @@ Examples: bd children hq-abc123 --pretty # Show children in tree format ``` -bd children +bd children [flags] +``` + +**Flags:** + +``` + --pretty Show children in tree format ``` diff --git a/website/versioned_docs/version-1.0.0/cli-reference/defer.md b/website/versioned_docs/version-1.0.0/cli-reference/defer.md index 476f4d8d6..41a8a6223 100644 --- a/website/versioned_docs/version-1.0.0/cli-reference/defer.md +++ b/website/versioned_docs/version-1.0.0/cli-reference/defer.md @@ -22,6 +22,7 @@ Deferred issues don't show in 'bd ready' but remain visible in 'bd list'. Examples: bd defer bd-abc # Defer a single issue (status-based) bd defer bd-abc --until=tomorrow # Defer until specific time + bd defer bd-abc --reason="waiting on API access" bd defer bd-abc bd-def # Defer multiple issues ``` @@ -31,5 +32,6 @@ bd defer [id...] [flags] **Flags:** ``` - --until string Defer until specific time (e.g., +1h, tomorrow, next monday) + --reason string Record why this issue is being deferred (appended to notes) + --until string Defer until specific time (e.g., +1h, tomorrow, next monday) ``` diff --git a/website/versioned_docs/version-1.0.4/cli-reference/children.md b/website/versioned_docs/version-1.0.4/cli-reference/children.md index 1ed30f6c2..05a474bee 100644 --- a/website/versioned_docs/version-1.0.4/cli-reference/children.md +++ b/website/versioned_docs/version-1.0.4/cli-reference/children.md @@ -22,5 +22,11 @@ Examples: bd children hq-abc123 --pretty # Show children in tree format ``` -bd children +bd children [flags] +``` + +**Flags:** + +``` + --pretty Show children in tree format ``` diff --git a/website/versioned_docs/version-1.0.4/cli-reference/defer.md b/website/versioned_docs/version-1.0.4/cli-reference/defer.md index 476f4d8d6..41a8a6223 100644 --- a/website/versioned_docs/version-1.0.4/cli-reference/defer.md +++ b/website/versioned_docs/version-1.0.4/cli-reference/defer.md @@ -22,6 +22,7 @@ Deferred issues don't show in 'bd ready' but remain visible in 'bd list'. Examples: bd defer bd-abc # Defer a single issue (status-based) bd defer bd-abc --until=tomorrow # Defer until specific time + bd defer bd-abc --reason="waiting on API access" bd defer bd-abc bd-def # Defer multiple issues ``` @@ -31,5 +32,6 @@ bd defer [id...] [flags] **Flags:** ``` - --until string Defer until specific time (e.g., +1h, tomorrow, next monday) + --reason string Record why this issue is being deferred (appended to notes) + --until string Defer until specific time (e.g., +1h, tomorrow, next monday) ``` diff --git a/website/versioned_docs/version-1.0.5/cli-reference/children.md b/website/versioned_docs/version-1.0.5/cli-reference/children.md index 1ed30f6c2..05a474bee 100644 --- a/website/versioned_docs/version-1.0.5/cli-reference/children.md +++ b/website/versioned_docs/version-1.0.5/cli-reference/children.md @@ -22,5 +22,11 @@ Examples: bd children hq-abc123 --pretty # Show children in tree format ``` -bd children +bd children [flags] +``` + +**Flags:** + +``` + --pretty Show children in tree format ``` diff --git a/website/versioned_docs/version-1.0.5/cli-reference/defer.md b/website/versioned_docs/version-1.0.5/cli-reference/defer.md index 476f4d8d6..41a8a6223 100644 --- a/website/versioned_docs/version-1.0.5/cli-reference/defer.md +++ b/website/versioned_docs/version-1.0.5/cli-reference/defer.md @@ -22,6 +22,7 @@ Deferred issues don't show in 'bd ready' but remain visible in 'bd list'. Examples: bd defer bd-abc # Defer a single issue (status-based) bd defer bd-abc --until=tomorrow # Defer until specific time + bd defer bd-abc --reason="waiting on API access" bd defer bd-abc bd-def # Defer multiple issues ``` @@ -31,5 +32,6 @@ bd defer [id...] [flags] **Flags:** ``` - --until string Defer until specific time (e.g., +1h, tomorrow, next monday) + --reason string Record why this issue is being deferred (appended to notes) + --until string Defer until specific time (e.g., +1h, tomorrow, next monday) ```