orchestrate

package
v0.37.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 23, 2026 License: MIT Imports: 19 Imported by: 0

Documentation

Overview

Package orchestrate runs typed repository mutations through isolated worktrees, local verification, and optional GitHub publication stages.

Index

Constants

View Source 
const DefaultCheckPollInterval = 30 * time.Second

DefaultCheckPollInterval deliberately leaves room for other WB operations sharing the authenticated GitHub user budget. A PR receipt still reads every dynamic fact on each observation; only static branch policy is cached within the bounded slice and is fetched again before a pass is returned.

View Source 
const MaxForegroundCheckWaitSlice = 9 * time.Minute

MaxForegroundCheckWaitSlice keeps a single agent-tool call under the common ten-minute harness ceiling. Longer CI is observed by explicit re-invocation, never a detached worker or a hidden thirty-minute loop.

Variables

This section is empty.

Functions

func EnsureCanonical 

func EnsureCanonical(ctx context.Context, repository Repository, canonical string, options Options) error

EnsureCanonical clones a missing repository, fetches origin, and verifies the configured base ref without checking out or modifying the canonical tree.

Types

type Assessment 

type Assessment[T any] struct {
	Metadata    T
	Applicable  bool
	NeedsChange bool
	Reason      string
}

Assessment is adapter-owned planning metadata plus an execution decision.

type Handler 

type Handler[T any] interface {
	Inspect(context.Context, string, string, Repository) (Assessment[T], error)
	Apply(context.Context, string, Repository) (T, error)
	ValidatePublishable(context.Context, string, Repository) error
	CommitMessage(Repository) string
	PullRequest(Repository) (title, body string)
}

Handler supplies mutation policy while Engine owns repository lifecycle.

type OperationLock 

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

OperationLock prevents two processes from mutating the same operation worktrees. Higher-level planners may hold a campaign lock while individual lifecycle runs also protect their wave directories.

func AcquireOperationLock 

func AcquireOperationLock(githubDir, operation string, resume bool) (OperationLock, error)

AcquireOperationLock creates an exclusive lock below the operation root. An unheld remnant is reclaimable only by an explicit resume and only when its descriptor proves exact ownership of this operation.

func (OperationLock) Release 

func (lock OperationLock) Release() error

Release retires the exact held lock inode. It is safe to call from defer and cannot unlink a successor lock installed after this operation acquired one.

type Options 

type Options struct {
	GitHubDir string
	Operation string
	Branch    string
	Ref       string
	Parallel  int
	DryRun    bool
	Resume    bool
	Verify    bool
	Checks    []quality.Check
	Timeout   time.Duration
	Retry     int
	// CheckPollInterval overrides the GitHub-check polling delay. A zero value
	// uses the production default. It is primarily useful for deterministic
	// lifecycle tests.
	CheckPollInterval time.Duration
	Commit            bool
	Push              bool
	PR                bool
	Merge             bool
}

Options controls a repository operation independently of mutation policy.

func Normalize 

func Normalize(options Options) (Options, error)

Normalize validates lifecycle settings and applies cumulative publication implications shared by every orchestrated command.

type PullRequestWaitOptions added in v0.28.0 

type PullRequestWaitOptions struct {
	Repository        string
	PullRequest       string
	Target            string
	Head              string
	Slice             time.Duration
	CheckPollInterval time.Duration
}

PullRequestWaitOptions identifies exactly one direct-push or pull-request head whose observed checks are read by a bounded foreground invocation. A caller resumes a pending result with the same repository, target, PR (when supplied), and head; any later head is a distinct integration candidate.

type PullRequestWaitResult added in v0.28.0 

