beads/examples/library-usage/main.go
Jim Wordelman bc9d854ebb
feat(stats): --no-blocked flag skips blocked-count computation; fix Blocked:0 red render (be-nnqp, be-4b63) (#4022)
* feat(stats): add --no-blocked flag; fix Blocked:0 red render (be-nnqp, be-4b63)

- types.go: BlockedIssues int → *int (nil when --no-blocked skips computation)
- storage: add FastStatisticsStore interface + GetStatisticsNoBlocked to DoltStorage;
  implement in DoltStore and EmbeddedDoltStore (ScanIssueCountsInTx only, no blocked traversal)
- status.go: --no-blocked flag (no short alias), BlockedCountSkipped bool in StatusOutput;
  fast path calls GetStatisticsNoBlocked; human output renders "(skipped)" in muted style
- be-4b63: Blocked:0 now renders plain text; only Blocked:N>0 uses RenderFail (red)
- nil-guard BlockedIssues callers: getAssignedStatistics, status_test.go, queries_test.go,
  examples/library-usage/main.go

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

* docs(cli): regen CLI reference for `bd status --no-blocked`

Regenerates docs/CLI_REFERENCE.md and the website CLI reference pages
(`website/docs/cli-reference/status.md` and the version-1.0.0 / 1.0.4
snapshots) from the live `bd help` output so the doc-flags freshness
check passes.

Picks up the new `--no-blocked` flag, the updated `--no-activity`
description ("Skip git activity summary"), and the matching example
lines added in ddf53438c.

Fixes the CI "Check doc flags freshness" failure on PR #4022.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* chore: release gate PASS for be-nnqp+be-4b63 (bd stats --no-blocked)

* fix(stats): ReadyIssues *int, data-derived skip render, proxied-server warning

Address the adjudicated cross-vendor review on PR #4022:

- internal/types.Statistics.ReadyIssues is now *int, mirroring BlockedIssues:
  nil when --no-blocked skips the computation (readiness needs the blocked
  set), populated by all three backends' full GetStatistics, by
  issueops.GetStatisticsInTx, and by buildAssignedStats. Left nil only in
  the *NoBlocked fast-path variants. JSON now emits `"ready_issues": null`
  instead of a fake 0 a CI consumer could misread as "nothing ready".
- renderStatus derives "(skipped)" rendering from the data itself
  (stats.BlockedIssues/ReadyIssues == nil) instead of the noBlocked flag,
  fixing the --assigned + --no-blocked contradiction where fully-recomputed
  stats were mislabeled as skipped. The noBlocked parameter is gone from
  renderStatus entirely; both call sites (status.go, status_proxied_server.go)
  simplified accordingly.
- Proxied-server mode now prints a one-line stderr warning when --no-blocked
  is passed but not honored, instead of silently discarding the flag; the
  flag's help string documents the limitation.

Agent-Signature: claude-sonnet-medium on behalf of maphew

* test(stats): cover GetStatisticsNoBlocked nil semantics and renderStatus skip branch

- internal/storage/dolt: new TestGetStatisticsNoBlocked_LeavesBlockedAndReadyNil
  asserts the --no-blocked fast path leaves BlockedIssues/ReadyIssues nil
  while the full GetStatistics path on the same store populates both.
- cmd/bd: new TestGetStatisticsNoBlocked (storage-level, same assertion via
  the CLI-facing store handle), TestRenderStatus_SkipJSONEmitsNullNotZero
  (asserts blocked_count_skipped:true plus literal `"blocked_issues": null`
  / `"ready_issues": null` in the JSON envelope),
  TestRenderStatus_SkipHumanRendersSkippedNotZero (asserts the "(skipped)"
  human branch renders for both fields), and
  TestRenderStatus_AssignedIgnoresSkipEvenWithNoBlockedFlag (guards the
  --assigned + --no-blocked fix: fully-populated stats never render
  "(skipped)").
- Update existing statistics assertions in
  internal/storage/conformance/audit_search-counts-stats.go,
  internal/storage/dolt/queries_test.go, and
  internal/storage/domain/db/ready_helpers*_test.go for
  ReadyIssues's int -> *int change.

Agent-Signature: claude-sonnet-medium on behalf of maphew

* docs(cli): drop --no-blocked doc lines from CLI_REFERENCE.md/status.md (pinned-generator policy)

CI's "Check doc flags freshness" job builds bd from the release pin in
docs/cli-docs.pin (currently v1.1.0) to regenerate docs/CLI_REFERENCE.md
and docs/cli-reference/status.md, not from this branch's HEAD. v1.1.0
predates --no-blocked entirely, so the pinned generator's output omits
every --no-blocked reference (use case bullet, both example lines, the
flag description) and also reverts the --no-activity flag description
wording, flagging both files as stale relative to it. Same trap PR #3920
hit for --mem-profile.

Applied the exact patch CI generated and uploaded as the
cli-docs-freshness-patch artifact on the failing job
(run 30063539327 / job 89390739992) verbatim to both files; the lines
will reappear automatically once the pin advances past a release that
includes --no-blocked.

Agent-Signature: claude-sonnet-medium on behalf of maphew

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-authored-by: matt wilkie <maphew@gmail.com>
2026-07-23 23:52:39 -07:00

137 lines
4 KiB
Go

// Package main demonstrates using Beads as a Go library
//
// This example shows how an external project (like VC) can import and use
// Beads programmatically instead of spawning CLI processes.
package main
import (
"context"
"fmt"
"log"
"time"
"github.com/steveyegge/beads"
)
func main() {
ctx := context.Background()
// Find the Beads workspace so backend selection can follow metadata.json.
beadsDir := beads.FindBeadsDir()
if beadsDir == "" {
log.Fatal("No Beads workspace found. Run 'bd init' first.")
}
fmt.Printf("Using workspace: %s\n\n", beadsDir)
// Open the configured Dolt implementation (embedded or server mode).
store, err := beads.OpenBestAvailable(ctx, beadsDir)
if err != nil {
log.Fatalf("Failed to open storage: %v", err)
}
defer store.Close()
// Example 1: Get ready work
fmt.Println("=== Ready Work ===")
ready, err := store.GetReadyWork(ctx, beads.WorkFilter{
Status: beads.StatusOpen,
Limit: 5,
})
if err != nil {
log.Fatalf("Failed to get ready work: %v", err)
}
for _, issue := range ready {
fmt.Printf("- %s: %s (priority %d)\n", issue.ID, issue.Title, issue.Priority)
}
// Example 2: Create an issue
fmt.Println("\n=== Creating Issue ===")
newIssue := &beads.Issue{
ID: "", // Empty = auto-generate
Title: "Example library-created issue",
Description: "This issue was created programmatically using Beads as a library",
Status: beads.StatusOpen,
Priority: 2,
IssueType: beads.TypeTask,
CreatedAt: time.Now(),
UpdatedAt: time.Now(),
}
if err := store.CreateIssue(ctx, newIssue, "library-example"); err != nil {
log.Fatalf("Failed to create issue: %v", err)
}
fmt.Printf("Created issue: %s\n", newIssue.ID)
// Example 3: Add a dependency
fmt.Println("\n=== Adding Dependency ===")
dep := &beads.Dependency{
IssueID: newIssue.ID,
DependsOnID: "bd-1", // Assumes bd-1 exists
Type: beads.DepDiscoveredFrom,
CreatedAt: time.Now(),
CreatedBy: "library-example",
}
if err := store.AddDependency(ctx, dep, "library-example"); err != nil {
// Don't fail if bd-1 doesn't exist
fmt.Printf("Note: Could not add dependency (bd-1 may not exist): %v\n", err)
} else {
fmt.Printf("Added dependency: %s discovered-from bd-1\n", newIssue.ID)
}
// Example 4: Add a label
fmt.Println("\n=== Adding Label ===")
if err := store.AddLabel(ctx, newIssue.ID, "library-usage", "library-example"); err != nil {
log.Fatalf("Failed to add label: %v", err)
}
fmt.Printf("Added label 'library-usage' to %s\n", newIssue.ID)
// Example 5: Add a comment
fmt.Println("\n=== Adding Comment ===")
comment, err := store.AddIssueComment(ctx, newIssue.ID, "library-example", "This is a programmatic comment")
if err != nil {
log.Fatalf("Failed to add comment: %v", err)
}
fmt.Printf("Added comment #%s\n", comment.ID)
// Example 6: Update issue status
fmt.Println("\n=== Updating Status ===")
updates := map[string]interface{}{
"status": beads.StatusInProgress,
}
if err := store.UpdateIssue(ctx, newIssue.ID, updates, "library-example"); err != nil {
log.Fatalf("Failed to update issue: %v", err)
}
fmt.Printf("Updated %s status to in_progress\n", newIssue.ID)
// Example 7: Get statistics
fmt.Println("\n=== Statistics ===")
stats, err := store.GetStatistics(ctx)
if err != nil {
log.Fatalf("Failed to get statistics: %v", err)
}
blockedCount := 0
if stats.BlockedIssues != nil {
blockedCount = *stats.BlockedIssues
}
readyCount := 0
if stats.ReadyIssues != nil {
readyCount = *stats.ReadyIssues
}
fmt.Printf("Total issues: %d\n", stats.TotalIssues)
fmt.Printf("Open: %d | In Progress: %d | Closed: %d | Blocked: %d | Ready: %d\n",
stats.OpenIssues, stats.InProgressIssues, stats.ClosedIssues,
blockedCount, readyCount)
// Example 8: Close the issue
fmt.Println("\n=== Closing Issue ===")
if err := store.CloseIssue(ctx, newIssue.ID, "Completed demo", "library-example", ""); err != nil {
log.Fatalf("Failed to close issue: %v", err)
}
fmt.Printf("Closed issue %s\n", newIssue.ID)
fmt.Println("\n✅ Library usage demo complete!")
}