beads/cmd/bd/gate.go
Bee 9f9cfc4968
fix(gate): report an unreadable store as an error, not a pending bead gate (#6404)
* fix(gate): report an unreadable store as an error, not a pending bead gate (wy-2hz4ol)

evaluateGates assigned r.err for the gh:run, gh:pr and timer arms but never
for the bead arm, so a backend or transport failure on the awaited bead's
read fell through applyGateCheckResults' pending branch: no error row, no
error count, exit 0 — indistinguishable from a healthy gate still waiting.

checkBeadGate now returns (satisfied, reason, err). A read that fails for
any reason other than not-found (storage.ErrNotFound, sql.ErrNoRows, the
partial-id resolver's text) is an error; a missing bead stays pending with
the not-found reason as before. printGateCheckSummary returns an error when
any gate could not be checked so the command exits non-zero on both the
classic and proxied routes. bd close keeps refusing on such a gate (fail
closed, --force to override) instead of treating "could not read" as
satisfied.

Tests: TestCheckBeadGate_LocalBeadLookupError now asserts the wrapped error;
TestCheckBeadGate_LocalBeadNotFoundErrorStaysPending pins the four not-found
shapes; TestEvaluateGates_BeadStoreErrorCountsAsError and
TestPrintGateCheckSummary_ErrorsFailTheCommand pin the error row/count and
the non-zero exit. Each of the three fails against its reverted line.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PNYoASfCXUd5AeeCNiXn51

* ci: re-run the gate after a module-proxy GOAWAY on 'Check doc flags freshness' (no code change)

* fix(gate): name close failures in the exit error; test the close refusal

Maintainer fixup for #6404 (adopt-pr review iteration 1; quality scorecard
956/1000, approve). It fixes the review's three minor findings, all in code
or text this PR introduced.

- printGateCheckSummary: the exit error said "N gate(s) could not be
  checked", but errorCount also counts resolved gates whose close failed
  (the "error closing" rows) on the classic and proxied routes. It now says
  "could not be checked or closed", naming both row kinds, and the summary
  test asserts the new text.
- close_gate_test.go: add
  TestCheckGateSatisfaction_BeadGateUnreadableStoreRefuses. A store stub
  whose GetIssue fails with a non-not-found error must make
  checkGateSatisfaction refuse with "could not check bead gate", the read
  error, and --force. Checked against three mutants: the refusal
  falling through to the fail-open warning, the pre-PR reason-only refusal,
  and checkBeadGate folding the read error into the reason. The existing
  BeadGateInvalidFormat and ErrorMessageFormat tests catch only the first,
  and only through the typed-nil routedBeadGateGetter left by a nil package
  store.
- CHANGELOG: narrow the error-row claim to reads of the workspace's own
  store. A bead in a prefix-routed rig whose store cannot be read still
  reads as not found (pending): the routing fallback returns the local
  not-found and drops the routed error. That is pre-existing and left as a
  non-gating follow-up. Also say the non-zero exit covers gh, timer, and
  bead gates and close failures.

Left as-is: the nit that a typed-nil routedBeadGateGetter{localStore: nil}
gets past checkBeadGate's st == nil guard (unreachable on the classic route,
where store is set before RunE). The optional `gate check` Long-help note
was skipped so the generated CLI reference does not need regenerating.

Agent-Signature: claude-code-claude-opus-5-5-max on behalf of Julian Knutsen
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
Co-authored-by: Eddie the Engineer <adopt-pr@gascity.com>
2026-10-06 23:05:06 +00:00

1321 lines
42 KiB
Go

package main
import (
"bytes"
"context"
"encoding/json"
"fmt"
"os"
"os/exec"
"strings"
"time"
"github.com/spf13/cobra"
"github.com/steveyegge/beads/internal/metrics"
"github.com/steveyegge/beads/internal/storage"
"github.com/steveyegge/beads/internal/types"
"github.com/steveyegge/beads/internal/ui"
)
// gateCmd is the parent command for gate operations
var gateCmd = &cobra.Command{
Use: "gate",
GroupID: "issues",
Short: "Manage async coordination gates",
Long: `Gates are async wait conditions that block workflow steps.
Gates are created automatically when a formula step has a gate field.
They must be closed (manually or via watchers) for the blocked step to proceed.
Gate types:
human - Requires manual bd close (Phase 1)
timer - Expires after timeout (Phase 2)
gh:run - Waits for GitHub workflow (Phase 3)
gh:pr - Waits for PR merge (Phase 3)
bead - Waits for another bead to close (Phase 4)
For bead gates, await_id may be a bead ID in this rig's database (e.g.,
"bd-abc123") or the historical cross-rig form <rig>:<bead-id>. Cross-rig
targets resolve through the bead ID's prefix route in routes.jsonl.
Examples:
bd gate list # Show all open gates
bd gate list --all # Show all gates including closed
bd gate check # Evaluate all open gates
bd gate check --type=bead # Evaluate only bead gates
bd gate resolve <id> # Close a gate manually`,
}
// gateListCmd lists gate issues
var gateListCmd = &cobra.Command{
Use: "list [issue-id]",
Short: "List gate issues",
Long: `List gate issues.
With no argument, lists all gate issues in the current beads database.
With an [issue-id] argument, lists ONLY the gates that block that issue
(its own dependency gates) — not every gate in the database.
By default, shows only open gates. Use --all to include closed gates.`,
Args: cobra.MaximumNArgs(1),
SilenceUsage: true,
SilenceErrors: true,
RunE: func(cmd *cobra.Command, args []string) error {
evt := metrics.NewCommandEvent("gate-list")
defer func() {
if c := metrics.Global(); c != nil {
c.CloseEventAndAdd(evt)
}
}()
if usesProxiedServer() {
return runGateListProxiedServer(cmd, rootCtx, args)
}
allFlag, _ := cmd.Flags().GetBool("all")
limit, _ := cmd.Flags().GetInt("limit")
ctx := rootCtx
// Bead-scoped: list only the gates that block this specific issue
// (its dependency gates), never the whole database. Without this an
// issue-id argument was silently ignored and the DB-wide list was
// returned, which could lead a caller to act on unrelated gates.
if len(args) == 1 {
target, err := store.GetIssue(ctx, args[0])
if err != nil {
return HandleErrorRespectJSON("issue not found: %s", args[0])
}
deps, err := store.GetDependencies(ctx, target.ID)
if err != nil {
return HandleErrorRespectJSON("%v", err)
}
gates := filterIssueGates(deps, allFlag, limit)
if jsonOutput {
return outputJSON(gates)
}
displayGates(gates, allFlag)
return nil
}
gateType := types.IssueType("gate")
filter := types.IssueFilter{
IssueType: &gateType,
Limit: limit,
}
if !allFlag {
filter.ExcludeStatus = []types.Status{types.StatusClosed}
}
issues, err := store.SearchIssues(ctx, "", filter)
if err != nil {
return HandleErrorRespectJSON("%v", err)
}
if jsonOutput {
return outputJSON(issues)
}
displayGates(issues, allFlag)
return nil
},
}
// filterIssueGates selects the gate-type issues from an issue's dependency set,
// honoring the same open/closed and limit semantics as the DB-wide list path.
// Pulled out as a pure helper so the bead-scoping logic is unit-testable without
// a live store.
func filterIssueGates(deps []*types.Issue, all bool, limit int) []*types.Issue {
var gates []*types.Issue
for _, d := range deps {
if d == nil || d.IssueType != types.IssueType("gate") {
continue
}
if !all && d.Status == types.StatusClosed {
continue
}
gates = append(gates, d)
if limit > 0 && len(gates) >= limit {
break
}
}
return gates
}
// displayGates formats and displays gate issues, separating open and closed gates
func displayGates(gates []*types.Issue, showAll bool) {
if len(gates) == 0 {
fmt.Println("No gates found.")
return
}
// Separate open and closed gates
var openGates, closedGates []*types.Issue
for _, gate := range gates {
if gate.Status == types.StatusClosed {
closedGates = append(closedGates, gate)
} else {
openGates = append(openGates, gate)
}
}
// Display open gates
if len(openGates) > 0 {
fmt.Printf("\n%s Open Gates (%d):\n\n", ui.RenderAccent("⏳"), len(openGates))
for _, gate := range openGates {
displaySingleGate(gate)
}
}
// Display closed gates only if --all was used
if showAll && len(closedGates) > 0 {
fmt.Printf("\n%s Closed Gates (%d):\n\n", ui.RenderMuted("●"), len(closedGates))
for _, gate := range closedGates {
displaySingleGate(gate)
}
}
if len(openGates) == 0 && (!showAll || len(closedGates) == 0) {
fmt.Println("No gates found.")
return
}
fmt.Printf("To resolve a gate: bd close <gate-id>\n")
}
// displaySingleGate formats and displays a single gate issue
func displaySingleGate(gate *types.Issue) {
statusSym := "○"
if gate.Status == types.StatusClosed {
statusSym = "●"
}
// Format gate info
gateInfo := gate.AwaitType
if gate.AwaitID != "" {
gateInfo = fmt.Sprintf("%s %s", gate.AwaitType, gate.AwaitID)
}
// Format timeout if present
timeoutStr := ""
if gate.Timeout > 0 {
timeoutStr = fmt.Sprintf(" (timeout: %s)", gate.Timeout)
}
// Find blocked step from ID (gate ID format: parent.gate-stepid)
blockedStep := ""
if strings.Contains(gate.ID, ".gate-") {
parts := strings.Split(gate.ID, ".gate-")
if len(parts) == 2 {
blockedStep = fmt.Sprintf("%s.%s", parts[0], parts[1])
}
}
fmt.Printf("%s %s - %s%s\n", statusSym, ui.RenderID(gate.ID), gateInfo, timeoutStr)
if blockedStep != "" {
fmt.Printf(" Blocks: %s\n", blockedStep)
}
fmt.Println()
}
// gateAddWaiterCmd adds a waiter to a gate
var gateAddWaiterCmd = &cobra.Command{
Use: "add-waiter <gate-id> <waiter>",
Short: "Add a waiter to a gate",
Long: `Register an agent as a waiter on a gate bead.
When the gate closes, the waiter will receive a wake notification via 'bd gate wake'.
The waiter is typically the worker's address (e.g., "my-project/workers/agent-1").
This is used by 'bd done --phase-complete' to register for gate wake notifications.`,
Args: cobra.ExactArgs(2),
SilenceUsage: true,
SilenceErrors: true,
RunE: func(cmd *cobra.Command, args []string) error {
if usesProxiedServer() {
return runGateAddWaiterProxiedServer(cmd, rootCtx, args)
}
CheckReadonly("gate add-waiter")
evt := metrics.NewCommandEvent("gate-add-waiter")
defer func() {
if c := metrics.Global(); c != nil {
c.CloseEventAndAdd(evt)
}
}()
gateID := args[0]
waiter := args[1]
ctx := rootCtx
var issue *types.Issue
var err error
issue, err = store.GetIssue(ctx, gateID)
if err != nil {
return HandleError("gate not found: %s", gateID)
}
if issue.IssueType != "gate" {
return HandleError("%s is not a gate issue (type=%s)", gateID, issue.IssueType)
}
for _, w := range issue.Waiters {
if w == waiter {
renderGateWaiterAlready(gateID)
return nil
}
}
newWaiters := append(issue.Waiters, waiter)
updates := map[string]interface{}{
"waiters": newWaiters,
}
if err := store.UpdateIssue(ctx, gateID, updates, actor); err != nil {
return HandleError("updating gate: %v", err)
}
commandDidWrite.Store(true)
renderGateWaiterAdded(gateID, waiter)
return nil
},
}
// renderGateWaiterAlready and renderGateWaiterAdded are shared by the direct
// and proxied-server routes so `bd gate add-waiter` prints identically on both.
func renderGateWaiterAlready(gateID string) {
fmt.Printf("Waiter already registered on gate %s\n", gateID)
}
func renderGateWaiterAdded(gateID, waiter string) {
fmt.Printf("%s Added waiter to gate %s: %s\n", ui.RenderPass("✓"), gateID, waiter)
}
// gateCreateCmd creates an ad-hoc gate issue that blocks another issue
var gateCreateCmd = &cobra.Command{
Use: "create",
Short: "Create a gate that blocks an issue",
Long: `Create an ad-hoc gate issue that blocks another issue until resolved.
The blocked issue will not appear in 'bd ready' until the gate is resolved
via 'bd gate resolve'.
Gate types:
human - Requires manual 'bd gate resolve' (default)
timer - Auto-resolves after --timeout duration
gh:run - Waits for GitHub Actions workflow
gh:pr - Waits for PR merge
Examples:
bd gate create --blocks bd-abc
bd gate create --type=human --blocks bd-abc --reason="Need design review"
bd gate create --type=timer --blocks bd-abc --timeout=2h
bd gate create --type=gh:pr --blocks bd-abc --await-id=42
bd gate create --blocks bd-abc --title="Gate: awaiting owner sign-off"`,
SilenceUsage: true,
SilenceErrors: true,
RunE: func(cmd *cobra.Command, args []string) error {
if usesProxiedServer() {
return runGateCreateProxiedServer(cmd, rootCtx)
}
CheckReadonly("gate create")
evt := metrics.NewCommandEvent("gate-create")
defer func() {
if c := metrics.Global(); c != nil {
c.CloseEventAndAdd(evt)
}
}()
in, err := gatherGateCreateInput(cmd)
if err != nil {
return HandleErrorRespectJSON("%v", err)
}
ctx := rootCtx
targetIssue, err := store.GetIssue(ctx, in.blocksID)
if err != nil {
return HandleErrorRespectJSON("issue not found: %s", in.blocksID)
}
gate := buildGateIssue(in, targetIssue.ID)
metadata, metaErr := repoMetadataForGate(in.gateType, targetIssue)
if metaErr != nil {
return HandleErrorRespectJSON("invalid GitHub repository metadata on %s: %v", targetIssue.ID, metaErr)
}
gate.Metadata = metadata
if err := store.CreateIssue(ctx, gate, actor); err != nil {
return HandleErrorRespectJSON("creating gate: %v", err)
}
dep := &types.Dependency{
IssueID: targetIssue.ID,
DependsOnID: gate.ID,
Type: types.DepBlocks,
}
if err := store.AddDependency(ctx, dep, actor); err != nil {
return HandleErrorRespectJSON("adding blocking dependency: %v", err)
}
commitMsg := fmt.Sprintf("bd: create gate %s blocking %s", gate.ID, targetIssue.ID)
if err := store.Commit(ctx, commitMsg); err != nil && !isDoltNothingToCommit(err) {
return HandleErrorRespectJSON("failed to commit: %v", err)
}
if jsonOutput {
return outputJSON(gate)
}
renderGateCreated(gate, targetIssue, in)
return nil
},
}
// gateCreateInput carries `bd gate create`'s parsed flags. Both routes gather
// it through gatherGateCreateInput so they cannot drift on flag semantics.
type gateCreateInput struct {
blocksID string
gateType string
reason string
awaitID string
titleFlag string
timeout time.Duration
}
func gatherGateCreateInput(cmd *cobra.Command) (gateCreateInput, error) {
in := gateCreateInput{}
in.blocksID, _ = cmd.Flags().GetString("blocks")
in.gateType, _ = cmd.Flags().GetString("type")
in.reason, _ = cmd.Flags().GetString("reason")
in.awaitID, _ = cmd.Flags().GetString("await-id")
in.titleFlag, _ = cmd.Flags().GetString("title")
timeoutStr, _ := cmd.Flags().GetString("timeout")
if timeoutStr != "" {
parsed, err := time.ParseDuration(timeoutStr)
if err != nil {
return in, fmt.Errorf("invalid timeout: %v", err)
}
in.timeout = parsed
}
return in, nil
}
// buildGateIssue constructs the ad-hoc gate issue exactly the way the direct
// route always has; the proxied route reuses it for the same reason the
// renderers are shared.
func buildGateIssue(in gateCreateInput, targetID string) *types.Issue {
title := fmt.Sprintf("Gate: %s", in.gateType)
if in.awaitID != "" {
title = fmt.Sprintf("Gate: %s %s", in.gateType, in.awaitID)
}
if in.titleFlag != "" {
title = in.titleFlag
}
desc := fmt.Sprintf("Ad-hoc gate blocking %s", targetID)
if in.reason != "" {
desc = fmt.Sprintf("%s\n\nReason: %s", desc, in.reason)
}
return &types.Issue{
Title: title,
Description: desc,
Status: types.StatusOpen,
Priority: 2,
IssueType: types.IssueType("gate"),
AwaitType: in.gateType,
AwaitID: in.awaitID,
Timeout: in.timeout,
CreatedBy: getActorWithGit(),
Owner: getOwner(),
}
}
// renderGateCreated is shared by the direct and proxied-server routes; the
// first line's "Created gate <id>" is parsed by downstream scripts, so both
// routes must print it identically.
func renderGateCreated(gate, targetIssue *types.Issue, in gateCreateInput) {
fmt.Printf("%s Created gate %s (type: %s)\n", ui.RenderPass("✓"), ui.RenderID(gate.ID), in.gateType)
fmt.Printf(" Blocks: %s (%s)\n", targetIssue.ID, targetIssue.Title)
if in.reason != "" {
fmt.Printf(" Reason: %s\n", in.reason)
}
if in.timeout > 0 {
fmt.Printf(" Timeout: %s\n", in.timeout)
}
fmt.Printf("\nResolve with: bd gate resolve %s\n", gate.ID)
}
// gateShowCmd shows a gate issue
var gateShowCmd = &cobra.Command{
Use: "show <gate-id>",
Short: "Show a gate issue",
Long: `Display details of a gate issue including its waiters.
This is similar to 'bd show' but validates that the issue is a gate.`,
Args: cobra.ExactArgs(1),
SilenceUsage: true,
SilenceErrors: true,
RunE: func(cmd *cobra.Command, args []string) error {
if usesProxiedServer() {
return runGateShowProxiedServer(cmd, rootCtx, args)
}
evt := metrics.NewCommandEvent("gate-show")
defer func() {
if c := metrics.Global(); c != nil {
c.CloseEventAndAdd(evt)
}
}()
gateID := args[0]
ctx := rootCtx
var issue *types.Issue
var err error
issue, err = store.GetIssue(ctx, gateID)
if err != nil {
return HandleErrorRespectJSON("gate not found: %s", gateID)
}
if issue.IssueType != "gate" {
return HandleErrorRespectJSON("%s is not a gate issue (type=%s)", gateID, issue.IssueType)
}
if jsonOutput {
return outputJSON(issue)
}
renderGateShow(issue)
return nil
},
}
// renderGateShow is shared by the direct and proxied-server routes; downstream
// scripts grep this plain-text output for markers, so both routes must print
// it identically.
func renderGateShow(issue *types.Issue) {
statusSym := "○"
if issue.Status == types.StatusClosed {
statusSym = "●"
}
fmt.Printf("%s %s - %s\n", statusSym, ui.RenderID(issue.ID), issue.Title)
fmt.Printf(" Status: %s\n", issue.Status)
fmt.Printf(" Await Type: %s\n", issue.AwaitType)
if issue.AwaitID != "" {
fmt.Printf(" Await ID: %s\n", issue.AwaitID)
}
if issue.Timeout > 0 {
fmt.Printf(" Timeout: %s\n", issue.Timeout)
}
if len(issue.Waiters) > 0 {
fmt.Printf(" Waiters:\n")
for _, w := range issue.Waiters {
fmt.Printf(" - %s\n", w)
}
}
if issue.Description != "" {
fmt.Printf(" Description: %s\n", issue.Description)
}
}
// gateResolveCmd manually closes a gate
var gateResolveCmd = &cobra.Command{
Use: "resolve <gate-id>",
Short: "Manually resolve (close) a gate",
Long: `Close a gate issue to unblock the step waiting on it.
This is equivalent to 'bd close <gate-id>' but with a more explicit name.
Use --reason to provide context for why the gate was resolved.`,
Args: cobra.ExactArgs(1),
SilenceUsage: true,
SilenceErrors: true,
RunE: func(cmd *cobra.Command, args []string) error {
if usesProxiedServer() {
return runGateResolveProxiedServer(cmd, rootCtx, args)
}
CheckReadonly("gate resolve")
evt := metrics.NewCommandEvent("gate-resolve")
defer func() {
if c := metrics.Global(); c != nil {
c.CloseEventAndAdd(evt)
}
}()
gateID := args[0]
reason, _ := cmd.Flags().GetString("reason")
ctx := rootCtx
var issue *types.Issue
var err error
issue, err = store.GetIssue(ctx, gateID)
if err != nil {
return HandleError("gate not found: %s", gateID)
}
if issue.IssueType != "gate" {
return HandleError("%s is not a gate issue (type=%s)", gateID, issue.IssueType)
}
if err := store.CloseIssue(ctx, gateID, reason, actor, ""); err != nil {
return HandleError("closing gate: %v", err)
}
commandDidWrite.Store(true)
renderGateResolved(gateID, reason)
return nil
},
}
// renderGateResolved is shared by the direct and proxied-server routes so
// `bd gate resolve` prints identically on both.
func renderGateResolved(gateID, reason string) {
fmt.Printf("%s Gate resolved: %s\n", ui.RenderPass("✓"), gateID)
if reason != "" {
fmt.Printf(" Reason: %s\n", reason)
}
}
// gateCheckCmd evaluates gates and closes those that are resolved
var gateCheckCmd = &cobra.Command{
Use: "check",
Short: "Evaluate gates and close resolved ones",
Long: `Evaluate gate conditions and automatically close resolved gates.
By default, checks all open gates. Use --type to filter by gate type.
Gate types:
gh - Check all GitHub gates (gh:run and gh:pr)
gh:run - Check GitHub Actions workflow runs
gh:pr - Check pull request merge status
timer - Check timer gates (auto-expire based on timeout)
bead - Check cross-rig bead gates
all - Check all gate types
GitHub gates use the 'gh' CLI to query status:
- gh:run checks 'gh run view <id> --json status,conclusion'
- gh:pr checks 'gh pr view <id> --json state,title'
A gate is resolved when:
- gh:run: status=completed AND conclusion=success
- gh:pr: state=MERGED
- timer: current time > created_at + timeout
- bead: target bead status=closed
A gate is escalated when:
- gh:run: status=completed AND conclusion in (failure, canceled)
- gh:pr: state=CLOSED
Examples:
bd gate check # Check all gates
bd gate check --type=gh # Check only GitHub gates
bd gate check --type=gh:run # Check only workflow run gates
bd gate check --type=timer # Check only timer gates
bd gate check --type=bead # Check only cross-rig bead gates
bd gate check --dry-run # Show what would happen without changes
bd gate check --escalate # Escalate expired/failed gates`,
SilenceUsage: true,
SilenceErrors: true,
RunE: func(cmd *cobra.Command, args []string) error {
if usesProxiedServer() {
return runGateCheckProxiedServer(cmd, rootCtx)
}
CheckReadonly("gate check")
evt := metrics.NewCommandEvent("gate-check")
defer func() {
if c := metrics.Global(); c != nil {
c.CloseEventAndAdd(evt)
}
}()
gateTypeFilter, _ := cmd.Flags().GetString("type")
dryRun, _ := cmd.Flags().GetBool("dry-run")
escalateFlag, _ := cmd.Flags().GetBool("escalate")
limit, _ := cmd.Flags().GetInt("limit")
gateType := types.IssueType("gate")
filter := types.IssueFilter{
IssueType: &gateType,
ExcludeStatus: []types.Status{types.StatusClosed},
Limit: limit,
}
ctx := rootCtx
gates, err := store.SearchIssues(ctx, "", filter)
if err != nil {
return HandleErrorRespectJSON("%v", err)
}
filteredGates := filterCheckableGates(gates, gateTypeFilter)
if len(filteredGates) == 0 {
printNoOpenGates(gateTypeFilter)
return nil
}
var persistAwaitID func(gateID, runID string) error
if !dryRun {
persistAwaitID = func(gateID, runID string) error {
return updateGateAwaitIDFunc(nil, gateID, runID)
}
}
results := evaluateGates(ctx, filteredGates, time.Now(), routedBeadGateGetter{localStore: store}, persistAwaitID)
resolvedCount, escalatedCount, errorCount := applyGateCheckResults(
results, dryRun, escalateFlag,
func(gate *types.Issue, reason string) error {
return closeGate(ctx, gate.ID, reason)
},
)
return printGateCheckSummary(len(results), resolvedCount, escalatedCount, errorCount, dryRun)
},
}
type gateCheckResult struct {
gate *types.Issue
resolved bool
escalated bool
reason string
err error
}
func filterCheckableGates(gates []*types.Issue, typeFilter string) []*types.Issue {
var out []*types.Issue
for _, gate := range gates {
if shouldCheckGate(gate, typeFilter) {
out = append(out, gate)
}
}
return out
}
func printNoOpenGates(typeFilter string) {
if typeFilter != "" {
fmt.Printf("No open gates of type '%s' found.\n", typeFilter)
} else {
fmt.Println("No open gates found.")
}
}
func evaluateGates(ctx context.Context, gates []*types.Issue, now time.Time, getter issueGetter, persistAwaitID func(gateID, runID string) error) []gateCheckResult {
results := make([]gateCheckResult, 0, len(gates))
for _, gate := range gates {
r := gateCheckResult{gate: gate}
switch {
case strings.HasPrefix(gate.AwaitType, "gh:run"):
r.resolved, r.escalated, r.reason, r.err = checkGHRun(gate, persistAwaitID)
case strings.HasPrefix(gate.AwaitType, "gh:pr"):
r.resolved, r.escalated, r.reason, r.err = checkGHPR(gate)
case gate.AwaitType == "timer":
r.resolved, r.escalated, r.reason, r.err = checkTimer(gate, now)
case gate.AwaitType == "bead":
r.resolved, r.reason, r.err = checkBeadGate(ctx, getter, gate.AwaitID)
default:
continue
}
results = append(results, r)
}
return results
}
func applyGateCheckResults(results []gateCheckResult, dryRun, escalate bool, closeResolved func(gate *types.Issue, reason string) error) (resolvedCount, escalatedCount, errorCount int) {
for _, r := range results {
if r.err != nil {
errorCount++
fmt.Fprintf(os.Stderr, "%s %s: error checking - %v\n",
ui.RenderFail("✗"), r.gate.ID, r.err)
continue
}
switch {
case r.resolved:
resolvedCount++
if dryRun {
fmt.Printf("%s %s: would resolve - %s\n",
ui.RenderPass("✓"), r.gate.ID, r.reason)
continue
}
if closeErr := closeResolved(r.gate, r.reason); closeErr != nil {
fmt.Fprintf(os.Stderr, "%s %s: error closing - %v\n",
ui.RenderFail("✗"), r.gate.ID, closeErr)
errorCount++
} else {
fmt.Printf("%s %s: resolved - %s\n",
ui.RenderPass("✓"), r.gate.ID, r.reason)
}
case r.escalated:
escalatedCount++
if dryRun {
fmt.Printf("%s %s: would escalate - %s\n",
ui.RenderWarn("⚠"), r.gate.ID, r.reason)
continue
}
fmt.Printf("%s %s: ESCALATE - %s\n",
ui.RenderWarn("⚠"), r.gate.ID, r.reason)
if escalate {
escalateGate(r.gate, r.reason)
}
default:
fmt.Printf("%s %s: pending - %s\n",
ui.RenderAccent("○"), r.gate.ID, r.reason)
}
}
return resolvedCount, escalatedCount, errorCount
}
func printGateCheckSummary(checked, resolvedCount, escalatedCount, errorCount int, dryRun bool) error {
fmt.Println()
fmt.Printf("Checked %d gates: %d resolved, %d escalated, %d errors\n",
checked, resolvedCount, escalatedCount, errorCount)
if jsonOutput {
if err := outputJSON(map[string]interface{}{
"checked": checked,
"resolved": resolvedCount,
"escalated": escalatedCount,
"errors": errorCount,
"dry_run": dryRun,
}); err != nil {
return err
}
}
if errorCount > 0 {
// errorCount holds both row kinds applyGateCheckResults prints: a gate
// whose check failed ("error checking") and a resolved gate whose close
// failed ("error closing"). Neither is resolved or pending, so the
// caller must not mistake this run for a clean sweep.
return fmt.Errorf("%d gate(s) could not be checked or closed", errorCount)
}
return nil
}
// shouldCheckGate returns true if the gate matches the type filter
func shouldCheckGate(gate *types.Issue, typeFilter string) bool {
if typeFilter == "" || typeFilter == "all" {
return true
}
if typeFilter == "gh" {
return strings.HasPrefix(gate.AwaitType, "gh:")
}
return gate.AwaitType == typeFilter
}
// ghRunStatus holds the JSON response from 'gh run view'
type ghRunStatus struct {
Status string `json:"status"`
Conclusion string `json:"conclusion"`
Name string `json:"name"`
}
// ghPRStatus holds the JSON response from 'gh pr view'
type ghPRStatus struct {
State string `json:"state"`
Title string `json:"title"`
}
type ghCommandRunner func(args ...string) (stdout, stderr []byte, err error)
func runGHCommand(args ...string) (stdout, stderr []byte, err error) {
cmd := exec.Command("gh", args...) // #nosec G204 -- callers pass validated values as an argument vector, without a shell
var stdoutBuffer, stderrBuffer bytes.Buffer
cmd.Stdout = &stdoutBuffer
cmd.Stderr = &stderrBuffer
err = cmd.Run()
return stdoutBuffer.Bytes(), stderrBuffer.Bytes(), err
}
var (
discoverRunIDByWorkflowNameFunc = discoverRunIDByWorkflowName
updateGateAwaitIDFunc = updateGateAwaitID
checkGHRunStatusFunc = checkGHRunStatus
)
// isNumericID returns true if the string contains only digits (a GitHub run ID)
func isNumericID(s string) bool {
if s == "" {
return false
}
for _, c := range s {
if c < '0' || c > '9' {
return false
}
}
return true
}
// githubRepoFromIssue returns a validated [HOST/]OWNER/REPO value from metadata.repo.
// A missing repo key, or metadata without a repo key at all, means the current
// Git repository should be used. An explicit `"repo":null` or a non-string
// repo value is rejected as malformed rather than silently falling back to
// the current repository - the docs promise malformed values are rejected,
// and a silent fallback here is the dangerous direction (it can point a
// cross-repo check at the wrong repository instead of failing loudly).
func githubRepoFromIssue(issue *types.Issue) (string, error) {
if issue == nil || len(issue.Metadata) == 0 || string(issue.Metadata) == "null" {
return "", nil
}
var raw map[string]json.RawMessage
if err := json.Unmarshal(issue.Metadata, &raw); err != nil {
return "", fmt.Errorf("metadata must be a JSON object: %w", err)
}
repoRaw, hasRepo := raw["repo"]
if !hasRepo {
return "", nil
}
var repoValue interface{}
if err := json.Unmarshal(repoRaw, &repoValue); err != nil {
return "", fmt.Errorf("metadata.repo: %w", err)
}
if repoValue == nil {
return "", fmt.Errorf("metadata.repo must not be null")
}
repo, ok := repoValue.(string)
if !ok {
return "", fmt.Errorf("metadata.repo must be a string, got %T", repoValue)
}
if repo == "" {
return "", nil
}
parts := strings.Split(repo, "/")
if len(parts) != 2 && len(parts) != 3 {
return "", fmt.Errorf("repo %q must use OWNER/REPO or HOST/OWNER/REPO", repo)
}
for _, part := range parts {
if part == "" {
return "", fmt.Errorf("repo %q contains an empty path component", repo)
}
for _, char := range part {
if (char >= 'a' && char <= 'z') || (char >= 'A' && char <= 'Z') ||
(char >= '0' && char <= '9') || char == '-' || char == '_' || char == '.' {
continue
}
return "", fmt.Errorf("repo %q contains invalid character %q", repo, char)
}
}
return repo, nil
}
// isGitHubGateType returns true for gate types whose condition is checked
// against a GitHub repository (gh:run, gh:pr, and any future gh:* type).
func isGitHubGateType(gateType string) bool {
return strings.HasPrefix(gateType, "gh:")
}
// repoMetadataForGate computes the metadata to store on a new ad-hoc gate,
// inheriting a validated GitHub repo selector from the blocked issue.
//
// This is restricted to gh:* gate types (SF4): "repo" is legal, unrelated
// metadata on any issue (the metadata contract allows arbitrary JSON), so
// running GitHub-repo validation for human/timer gates would fail ordinary
// gate creation whenever the blocked issue happened to carry a non-GitHub-
// shaped "repo" key. Only gh:run/gh:pr gates need the value at check time,
// so only they inherit and validate it here.
func repoMetadataForGate(gateType string, targetIssue *types.Issue) (json.RawMessage, error) {
if !isGitHubGateType(gateType) {
return nil, nil
}
repo, err := githubRepoFromIssue(targetIssue)
if err != nil {
return nil, err
}
if repo == "" {
return nil, nil
}
metadata, err := json.Marshal(map[string]string{"repo": repo})
if err != nil {
return nil, err
}
return metadata, nil
}
// queryGitHubRunsForWorkflow queries recent runs for a specific workflow using gh CLI.
// Returns runs sorted newest-first (GitHub API default).
func queryGitHubRunsForWorkflow(workflow string, limit int) ([]GHWorkflowRun, error) {
return queryGitHubRunsForWorkflowInRepo(workflow, limit, "")
}
func queryGitHubRunsForWorkflowInRepo(workflow string, limit int, repo string) ([]GHWorkflowRun, error) {
if _, err := exec.LookPath("gh"); err != nil {
return nil, fmt.Errorf("gh CLI not found: install from https://cli.github.com")
}
return queryGitHubRunsForWorkflowInRepoWithRunner(workflow, limit, repo, runGHCommand)
}
func queryGitHubRunsForWorkflowInRepoWithRunner(workflow string, limit int, repo string, runGH ghCommandRunner) ([]GHWorkflowRun, error) {
args := []string{
"run", "list",
"--workflow", workflow,
"--json", "databaseId,name,status,conclusion,createdAt,workflowName",
"--limit", fmt.Sprintf("%d", limit),
}
if repo != "" {
args = append(args, "--repo", repo)
}
output, stderr, err := runGH(args...)
if err != nil {
if len(stderr) > 0 {
return nil, fmt.Errorf("gh run list --workflow=%s failed: %s", workflow, string(stderr))
}
return nil, fmt.Errorf("gh run list: %w", err)
}
var runs []GHWorkflowRun
if err := json.Unmarshal(output, &runs); err != nil {
return nil, fmt.Errorf("parse gh output: %w", err)
}
return runs, nil
}
// discoverRunIDByWorkflowName queries GitHub for the most recent run of a workflow.
// Returns (runID, error). This is ZFC-compliant: "most recent run" is deterministic.
func discoverRunIDByWorkflowName(workflowHint string) (string, error) {
return discoverRunIDByWorkflowNameInRepo(workflowHint, "")
}
func discoverRunIDByWorkflowNameInRepo(workflowHint, repo string) (string, error) {
return discoverRunIDByWorkflowNameInRepoWithRunner(workflowHint, repo, runGHCommand)
}
// discoverRunIDByWorkflowNameInRepoWithRunner is the runner-injectable form of
// discoverRunIDByWorkflowNameInRepo. checkGHRunWithRunner's cross-repo branch
// must call this (not discoverRunIDByWorkflowNameInRepo directly) so the same
// injected ghCommandRunner seam used everywhere else in the gh:run/gh:pr
// checks also covers cross-repo discovery, keeping that path unit-testable
// without a live `gh` CLI (standards note on the SF1 review).
func discoverRunIDByWorkflowNameInRepoWithRunner(workflowHint, repo string, runGH ghCommandRunner) (string, error) {
// Query GitHub directly for this workflow (efficient, avoids limit issues)
runs, err := queryGitHubRunsForWorkflowInRepoWithRunner(workflowHint, 5, repo, runGH)
if err != nil {
return "", fmt.Errorf("failed to query workflow runs: %w", err)
}
if len(runs) == 0 {
return "", fmt.Errorf("no runs found for workflow '%s'", workflowHint)
}
// Take the most recent run (gh returns newest-first)
// This is deterministic: "most recent" is a total ordering by creation time
return fmt.Sprintf("%d", runs[0].DatabaseID), nil
}
// checkGHRun checks a GitHub Actions workflow run gate.
// When persistAwaitID is nil, workflow-name discovery stays in-memory only.
func checkGHRun(gate *types.Issue, persistAwaitID func(gateID, runID string) error) (resolved, escalated bool, reason string, err error) {
return checkGHRunWithRunner(gate, persistAwaitID, runGHCommand)
}
func checkGHRunWithRunner(gate *types.Issue, persistAwaitID func(gateID, runID string) error, runGH ghCommandRunner) (resolved, escalated bool, reason string, err error) {
if gate.AwaitID == "" {
return false, false, "no run ID specified - set await_id or use workflow name hint", nil
}
runID := gate.AwaitID
repo, repoErr := githubRepoFromIssue(gate)
if repoErr != nil {
return false, false, "", repoErr
}
// If await_id is a workflow name hint (non-numeric), auto-discover the run ID
if !isNumericID(gate.AwaitID) {
var discoveredID string
var discoverErr error
if repo == "" {
discoveredID, discoverErr = discoverRunIDByWorkflowNameFunc(gate.AwaitID)
} else {
discoveredID, discoverErr = discoverRunIDByWorkflowNameInRepoWithRunner(gate.AwaitID, repo, runGH)
}
if discoverErr != nil {
return false, false, fmt.Sprintf("workflow hint '%s': %v", gate.AwaitID, discoverErr), nil
}
if persistAwaitID != nil {
// Non-dry-run flows persist the numeric run ID for future checks.
if updateErr := persistAwaitID(gate.ID, discoveredID); updateErr != nil {
return false, false, "", fmt.Errorf("failed to update gate with discovered run ID: %w", updateErr)
}
}
runID = discoveredID
}
if repo == "" {
return checkGHRunStatusFunc(runID)
}
return checkGHRunStatusInRepoWithRunner(runID, repo, runGH)
}
func checkGHRunStatus(runID string) (resolved, escalated bool, reason string, err error) {
return checkGHRunStatusInRepo(runID, "")
}
func checkGHRunStatusInRepo(runID, repo string) (resolved, escalated bool, reason string, err error) {
return checkGHRunStatusInRepoWithRunner(runID, repo, runGHCommand)
}
func checkGHRunStatusInRepoWithRunner(runID, repo string, runGH ghCommandRunner) (resolved, escalated bool, reason string, err error) {
// Run: gh run view <id> --json status,conclusion,name
args := []string{"run", "view", runID, "--json", "status,conclusion,name"}
if repo != "" {
args = append(args, "--repo", repo)
}
stdout, stderr, runErr := runGH(args...)
if runErr != nil {
// Check if gh CLI is not found
if strings.Contains(string(stderr), "command not found") ||
strings.Contains(runErr.Error(), "executable file not found") {
return false, false, "", fmt.Errorf("gh CLI not installed")
}
// Check if run not found
if strings.Contains(string(stderr), "not found") {
return false, true, "workflow run not found", nil
}
return false, false, "", fmt.Errorf("gh run view failed: %s", string(stderr))
}
var status ghRunStatus
if parseErr := json.Unmarshal(stdout, &status); parseErr != nil {
return false, false, "", fmt.Errorf("failed to parse gh output: %w", parseErr)
}
// Evaluate status
switch status.Status {
case "completed":
switch status.Conclusion {
case "success":
return true, false, fmt.Sprintf("workflow '%s' succeeded", status.Name), nil
case "failure":
return false, true, fmt.Sprintf("workflow '%s' failed", status.Name), nil
case "cancelled", "canceled":
return false, true, fmt.Sprintf("workflow '%s' was canceled", status.Name), nil
case "skipped":
return true, false, fmt.Sprintf("workflow '%s' was skipped", status.Name), nil
default:
return false, true, fmt.Sprintf("workflow '%s' concluded with %s", status.Name, status.Conclusion), nil
}
case "in_progress", "queued", "pending", "waiting":
return false, false, fmt.Sprintf("workflow '%s' is %s", status.Name, status.Status), nil
default:
return false, false, fmt.Sprintf("workflow '%s' status: %s", status.Name, status.Status), nil
}
}
// checkGHPR checks a GitHub pull request gate
func checkGHPR(gate *types.Issue) (resolved, escalated bool, reason string, err error) {
return checkGHPRWithRunner(gate, runGHCommand)
}
func checkGHPRWithRunner(gate *types.Issue, runGH ghCommandRunner) (resolved, escalated bool, reason string, err error) {
if gate.AwaitID == "" {
return false, false, "no PR number specified", nil
}
repo, repoErr := githubRepoFromIssue(gate)
if repoErr != nil {
return false, false, "", repoErr
}
// Run: gh pr view <id> --json state,title [--repo <repo>]
args := []string{"pr", "view", gate.AwaitID, "--json", "state,title"}
if repo != "" {
args = append(args, "--repo", repo)
}
stdout, stderr, runErr := runGH(args...)
if runErr != nil {
// Check if gh CLI is not found
if strings.Contains(string(stderr), "command not found") ||
strings.Contains(runErr.Error(), "executable file not found") {
return false, false, "", fmt.Errorf("gh CLI not installed")
}
// Check if PR not found
if strings.Contains(string(stderr), "not found") || strings.Contains(string(stderr), "Could not resolve") {
return false, true, "pull request not found", nil
}
return false, false, "", fmt.Errorf("gh pr view failed: %s", string(stderr))
}
var status ghPRStatus
if parseErr := json.Unmarshal(stdout, &status); parseErr != nil {
return false, false, "", fmt.Errorf("failed to parse gh output: %w", parseErr)
}
// Evaluate status
switch status.State {
case "MERGED":
return true, false, fmt.Sprintf("PR '%s' was merged", status.Title), nil
case "CLOSED":
return false, true, fmt.Sprintf("PR '%s' was closed without merging", status.Title), nil
case "OPEN":
return false, false, fmt.Sprintf("PR '%s' is still open", status.Title), nil
default:
return false, false, fmt.Sprintf("PR '%s' state: %s", status.Title, status.State), nil
}
}
// checkTimer checks a timer gate for expiration
// Note: timers resolve but never escalate (escalated is always false by design)
func checkTimer(gate *types.Issue, now time.Time) (resolved, escalated bool, reason string, err error) { //nolint:unparam // escalated intentionally always false
if gate.Timeout == 0 {
return false, false, "timer gate without timeout configured", fmt.Errorf("no timeout set")
}
expiresAt := gate.CreatedAt.Add(gate.Timeout)
if now.After(expiresAt) {
expired := now.Sub(expiresAt).Round(time.Second)
return true, false, fmt.Sprintf("timer expired %s ago", expired), nil
}
remaining := expiresAt.Sub(now).Round(time.Second)
return false, false, fmt.Sprintf("expires in %s", remaining), nil
}
// issueGetter is the one storage method checkBeadGate needs, split out so
// tests can fake the lookup without standing up a Dolt store.
type issueGetter interface {
GetIssue(ctx context.Context, id string) (*types.Issue, error)
}
// routedBeadGateGetter gives direct-mode gate checks the same local -> prefix
// route -> contributor fallback used by other read commands. Routed stores are
// opened read-only and closed before the result is returned.
type routedBeadGateGetter struct {
localStore storage.DoltStorage
}
func (g routedBeadGateGetter) GetIssue(ctx context.Context, id string) (*types.Issue, error) {
if g.localStore == nil {
return nil, fmt.Errorf("no local store available")
}
result, err := getIssueWithRouting(ctx, g.localStore, id)
if err != nil {
return nil, err
}
defer result.Close()
return result.Issue, nil
}
// checkBeadGate checks if a bead gate is satisfied.
// Returns (satisfied, reason, err). A non-nil err means the awaited bead could
// not be read at all (backend or transport failure): the gate is neither
// satisfied nor pending, and the caller reports it as an error rather than
// letting a dead store read as "still waiting". A missing bead is not an
// error; it stays pending with a not-found reason.
//
// A plain await_id names a bead in this rig. The historical
// <rig>:<bead-id> form uses the bead ID as the routed lookup key; the rig
// component is retained for compatibility while routes.jsonl remains keyed by
// bead prefix. The supplied getter owns local-versus-routed lookup policy.
func checkBeadGate(ctx context.Context, st issueGetter, awaitID string) (bool, string, error) {
if awaitID == "" {
return false, "bead gate has no await_id", nil
}
targetID := awaitID
if strings.Contains(awaitID, ":") {
parts := strings.SplitN(awaitID, ":", 2)
if parts[0] == "" || parts[1] == "" {
return false, fmt.Sprintf("invalid cross-rig bead gate %q: expected <rig>:<bead-id>", awaitID), nil
}
targetID = parts[1]
}
if st == nil {
return false, fmt.Sprintf("bead gate %q: no local store available", awaitID), nil
}
issue, err := st.GetIssue(ctx, targetID)
if err != nil {
if gateProxiedNotFound(err) || isNotFoundErr(err) {
return false, fmt.Sprintf("bead gate %q: bead not found", awaitID), nil
}
return false, "", fmt.Errorf("bead gate %q: %w", awaitID, err)
}
if issue == nil {
return false, fmt.Sprintf("bead gate %q: bead not found", awaitID), nil
}
if issue.Status == types.StatusClosed {
return true, fmt.Sprintf("bead %s closed", targetID), nil
}
return false, fmt.Sprintf("bead %s is %s", targetID, issue.Status), nil
}
// closeGate closes a gate issue with the given reason
func closeGate(_ interface{}, gateID, reason string) error {
if err := store.CloseIssue(rootCtx, gateID, reason, actor, ""); err != nil {
return err
}
commandDidWrite.Store(true)
return nil
}
// escalateGate sends an escalation for a failed/expired gate
func escalateGate(gate *types.Issue, reason string) {
topic := fmt.Sprintf("Gate escalation: %s", gate.ID)
message := fmt.Sprintf("Gate %s needs attention.\nType: %s\nReason: %s\nCreated: %s",
gate.ID,
gate.AwaitType,
reason,
gate.CreatedAt.Format(time.RFC3339))
// Call gt escalate if available
escalateCmd := exec.Command("gt", "escalate", topic, "-s", "HIGH", "-m", message)
escalateCmd.Stdout = os.Stdout
escalateCmd.Stderr = os.Stderr
if err := escalateCmd.Run(); err != nil {
fmt.Fprintf(os.Stderr, "Warning: escalation failed for %s: %v\n", gate.ID, err)
}
}
func init() {
// gate list flags
gateListCmd.Flags().BoolP("all", "a", false, "Show all gates including closed")
gateListCmd.Flags().IntP("limit", "n", 50, "Limit results (default 50)")
// gate resolve flags
gateResolveCmd.Flags().StringP("reason", "r", "", "Reason for resolving the gate")
// gate check flags
gateCheckCmd.Flags().StringP("type", "t", "", "Gate type to check (gh, gh:run, gh:pr, timer, bead, all)")
gateCheckCmd.Flags().Bool("dry-run", false, "Show what would happen without making changes")
gateCheckCmd.Flags().BoolP("escalate", "e", false, "Escalate failed/expired gates")
gateCheckCmd.Flags().IntP("limit", "l", 100, "Limit results (default 100)")
// gate create flags
gateCreateCmd.Flags().String("blocks", "", "Issue ID to block (required)")
gateCreateCmd.Flags().StringP("type", "t", "human", "Gate type (human, timer, gh:run, gh:pr)")
gateCreateCmd.Flags().StringP("reason", "r", "", "Reason for the gate")
gateCreateCmd.Flags().String("await-id", "", "Condition identifier (run ID, PR number, etc.)")
gateCreateCmd.Flags().String("timeout", "", "Timeout duration (e.g., 2h, 30m)")
gateCreateCmd.Flags().String("title", "", "Custom gate title (default: \"Gate: <type>\")")
_ = gateCreateCmd.MarkFlagRequired("blocks")
// Issue ID completions
gateShowCmd.ValidArgsFunction = issueIDCompletion
gateResolveCmd.ValidArgsFunction = issueIDCompletion
gateAddWaiterCmd.ValidArgsFunction = issueIDCompletion
gateCreateCmd.ValidArgsFunction = issueIDCompletion
// Add subcommands
gateCmd.AddCommand(gateListCmd)
gateCmd.AddCommand(gateCreateCmd)
gateCmd.AddCommand(gateShowCmd)
gateCmd.AddCommand(gateResolveCmd)
gateCmd.AddCommand(gateCheckCmd)
gateCmd.AddCommand(gateAddWaiterCmd)
rootCmd.AddCommand(gateCmd)
}