repository

type AuditBase struct {
	Name   string `json:"name,omitempty"`
	Source string `json:"source"`
	Ahead  int    `json:"ahead"`
	Behind int    `json:"behind"`
}

type AuditInput struct {
	Name   string
	Path   string
	Status *RepositoryStatusResult
	Base   BaseBranchInfo

	// Integration* is the repo-root integrationBranch answer used only for the
	// upstream safety finding. It is deliberately separate from Base, whose
	// public meaning remains defaultBranch-relative divergence.
	IntegrationName            string
	IntegrationSource          string
	UpstreamTargetsIntegration bool
	UpstreamRemote             string
	TaskRemoteExists           bool

	// Worktrees are the checkouts other than the main one, with the branch each
	// holds. Branches checked out here are excluded from plain branch deletion:
	// `git branch -d` refuses a branch a worktree is using, so a remediation
	// that ignored this would emit a command that cannot run.
	Worktrees []AuditWorktree

	// PrunableWorktrees are paths git reports as orphaned metadata.
	PrunableWorktrees []string

	// MergedBranches are local branches fully contained in the base branch,
	// excluding the base itself. Verified by ancestry, never inferred from
	// naming or from divergence counts.
	MergedBranches []string

	// RemoteBotMerged are origin remote-tracking bot branches whose tips are
	// ancestors of the base. Names have no origin/ prefix.
	RemoteBotMerged []string

	// RemoteBotSuperseded are origin remote-tracking bot branches that are not
	// ancestors of the base, but whose version target is already satisfied
	// there (equal or newer Go module / Actions pin).
	RemoteBotSuperseded []string

	// RemoteBotPending are origin remote-tracking bot branches that are not
	// ancestors of the base and still newer or not comparable — they may
	// still be an open PR.
	RemoteBotPending []string

	// EnrichErr is a failure from collecting the extra facts above.
	EnrichErr error

	// StaleStashAfter is how old the oldest stash must be to be reported.
	// Zero disables the check.
	StaleStashAfter time.Duration

	// Now is the reference time for age comparisons, injected so results are
	// reproducible in tests.
	Now time.Time

	// AutofixPolicy answers whether an agent may apply a given code
	// unattended. A nil policy means nothing is auto-fixable.
	AutofixPolicy func(code string) bool
}

type AuditRepo struct {
	Name   string `json:"name"`
	Path   string `json:"path"`
	Branch string `json:"branch,omitempty"`

	// Complete reports whether every check ran against trustworthy state.
	// False means findings on this repository are partial, and an agent must
	// resolve the blocker before acting on anything else here — emitting
	// confident numbers derived from a half-finished rebase would be worse
	// than admitting the audit could not run.
	//
	// The wire name keeps the "audit_" prefix the Go field drops: inside
	// AuditRepo the type already supplies that context, but in the emitted
	// document a bare "complete" reads as a property of the repository rather
	// than of the audit that examined it.
	Complete bool `json:"audit_complete"` //nolint:tagliatelle // wire name is part of the published v1 schema

	// IncompleteReason is the code of the blocker that set Complete false.
	IncompleteReason string `json:"incomplete_reason,omitempty"`

	Base     AuditBase `json:"base"`
	Upstream string    `json:"upstream,omitempty"`

	// Worktrees lists the linked checkouts. They are reported even when they
	// produce no finding: a branch checked out elsewhere is not visible in this
	// repository's own status, so without this an agent reading the document
	// would conclude the work does not exist.
	Worktrees []AuditWorktree `json:"worktrees,omitempty"`

	Findings []Finding `json:"findings"`
}

type AuditResult struct {
	Schema       string       `json:"schema"`
	Directory    string       `json:"directory"`
	Repositories []AuditRepo  `json:"repositories"`
	Summary      AuditSummary `json:"summary"`
}

type AuditSummary struct {
	Total          int            `json:"total"`
	Complete       int            `json:"complete"`
	Incomplete     int            `json:"incomplete"`
	WithFindings   int            `json:"with_findings"`
	FindingsByCode map[string]int `json:"findings_by_code,omitempty"`
	Blockers       int            `json:"blockers"`
}

type AuditWorktree struct {
	Path string `json:"path"`

	// Branch is empty for a detached worktree.
	Branch string `json:"branch,omitempty"`
}

type BaseBranchInfo struct {
	// Name is the resolved base branch, or empty when no candidate exists.
	Name string

	// Source explains the resolution: "config.defaultBranch[i]" for the i-th
	// configured candidate that won, "heuristic" for the fallback list, or
	// "none" when nothing matched. Never empty.
	Source string

	// Ahead is the number of commits reachable from HEAD but not from the base
	// (work the base does not have yet). Zero when there is no base.
	Ahead int

	// Behind is the number of commits reachable from the base but not from HEAD
	// (work the base has that HEAD lacks — the rebase/pull signal). Zero when
	// there is no base.
	Behind int

	// SHA is the short hash of the base tip, or empty when there is no base.
	SHA string
}

type BaseDivergence struct {
	// RemoteOnly is the number of commits the remote base has that the local
	// ref lacks — how far the local pointer fell behind.
	RemoteOnly int

	// LocalOnly is the number of commits on the local base ref that the remote
	// base does not have. Non-zero means this is not a fast-forward.
	LocalOnly int

	// Stranded is how many of the LocalOnly commits are reachable from no
	// remote-tracking ref of this remote at all — not from the base, not from a
	// task branch, not from anything that was ever pushed.
	//
	// This is the number that decides whether local-only commits represent real
	// unpushed work or a stale pointer parked on a branch that was pushed
	// elsewhere. A local base sitting on the tip of a task branch that lives on
	// the remote has LocalOnly > 0 and Stranded == 0: the commits exist on
	// origin under another name, so moving the pointer loses no history. A base
	// carrying genuinely unpushed commits has Stranded > 0, and moving the
	// pointer would strand them in the reflog.
	Stranded int
}

type BaseSyncAction string

type BaseSyncOptions struct {
	// Remote is the remote whose base ref is the target. Required.
	Remote string

	// Candidates is the base-branch search order, typically
	// EffectiveConfig.Branch.DefaultBranch. Empty falls back to the heuristic
	// list ResolveBase already uses.
	Candidates []string

	// Fetch refreshes the base's remote-tracking ref before comparing.
	Fetch bool

	// DryRun reports the decision without writing any ref.
	DryRun bool

	// CreateMissing materializes a local base ref from the remote when the
	// repository has none. Off by default: absence of a local trunk is often
	// intentional on a develop-only clone, and creating a branch the user never
	// asked for is a different act than repairing one that fell behind.
	CreateMissing bool
}

type BaseSyncResult struct {
	// Base is the resolved base branch name, empty when none resolved.
	Base string

	// BaseSource echoes BaseBranchInfo.Source so a caller can explain which
	// policy picked this branch.
	BaseSource string

	// Remote is the remote whose base ref was used as the target.
	Remote string

	// Action is the decision reached.
	Action BaseSyncAction

	// Advanced is how many commits the local base ref gained. Zero for every
	// action except FastForward and Adopted, and zero on a dry run.
	Advanced int

	// Divergence holds the counts the decision was made from.
	Divergence BaseDivergence

	// Reason explains a Skipped or Blocked action in one clause. Empty when the
	// action speaks for itself.
	Reason string

	// Backup is the ref the previous base tip was parked at before an adopt
	// rewound it, empty when nothing was parked. Only Adopted sets it.
	Backup string

	// DryRun echoes BaseSyncOptions.DryRun.
	//
	// Advanced is zero both on a dry run and on a real adopt that only rewinds,
	// so a renderer cannot tell "nothing happened yet" from "a ref moved
	// backwards" without being told which run this was.
	DryRun bool
}

type BranchConfig struct {
	// Remote is the default remote for this branch.
	Remote string

	// Merge is the default merge ref for this branch.
	Merge string

	// Rebase indicates if rebase should be used instead of merge.
	Rebase bool
}

type BranchInfo struct {
	Name     string // Branch name
	SHA      string // Commit SHA
	IsHead   bool   // Currently checked out
	IsRemote bool   // Remote branch
	Upstream string // Upstream branch (if set)
	AheadBy  int    // Commits ahead of upstream
	BehindBy int    // Commits behind upstream
}

type BulkBranchListOptions struct {
	// Directory is the root directory to scan for repositories
	Directory string

	// Parallel is the number of concurrent workers (default: 10)
	Parallel int

	// MaxDepth is the maximum directory depth to scan (default: 10)
	MaxDepth int

	// All includes remote branches (-a/--all)
	All bool

	// Merged shows only merged branches
	Merged bool

	// Unmerged shows only unmerged branches
	Unmerged bool

	// IncludeSubmodules includes git submodules in the scan
	IncludeSubmodules bool

	// IncludePattern is a regex pattern for repositories to include
	IncludePattern string

	// ExcludePattern is a regex pattern for repositories to exclude
	ExcludePattern string

	// Logger for operation feedback
	Logger Logger

	// ProgressCallback is called for each processed repository
	ProgressCallback func(current, total int, repo string)
}

