beads/cmd/bd/ready.go
Julian Knutsen d097b6c8a4
perf(ready): skip the countReadyWork request when bd ready --json prints no total (#7699)
* perf(ready): skip the countReadyWork request when bd ready --json prints no total

Over a remote backend, bd ready --json sent GET /v0/beads/ready and then,
whenever the page came back with has_more, GET /v0/beads/ready:count, only to
put "of N" into the stderr hint. Without BD_JSON_ENVELOPE nothing else prints
the total, so that second request (about 120 ms at a 52 ms RTT) bought a
number no caller reads.

On a remote backend without the envelope, bd ready --json now lists one row
past the limit and says whether more exist without saying how many, in the
wording the proxied route already uses. A local store keeps the in-band total
it takes in the page's own transaction, and the envelope keeps
pagination.total. A --max-rows cap at or below the limit keeps the counted
listing, so the extra row never trips the cap.

Agent-Signature: claude-code-claude-opus-5-5-unknown-reasoning on behalf of gascity-agent
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* fix(ready): say "1 ready issue", not "1 ready issues", in the no-total hint

Review follow-up. The hint the remote --json path shares with the proxied
route now agrees in number; both routes take it from readyHiddenHint, so
they stay one wording.

Agent-Signature: claude-code-claude-opus-5-5-unknown-reasoning on behalf of gascity-agent
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-10-19 18:15:57 +00:00

934 lines
34 KiB
Go
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

package main
import (
"context"
"fmt"
"os"
"strings"
"github.com/spf13/cobra"
"github.com/steveyegge/beads/internal/debug"
"github.com/steveyegge/beads/internal/metrics"
"github.com/steveyegge/beads/internal/storage"
"github.com/steveyegge/beads/internal/types"
"github.com/steveyegge/beads/internal/ui"
"github.com/steveyegge/beads/internal/utils"
"github.com/steveyegge/beads/internal/workapi"
"github.com/steveyegge/beads/issueops"
)
var readyCmd = &cobra.Command{
Use: "ready",
Short: "Show ready work (open, no active blockers)",
Long: `Show ready work (open issues with no active blockers).
Excludes in_progress, blocked, deferred, and hooked issues. This uses the
GetReadyWork API which applies blocker-aware semantics to find truly claimable work.
Note: 'bd list --ready' uses the same blocker-aware ready-work semantics.
Use --mol to filter to a specific molecule's steps:
bd ready --mol bd-patrol # Show ready steps within molecule
Use --gated to find molecules ready for gate-resume dispatch:
bd ready --gated # Find molecules where a gate closed
Use --claim to atomically claim the first ready issue matching the filters:
bd ready --claim --json
This is useful for agents executing molecules to see which steps can run next.`,
SilenceUsage: true,
SilenceErrors: true,
RunE: func(cmd *cobra.Command, args []string) error {
evt := metrics.NewCommandEvent("ready")
defer func() {
if c := metrics.Global(); c != nil {
c.CloseEventAndAdd(evt)
}
}()
claimReady, _ := cmd.Flags().GetBool("claim")
// ABOVE THE MODE DISPATCH, and above the proxied branch, so it is the
// one place a --brief conflict is decided for this command on either
// route. The branches below return before gatherReadyInput runs, so a
// check written into each of them would be three untested copies; this
// is one call into the body the gatherer also uses.
if err := briefModeConflictFromFlags(cmd); err != nil {
return err
}
if usesProxiedServer() {
// The proxied ready role cannot enforce a row cap, including on
// --claim. Refuse any positive cap rather than silently dropping
// this safety limit; malformed values remain usage errors. The
// pre-provider front door refuses the same cap first, so this is
// its backstop — both raise proxy.max_rows.unsupported.
//
// --gated is skipped here as well as at the front door, and it has
// to be skipped in both places: this backstop calls
// AssertProxyCapability with an empty command, so it always
// resolves the mode-wide refusal and cannot honor the
// command-specific allow the front door's path-keyed assert reads.
// Exempting only the front door would move the split from one
// refusal site to the other, not close it.
if err := rejectReadyMaxRowsUnderProxiedServer(cmd); err != nil {
return err
}
return runReadyProxiedServer(cmd, rootCtx)
}
if offset, _ := cmd.Flags().GetInt("offset"); offset > 0 {
return HandleErrorRespectJSON("--offset is only supported under --proxied-server")
}
gated, _ := cmd.Flags().GetBool("gated")
if gated {
if claimReady {
return HandleErrorRespectJSON("--claim cannot be combined with --gated")
}
// Delegate to the non-emitting core so `bd ready --gated` records
// exactly one cli_command event ("ready"), not also "mol-ready-gated".
return runMolReadyGatedCore(cmd, args)
}
molID, _ := cmd.Flags().GetString("mol")
if molID != "" {
if claimReady {
return HandleErrorRespectJSON("--claim cannot be combined with --mol")
}
if store == nil {
return HandleErrorRespectJSON("no database connection")
}
resolve := func(ctx context.Context, arg string) (string, error) {
return utils.ResolvePartialID(ctx, store, arg)
}
return runMoleculeReady(rootCtx, store, resolve, molID)
}
explain, _ := cmd.Flags().GetBool("explain")
if explain {
if claimReady {
return HandleErrorRespectJSON("--claim cannot be combined with --explain")
}
return runReadyExplain(cmd)
}
// The row cap is meaningful on this route alone - the proxied one
// rejects a live cap outright - so this is the only caller that hands
// the gatherer a resolver for it.
in, err := gatherReadyInput(cmd, resolveMaxRows)
if err != nil {
return err
}
filter := in.filter
ctx := rootCtx
activeStore := store
if claimReady {
CheckReadonly("ready --claim")
} else {
routedStore, routed, routingRule, err := openRoutedReadStore(ctx, activeStore)
if err != nil {
return HandleErrorRespectJSON("%v", err)
}
if routed {
defer func() { _ = routedStore.Close() }()
printContributorRoutingNotice(ctx, activeStore, routingRule)
activeStore = routedStore
}
}
if claimReady {
// The claim is on the ReadyClaimer role, through the store's own
// accessor, so selection, the compare-and-set and the hydration
// that feeds --json all share one transaction. The listing below
// is not on a role and still builds the filter, for the reasons
// issueops.Reader's doc comment gives.
claimer, err := activeStore.ReadyClaimer()
if err != nil {
return HandleErrorRespectJSON("%v", err)
}
res, err := claimer.ClaimNext(ctx, claimNextRequest(in))
if err != nil {
// No handleMaxRowsError here, unlike the listing below: the
// request carries no cap, so ErrTooManyRows cannot come back.
// See claimNextRequest for why the cap never applied.
return HandleErrorRespectJSON("%v", err)
}
if res.Claimed == nil {
if jsonOutput {
return outputJSON([]*types.IssueWithCounts{})
}
fmt.Printf("\n%s No ready work to claim\n\n", ui.RenderWarn("○"))
return nil
}
claimed := res.Claimed
if err := commitPendingIfEmbedded(ctx, activeStore, currentActor(), doltAutoCommitParams{
Command: "ready",
IssueIDs: []string{claimed.ID},
}); err != nil {
return HandleErrorRespectJSON("failed to commit: %v", err)
}
SetLastTouchedID(claimed.ID)
if jsonOutput {
return outputJSON([]*types.IssueWithCounts{claimed})
}
fmt.Printf("%s Claimed issue: %s\n", ui.RenderPass("✓"), formatFeedbackID(claimed.ID, claimed.Title))
return nil
}
if jsonOutput && readyJSONPrintsNoTotal(activeStore) {
return runReadyJSONWithoutTotal(ctx, activeStore, filter)
}
if jsonOutput {
// The page and the size of the whole ready set come back from ONE
// read transaction: the total rides the page's own ID query, so a
// capped listing no longer pays for a second counting pass (and a
// second defer-wake sweep) just to print "Showing N of M". Against
// a remote SQL server each of that pass's statements was a
// sequential round trip. The total is the same number the
// ReadyCounter role answers (storage.DoltStorage documents the
// identity), taken over the listing's own filter.
results, total, err := activeStore.GetReadyWorkWithCountsAndTotal(ctx, filter)
if err != nil {
if capErr := handleMaxRowsError(err); capErr != nil {
return capErr
}
return HandleErrorRespectJSON("%v", err)
}
totalReady := len(results)
truncated := false
if filter.Limit > 0 && len(results) == filter.Limit && total > len(results) {
totalReady = total
truncated = true
}
if results == nil {
results = []*types.IssueWithCounts{}
}
var pag *PaginationMeta
if truncated {
pag = &PaginationMeta{
Returned: len(results),
Total: totalReady,
Truncated: true,
}
}
if jerr := outputJSONWithPagination(results, pag); jerr != nil {
return jerr
}
if truncated {
fmt.Fprintf(os.Stderr, "Showing %d of %d ready issues. Use --limit 0 for all, or --limit N to raise the cap.\n", len(results), totalReady)
}
return nil
}
issues, err := activeStore.GetReadyWork(ctx, filter)
if err != nil {
if capErr := handleMaxRowsError(err); capErr != nil {
return capErr
}
return HandleErrorRespectJSON("%v", err)
}
totalReady := len(issues)
truncated := false
if filter.Limit > 0 && len(issues) == filter.Limit {
// The same question the --json branch answers in-band, asked here
// of the ReadyCounter role, whose answer is the same identity, so
// the "Showing X of N" a human reads and the total a script parses
// are one number.
if n, countErr := readyTotal(ctx, activeStore, in); countErr == nil && n > len(issues) {
totalReady = n
truncated = true
}
}
maybeShowUpgradeNotification()
if len(issues) == 0 {
hasOpenIssues := false
if stats, statsErr := activeStore.GetStatistics(ctx); statsErr == nil {
hasOpenIssues = stats.OpenIssues > 0 || stats.InProgressIssues > 0
}
if hasOpenIssues {
fmt.Printf("\n%s No ready work found (all issues have blocking dependencies)\n\n",
ui.RenderWarn("✨"))
} else {
fmt.Printf("\n%s No open issues\n\n", ui.RenderPass("✨"))
}
maybeShowTip(store)
return nil
}
parentEpicMap := buildParentEpicMap(ctx, activeStore, issues)
usePlain := in.plainFormat || !in.prettyFormat
if usePlain {
fmt.Printf("\n%s Ready work (%d issues with no active blockers):\n\n", ui.RenderAccent("📋"), len(issues))
for i, issue := range issues {
fmt.Printf("%d. [%s] [%s] %s: %s\n", i+1,
ui.RenderPriority(issue.Priority),
ui.RenderType(string(issue.IssueType)),
ui.RenderID(issue.ID), issue.Title)
if issue.EstimatedMinutes != nil {
fmt.Printf(" Estimate: %d min\n", *issue.EstimatedMinutes)
}
if issue.Assignee != "" {
fmt.Printf(" Assignee: %s\n", issue.Assignee)
}
}
fmt.Println()
} else {
displayReadyList(issues, parentEpicMap)
}
if truncated {
fmt.Printf("%s\n\n", ui.RenderMuted(fmt.Sprintf("Showing %d of %d ready issues. Use -n to show more.", len(issues), totalReady)))
}
maybeShowTip(store)
return nil
},
}
// readyGatedArm reports whether this `bd ready` invocation dispatches to the
// gate-resume arm — the same scan `bd mol ready --gated` runs, and the reason
// the row cap does not apply to it. Both proxied refusal sites call this, so
// the exemption cannot land on one and miss the other.
//
// The arm lists molecules whose gate closed, never ready rows: on the direct
// route --gated reaches runMolReadyGatedCore above any cap resolution, and on
// the proxied route runReadyProxiedGated discards its readyInput and calls the
// same findGateReadyMolecules as runMolReadyGatedProxiedServer. `mol ready`,
// the documented alias, carries a notApplicable() cap row for exactly that
// reason; keying the refusal on `bd ready` alone split one documented command
// line across its two spellings.
//
// --claim is excluded deliberately. `--claim --gated` is a usage error
// (gatherReadyInput), not a gated run, so the claim arm keeps the refusal it is
// owed on every code path and this exemption cannot reopen it.
func readyGatedArm(cmd *cobra.Command) bool {
if cmd == nil {
return false
}
if gated, _ := cmd.Flags().GetBool("gated"); !gated {
return false
}
claim, _ := cmd.Flags().GetBool("claim")
return !claim
}
// rejectReadyMaxRowsUnderProxiedServer is `bd ready`'s in-RunE backstop for the
// row cap the proxied ready role cannot enforce. It exists as a named function
// rather than an inline `if` so the exemption is reachable from a unit test:
// the front door's half runs against the real command tree in
// TestProxyCapabilityFrontDoorAllowsSupportedCommands, but this half sits
// behind usesProxiedServer() and would otherwise be pinned only by the
// env-gated proxied e2e lane.
//
// Call it in place of rejectMaxRowsUnderProxiedServer on this command; every
// other capped command wants the unconditional form.
func rejectReadyMaxRowsUnderProxiedServer(cmd *cobra.Command) error {
if readyGatedArm(cmd) {
return nil
}
return rejectMaxRowsUnderProxiedServer(cmd)
}
// blockedRequestFromFlags builds the blocked listing's request from
// blockedCmd's flags. Every route calls it, so the routes cannot drift as
// filtering flags are added.
//
// The labels go to the role as written: the role normalizes them, as every
// other label filter is normalized (list_input.go, search.go, orphans.go,
// workapi/ready.go). These clauses match a label EXACTLY, so an untrimmed
// value would silently under-report: pflag's CSV split leaves the leading
// space in the everyday `--label 'a, b'` form, and `--label 'a,,b'` would AND
// in an empty-label clause that matches nothing at all. Normalizing in the
// role rather than here is what makes a served listing normalize the same way
// for every client.
func blockedRequestFromFlags(cmd *cobra.Command) issueops.BlockedRequest {
parentID, _ := cmd.Flags().GetString("parent")
labels, _ := cmd.Flags().GetStringSlice("label")
labelsAny, _ := cmd.Flags().GetStringSlice("label-any")
excludeLabels, _ := cmd.Flags().GetStringSlice("exclude-label")
return issueops.BlockedRequest{
ParentID: parentID,
Labels: labels,
LabelsAny: labelsAny,
ExcludeLabels: excludeLabels,
}
}
// blockedLister is the blocked-listing role for the route this invocation
// runs: the store's own BlockedLister accessor on the direct routes (dolt,
// embedded dolt, and a registered HTTP backend, where it dials blocked.list
// and an older server is refused before the dial naming the token), and the
// proxied-server provider's on the proxied one.
func blockedLister() (issueops.BlockedLister, error) {
if usesProxiedServer() {
return proxiedBlockedLister()
}
if store == nil {
return nil, fmt.Errorf("no storage available")
}
return store.BlockedLister()
}
var blockedCmd = &cobra.Command{
Use: "blocked",
Short: "Show blocked issues",
SilenceUsage: true,
SilenceErrors: true,
RunE: func(cmd *cobra.Command, args []string) error {
evt := metrics.NewCommandEvent("blocked")
defer func() {
if c := metrics.Global(); c != nil {
c.CloseEventAndAdd(evt)
}
}()
// One role on every route (blockedLister). Use global jsonOutput set
// by PersistentPreRun (respects config.yaml + env vars).
ctx := rootCtx
if flagsMode, _ := cmd.Flags().GetBool("flags"); flagsMode {
return runBlockedFlags(cmd, ctx, cmd.InOrStdin())
}
if cmd.Flags().Changed("raw") {
return HandleErrorRespectJSON("--raw qualifies --flags (the stored blocked column per id); it has no meaning for the listing")
}
lister, err := blockedLister()
if err != nil {
return HandleErrorRespectJSON("%v", err)
}
result, err := lister.ListBlocked(ctx, blockedRequestFromFlags(cmd))
if err != nil {
return HandleErrorRespectJSON("%v", err)
}
blocked := result.Items
if jsonOutput {
if blocked == nil {
blocked = []*types.BlockedIssue{}
}
return outputJSON(blocked)
}
if len(blocked) == 0 {
fmt.Printf("\n%s No blocked issues\n\n", ui.RenderPass("✨"))
return nil
}
fmt.Printf("\n%s Blocked issues (%d):\n\n", ui.RenderFail("🚫"), len(blocked))
for _, issue := range blocked {
fmt.Printf("[%s] %s: %s\n",
ui.RenderPriority(issue.Priority),
ui.RenderID(issue.ID), issue.Title)
blockedBy := issue.BlockedBy
if blockedBy == nil {
blockedBy = []string{}
}
fmt.Printf(" Blocked by %d open dependencies: %v\n",
issue.BlockedByCount, blockedBy)
fmt.Println()
}
return nil
},
}
// readyJSONPrintsNoTotal reports whether `bd ready --json` should skip sizing
// the whole ready set. Without BD_JSON_ENVELOPE the total only decorates the
// stderr hint. A local store takes it in the page's own transaction, so the
// hint keeps it there; a remote backend pays a second request
// (countReadyWork) for it, so the hint goes without.
func readyJSONPrintsNoTotal(activeStore storage.DoltStorage) bool {
return !jsonEnvelopeEnabled() && storeIsRemoteBackend(activeStore)
}
// runReadyJSONWithoutTotal lists one row past the limit, which says whether
// the limit hid anything: all the hint needs. A cap at or below the limit
// would count that extra row against it, so such a listing keeps the counted
// path and its refusal exactly as before.
func runReadyJSONWithoutTotal(ctx context.Context, activeStore storage.DoltStorage, filter types.WorkFilter) error {
limit := filter.Limit
var results []*types.IssueWithCounts
var total int
var err error
if limit > 0 && filter.MaxRows > 0 && filter.MaxRows <= limit {
results, total, err = activeStore.GetReadyWorkWithCountsAndTotal(ctx, filter)
} else {
if limit > 0 {
filter.Limit = limit + 1
}
results, err = activeStore.GetReadyWorkWithCounts(ctx, filter)
total = len(results)
}
if err != nil {
if capErr := handleMaxRowsError(err); capErr != nil {
return capErr
}
return HandleErrorRespectJSON("%v", err)
}
truncated := limit > 0 && len(results) >= limit && total > limit
if len(results) > limit && limit > 0 {
results = results[:limit]
}
if results == nil {
results = []*types.IssueWithCounts{}
}
if err := outputJSON(results); err != nil {
return err
}
if truncated {
fmt.Fprintf(os.Stderr, "%s Use --limit 0 for all, or --limit N to raise the cap.\n", readyHiddenHint(len(results)))
}
return nil
}
// readyHiddenHint is the truncation hint for a page whose total is unknown:
// how many rows are shown, and that the limit hid more.
func readyHiddenHint(shown int) string {
noun := "issues"
if shown == 1 {
noun = "issue"
}
return fmt.Sprintf("Showing %d ready %s; more matched but were hidden by --limit.", shown, noun)
}
// readyTotal sizes the whole ready set for the request `bd ready` just listed
// a page of, through the store's own ReadyCounter accessor.
//
// THE TEXT OUTPUT CALLS IT, and only when the page came back full, which is
// the one situation where the answer can differ from what is already on
// screen. The --json listing does not: it takes its total in-band from
// GetReadyWorkWithCountsAndTotal, in the page's own transaction.
//
// The role has no --max-rows field to honor and needs none: the cap bounds a
// page this machine materializes, and a count materializes no rows.
//
// A failed count is not a failed command — the page is already correct; all
// that is lost is the "of N" beside it.
func readyTotal(ctx context.Context, activeStore storage.DoltStorage, in readyInput) (int, error) {
counter, err := activeStore.ReadyCounter()
if err != nil {
return 0, err
}
result, err := counter.CountReady(ctx, readyRoleRequest(in))
if err != nil {
return 0, err
}
return int(result.Total), nil
}
// buildParentEpicMap builds a map from child issue ID to parent epic title.
// Only includes parents that are epics.
func buildParentEpicMap(ctx context.Context, s storage.DoltStorage, issues []*types.Issue) map[string]string {
if len(issues) == 0 {
return nil
}
issueIDs := make([]string, len(issues))
for i, issue := range issues {
issueIDs[i] = issue.ID
}
allDeps, err := s.GetDependencyRecordsForIssues(ctx, issueIDs)
if err != nil {
return nil
}
// Find parent-child deps where the issue is the child
parentIDs := make(map[string]bool)
childToParent := make(map[string]string) // childID -> parentID
for issueID, deps := range allDeps {
for _, dep := range deps {
if dep.Type == types.DepParentChild {
parentIDs[dep.DependsOnID] = true
childToParent[issueID] = dep.DependsOnID
}
}
}
if len(parentIDs) == 0 {
return nil
}
// Fetch parent issues and filter to epics
epicTitles := make(map[string]string) // parentID -> title
for parentID := range parentIDs {
parent, err := s.GetIssue(ctx, parentID)
if err != nil || parent == nil {
continue
}
if parent.IssueType == "epic" {
epicTitles[parentID] = parent.Title
}
}
// Build final map: childID -> epic title
result := make(map[string]string)
for childID, parentID := range childToParent {
if title, ok := epicTitles[parentID]; ok {
result[childID] = title
}
}
return result
}
// displayReadyList displays ready issues in pretty format with optional parent epic context
func displayReadyList(issues []*types.Issue, parentEpicMap map[string]string) {
for _, issue := range issues {
epicTitle := ""
if parentEpicMap != nil {
epicTitle = parentEpicMap[issue.ID]
}
fmt.Println(formatPrettyIssueWithContext(issue, epicTitle))
}
// Summary footer
fmt.Println()
fmt.Println(strings.Repeat("-", 80))
fmt.Printf("Ready: %d issues with no active blockers\n", len(issues))
fmt.Println()
fmt.Println("Status: ○ open ◐ in_progress ● blocked ✓ closed ❄ deferred")
fmt.Println("Priority: P0–P4 (label only; not a status icon)")
}
// readyExplainFilter is the filter both --explain routes run, derived from the
// same builder the listing uses so the set `bd ready --explain` explains cannot
// drift from the set `bd ready` shows (bd-3fs.3).
//
// --explain takes no listing flags: it is a whole-graph diagnostic, and the
// direct route reaches it before the flags are even gathered. The limit is
// therefore pinned to unlimited rather than left to workapi.DefaultReadyLimit,
// which would silently truncate the explanation at 100 rows.
func readyExplainFilter() (types.WorkFilter, error) {
unlimited := 0
return workapi.BuildReadyFilter(issueops.ReadyRequest{
Sort: string(types.SortPolicyPriority),
Limit: &unlimited,
})
}
func runReadyExplain(_ *cobra.Command) error {
ctx := rootCtx
activeStore := store
filter, err := readyExplainFilter()
if err != nil {
return HandleErrorRespectJSON("%v", err)
}
readyIssues, err := activeStore.GetReadyWork(ctx, filter)
if err != nil {
return HandleErrorRespectJSON("%v", err)
}
blockedIssues, err := activeStore.GetBlockedIssues(ctx, types.WorkFilter{})
if err != nil {
return HandleErrorRespectJSON("%v", err)
}
// Get dependency records for ready issues to find resolved blockers
readyIDs := make([]string, len(readyIssues))
for i, issue := range readyIssues {
readyIDs[i] = issue.ID
}
depCounts, err := activeStore.GetDependencyCounts(ctx, readyIDs)
if err != nil {
debug.Logf("warning: failed to get dependency counts: %v", err)
}
allDeps, err := activeStore.GetDependencyRecordsForIssues(ctx, readyIDs)
if err != nil {
debug.Logf("warning: failed to get dependency records: %v", err)
}
// Detect cycles
cycles, err := activeStore.DetectCycles(ctx)
if err != nil {
debug.Logf("warning: failed to detect cycles: %v", err)
}
// Collect all blocker IDs to batch-fetch blocker details: the blockers
// of blocked issues, plus the blocking-dependency targets of the ready
// issues, whose status decides whether --explain reports each as
// resolved, pinned or open.
blockerIDList := explainBlockerIDs(blockedIssues, readyIssues, allDeps)
// Build ready items with explanations
// TODO(batchgetter): unbounded id list; see issueops.BatchGetter's doc and
// the importIssueLookup TODO in import_shared.go for why this is not yet
// routed through the role.
blockerIssues, err := activeStore.GetIssuesByIDs(ctx, blockerIDList)
if err != nil {
debug.Logf("warning: failed to get blocker issues: %v", err)
}
blockerMap := make(map[string]*types.Issue, len(blockerIssues))
for _, issue := range blockerIssues {
blockerMap[issue.ID] = issue
}
explanation := types.BuildReadyExplanation(readyIssues, blockedIssues, depCounts, allDeps, blockerMap, cycles)
if jsonOutput {
return outputJSON(explanation)
}
fmt.Printf("\n%s Ready Work Explanation\n\n", ui.RenderAccent("📊"))
// Ready section
if len(explanation.Ready) > 0 {
fmt.Printf("%s Ready (%d issues):\n\n", ui.RenderPass("●"), len(explanation.Ready))
for _, item := range explanation.Ready {
fmt.Printf(" %s [%s] %s\n",
ui.RenderID(item.ID),
ui.RenderPriority(item.Priority),
item.Title)
fmt.Printf(" Reason: %s\n", item.Reason)
printReadyItemDependencies(item)
if item.DependentCount > 0 {
fmt.Printf(" Unblocks: %d issue(s)\n", item.DependentCount)
}
fmt.Println()
}
} else {
fmt.Printf("%s No ready work\n\n", ui.RenderWarn("○"))
}
// Blocked section
if len(explanation.Blocked) > 0 {
fmt.Printf("%s Blocked (%d issues):\n\n", ui.RenderFail("●"), len(explanation.Blocked))
for _, item := range explanation.Blocked {
fmt.Printf(" %s [%s] %s\n",
ui.RenderID(item.ID),
ui.RenderPriority(item.Priority),
item.Title)
for _, blocker := range item.BlockedBy {
fmt.Printf(" ← blocked by %s: %s [%s]\n",
ui.RenderID(blocker.ID), blocker.Title, blocker.Status)
}
fmt.Println()
}
}
// Cycles section
if len(explanation.Cycles) > 0 {
fmt.Printf("%s Cycles detected (%d):\n\n", ui.RenderFail("⚠"), len(explanation.Cycles))
for _, cycle := range explanation.Cycles {
fmt.Printf(" %s → %s\n", strings.Join(cycle, " → "), cycle[0])
}
fmt.Println()
}
// Summary
fmt.Printf("%s Summary: %d ready, %d blocked",
ui.RenderMuted("─"),
explanation.Summary.TotalReady,
explanation.Summary.TotalBlocked)
if explanation.Summary.CycleCount > 0 {
fmt.Printf(", %d cycle(s)", explanation.Summary.CycleCount)
}
fmt.Printf("\n\n")
return nil
}
// runMoleculeReady is `bd ready --mol` on every route. The molecule's nodes,
// their readiness, the ready list and parallel groups are the library's one
// derivation (issueops.ViewMolecule, shared with `mol current`); what is here
// is presentation.
func runMoleculeReady(ctx context.Context, s storage.DoltStorage, resolve func(context.Context, string) (string, error), molIDArg string) error {
moleculeID, err := resolve(ctx, molIDArg)
if err != nil {
return moleculeNotResolved(molIDArg, err)
}
roles, err := currentMoleculeRoles(s)
if err != nil {
return HandleErrorRespectJSON("%v", err)
}
view, err := issueops.ViewMolecule(ctx, roles.molecule, moleculeID)
if err != nil {
return HandleErrorRespectJSON("loading molecule: %v", err)
}
subgraph, analysis := view.Graph, view.Analysis
var readySteps []*MoleculeReadyStep
for _, issue := range view.Ready {
info := analysis.Steps[issue.ID]
readySteps = append(readySteps, &MoleculeReadyStep{
Issue: issue,
ParallelInfo: info,
ParallelGroup: info.ParallelGroup,
})
}
if jsonOutput {
return outputJSON(MoleculeReadyOutput{
MoleculeID: moleculeID,
MoleculeTitle: subgraph.Root.Title,
TotalSteps: analysis.TotalSteps,
ReadySteps: len(readySteps),
Steps: readySteps,
ParallelGroups: analysis.ParallelGroups,
})
}
fmt.Printf("\n%s Ready steps in molecule: %s\n", ui.RenderAccent("🧪"), subgraph.Root.Title)
fmt.Printf(" ID: %s\n", moleculeID)
fmt.Printf(" Total: %d steps, %d ready\n", analysis.TotalSteps, len(readySteps))
if len(readySteps) == 0 {
fmt.Printf("\n%s No ready steps (all blocked or completed)\n\n", ui.RenderWarn("✨"))
return nil
}
// Show parallel groups if any
if len(analysis.ParallelGroups) > 0 {
fmt.Printf("\n%s Parallel Groups:\n", ui.RenderPass("⚡"))
for groupName, members := range analysis.ParallelGroups {
// Check if any members are ready
readyInGroup := 0
for _, id := range members {
if info := analysis.Steps[id]; info != nil && info.IsReady {
readyInGroup++
}
}
if readyInGroup > 0 {
fmt.Printf(" %s: %d ready\n", groupName, readyInGroup)
}
}
}
fmt.Printf("\n%s Ready steps:\n\n", ui.RenderPass("📋"))
for i, step := range readySteps {
// Show parallel group if in one
groupAnnotation := ""
if step.ParallelGroup != "" {
groupAnnotation = fmt.Sprintf(" [%s]", ui.RenderAccent(step.ParallelGroup))
}
fmt.Printf("%d. [%s] [%s] %s: %s%s\n", i+1,
ui.RenderPriority(step.Issue.Priority),
ui.RenderType(string(step.Issue.IssueType)),
ui.RenderID(step.Issue.ID),
step.Issue.Title,
groupAnnotation)
if len(step.ParallelInfo.CanParallel) > 0 {
readyParallel := []string{}
for _, pID := range step.ParallelInfo.CanParallel {
if pInfo := analysis.Steps[pID]; pInfo != nil && pInfo.IsReady {
readyParallel = append(readyParallel, pID)
}
}
if len(readyParallel) > 0 {
fmt.Printf(" Can run with: %v\n", readyParallel)
}
}
}
fmt.Println()
return nil
}
// MoleculeReadyStep holds a ready step with its parallel info
type MoleculeReadyStep struct {
Issue *types.Issue `json:"issue"`
ParallelInfo *ParallelInfo `json:"parallel_info"`
ParallelGroup string `json:"parallel_group,omitempty"`
}
// MoleculeReadyOutput is the JSON output for bd ready --mol
type MoleculeReadyOutput struct {
MoleculeID string `json:"molecule_id"`
MoleculeTitle string `json:"molecule_title"`
TotalSteps int `json:"total_steps"`
ReadySteps int `json:"ready_steps"`
Steps []*MoleculeReadyStep `json:"steps"`
ParallelGroups map[string][]string `json:"parallel_groups"`
}
func init() {
readyCmd.Flags().IntP("limit", "n", workapi.DefaultReadyLimit, "Maximum issues to show (use 0 for unlimited)")
readyCmd.Flags().Int("offset", 0, "Skip the first N matching results (0-based). Only supported under --proxied-server.")
readyCmd.Flags().IntP("priority", "p", 0, "Filter by priority")
readyCmd.Flags().StringP("assignee", "a", "", "Filter by assignee")
readyCmd.Flags().BoolP("unassigned", "u", false, "Show only unassigned issues")
readyCmd.Flags().StringP("sort", "s", "priority", "Sort policy: priority (default), hybrid, oldest")
readyCmd.Flags().StringSliceP("label", "l", []string{}, "Filter by labels (AND: must have ALL). Can combine with --label-any")
readyCmd.Flags().StringSlice("label-any", []string{}, "Filter by labels (OR: must have AT LEAST ONE). Can combine with --label")
readyCmd.Flags().StringSlice("exclude-label", []string{}, "Exclude issues that have ANY of these labels")
readyCmd.Flags().String("label-pattern", "", "Filter by label glob pattern (e.g., 'tech-*' matches tech-debt, tech-legacy)")
readyCmd.Flags().String("label-regex", "", "Filter by label regex pattern (e.g., 'tech-(debt|legacy)')")
readyCmd.Flags().StringP("type", "t", "", "Filter by issue type (task, bug, feature, epic, decision, merge-request). Aliases: mr→merge-request, feat→feature, mol→molecule, dec/adr→decision")
readyCmd.Flags().String("mol", "", "Filter to steps within a specific molecule")
readyCmd.Flags().String("parent", "", "Filter to descendants of this bead/epic")
readyCmd.Flags().String("mol-type", "", "Filter by molecule type: swarm, patrol, or work")
readyCmd.Flags().Bool("pretty", true, "Display issues in a tree format with status/priority symbols")
readyCmd.Flags().Bool("plain", false, "Display issues as a plain numbered list")
readyCmd.Flags().Bool("flat", false, "Alias for --plain, spelled the way bd list spells it")
readyCmd.Flags().Bool("include-deferred", false, "Include issues with future defer_until timestamps")
readyCmd.Flags().Bool("include-ephemeral", false, "Include ephemeral issues (wisps) in results")
readyCmd.Flags().Bool("gated", false, "Find molecules ready for gate-resume dispatch")
readyCmd.Flags().StringSlice("exclude-type", nil, "Exclude issue types from results (comma-separated or repeatable, e.g., --exclude-type=convoy,epic)")
readyCmd.Flags().Bool("explain", false, "Show dependency-aware reasoning for why issues are ready or blocked")
readyCmd.Flags().Bool("claim", false, "Atomically claim the first ready issue matching the filters")
// Projection toggle, the same one `bd list --brief` sets. Refused with
// --claim, which returns one whole row by contract; see gatherReadyInput.
readyCmd.Flags().Bool("brief", false,
"Omit the free-form text (description, design, acceptance criteria, notes, "+
"payload, waiters) from each row. Filters that read those fields still "+
"select on them. An omitted field is indistinguishable from an empty "+
"one; fetch a whole issue with bd show. Requires --json, and cannot be "+
"combined with --claim, --gated, --mol or --explain.")
// Metadata filtering (GH#1406)
readyCmd.Flags().StringArray("metadata-field", nil, "Filter by metadata field (key=value, repeatable)")
readyCmd.Flags().String("has-metadata-key", "", "Filter issues that have this metadata key set")
// Defensive row cap (be-x42v): exits 2 on overage, default disabled.
addMaxRowsFlag(readyCmd)
rootCmd.AddCommand(readyCmd)
blockedCmd.Flags().String("parent", "", "Filter to descendants of this bead/epic")
blockedCmd.Flags().StringSliceP("label", "l", []string{}, "Filter by labels (AND: must have ALL). Can combine with --label-any")
blockedCmd.Flags().StringSlice("label-any", []string{}, "Filter by labels (OR: must have AT LEAST ONE). Can combine with --label")
blockedCmd.Flags().StringSlice("exclude-label", []string{}, "Exclude issues that have ANY of these labels")
blockedCmd.Flags().Bool("raw", false, "With --flags: the stored blocked column itself, without the external-dependency policy (an unsatisfied external: blocker does not set it)")
blockedCmd.Flags().Bool("flags", false, "Print the blocked flag for each id read from stdin (one per line) instead of the listing; with --json, [{\"id\",\"is_blocked\"}]")
rootCmd.AddCommand(blockedCmd)
}
// explainBlockerIDs collects, once each, the ids whose status --explain
// needs: every blocker of a blocked issue, and the target of every blocking
// dependency (blocks, conditional-blocks, waits-for) of a ready issue. The
// ready targets matter because the ready query admits an issue whose blocking
// targets are closed OR pinned, and only the target's status tells the
// explanation which of the two it saw.
func explainBlockerIDs(blockedIssues []*types.BlockedIssue, readyIssues []*types.Issue, allDeps map[string][]*types.Dependency) []string {
seen := make(map[string]bool)
var ids []string
add := func(id string) {
if id == "" || seen[id] {
return
}
seen[id] = true
ids = append(ids, id)
}
for _, bi := range blockedIssues {
for _, blockerID := range bi.BlockedBy {
add(blockerID)
}
}
for _, issue := range readyIssues {
for _, dep := range allDeps[issue.ID] {
if dep.Type == types.DepBlocks || dep.Type == types.DepConditionalBlocks || dep.Type == types.DepWaitsFor {
add(dep.DependsOnID)
}
}
}
return ids
}
// printReadyItemDependencies prints the three dependency lines of a ready
// item in --explain's text form, each only when non-empty.
func printReadyItemDependencies(item types.ReadyItem) {
if len(item.ResolvedBlockers) > 0 {
fmt.Printf(" Resolved blockers: %s\n", strings.Join(item.ResolvedBlockers, ", "))
}
if len(item.PinnedDependencies) > 0 {
fmt.Printf(" Pinned dependencies (never block): %s\n", strings.Join(item.PinnedDependencies, ", "))
}
if len(item.OpenDependencies) > 0 {
fmt.Printf(" Open dependencies (not blocking): %s\n", strings.Join(item.OpenDependencies, ", "))
}
}