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
This commit is contained in:
matt wilkie 2026-06-13 21:22:38 -07:00
commit a006a3369f
14 changed files with 143 additions and 12 deletions

View file

@ -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)
}

View file

@ -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)
}

View file

@ -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)
}
}

View file

@ -18,3 +18,29 @@ func TestProtocol_DeferPastDateWarns(t *testing.T) {
t.Errorf("bd defer --until=<past date> 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")
}
}

View file

@ -337,7 +337,13 @@ Examples:
bd children hq-abc123 --pretty # Show children in tree format
```
bd children <parent-id>
bd children <parent-id> [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

View file

@ -22,5 +22,11 @@ Examples:
bd children hq-abc123 --pretty # Show children in tree format
```
bd children <parent-id>
bd children <parent-id> [flags]
```
**Flags:**
```
--pretty Show children in tree format
```

View file

@ -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)
```

View file

@ -3520,7 +3520,13 @@ Examples:
bd children hq-abc123 --pretty # Show children in tree format
```
bd children <parent-id>
bd children <parent-id> [flags]
```
**Flags:**
```
--pretty Show children in tree format
```
</document>
@ -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)
```
</document>

View file

@ -22,5 +22,11 @@ Examples:
bd children hq-abc123 --pretty # Show children in tree format
```
bd children <parent-id>
bd children <parent-id> [flags]
```
**Flags:**
```
--pretty Show children in tree format
```

View file

@ -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)
```

View file

@ -22,5 +22,11 @@ Examples:
bd children hq-abc123 --pretty # Show children in tree format
```
bd children <parent-id>
bd children <parent-id> [flags]
```
**Flags:**
```
--pretty Show children in tree format
```

View file

@ -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)
```

View file

@ -22,5 +22,11 @@ Examples:
bd children hq-abc123 --pretty # Show children in tree format
```
bd children <parent-id>
bd children <parent-id> [flags]
```
**Flags:**
```
--pretty Show children in tree format
```

View file

@ -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)
```