type BulkBranchListResult struct {
	// TotalScanned is the number of repositories found
	TotalScanned int

	// TotalProcessed is the number of repositories processed
	TotalProcessed int

	// Repositories contains individual repository results
	Repositories []RepositoryBranchListResult

	// Duration is the total operation time
	Duration time.Duration

	// Summary contains status counts
	Summary map[string]int

	// TotalBranchCount is the total number of branches across all repos
	TotalBranchCount int

	// TotalLocalCount is the total number of local branches
	TotalLocalCount int

	// TotalRemoteCount is the total number of remote branches
	TotalRemoteCount int
}

type BulkCleanOptions struct {
	// Directory is the root directory to scan for repositories
	Directory string

	// Parallel is the number of concurrent workers (default: 10)
	Parallel int

	// MaxDepth is the maximum directory depth to scan (default: 10)
	MaxDepth int

	// DryRun performs simulation without actual deletion (default: true)
	DryRun bool

	// RemoveDirectories also removes untracked directories (-d flag)
	RemoveDirectories bool

	// RemoveIgnored removes ignored files in addition to untracked (-x flag)
	RemoveIgnored bool

	// OnlyIgnored removes only ignored files, not untracked (-X flag)
	OnlyIgnored bool

	// ExcludePatterns are patterns to exclude from cleaning (-e flag)
	ExcludePatterns []string

	// IncludeSubmodules includes git submodules in the scan (default: false)
	IncludeSubmodules bool

	// IncludePattern is a regex pattern for repositories to include
	IncludePattern string

	// ExcludePattern is a regex pattern for repositories to exclude
	ExcludePattern string

	// Logger for operation feedback
	Logger Logger

	// ProgressCallback is called for each processed repository
	ProgressCallback func(current, total int, repo string)
}

type BulkCleanResult struct {
	// TotalScanned is the number of repositories found
	TotalScanned int

	// TotalProcessed is the number of repositories processed
	TotalProcessed int

	// Repositories contains individual repository results
	Repositories []RepositoryCleanResult

	// Duration is the total operation time
	Duration time.Duration

	// Summary contains status counts
	Summary map[string]int

	// TotalFiles is the total number of files removed/would-remove across all repos
	TotalFiles int
}

type BulkCleanupOptions struct {
	// Directory is the root directory to scan for repositories
	Directory string

	// Parallel is the number of concurrent workers (default: 10)
	Parallel int

	// MaxDepth is the maximum directory depth to scan (default: 10)
	MaxDepth int

	// DryRun performs simulation without actual changes
	DryRun bool

	// Verbose enables detailed logging
	Verbose bool

	// IncludeMerged includes fully merged branches
	IncludeMerged bool

	// IncludeStale includes stale branches (no recent activity)
	IncludeStale bool

	// IncludeGone includes gone branches (remote deleted)
	IncludeGone bool

	// IncludeSuperseded includes unmerged bot remotes whose version target
	// is already satisfied on the base. Only bot names are considered.
	IncludeSuperseded bool

	// IncludeNonCanonical retires branches that duplicate the repository's
	// declared canonical branch. It does nothing without CanonicalResolver.
	IncludeNonCanonical bool

	// CanonicalResolver resolves one repository's declared canonical branch and
	// task-branch allow-list from its .gz-git.yaml.
	//
	// It is injected rather than called directly because the declaration is
	// owned by pkg/config, and pkg/config imports this package — the dependency
	// cannot run the other way. A nil resolver disables the classification
	// entirely, which is the safe default for every existing caller.
	CanonicalResolver func(ctx context.Context, repoPath string) (canonical string, taskPatterns []string, err error)

	// StaleThreshold is the threshold for stale branches (default: 30 days)
	StaleThreshold time.Duration

	// BaseBranch is the base branch for merge detection (default: auto-detect)
	BaseBranch string

	// DeleteRemote also deletes remote branches
	DeleteRemote bool

	// RemoteDeleteGuard authorizes a remote branch deletion for one repository.
	// It is injected by the command boundary because workspace access policy is
	// outside this package. A nil guard preserves existing read-write behavior.
	RemoteDeleteGuard func(ctx context.Context, repoPath string) error

	// BotsOnly restricts candidates to Dependabot/Renovate/github-actions
	// prefixes. It is a filter, not a cleanup type.
	BotsOnly bool

	// ProtectPatterns are additional patterns to protect from deletion
	ProtectPatterns []string

	// IncludeSubmodules includes git submodules in the scan (default: false)
	IncludeSubmodules bool

	// IncludePattern is a regex pattern for repositories to include
	IncludePattern string

	// ExcludePattern is a regex pattern for repositories to exclude
	ExcludePattern string

	// Logger for operation feedback
	Logger Logger

	// ProgressCallback is called for each processed repository
	ProgressCallback func(current, total int, repo string)
}

type BulkCleanupResult struct {
	// TotalScanned is the number of repositories found
	TotalScanned int

	// TotalProcessed is the number of repositories processed
	TotalProcessed int

	// Repositories contains individual repository results
	Repositories []RepositoryCleanupResult

	// Duration is the total operation time
	Duration time.Duration

	// Summary contains status counts
	Summary map[string]int

	// TotalBranchesDeleted is the total number of branches deleted across all repos
	TotalBranchesDeleted int

	// TotalBranchesFailed is the total number of branches the run tried to
	// delete and could not.
	TotalBranchesFailed int

	// TotalBranchesAnalyzed is the total number of branches analyzed
	TotalBranchesAnalyzed int
}

type BulkCloneOptions struct {
	// URLs is the list of repository URLs to clone.
	URLs []string

	// Directory is the base directory for cloning (default: current directory).
	Directory string

	// Structure determines directory organization (flat or user).
	Structure DirectoryStructure

	// Strategy determines how to handle existing repositories.
	// Valid values: "skip" (default), "pull", "fetch", "force".
	Strategy UpdateStrategy

	// Branch is the branch to checkout after cloning.
	Branch string

	// Depth limits clone depth (0 = full clone).
	Depth int

	// SingleBranch clones only the target branch history (--single-branch).
	SingleBranch bool

	// Recursive initializes and clones submodules (--recurse-submodules).
	Recursive bool

	// Parallel is the number of concurrent operations.
	Parallel int

	// DryRun shows what would be done without doing it.
	DryRun bool

	// Verbose enables detailed output.
	Verbose bool

	// Logger for operation feedback.
	Logger Logger

	// ProgressCallback is called during bulk operations.
	ProgressCallback func(current, total int, repo string)
}

type BulkCloneResult struct {
	// TotalRequested is the number of URLs requested.
	TotalRequested int

	// TotalCloned is the number successfully cloned.
	TotalCloned int

	// TotalUpdated is the number successfully updated (when --update is used).
	TotalUpdated int

	// TotalSkipped is the number skipped (already exists, no --update).
	TotalSkipped int

	// TotalFailed is the number that failed.
	TotalFailed int

	// Duration is the total operation time.
	Duration time.Duration

	// Repositories contains individual results.
	Repositories []RepositoryCloneResult

	// Summary contains counts by status.
	Summary map[string]int
}

type BulkCommitOptions struct {
	// Directory is the root directory to scan for repositories
	Directory string

	// Parallel is the number of concurrent workers (default: 10)
	Parallel int

	// MaxDepth is the maximum directory depth to scan (default: 1)
	MaxDepth int

	// DryRun shows what would be committed without actually committing
	DryRun bool

	// Message is a common message for all repositories (overrides auto-generation)
	Message string

	// Yes auto-approves without confirmation
	Yes bool

	// IncludePattern is a regex pattern to include repositories
	IncludePattern string

	// ExcludePattern is a regex pattern to exclude repositories
	ExcludePattern string

	// IncludeSubmodules includes git submodules in the scan
	IncludeSubmodules bool

	// AllowConflicted commits repositories that still have unmerged paths.
	// Off by default: `git add -A` marks conflicts as resolved, so committing
	// them writes conflict markers into history irreversibly.
	AllowConflicted bool

	// Verbose enables detailed logging
	Verbose bool

	// Logger for progress logging
	Logger Logger

	// ProgressCallback is called for each repository processed
	ProgressCallback func(current, total int, repo string)

	// MessageGenerator generates commit messages for repositories
	// If nil, a simple default message is generated
	MessageGenerator func(ctx context.Context, repoPath string, files []string) (string, error)
}

type BulkCommitResult struct {
	// TotalScanned is the number of repositories found
	TotalScanned int

	// TotalDirty is the number of repositories with uncommitted changes
	TotalDirty int

	// TotalCommitted is the number of repositories successfully committed
	TotalCommitted int

	// TotalFailed is the number of repositories that failed to commit
	TotalFailed int

	// TotalSkipped is the number of repositories skipped (clean or excluded)
	TotalSkipped int

	// TotalConflicted is the number of repositories left uncommitted because
	// they still have unmerged paths
	TotalConflicted int

	// Repositories contains individual repository results
	Repositories []RepositoryCommitResult

	// Duration is the total operation time
	Duration time.Duration

	// Summary contains status counts
	Summary map[string]int
}

