domain

package

v0.1.0 Latest Latest Go to latest Published: Jun 26, 2026 License: MIT Imports: 5 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/JacobRWebb/shepherd

Links

Open Source Insights

Documentation ¶

Overview ¶

Package domain defines Shepherd's core entities and sentinel errors.

It is the innermost layer of the application: it imports nothing else in the project. Every other package (worktree, agent, session, forge, pipeline, ...) maps its own provider- or tool-specific data into these neutral types, so no gh/Bitbucket/tmux detail ever leaks outward.

Constants ¶

This section is empty.

Variables ¶

View Source

var (
	ErrNotFound     = errors.New("not found")
	ErrInvalidInput = errors.New("invalid input")
	ErrConflict     = errors.New("conflict")
	ErrNotGitRepo   = errors.New("not a git repository")
	ErrDirty        = errors.New("working tree has uncommitted changes")
	ErrUnsupported  = errors.New("unsupported operation")
)

Sentinel errors. Wrap these with fmt.Errorf("%w: ...", ErrX) and compare with errors.Is. The CLI maps each to a distinct process exit code.

View Source

var (
	// ErrUnsupportedIssueRef means the issue id cannot be resolved by this
	// provider (e.g. a non-numeric ref on GitHub).
	ErrUnsupportedIssueRef = errors.New("issue reference not supported by this provider")
	// ErrIssueTrackerDisabled means the repository has no issue tracker.
	ErrIssueTrackerDisabled = errors.New("issue tracker is disabled for this repository")
)

Forge-related sentinel errors (defined here so provider impls can return them without importing the forge package).

Functions ¶

func Conflictf ¶

func Conflictf(format string, args ...any) error

Conflictf builds an error that satisfies errors.Is(err, ErrConflict).

func InvalidInputf ¶

func InvalidInputf(format string, args ...any) error

InvalidInputf builds an error that satisfies errors.Is(err, ErrInvalidInput) while carrying a specific, human-readable message.

func NotFoundf ¶

func NotFoundf(format string, args ...any) error

NotFoundf builds an error that satisfies errors.Is(err, ErrNotFound).

Types ¶

type Check ¶

type Check struct {
	Name        string      `json:"name"`
	Bucket      CheckBucket `json:"bucket"`
	RawState    string      `json:"raw_state,omitempty"` // provider-native state, for logs
	Workflow    string      `json:"workflow,omitempty"`
	Link        string      `json:"link,omitempty"`
	Description string      `json:"description,omitempty"`
	StartedAt   time.Time   `json:"started_at,omitempty"`
	CompletedAt time.Time   `json:"completed_at,omitempty"`
}

Check is a forge-neutral CI/status check on a pull request.

type CheckBucket ¶

type CheckBucket string

CheckBucket normalizes CI/check outcomes across providers. It mirrors the GitHub `gh pr checks --json bucket` categories; Bitbucket states are mapped onto the same set.

const (
	CheckPass    CheckBucket = "pass"
	CheckFail    CheckBucket = "fail"
	CheckPending CheckBucket = "pending"
	CheckSkip    CheckBucket = "skipping"
	CheckCancel  CheckBucket = "cancel"
)

type CheckSummary ¶

type CheckSummary struct {
	Checks  []Check `json:"checks"`
	AllPass bool    `json:"all_pass"`
	AnyFail bool    `json:"any_fail"`
	Pending int     `json:"pending"`
	Failed  []Check `json:"failed,omitempty"`
}

CheckSummary is an aggregate verdict over a set of checks.

func Summarize ¶

func Summarize(cs []Check) CheckSummary

Summarize reduces a slice of checks to a CheckSummary. With no checks, AllPass is false (nothing has reported success yet).

type Comment ¶

type Comment struct {
	ID        string    `json:"id,omitempty"`
	Author    string    `json:"author,omitempty"`
	Body      string    `json:"body"`
	Path      string    `json:"path,omitempty"`
	Line      int       `json:"line,omitempty"`
	IsReview  bool      `json:"is_review"`
	URL       string    `json:"url,omitempty"`
	CreatedAt time.Time `json:"created_at,omitempty"`
}

Comment is a forge-neutral PR comment. A non-empty Path marks an inline review comment anchored to a file/line.

type Issue ¶