type PullRequestWaitResult struct {
	Status                   PullRequestWaitStatus `json:"status" yaml:"status"`
	Repository               string                `json:"repository" yaml:"repository"`
	PullRequest              string                `json:"pull_request,omitempty" yaml:"pull_request,omitempty"`
	Target                   string                `json:"target" yaml:"target"`
	Head                     string                `json:"head" yaml:"head"`
	ObservedHead             string                `json:"observed_head,omitempty" yaml:"observed_head,omitempty"`
	ObservedTargetHead       string                `json:"observed_target_head,omitempty" yaml:"observed_target_head,omitempty"`
	CandidateContainsTarget  bool                  `json:"candidate_contains_target,omitempty" yaml:"candidate_contains_target,omitempty"`
	TargetFreshnessAuthority string                `json:"target_freshness_authority,omitempty" yaml:"target_freshness_authority,omitempty"`
	Checks                   []RemoteCheck         `json:"checks,omitempty" yaml:"checks,omitempty"`
	RequiredChecks           []RequiredRemoteCheck `json:"required_checks,omitempty" yaml:"required_checks,omitempty"`
	RequiredChecksAuthority  string                `json:"required_checks_authority,omitempty" yaml:"required_checks_authority,omitempty"`
	StableObservations       int                   `json:"stable_observations" yaml:"stable_observations"`
	Reason                   string                `json:"reason,omitempty" yaml:"reason,omitempty"`
}

PullRequestWaitResult is one terminating foreground observation slice. Pending means resume is required, not that the merger is finished.

func WaitForCommitChecks added in v0.28.0 

func WaitForCommitChecks(ctx context.Context, options PullRequestWaitOptions) (PullRequestWaitResult, error)

WaitForCommitChecks observes checks for one exact target commit. PullRequest is optional: when present it corroborates that exact PR head and target and augments the exact-head check-run/status receipt with GitHub's PR view. Every mode observes the exact commit through producer-aware APIs. Pending is an intermediate terminal result that callers resume with the same identity, not successful completion.

func WaitForPullRequestChecks added in v0.28.0 

func WaitForPullRequestChecks(ctx context.Context, options PullRequestWaitOptions) (PullRequestWaitResult, error)

WaitForPullRequestChecks retains the original internal seam for existing orchestrated PR flows while using the exact-commit waiter above.

type PullRequestWaitStatus added in v0.28.0 

type PullRequestWaitStatus string

PullRequestWaitStatus is intentionally small so callers can branch on a machine result instead of parsing human GitHub CLI output. 

const (
	PullRequestWaitPassed  PullRequestWaitStatus = "passed"
	PullRequestWaitPending PullRequestWaitStatus = "pending"
	PullRequestWaitFailed  PullRequestWaitStatus = "failed"
)

type RemoteCheck 

type RemoteCheck struct {
	Name   string `json:"name" yaml:"name"`
	Bucket string `json:"bucket" yaml:"bucket"`
	Link   string `json:"link,omitempty" yaml:"link,omitempty"`
	AppID  int64  `json:"app_id,omitempty" yaml:"app_id,omitempty"`
}

RemoteCheck is the normalized GitHub check state observed before merge.

type Repository 

type Repository struct {
	Slug     string
	Path     string
	CloneURL string
	Archived bool
}

Repository identifies a canonical clone selected by command-level discovery.

type RequiredRemoteCheck added in v0.28.0 

type RequiredRemoteCheck struct {
	Name          string `json:"name" yaml:"name"`
	IntegrationID int64  `json:"integration_id,omitempty" yaml:"integration_id,omitempty"`
}

RequiredRemoteCheck is GitHub's target-policy expectation. IntegrationID is non-zero when a ruleset pins the context to one GitHub App; every receipt must then observe the matching exact-head check-run producer, not merely a same-named PR summary or legacy status from another actor.

type Result 

type Result[T any] struct {
	Repository    string
	CanonicalDir  string
	WorktreeDir   string
	Branch        string
	Ref           string
	Status        string
	Reason        string
	Metadata      T
	ChangedFiles  []string
	Verifications []quality.VerificationEntry
	Commit        string
	Pushed        bool
	PR            string
	Checks        []RemoteCheck
	Merged        bool
}

Result records lifecycle state and typed adapter metadata for one repository.

func Run 

func Run[T any](ctx context.Context, repositories []Repository, handler Handler[T], options Options) ([]Result[T], error)

Run executes a typed mutation over independent repositories. It completes every safe local/PR stage before entering the CI wait-and-merge phase.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.