type BulkDiffOptions struct {
	// Directory is the root directory to scan for repositories
	Directory string

	// Parallel is the number of concurrent workers (default: 10)
	Parallel int

	// MaxDepth is the maximum directory depth to scan (default: 1)
	MaxDepth int

	// Staged shows only staged changes (git diff --cached)
	Staged bool

	// IncludeUntracked includes untracked files in the output
	IncludeUntracked bool

	// ContextLines is the number of context lines around changes (default: 3)
	ContextLines int

	// MaxDiffSize limits the diff size per repository in bytes (default: 100KB)
	MaxDiffSize int

	// IncludePattern is a regex pattern to include repositories
	IncludePattern string

	// ExcludePattern is a regex pattern to exclude repositories
	ExcludePattern string

	// IncludeSubmodules includes git submodules in the scan
	IncludeSubmodules bool

	// Verbose enables detailed logging
	Verbose bool

	// Logger for progress logging
	Logger Logger

	// ProgressCallback is called for each repository processed
	ProgressCallback func(current, total int, repo string)
}

type BulkDiffResult struct {
	// TotalScanned is the number of repositories found
	TotalScanned int

	// TotalWithChanges is the number of repositories with changes
	TotalWithChanges int

	// TotalClean is the number of repositories without changes
	TotalClean int

	// Repositories contains individual repository results
	Repositories []RepositoryDiffResult

	// Duration is the total operation time
	Duration time.Duration

	// Summary contains status counts
	Summary map[string]int
}

type BulkExecOptions struct {
	Directory         string
	Parallel          int
	MaxDepth          int
	DryRun            bool
	IncludeSubmodules bool
	IncludePattern    string
	ExcludePattern    string
	Logger            Logger
	ProgressCallback  func(current, total int, repo string)

	// Command is argv[0]; Args are remaining argv elements. Never passed through a shell.
	Command string
	Args    []string

	// Env extra environment variables (merged with process env). Values for
	// GZ_REPO_NAME / GZ_REPO_PATH are set per-repo automatically.
	// Timeout is the per-repository command deadline (0 = no limit).
	Timeout time.Duration

	// FailFast cancels remaining work after the first non-zero exit.
	FailFast bool

	// OutputTailMax is max bytes of combined stdout/stderr retained per repo (default 4KiB).
	OutputTailMax int
}

type BulkExecResult struct {
	TotalScanned   int
	TotalProcessed int
	Repositories   []RepositoryExecResult
	Duration       time.Duration
	Summary        map[string]int
	Command        string
	Args           []string
}

type BulkFetchOptions struct {
	// Directory is the root directory to scan for repositories
	Directory string

	// Parallel is the number of concurrent workers (default: 10)
	Parallel int

	// MaxDepth is the maximum directory depth to scan (default: 10)
	MaxDepth int

	// DryRun performs simulation without actual changes
	DryRun bool

	// Verbose enables detailed logging
	Verbose bool

	// AllRemotes fetches from all remotes (default: origin only)
	AllRemotes bool

	// Prune removes remote-tracking branches that no longer exist
	Prune bool

	// Tags fetches all tags from remote
	Tags bool

	// IncludeSubmodules includes git submodules in the scan (default: false)
	// When false, only scans for independent nested repositories
	IncludeSubmodules bool

	// IncludePattern is a regex pattern for repositories to include
	IncludePattern string

	// ExcludePattern is a regex pattern for repositories to exclude
	ExcludePattern string

	// Logger for operation feedback
	Logger Logger

	// ProgressCallback is called for each processed repository
	ProgressCallback func(current, total int, repo string)
}

type BulkFetchResult struct {
	// TotalScanned is the number of repositories found
	TotalScanned int

	// TotalProcessed is the number of repositories processed
	TotalProcessed int

	// Repositories contains individual repository results
	Repositories []RepositoryFetchResult

	// Duration is the total operation time
	Duration time.Duration

	// Summary contains status counts
	Summary map[string]int
}

type BulkPullOptions struct {
	// Directory is the root directory to scan for repositories
	Directory string

	// Parallel is the number of concurrent workers (default: 10)
	Parallel int

	// MaxDepth is the maximum directory depth to scan (default: 10)
	MaxDepth int

	// DryRun performs simulation without actual changes
	DryRun bool

	// Verbose enables detailed logging
	Verbose bool

	// Strategy defines how to merge changes (merge, rebase, ff-only)
	Strategy string

	// Prune removes remote-tracking branches that no longer exist
	Prune bool

	// Tags fetches all tags from remote
	Tags bool

	// Stash automatically stashes local changes before pull
	Stash bool

	// IncludeSubmodules includes git submodules in the scan (default: false)
	// When false, only scans for independent nested repositories
	IncludeSubmodules bool

	// IncludePattern is a regex pattern for repositories to include
	IncludePattern string

	// ExcludePattern is a regex pattern for repositories to exclude
	ExcludePattern string

	// Logger for operation feedback
	Logger Logger

	// ProgressCallback is called for each processed repository
	ProgressCallback func(current, total int, repo string)
}

type BulkPullResult struct {
	// TotalScanned is the number of repositories found
	TotalScanned int

	// TotalProcessed is the number of repositories processed
	TotalProcessed int

	// Repositories contains individual repository results
	Repositories []RepositoryPullResult

	// Duration is the total operation time
	Duration time.Duration

	// Summary contains status counts
	Summary map[string]int
}

type BulkPushOptions struct {
	// Directory is the root directory to scan for repositories
	Directory string

	// Parallel is the number of concurrent workers (default: 10)
	Parallel int

	// MaxDepth is the maximum directory depth to scan (default: 10)
	MaxDepth int

	// DryRun performs simulation without actual changes
	DryRun bool

	// Verbose enables detailed logging
	Verbose bool

	// Force forces the push (use with caution)
	Force bool

	// SetUpstream sets upstream for new branches
	SetUpstream bool

	// Tags pushes all tags
	Tags bool

	// Refspec is a custom refspec for branch mapping (e.g., "develop:master")
	Refspec string

	// Remotes is a list of remotes to push to (empty = use origin)
	Remotes []string

	// AllRemotes pushes to all configured remotes
	AllRemotes bool

	// IgnoreDirty skips dirty status check after push (useful for CI/CD)
	IgnoreDirty bool

	// PushAccess optionally decides whether a repository may be pushed. It is
	// evaluated before the repository is opened or any remote is contacted.
	// A denied repository is reported as skipped and the rest of the batch
	// continues.
	PushAccess func(repoPath string) (allowed bool, reason string, err error)

	// Policy restricts which branches may be pushed to and how. A nil policy
	// permits every push. Repositories it refuses are reported as StatusBlocked
	// and the rest of the batch still runs.
	Policy *PushPolicy

	// Identity names this machine and agent, so a force push can tell its own
	// commits from another writer's. An unnamed identity disables that check:
	// a machine that cannot say who it is cannot say who anyone else is.
	Identity identity.Identity

	// IncludeSubmodules includes git submodules in the scan (default: false)
	// When false, only scans for independent nested repositories
	IncludeSubmodules bool

	// IncludePattern is a regex pattern for repositories to include
	IncludePattern string

	// ExcludePattern is a regex pattern for repositories to exclude
	ExcludePattern string

	// Logger for operation feedback
	Logger Logger

	// ProgressCallback is called for each processed repository
	ProgressCallback func(current, total int, repo string)
}

type BulkPushResult struct {
	// TotalScanned is the number of repositories found
	TotalScanned int

	// TotalProcessed is the number of repositories processed
	TotalProcessed int

	// Repositories contains individual repository results
	Repositories []RepositoryPushResult

	// Duration is the total operation time
	Duration time.Duration

	// Summary contains status counts
	Summary map[string]int
}

type BulkRepoResult interface {
	GetStatus() string
	GetPath() string
	GetMessage() string
	GetError() error
}

type BulkStashOptions struct {
	// Directory is the root directory to scan for repositories
	Directory string

	// Parallel is the number of concurrent workers (default: 10)
	Parallel int

	// MaxDepth is the maximum directory depth to scan (default: 10)
	MaxDepth int

	// DryRun performs simulation without actual changes
	DryRun bool

	// Operation is the stash operation: "save", "list", "pop", "apply"
	Operation string

	// Message is the stash message (for save operation)
	Message string

	// IncludeUntracked includes untracked files (for save operation)
	IncludeUntracked bool

	// IncludeSubmodules includes git submodules in the scan
	IncludeSubmodules bool

	// IncludePattern is a regex pattern for repositories to include
	IncludePattern string

	// ExcludePattern is a regex pattern for repositories to exclude
	ExcludePattern string

	// OnlyDirty only processes repositories with uncommitted changes (for save)
	OnlyDirty bool

	// OnlyWithStash only processes repositories with existing stashes (for pop/list)
	OnlyWithStash bool

	// Logger for operation feedback
	Logger Logger

	// ProgressCallback is called for each processed repository
	ProgressCallback func(current, total int, repo string)
}