type Issue struct {
	ID     string   `json:"id,omitempty"`
	Number int      `json:"number,omitempty"`
	Title  string   `json:"title"`
	Body   string   `json:"body,omitempty"`
	State  string   `json:"state,omitempty"`
	Author string   `json:"author,omitempty"`
	URL    string   `json:"url,omitempty"`
	Labels []string `json:"labels,omitempty"`
}

Issue is a forge-neutral issue/work item.

type OpenPROpts ¶

type OpenPROpts struct {
	Title     string
	Body      string
	Head      string // source branch
	Base      string // destination branch (empty => provider default)
	Draft     bool
	Reviewers []string // logins (GitHub) or account UUIDs (Bitbucket)
	Labels    []string // GitHub only
}

OpenPROpts are the inputs to opening a pull request.

type PRState ¶

type PRState string

PRState is the forge-neutral state of a pull request.

const (
	PRStateOpen   PRState = "open"
	PRStateClosed PRState = "closed"
	PRStateMerged PRState = "merged"
)

type PullRequest ¶

type PullRequest struct {
	Number      int       `json:"number"`
	ID          string    `json:"id,omitempty"`
	Title       string    `json:"title"`
	Body        string    `json:"body,omitempty"`
	State       PRState   `json:"state"`
	IsDraft     bool      `json:"is_draft"`
	URL         string    `json:"url"`
	HeadRef     string    `json:"head_ref"`           // source branch
	BaseRef     string    `json:"base_ref"`           // destination branch
	HeadSHA     string    `json:"head_sha,omitempty"` // source commit (Bitbucket needs this)
	Author      string    `json:"author,omitempty"`
	Mergeable   *bool     `json:"mergeable,omitempty"`    // nil = unknown
	ReviewState string    `json:"review_state,omitempty"` // e.g. APPROVED, CHANGES_REQUESTED
	CreatedAt   time.Time `json:"created_at,omitempty"`
	UpdatedAt   time.Time `json:"updated_at,omitempty"`
}

PullRequest is a forge-neutral pull/merge request.

type Repo ¶

type Repo struct {
	Owner string `json:"owner"`
	Name  string `json:"name"`
}

Repo identifies a repository across providers. GitHub: Owner/Name. Bitbucket: Owner=workspace, Name=repo_slug.

func (Repo) IsZero ¶

func (r Repo) IsZero() bool

IsZero reports whether the repo is unset.

func (Repo) String ¶

func (r Repo) String() string

type Task ¶

type Task struct {
	Raw     string     `json:"raw"`                // original user input
	Title   string     `json:"title"`              // short title (issue title or first line)
	Body    string     `json:"body,omitempty"`     // detailed description (issue body or full text)
	Source  TaskSource `json:"source"`             // free_text | issue
	IssueID string     `json:"issue_id,omitempty"` // set when Source == TaskSourceIssue (e.g. "123")
}

Task is a unit of work to be carried out inside a worktree. It is derived either from a forge issue reference (#123, PROJ-45, a URL) or from free text.

func NewTask ¶

func NewTask(raw string) Task

NewTask interprets raw as either an issue reference or free text. Forge enrichment (fetching the real title/body) happens later in the `new` flow; this only does cheap local parsing so the tool works offline.

func (Task) Slug ¶

func (t Task) Slug() string

Slug returns a lowercase, dash-separated identifier derived from the task, suitable as the base for a branch/worktree name. It is OS-agnostic; the worktree package applies any filesystem sanitization on top.

type TaskSource ¶

type TaskSource string

TaskSource records where a Task came from.

const (
	TaskSourceFreeText TaskSource = "free_text"
	TaskSourceIssue    TaskSource = "issue"
)

type Worktree ¶

type Worktree struct {
	Name     string `json:"name"`     // logical name (directory basename)
	Path     string `json:"path"`     // absolute path on disk
	Branch   string `json:"branch"`   // branch name (empty if detached)
	Head     string `json:"head"`     // checked-out commit SHA
	IsMain   bool   `json:"is_main"`  // true for the primary working tree
	Detached bool   `json:"detached"` // HEAD is detached (no branch)
	Locked   bool   `json:"locked"`
	Prunable bool   `json:"prunable"`
}

Worktree is a git worktree known to the repository. The main working tree is included in listings and flagged with IsMain; Shepherd refuses to perform mutating operations against it.

Source Files ¶

View all Source files

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL