foreach

Documentation

Overview

Package foreach provides functionality for executing a command on each branch in a stack.

Index

• func Action(ctx *app.Context, opts Options, handler Handler) error
• func HasForeachWork(ctx *app.Context, opts Options) (bool, error)
• type BranchInfo
• type BranchProgressEvent
• type BranchResult
• type BranchStatus
• type ChannelHandler
  • func NewChannelHandler(bufferSize int) *ChannelHandler
  • func (h *ChannelHandler) Close()
  • func (h *ChannelHandler) Events() <-chan Event
  • func (h *ChannelHandler) OnEvent(e Event)
• type CompletionEvent
• type Event
• type ExecutionStartEvent
• type Handler
• type JSONBranchResult
• type JSONHandler
  • func NewJSONHandler() *JSONHandler
  • func (h *JSONHandler) OnEvent(e Event)
  • func (h *JSONHandler) SetError(err error)
• type JSONResult
• type JSONStatus
• type Options
• type StackDisplayEvent

Functions

func Action

func Action(ctx *app.Context, opts Options, handler Handler) error

Action executes a command on each branch in the stack with event handling

func HasForeachWork

func HasForeachWork(ctx *app.Context, opts Options) (bool, error)

HasForeachWork reports whether Action would have at least one non-trunk branch to execute the command on. Use this from the CLI to gate TUI initialization — when the answer is no, starting the bubbletea runner only flashes startup/teardown escape codes and races with the deferred Cleanup before the "no branches to process" CompletionEvent can render.

Types

type BranchInfo

type BranchInfo struct {
	Name string
}

BranchInfo contains information about a branch for execution tracking.

type BranchProgressEvent

type BranchProgressEvent struct {
	BranchName string
	Status     BranchStatus
	Output     string // command output (may be truncated)
	Error      error  // set on failure
}

BranchProgressEvent indicates per-branch execution progress.

type BranchResult

type BranchResult struct {
	BranchName string
	Status     BranchStatus
	ExitCode   int
	Output     string
	Error      error
}

BranchResult contains the final result for a branch

type BranchStatus

type BranchStatus string

BranchStatus represents the status of a branch during execution.

const (
	StatusPending BranchStatus = "pending"
	StatusRunning BranchStatus = "running"
	StatusDone    BranchStatus = "done"
	StatusError   BranchStatus = "error"
	StatusSkipped BranchStatus = "skipped"
)

BranchStatus values for tracking execution progress.

type ChannelHandler

type ChannelHandler struct {
	// contains filtered or unexported fields
}

ChannelHandler is a Handler that sends events to a channel. Useful for async consumers like the dashboard.

func NewChannelHandler

func NewChannelHandler(bufferSize int) *ChannelHandler

NewChannelHandler creates a new ChannelHandler with a buffered channel.

func (*ChannelHandler) Close

func (h *ChannelHandler) Close()

Close closes the event channel. Should be called when the action is complete.

func (*ChannelHandler) Events

func (h *ChannelHandler) Events() <-chan Event

Events returns the event channel for reading.

func (*ChannelHandler) OnEvent

func (h *ChannelHandler) OnEvent(e Event)

OnEvent sends the event to the channel. Non-blocking: if the channel is full, the event is dropped.

type CompletionEvent

type CompletionEvent struct {
	Success bool
	Message string
	Results []BranchResult // Consolidated results for all branches
}

CompletionEvent indicates the action has finished.

type Event

type Event interface {
	// contains filtered or unexported methods
}

Event represents a feedback event from the foreach action. Implementations should use type switches to handle specific event types.

type ExecutionStartEvent

type ExecutionStartEvent struct {
	Branches []BranchInfo
}

ExecutionStartEvent indicates the execution phase is beginning.

type Handler

type Handler interface {
	// OnEvent is called for each event during execution.
	// Handlers should use type switches to handle specific event types.
	OnEvent(event Event)
}

Handler receives events from the foreach action and handles user interaction. Implementations should handle events appropriately for their UI context (interactive terminal, non-interactive, dashboard, etc.)

type JSONBranchResult

type JSONBranchResult struct {
	Branch   string       `json:"branch"`
	Status   BranchStatus `json:"status"`
	ExitCode int          `json:"exit_code"`
	Output   string       `json:"output,omitempty"`
	Error    string       `json:"error,omitempty"`
}

JSONBranchResult represents one branch result in foreach JSON output.

type JSONHandler

type JSONHandler struct {
	Result *JSONResult
	// contains filtered or unexported fields
}

JSONHandler collects foreach events for JSON output.

func NewJSONHandler

func NewJSONHandler() *JSONHandler

NewJSONHandler creates a handler that collects foreach results as JSON data.

func (*JSONHandler) OnEvent

func (h *JSONHandler) OnEvent(e Event)

OnEvent implements Handler.

func (*JSONHandler) SetError

func (h *JSONHandler) SetError(err error)

SetError records an action-level error in the JSON result.

type JSONResult

type JSONResult struct {
	Status       JSONStatus         `json:"status"`
	Error        string             `json:"error,omitempty"`
	Message      string             `json:"message,omitempty"`
	Command      string             `json:"command,omitempty"`
	Results      []JSONBranchResult `json:"results"`
	TotalCount   int                `json:"total_count"`
	SuccessCount int                `json:"success_count"`
	FailureCount int                `json:"failure_count"`
}

JSONResult represents the JSON output for foreach operations.

type JSONStatus

type JSONStatus string

JSONStatus represents the aggregate outcome of a foreach operation.

const (
	JSONStatusSuccess JSONStatus = "success"
	JSONStatusFailure JSONStatus = "failure"
	JSONStatusError   JSONStatus = "error"
)

type Options

type Options struct {
	Command          string
	Args             []string
	BranchName       string
	Scope            engine.StackRange
	AllStacks        bool     // Run across every independent stack rooted at trunk
	StackRoots       []string // Run across the listed independent stack roots only
	FailFast         bool
	Parallel         bool
	FindFirstFailure bool
	Jobs             int
}

Options contains options for the foreach command

type StackDisplayEvent

type StackDisplayEvent struct {
	Stack   *tree.StackTree // tree structure for rendering the stack
	Command string          // command being executed
}

StackDisplayEvent indicates the initial stack visualization phase. Handlers can use this to display the branches that will be processed.