type BulkStashResult struct {
	// TotalScanned is the number of repositories found
	TotalScanned int

	// TotalProcessed is the number of repositories processed
	TotalProcessed int

	// Repositories contains individual repository results
	Repositories []RepositoryStashResult

	// Duration is the total operation time
	Duration time.Duration

	// Summary contains status counts
	Summary map[string]int

	// TotalStashCount is the total number of stashes affected
	TotalStashCount int
}

type BulkStatusOptions struct {
	// Directory is the root directory to scan for repositories
	Directory string

	// Parallel is the number of concurrent workers (default: 10)
	Parallel int

	// MaxDepth is the maximum directory depth to scan (default: 10)
	MaxDepth int

	// Verbose enables detailed logging for all repositories (including clean ones)
	Verbose bool

	// IncludeSubmodules includes git submodules in the scan (default: false)
	// When false, only scans for independent nested repositories
	IncludeSubmodules bool

	// IncludePattern is a regex pattern for repositories to include
	IncludePattern string

	// ExcludePattern is a regex pattern for repositories to exclude
	ExcludePattern string

	// Logger for operation feedback
	Logger Logger

	// ProgressCallback is called for each processed repository
	ProgressCallback func(current, total int, repo string)
}

type BulkStatusResult struct {
	// TotalScanned is the number of repositories found
	TotalScanned int

	// TotalProcessed is the number of repositories processed
	TotalProcessed int

	// Repositories contains individual repository results
	Repositories []RepositoryStatusResult

	// Duration is the total operation time
	Duration time.Duration

	// Summary contains status counts
	Summary map[string]int
}

type BulkSwitchOptions struct {
	// Directory is the root directory to scan for repositories
	Directory string

	// Branch is the target branch to switch to (required)
	Branch string

	// Parallel is the number of concurrent workers (default: 10)
	Parallel int

	// MaxDepth is the maximum directory depth to scan (default: 1)
	MaxDepth int

	// DryRun performs simulation without actual changes
	DryRun bool

	// Verbose enables detailed logging
	Verbose bool

	// Create creates the branch if it doesn't exist
	Create bool

	// Force forces the switch even with uncommitted changes (dangerous)
	Force bool

	// IncludeSubmodules includes git submodules in the scan (default: false)
	IncludeSubmodules bool

	// IncludePattern is a regex pattern for repositories to include
	IncludePattern string

	// ExcludePattern is a regex pattern for repositories to exclude
	ExcludePattern string

	// Logger for operation feedback
	Logger Logger

	// ProgressCallback is called for each processed repository
	ProgressCallback func(current, total int, repo string)
}

type BulkSwitchResult struct {
	// TotalScanned is the number of repositories found
	TotalScanned int

	// TotalProcessed is the number of repositories processed
	TotalProcessed int

	// Repositories contains individual repository results
	Repositories []RepositorySwitchResult

	// Duration is the total operation time
	Duration time.Duration

	// Summary contains status counts
	Summary map[string]int

	// TargetBranch is the branch that was switched to
	TargetBranch string
}

type BulkTagOptions struct {
	// Directory is the root directory to scan for repositories
	Directory string

	// Parallel is the number of concurrent workers (default: 10)
	Parallel int

	// MaxDepth is the maximum directory depth to scan (default: 10)
	MaxDepth int

	// DryRun performs simulation without actual changes
	DryRun bool

	// Operation is the tag operation: "create", "list", "push", "status"
	Operation string

	// TagName is the tag name (for create operation)
	TagName string

	// Message is the tag message (creates annotated tag)
	Message string

	// Force overwrites existing tags
	Force bool

	// PushAll pushes all tags (for push operation)
	PushAll bool

	// IncludeSubmodules includes git submodules in the scan
	IncludeSubmodules bool

	// IncludePattern is a regex pattern for repositories to include
	IncludePattern string

	// ExcludePattern is a regex pattern for repositories to exclude
	ExcludePattern string

	// Logger for operation feedback
	Logger Logger

	// ProgressCallback is called for each processed repository
	ProgressCallback func(current, total int, repo string)
}

type BulkTagResult struct {
	// TotalScanned is the number of repositories found
	TotalScanned int

	// TotalProcessed is the number of repositories processed
	TotalProcessed int

	// Repositories contains individual repository results
	Repositories []RepositoryTagResult

	// Duration is the total operation time
	Duration time.Duration

	// Summary contains status counts
	Summary map[string]int

	// TotalTagCount is the total number of tags affected/found
	TotalTagCount int
}

type BulkUpdateOptions struct {
	// Directory is the root directory to scan for repositories
	Directory string

	// Parallel is the number of concurrent workers (default: 10)
	Parallel int

	// MaxDepth is the maximum directory depth to scan (default: 10)
	MaxDepth int

	// DryRun performs simulation without actual changes
	DryRun bool

	// Verbose enables detailed logging
	Verbose bool

	// NoFetch skips fetching from remote
	NoFetch bool

	// IncludeSubmodules includes git submodules in the scan (default: false)
	// When false, only scans for independent nested repositories
	IncludeSubmodules bool

	// IncludePattern is a regex pattern for repositories to include
	IncludePattern string

	// ExcludePattern is a regex pattern for repositories to exclude
	ExcludePattern string

	// Logger for operation feedback
	Logger Logger

	// ProgressCallback is called for each processed repository
	ProgressCallback func(current, total int, repo string)

	// SyncBase additionally fast-forwards each repository's local base ref to
	// its remote-tracking counterpart, even when the base is not checked out.
	// Off by default: it writes to a ref the user did not ask about.
	SyncBase bool

	// BaseCandidates is the ordered integration-branch list handed to
	// ResolveBase, normally EffectiveConfig.Branch.DefaultBranch. Empty lets
	// ResolveBase fall back to its own heuristic rather than this option
	// inventing an order.
	BaseCandidates []string

	// CreateMissingBase creates a local base ref from the remote in
	// repositories that have none. Requires SyncBase. Off by default and kept
	// separate from it because the two are different acts: SyncBase repairs a
	// pointer the repository already has, this one adds a branch the user never
	// created.
	CreateMissingBase bool
}

type BulkUpdateResult struct {
	// TotalScanned is the number of repositories found
	TotalScanned int

	// TotalProcessed is the number of repositories processed
	TotalProcessed int

	// Repositories contains individual repository results
	Repositories []RepositoryUpdateResult

	// Duration is the total operation time
	Duration time.Duration

	// Summary contains status counts
	Summary map[string]int
}

type ChangeEntry struct {
	// Path is the repository-relative path as it exists on disk: never quoted,
	// never a collapsed directory.
	Path string

	// OldPath is the source path of a rename or copy, empty otherwise.
	OldPath string

	// Status is the normalized single-letter code (M, A, D, R, C, ?).
	Status string

	// Staged means the index differs from HEAD for this path.
	Staged bool

	// Untracked means the path is not in the index at all.
	Untracked bool

	// Conflicted means the path has unmerged index stages.
	Conflicted bool
}

type ChangeScope string

type ChangeSet struct {
	Entries []ChangeEntry

	// TrackedCount counts entries git already knows about; UntrackedCount counts
	// the rest. Their sum is len(Entries).
	TrackedCount   int
	UntrackedCount int

	// StagedCount and ConflictCount are subsets of Entries, not of each other.
	StagedCount   int
	ConflictCount int

	// Additions and Deletions are the line counts a commit of this change set
	// would record. Tracked lines come from `git diff --numstat`; untracked files
	// are counted separately, since git cannot diff what is not in the index.
	Additions int
	Deletions int

	// DiffFileCount is how many files actually differ from the scope's base.
	// It is not len(Entries): a path can be listed by status yet be identical to
	// HEAD (index and worktree both changed, canceling out), in which case there
	// is nothing to commit even though the repository looks dirty.
	DiffFileCount int

	Scope ChangeScope
}

type ChangedFile struct {
	// Path is the file path
	Path string

	// Status is the change status (M=modified, A=added, D=deleted, R=renamed, etc.)
	Status string

	// OldPath is the old path for renamed files
	OldPath string
}

type CleanupBranchEntry struct {
	Name     string `json:"name"`
	Reason   string `json:"reason"`
	Location string `json:"location"`
	Kind     string `json:"kind,omitempty"`
	// TargetRef and TargetSHA are set on non-canonical candidates: the ref the
	// ancestry was measured against, spelled in full, and where it pointed. They
	// are the justification for the deletion, and until they were carried here
	// the operator passing --force had the branch name and nothing else.
	TargetRef string `json:"target_ref,omitempty"`
	TargetSHA string `json:"target_sha,omitempty"`
}

type CleanupFailureEntry struct {
	Name     string `json:"name"`
	Reason   string `json:"reason"`
	Location string `json:"location"`
	Error    string `json:"error"`
}

type Client interface {

	// Open opens an existing Git repository at the specified path.
	// Returns an error if the path is not a valid Git repository.
	Open(ctx context.Context, path string) (*Repository, error)

	// Clone clones a repository from the specified URL to the destination path.
	// Returns the opened repository on success.
	Clone(ctx context.Context, opts CloneOptions) (*Repository, error)

	// CloneOrUpdate intelligently clones a repository if it doesn't exist,
	// or updates it using the specified strategy if it does.
	// This is a high-level convenience method for repository synchronization.
	CloneOrUpdate(ctx context.Context, opts CloneOrUpdateOptions) (*CloneOrUpdateResult, error)

	// BulkUpdate scans for repositories and updates them in parallel.
	// This is useful for updating multiple repositories at once.
	BulkUpdate(ctx context.Context, opts BulkUpdateOptions) (*BulkUpdateResult, error)

	// BulkFetch scans for repositories and fetches them in parallel.
	// This is useful for fetching updates from multiple repositories at once.
	BulkFetch(ctx context.Context, opts BulkFetchOptions) (*BulkFetchResult, error)

	// BulkPull scans for repositories and pulls them in parallel.
	// This is useful for pulling updates (fetch + merge/rebase) from multiple repositories at once.
	BulkPull(ctx context.Context, opts BulkPullOptions) (*BulkPullResult, error)

	// BulkPush scans for repositories and pushes them in parallel.
	// This is useful for pushing local commits from multiple repositories at once.
	BulkPush(ctx context.Context, opts BulkPushOptions) (*BulkPushResult, error)

	// BulkStatus scans for repositories and checks their status in parallel.
	// This is useful for checking the working tree status of multiple repositories at once.
	BulkStatus(ctx context.Context, opts BulkStatusOptions) (*BulkStatusResult, error)

	// BulkSwitch scans for repositories and switches their branches in parallel.
	// This is useful for switching branches across multiple repositories at once.
	BulkSwitch(ctx context.Context, opts BulkSwitchOptions) (*BulkSwitchResult, error)

	// BulkCommit scans for repositories with uncommitted changes and commits them in parallel.
	// This is useful for batch committing across multiple repositories at once.
	BulkCommit(ctx context.Context, opts BulkCommitOptions) (*BulkCommitResult, error)

	// BulkDiff scans for repositories and gets their diffs in parallel.
	// This is useful for reviewing changes across multiple repositories or for LLM-based commit message generation.
	BulkDiff(ctx context.Context, opts BulkDiffOptions) (*BulkDiffResult, error)

	// BulkClean scans for repositories and removes untracked/ignored files in parallel.
	// Dry-run by default; set DryRun=false (via --force) to actually delete files.
	BulkClean(ctx context.Context, opts BulkCleanOptions) (*BulkCleanResult, error)

	// BulkCleanup scans for repositories and performs branch cleanup in parallel.
	// This is useful for cleaning up merged, stale, or gone branches across multiple repositories.
	BulkCleanup(ctx context.Context, opts BulkCleanupOptions) (*BulkCleanupResult, error)

	// BulkStash scans for repositories and performs stash operations in parallel.
	// This is useful for stashing/popping changes across multiple repositories.
	BulkStash(ctx context.Context, opts BulkStashOptions) (*BulkStashResult, error)

	// BulkTag scans for repositories and performs tag operations in parallel.
	// This is useful for creating/pushing tags across multiple repositories.
	BulkTag(ctx context.Context, opts BulkTagOptions) (*BulkTagResult, error)

	// BulkClone clones multiple repositories from URLs in parallel.
	// Supports --update to pull existing repositories instead of skipping.
	BulkClone(ctx context.Context, opts BulkCloneOptions) (*BulkCloneResult, error)

	// BulkBranchList scans for repositories and lists their branches in parallel.
	// This is useful for listing branches across multiple repositories at once.
	BulkBranchList(ctx context.Context, opts BulkBranchListOptions) (*BulkBranchListResult, error)

	// BulkExec scans for repositories and runs an arbitrary command in each
	// working tree in parallel. Command is executed without a shell.
	BulkExec(ctx context.Context, opts BulkExecOptions) (*BulkExecResult, error)

	// ScanRepositories scans a directory for Git repositories and returns their paths.
	// This is a lightweight scan-only operation (no GetInfo/GetStatus) used when
	// only repository discovery is needed (e.g., before DiagnosticExecutor).
	ScanRepositories(ctx context.Context, opts ScanOptions) (*ScanResult, error)

	// IsRepository checks if the path points to a valid Git repository.
	// Returns true if the path contains a .git directory or is a bare repository.
	IsRepository(ctx context.Context, path string) bool

	// GetInfo retrieves detailed information about a repository.
	// This includes configuration, remote URLs, and other metadata.
	GetInfo(ctx context.Context, repo *Repository) (*Info, error)

	// GetStatus retrieves the current working tree status.
	// This shows modified, staged, untracked files, etc.
	GetStatus(ctx context.Context, repo *Repository) (*Status, error)

	// IncomingForeignWork lists the commits the upstream branch has that the
	// local branch does not, signed by a device or agent other than mine.
	// It names the other writers on a shared branch; an unnamed identity, or a
	// branch with no upstream, yields nothing.
	IncomingForeignWork(ctx context.Context, repoPath string, mine identity.Identity) ([]ForeignCommit, error)

	// ResolveBase picks the integration branch for a repository (config
	// defaultBranch first, then a heuristic fallback) and reports how HEAD
	// diverges from it. See BaseBranchInfo for the policy and the source label.
	ResolveBase(ctx context.Context, repo *Repository, candidates []string) (BaseBranchInfo, error)

	// MergedBranches lists local branches whose tips are already ancestors of
	// base — work that has landed and whose branch is now reclaimable. Base
	// itself and the current branch are excluded.
	MergedBranches(ctx context.Context, repo *Repository, base string) ([]string, error)

	// BotRemoteBranches partitions origin remote-tracking refs with bot prefixes
	// into merged (tip is an ancestor of base), superseded (not an ancestor,
	// but base already satisfies the bot's version target), and pending (not
	// an ancestor and still newer or not comparable). Names are returned
	// without the remote prefix. Skips origin/HEAD and IsProtected names.
	// Empty base returns nil, nil, nil, nil.
	BotRemoteBranches(ctx context.Context, repo *Repository, base string) (merged, superseded, pending []string, err error)

	// SyncBase fast-forwards a repository's local base ref to its
	// remote-tracking counterpart without checking it out. `git fetch` updates
	// refs/remotes/* and `git pull` updates only the checked-out branch, so a
	// base branch nobody checks out is updated by neither and drifts silently.
	// opts.Candidates is the same ordered list ResolveBase takes, so the branch
	// this repairs is the branch `info` reports on. See BaseSyncResult.
	SyncBase(ctx context.Context, repoPath string, opts BaseSyncOptions) (BaseSyncResult, error)
}

type ClientOption func(*client)

type CloneOption func(*CloneOptions)

type CloneOptions struct {
	// URL is the repository URL to clone (required).
	URL string

	// Destination is the local path where the repository will be cloned (required).
	Destination string

	// Branch is the branch to check out after cloning.
	// If empty, the remote's default branch is used.
	Branch string

	// Depth limits the clone depth (number of commits).
	// 0 means full clone, 1 means shallow clone with only the latest commit.
	Depth int

	// SingleBranch clones only the specified branch.
	// If true, other branches are not fetched.
	SingleBranch bool

	// Recursive clones submodules recursively.
	Recursive bool

	// Bare creates a bare repository (no working directory).
	Bare bool

	// Mirror creates a mirror repository (all refs are copied).
	Mirror bool

	// Quiet suppresses progress output.
	Quiet bool

	// CreateBranch creates the branch if it doesn't exist on the remote.
	// If true and the specified branch doesn't exist, it will be created after cloning.
	// Only effective when Branch is specified.
	CreateBranch bool

	// Progress is an optional progress reporter.
	// If provided, clone progress will be reported.
	Progress ProgressReporter

	// Logger is an optional logger.
	// If provided, clone operations will be logged.
	Logger Logger

	// Env contains additional environment variables for the git command.
	// Used for authentication (e.g., GIT_SSH_COMMAND for SSH keys).
	Env []string
}

type CloneOrUpdateOptions struct {
	// URL is the repository URL to clone (required)
	URL string

	// Destination is the local path where the repository will be cloned (required)
	Destination string

	// Strategy defines how to handle an existing repository
	// Default: StrategyRebase
	Strategy UpdateStrategy

	// Branch is the branch to check out after cloning
	// If empty, the remote's default branch is used
	Branch string

	// ExactBranchPrepared records that the caller has successfully fetched the
	// exact Branch ref from origin immediately before this reset. It is only
	// meaningful with StrategyReset and a non-empty Branch; when true, reset
	// uses that prepared remote-tracking ref without another network fetch.
	// Direct callers should leave it false, which preserves the normal fetch.
	ExactBranchPrepared bool

	// Depth limits the clone depth (number of commits)
	// 0 means full clone, 1 means shallow clone with only the latest commit
	Depth int

	// Force allows destructive operations even when not normally allowed
	Force bool

	// CreateBranch creates the branch if it doesn't exist on the remote
	// If true and the specified branch doesn't exist, it will be created after cloning
	// Only effective when Branch is specified
	CreateBranch bool

	// SingleBranch clones only the history of the target branch (--single-branch)
	SingleBranch bool

	// Recursive initializes and clones submodules (--recurse-submodules)
	Recursive bool

	// Logger is an optional logger for operation feedback
	Logger Logger

	// Progress is an optional progress reporter
	Progress ProgressReporter

	// Env contains additional environment variables for the git command.
	// Used for authentication (e.g., GIT_SSH_COMMAND for SSH keys).
	Env []string
}

type CloneOrUpdateResult struct {
	// Repository is the opened repository (nil if skipped)
	Repository *Repository

	// Action describes what action was taken
	Action string // "cloned", "updated", "skipped", "reset", etc.

	// StrategyUsed is the strategy that was actually used
	StrategyUsed UpdateStrategy

	// Success indicates if the operation succeeded
	Success bool

	// Message contains a human-readable result message
	Message string
}

type Config struct {
	// User is the user configuration.
	User UserConfig

	// Core is the core Git configuration.
	Core CoreConfig

	// Remote contains remote configurations.
	Remote map[string]Remote

	// Branch contains branch configurations.
	Branch map[string]BranchConfig
}

type CoreConfig struct {
	// RepositoryFormatVersion is the repository format version.
	RepositoryFormatVersion int

	// FileMode indicates if file mode is tracked.
	FileMode bool

	// Bare indicates if this is a bare repository.
	Bare bool

	// LogAllRefUpdates indicates if all ref updates are logged.
	LogAllRefUpdates bool

	// IgnoreCase indicates if file names are case-insensitive.
	IgnoreCase bool

	// PrecomposeUnicode indicates if Unicode is precomposed.
	PrecomposeUnicode bool
}

type DirectoryStructure string

type FileStatus string

type Finding struct {
	Code     string         `json:"code"`
	Severity string         `json:"severity"`
	Message  string         `json:"message"`
	Evidence map[string]any `json:"evidence,omitempty"`
	Fix      *Remediation   `json:"fix,omitempty"`
}

type ForceMode string

type ForeignCommit struct {
	Hash     string            `json:"hash"`
	Subject  string            `json:"subject"`
	Identity identity.Identity `json:"identity"`
}

type ForeignWorkMode string

type Info struct {
	// Branch is the current branch name (e.g., "main", "master").
	// Empty if in detached HEAD state.
	Branch string

	// Commit is the current HEAD commit hash (full SHA-1).
	Commit string

	// Remote is the default remote name (usually "origin").
	Remote string

	// RemoteURL is the URL of the default remote.
	RemoteURL string

	// IsDirty indicates if there are uncommitted changes.
	IsDirty bool

	// Upstream is the upstream branch (e.g., "origin/main").
	// Empty if no upstream is configured.
	Upstream string

	// AheadBy is the number of commits ahead of upstream.
	AheadBy int

	// BehindBy is the number of commits behind upstream.
	BehindBy int

	// Remotes contains all configured remotes (name -> url).
	Remotes map[string]string

	// HeadSHA is the short hash of the current commit.
	HeadSHA string

	// Describe is the result of 'git describe' (e.g. v1.0.0-5-g123abc).
	Describe string

	// LastCommitMsg is the subject of the last commit.
	LastCommitMsg string

	// LastCommitDate is the relative date of the last commit (e.g. "2 hours ago").
	LastCommitDate string

	// LastCommitAuthor is the author of the last commit.
	LastCommitAuthor string

	// LocalBranches contains the list of local branch names.
	LocalBranches []string

	// RemoteBranches contains remote-tracking branch names in remote/branch
	// form. Symbolic remote HEAD refs are excluded.
	RemoteBranches []string

	// StashCount is the number of stash entries.
	StashCount int

	// OldestStash is when the oldest stash entry was created, zero when there
	// is none. A stash is invisible to every other machine, so its age is the
	// difference between work in progress and work that was forgotten.
	OldestStash time.Time
}

type Logger interface {
	// Debug logs a debug-level message with optional key-value pairs.
	Debug(msg string, args ...any)

	// Info logs an info-level message with optional key-value pairs.
	Info(msg string, args ...any)

	// Warn logs a warning-level message with optional key-value pairs.
	Warn(msg string, args ...any)

	// Error logs an error-level message with optional key-value pairs.
	Error(msg string, args ...any)
}

type OmittedFile struct {
	// Path is the repository-relative file path
	Path string

	// Reason is why the content was omitted: "not-regular-file", "too-large",
	// or "read-error"
	Reason string
}

type OperationType string

type ParsedRefspec struct {
	// Source is the local branch/ref (left side of :)
	Source string
	// Destination is the remote branch/ref (right side of :), empty if not specified
	Destination string
	// Force indicates if this is a force push (+ prefix)
	Force bool
}

type ProgressReporter interface {
	// Start initializes the progress reporter with the total amount of work.
	// The total may be in bytes, number of files, or other units depending on the operation.
	Start(total int64)

	// Update reports current progress.
	// The current value should be <= total.
	Update(current int64)

	// Done signals that the operation is complete.
	// This should be called even if the operation fails.
	Done()
}

type PushDenial struct {
	Rule   PushRule
	Branch string
	Detail string
}

type PushIntent struct {
	// Branch is the branch HEAD is on, used when no refspec names a target.
	Branch string
	// Refspec is the --refspec value, if one was given.
	Refspec string
	// Force reports whether --force was given, which pushes with a lease.
	Force bool
}

type PushPolicy struct {
	// Protected lists branch names and trailing-* patterns that may not be
	// pushed to at all, matching the pattern syntax used for deletion.
	Protected []string `yaml:"protected,omitempty"`

	// ForceMode decides which force pushes are allowed to every other branch.
	ForceMode ForceMode `yaml:"forceMode,omitempty"`

	// ForeignWork decides what happens to a force push that would discard
	// commits signed by another machine or agent. Unset means block.
	//
	// Unlike the rules above it cannot be decided from intent alone: it needs
	// to read the commits the remote has and this machine does not.
	ForeignWork ForeignWorkMode `yaml:"foreignWork,omitempty"`
}

type PushRule string

type Ref struct {
	// Name is the reference name (e.g., "refs/heads/main", "main").
	Name string

	// Hash is the commit hash this reference points to.
	Hash string

	// Type is the reference type (branch, tag, remote).
	Type RefType
}

type RefType string

type Remediation struct {
	Action     string   `json:"action"`
	Command    []string `json:"command,omitempty"`
	Autofix    bool     `json:"autofix"`
	Reversible bool     `json:"reversible"`
	Note       string   `json:"note,omitempty"`
}

type Remote struct {
	// Name is the remote name (e.g., "origin").
	Name string

	// URL is the remote URL.
	URL string

	// Type is the remote type (https, ssh, git, file).
	Type RemoteType

	// FetchRefs are the fetch refspecs.
	FetchRefs []string

	// PushRefs are the push refspecs.
	PushRefs []string
}

type RemoteType string

type RenamedFile struct {
	// OldPath is the original file path.
	OldPath string

	// NewPath is the new file path.
	NewPath string
}

type Repository struct {
	// Path is the absolute path to the repository root.
	// This is the directory containing the .git directory (or the repository itself if bare).
	Path string

	// GitDir is the path to the .git directory.
	// For normal repositories, this is Path/.git
	// For bare repositories, this is the same as Path
	// For worktrees, this points to the linked .git file
	GitDir string

	// WorkTree is the working tree path.
	// For normal repositories, this is the same as Path
	// For bare repositories, this is empty
	// For worktrees, this may differ from Path
	WorkTree string

	// IsBare indicates if this is a bare repository (no working tree).
	IsBare bool

	// IsShallow indicates if this is a shallow clone (partial history).
	IsShallow bool
}

type RepositoryBranchListResult struct {
	// Path is the repository path
	Path string

	// RelativePath is the path relative to scan root
	RelativePath string

	// Status is the operation status
	Status string

	// Message is a human-readable status message
	Message string

	// Error if the operation failed
	Error error

	// Duration is how long this repository took to process
	Duration time.Duration

	// CurrentBranch is the currently checked out branch
	CurrentBranch string

	// Branches is the list of branches
	Branches []BranchInfo

	// LocalCount is the number of local branches
	LocalCount int

	// RemoteCount is the number of remote branches
	RemoteCount int
}

type RepositoryCleanResult struct {
	// Path is the repository path
	Path string

	// RelativePath is the path relative to scan root
	RelativePath string

	// Status is the operation status
	Status string

	// Message is a human-readable status message
	Message string

	// Error if the operation failed
	Error error

	// Duration is how long this repository took to process
	Duration time.Duration

	// Branch is the current branch name
	Branch string

	// FilesRemoved is the list of files removed or would be removed
	FilesRemoved []string

	// FilesCount is the number of files removed or would be removed
	FilesCount int
}

type RepositoryCleanupResult struct {
	// Path is the repository path
	Path string

	// RelativePath is the path relative to scan root
	RelativePath string

	// Status is the operation status
	Status string

	// Message is a human-readable status message
	Message string

	// Error if the operation failed
	Error error

	// Duration is how long this repository took to process
	Duration time.Duration

	// Branch is the current branch name
	Branch string

	// MergedCount is the number of merged branches found/deleted
	MergedCount int

	// StaleCount is the number of stale branches found/deleted
	StaleCount int

	// GoneCount is the number of gone branches found/deleted
	GoneCount int

	// SupersededCount is the number of superseded bot remotes found/deleted
	SupersededCount int

	// NonCanonicalCount is the number of branches retired for duplicating the
	// declared canonical branch
	NonCanonicalCount int

	// ProtectedCount is the number of protected branches skipped
	ProtectedCount int

	// TotalAnalyzed is the total number of branches analyzed
	TotalAnalyzed int

	// DeletedBranches is the list of deleted branch names
	DeletedBranches []string

	// Branches is the per-branch account (name, reason, location, kind)
	// used by machine-readable printers. DeletedBranches stays a flat name
	// list for existing human output.
	Branches []CleanupBranchEntry

	// FailedBranches records candidates the run tried to delete and could not.
	// A candidate count is not a deletion count: git refuses some deletes
	// (a remote's default branch, most commonly), and reporting those as
	// deleted would tell the operator the tree is clean when it is not.
	FailedBranches []CleanupFailureEntry

	// RetireRefusals records trunk-named branches the non-canonical gate
	// examined and declined. They were never candidates, so they are kept apart
	// from FailedBranches: folding them in would inflate TotalBranchesFailed and
	// turn a repository that is behaving correctly into a failing one.
	RetireRefusals []RetireRefusalEntry
}

type RepositoryCloneResult struct {
	// URL is the repository URL.
	URL string

	// Path is the local path where it was cloned.
	Path string

	// RelativePath is the path relative to the base directory.
	RelativePath string

	// Status is the operation status.
	Status string // "cloned", "updated", "skipped", "error", "would-clone", "would-update"

	// Branch is the checked out branch.
	Branch string

	// Duration is how long the operation took.
	Duration time.Duration

	// Error is set if the operation failed.
	Error error
}

type RepositoryCommitResult struct {
	// Path is the repository path
	Path string

	// RelativePath is the path relative to scan root
	RelativePath string

	// Branch is the current branch
	Branch string

	// Status is the operation status (success, skipped, error, would-commit)
	Status string

	// CommitHash is the commit hash if successful
	CommitHash string

	// Message is the commit message used
	Message string

	// SuggestedMessage is the auto-generated message (for preview)
	SuggestedMessage string

	// FilesChanged is the number of files changed
	FilesChanged int

	// TrackedFilesChanged, UntrackedFilesChanged and StagedFilesChanged break
	// FilesChanged down. The untracked count is the one that used to be wrong:
	// without -uall, `?? docs/` counted as a single file while the commit
	// recorded every file beneath it.
	TrackedFilesChanged   int
	UntrackedFilesChanged int
	StagedFilesChanged    int

	// Additions is the number of lines added
	Additions int

	// Deletions is the number of lines deleted
	Deletions int

	// ChangedFiles is the list of changed files
	ChangedFiles []string

	// ConflictedFiles is the list of unmerged files. Non-empty means the
	// repository was not committed (unless AllowConflicted was set).
	ConflictedFiles []string

	// Error if the operation failed
	Error error

	// Duration is the operation time for this repository
	Duration time.Duration
}

type RepositoryDiffResult struct {
	// Path is the repository path
	Path string

	// RelativePath is the path relative to scan root
	RelativePath string

	// Branch is the current branch
	Branch string

	// Status is the operation status (has-changes, clean, error)
	Status string

	// DiffContent is the actual diff output
	DiffContent string

	// DiffSummary is a short summary of changes
	DiffSummary string

	// FilesChanged is the number of tracked files that differ from the scope's
	// base. It equals TrackedFilesChanged and deliberately excludes untracked
	// files, preserving the meaning this key has always had for diff. The full
	// set a commit would record is TrackedFilesChanged + UntrackedFilesChanged.
	FilesChanged int

	// TrackedFilesChanged, UntrackedFilesChanged and StagedFilesChanged name the
	// three counts separately, so a caller can tell why diff and commit report
	// the numbers they do instead of having to guess which set each one means.
	// StagedFilesChanged overlaps the other two rather than partitioning them.
	TrackedFilesChanged   int
	UntrackedFilesChanged int
	StagedFilesChanged    int

	// Scope names the comparison these numbers describe ("head", "staged" or
	// "worktree"). See ChangeScope.
	Scope string

	// Additions is the number of lines added
	Additions int

	// Deletions is the number of lines deleted
	Deletions int

	// ChangedFiles is the list of changed files with their status
	ChangedFiles []ChangedFile

	// UntrackedFiles is the list of untracked files
	UntrackedFiles []string

	// OmittedFiles lists untracked files whose content was left out of
	// DiffContent, with the reason. Never silently empty: every skip in the
	// untracked reader is recorded here.
	OmittedFiles []OmittedFile

	// Truncated indicates if the diff was truncated due to size limits
	Truncated bool

	// Error if the operation failed
	Error error

	// Duration is the operation time for this repository
	Duration time.Duration
}

type RepositoryExecResult struct {
	Path         string
	RelativePath string
	Status       string
	Message      string
	Error        error
	Duration     time.Duration
	ExitCode     int
	Output       string
}

type RepositoryFetchResult struct {
	// Path is the repository path
	Path string

	// RelativePath is the path relative to scan root
	RelativePath string

	// Status is the operation status (success, skipped, error, etc.)
	Status string

	// Message is a human-readable status message
	Message string

	// Error if the operation failed
	Error error

	// Duration is how long this repository took to process
	Duration time.Duration

	// Branch is the current branch name
	Branch string

	// RemoteURL is the remote origin URL
	RemoteURL string

	// Remote is the remote name (e.g., "origin")
	Remote string

	// FetchedRefs is the number of refs fetched
	FetchedRefs int

	// FetchedObjects is the number of objects fetched
	FetchedObjects int

	// CommitsBehind is the number of commits behind remote after fetch
	CommitsBehind int

	// CommitsAhead is the number of commits ahead of remote after fetch
	CommitsAhead int

	// Deprecated: use TrackedChangedFiles. The name promised "uncommitted files"
	// but the value was len(StagedFiles)+len(ModifiedFiles), which counted a path
	// that is both staged and modified twice and missed working-tree-only
	// deletions entirely. It now carries the TrackedChangedFiles value.
	UncommittedFiles int

	// TrackedChangedFiles is the number of distinct tracked paths with
	// uncommitted changes, staged or not - checked after fetch
	TrackedChangedFiles int

	// StagedFiles is the number of paths whose index differs from HEAD - checked after fetch
	StagedFiles int

	// UnstagedFiles is the number of tracked paths whose working tree differs
	// from the index - checked after fetch
	UnstagedFiles int

	// UntrackedFiles is the number of untracked files - checked after fetch
	UntrackedFiles int
}

type RepositoryPullResult struct {
	// Path is the repository path
	Path string

	// RelativePath is the path relative to scan root
	RelativePath string

	// Status is the operation status (success, skipped, error, etc.)
	Status string

	// Message is a human-readable status message
	Message string

	// Error if the operation failed
	Error error

	// Duration is how long this repository took to process
	Duration time.Duration

	// Branch is the current branch name
	Branch string

	// RemoteURL is the remote origin URL
	RemoteURL string

	// Remote is the remote name (e.g., "origin")
	Remote string

	// CommitsBehind is the number of commits behind remote before pull
	CommitsBehind int

	// CommitsAhead is the number of commits ahead of remote before pull
	CommitsAhead int

	// UpdatedFiles is the number of files changed
	UpdatedFiles int

	// Stashed indicates if local changes were stashed
	Stashed bool

	// Deprecated: use TrackedChangedFiles. See RepositoryFetchResult for why the
	// old value was wrong; it now carries the TrackedChangedFiles value.
	UncommittedFiles int

	// TrackedChangedFiles is the number of distinct tracked paths with
	// uncommitted changes, staged or not - checked after pull
	TrackedChangedFiles int

	// StagedFiles is the number of paths whose index differs from HEAD - checked after pull
	StagedFiles int

	// UnstagedFiles is the number of tracked paths whose working tree differs
	// from the index - checked after pull
	UnstagedFiles int

	// UntrackedFiles is the number of untracked files - checked after pull
	UntrackedFiles int
}

type RepositoryPushResult struct {
	// Path is the repository path
	Path string

	// RelativePath is the path relative to scan root
	RelativePath string

	// Status is the operation status (success, skipped, error, etc.)
	Status string

	// Message is a human-readable status message
	Message string

	// Error if the operation failed
	Error error

	// Duration is how long this repository took to process
	Duration time.Duration

	// Branch is the current branch name
	Branch string

	// RemoteURL is the remote origin URL
	RemoteURL string

	// Remote is the remote name (e.g., "origin")
	Remote string

	// CommitsAhead is the number of commits ahead of remote before push
	CommitsAhead int

	// PushedCommits is the number of commits pushed
	PushedCommits int

	// Deprecated: use TrackedChangedFiles. See RepositoryFetchResult for why the
	// old value was wrong; it now carries the TrackedChangedFiles value.
	UncommittedFiles int

	// TrackedChangedFiles is the number of distinct tracked paths with
	// uncommitted changes, staged or not - checked after push
	TrackedChangedFiles int

	// StagedFiles is the number of paths whose index differs from HEAD - checked after push
	StagedFiles int

	// UnstagedFiles is the number of tracked paths whose working tree differs
	// from the index - checked after push
	UnstagedFiles int

	// UntrackedFiles is the number of untracked files - checked after push
	UntrackedFiles int
}

type RepositoryStashResult struct {
	// Path is the repository path
	Path string

	// RelativePath is the path relative to scan root
	RelativePath string

	// Status is the operation status
	Status string

	// Message is a human-readable status message
	Message string

	// Error if the operation failed
	Error error

	// Duration is how long this repository took to process
	Duration time.Duration

	// Branch is the current branch name
	Branch string

	// StashCount is the number of stashes in the repository
	StashCount int

	// StashMessage is the stash message (for save operation)
	StashMessage string
}

type RepositoryStatusResult struct {
	// Path is the repository path
	Path string

	// RelativePath is the path relative to scan root
	RelativePath string

	// Status is the operation status (clean, dirty, conflict, error, etc.)
	Status string

	// Message is a human-readable status message
	Message string

	// Error if the operation failed
	Error error

	// Duration is how long this repository took to process
	Duration time.Duration

	// Branch is the current branch name
	Branch string

	// RemoteURL is the remote origin URL
	RemoteURL string

	// Remote is the remote name (e.g., "origin")
	Remote string

	// Upstream is the tracking ref for the current branch (e.g.
	// "origin/master"), empty when the branch tracks nothing. CommitsAhead and
	// CommitsBehind are measured against it, so both are zero when it is empty
	// — without this field a caller cannot tell "in sync" from "nothing to
	// compare against", which are opposite situations.
	Upstream string

	// Remotes contains all configured remotes (name -> url).
	Remotes map[string]string

	// Metadata
	HeadSHA          string
	Describe         string
	LastCommitMsg    string
	LastCommitDate   string
	LastCommitAuthor string
	LocalBranches    []string
	RemoteBranches   []string
	StashCount       int

	// OldestStash is when the oldest stash entry was created, zero when there
	// is none. A stash never leaves this machine, so its age separates work in
	// progress from work that was forgotten here.
	OldestStash time.Time

	// CommitsBehind is how many commits behind remote
	CommitsBehind int

	// CommitsAhead is how many commits ahead of remote
	CommitsAhead int

	// Deprecated: use TrackedChangedFiles. Unlike the other three results, this
	// one was assigned the raw porcelain line count, so it also included every
	// untracked entry — which UntrackedFiles below then reported a second time.
	// It now carries the TrackedChangedFiles value and untracked paths appear
	// once, in UntrackedFiles.
	UncommittedFiles int

	// TrackedChangedFiles is the number of distinct tracked paths with
	// uncommitted changes, staged or not
	TrackedChangedFiles int

	// StagedFiles is the number of paths whose index differs from HEAD
	StagedFiles int

	// UnstagedFiles is the number of tracked paths whose working tree differs
	// from the index
	UnstagedFiles int

	// UntrackedFiles is the number of untracked files
	UntrackedFiles int

	// ConflictFiles is the list of files with conflicts
	ConflictFiles []string

	// RebaseInProgress indicates if repository is in rebase state
	RebaseInProgress bool

	// MergeInProgress indicates if repository is in merge state
	MergeInProgress bool
}

type RepositorySwitchResult struct {
	// Path is the repository path
	Path string

	// RelativePath is the path relative to scan root
	RelativePath string

	// Status is the operation status (switched, already-on-branch, dirty, error, etc.)
	Status string

	// Message is a human-readable status message
	Message string

	// Error if the operation failed
	Error error

	// Duration is how long this repository took to process
	Duration time.Duration

	// PreviousBranch is the branch before switching
	PreviousBranch string

	// CurrentBranch is the branch after switching (or current if not switched)
	CurrentBranch string

	// RemoteURL is the remote origin URL
	RemoteURL string

	// Remote is the remote name (e.g., "origin")
	Remote string

	// HasUncommittedChanges indicates if there were local changes preventing switch
	HasUncommittedChanges bool
}

type RepositoryTagResult struct {
	// Path is the repository path
	Path string

	// RelativePath is the path relative to scan root
	RelativePath string

	// Status is the operation status
	Status string

	// Message is a human-readable status message
	Message string

	// Error if the operation failed
	Error error

	// Duration is how long this repository took to process
	Duration time.Duration

	// Branch is the current branch name
	Branch string

	// TagCount is the number of tags in the repository
	TagCount int

	// LatestTag is the latest tag name
	LatestTag string

	// CreatedTag is the tag that was created
	CreatedTag string
}

type RepositoryUpdateResult struct {
	// Path is the repository path
	Path string

	// RelativePath is the path relative to scan root
	RelativePath string

	// Status is the operation status (success, skipped, error, etc.)
	Status string

	// Message is a human-readable status message
	Message string

	// Error if the operation failed
	Error error

	// Duration is how long this repository took to process
	Duration time.Duration

	// Branch is the current branch name
	Branch string

	// RemoteURL is the remote origin URL
	RemoteURL string

	// Remote is the remote name (e.g., "origin")
	Remote string

	// CommitsBehind is how many commits behind remote
	CommitsBehind int

	// CommitsAhead is how many commits ahead of remote
	CommitsAhead int

	// HasStash indicates if there are stashed changes
	HasStash bool

	// InMergeState indicates if repository is in merge state
	InMergeState bool

	// HasUncommittedChanges indicates if there are local changes
	HasUncommittedChanges bool

	// BaseSync reports what happened to the local base ref, or nil when
	// BulkUpdateOptions.SyncBase was off. Nil and "nothing to do" are different
	// answers and the renderer needs to tell them apart.
	BaseSync *BaseSyncResult
}

type Result struct {
	// Success indicates if the operation succeeded.
	Success bool

	// Output contains the operation's stdout output.
	Output string

	// Error contains the operation's stderr output or error message.
	Error string

	// ExitCode is the Git command's exit code.
	// 0 indicates success, non-zero indicates an error.
	ExitCode int

	// Duration is how long the operation took.
	Duration time.Duration

	// Timestamp is when the operation completed.
	Timestamp time.Time
}

type RetireRefusalEntry struct {
	Name     string `json:"name"`
	Location string `json:"location"`
	Reason   string `json:"reason"`
}

type ScanOptions struct {
	// Directory is the root directory to scan for repositories
	Directory string

	// MaxDepth is the maximum directory depth to scan (default: 1)
	MaxDepth int

	// IncludeSubmodules includes git submodules in the scan (default: false)
	IncludeSubmodules bool

	// IncludePattern is a regex pattern for repositories to include
	IncludePattern string

	// ExcludePattern is a regex pattern for repositories to exclude
	ExcludePattern string

	// Logger for operation feedback
	Logger Logger
}

type ScanResult struct {
	// Paths contains the absolute paths of discovered repositories.
	Paths []string

	// TotalScanned is the number of repositories found before filtering.
	TotalScanned int

	// Directory is the resolved absolute root directory.
	Directory string
}

type Status struct {
	// IsClean is true if there are no changes (working tree matches HEAD).
	IsClean bool

	// ModifiedFiles are files with unstaged changes.
	ModifiedFiles []string

	// StagedFiles are files staged for commit.
	StagedFiles []string

	// UntrackedFiles are files not tracked by Git.
	UntrackedFiles []string

	// ConflictFiles are files with merge conflicts.
	ConflictFiles []string

	// DeletedFiles are files deleted but not staged.
	DeletedFiles []string

	// RenamedFiles are files that have been renamed.
	RenamedFiles []RenamedFile

	// StagedCount is the number of paths whose index differs from HEAD.
	//
	// The three counts below cannot be recovered from the slices above, which is
	// why they are stored rather than derived: porcelain reports a two-character
	// XY code per path, and the slices keep only the union of the two sides. A
	// path deleted in the working tree and one deleted from the index both land
	// in DeletedFiles; len() over any combination of slices therefore cannot tell
	// staged from unstaged, and double-counts every path that appears in two of
	// them. These are computed once, where XY is still intact.
	StagedCount int

	// UnstagedCount is the number of tracked paths whose working tree differs
	// from the index.
	UnstagedCount int

	// TrackedChangedCount is the number of distinct tracked paths with any
	// uncommitted change — staged, unstaged, or conflicted. Untracked and ignored
	// paths are excluded. A path that is both staged and modified counts once
	// here but in each of StagedCount and UnstagedCount, so the two do not sum to
	// this value.
	TrackedChangedCount int
}

type UpdateStrategy string

type UserConfig struct {
	// Name is the user's name.
	Name string

	// Email is the user's email.
	Email string

	// SigningKey is the GPG signing key.
	SigningKey string
}

type ValidationError struct {
	// Field is the field that failed validation.
	Field string

	// Value is the invalid value.
	Value string

	// Reason describes why the value is invalid.
	Reason string
}

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