release

type CutOptions struct {
	RepoPath        string            // path to git repo (default ".")
	Branch          string            // expected branch (default "main")
	Remote          string            // git remote name (default "origin")
	PlanFile        string            // path to pre-generated plan JSON/YAML
	MutationsConfig string            // path to mutations config file
	DryRun          bool              // show what would happen without side effects
	Publish         bool              // create published release directly (no draft)
	Mode            ReleaseMode       // "auto" (default), "api", "local"
	CommitAuthor    string            // bot commit author name
	CommitEmail     string            // bot commit author email
	Token           string            // GitHub token for API and push
	ReleaseAPI      ReleaseService    // optional; created from Token if nil
	Assets          []string          // file paths to upload as release assets
	AssetLabels     map[string]string // optional asset name -> display label
}

type CutResult struct {
	TagName        string   `json:"tag_name"`
	Version        string   `json:"version"`
	CommitSHA      string   `json:"commit_sha"`
	ReleaseURL     string   `json:"release_url,omitempty"`
	ReleaseID      int64    `json:"release_id,omitempty"`
	Draft          bool     `json:"draft"`
	Published      bool     `json:"published"`
	FilesModified  []string `json:"files_modified,omitempty"`
	UploadedAssets []string `json:"uploaded_assets,omitempty"`
	DryRun         bool     `json:"dry_run"`
	NoRelease      bool     `json:"no_release"`
	Reason         string   `json:"reason,omitempty"`
}

type FileMutation struct {
	Path     string `json:"path" yaml:"path"`
	Type     string `json:"type" yaml:"type"`           // jsonPath, yamlPath, regex
	Field    string `json:"field" yaml:"field"`         // field being modified
	OldValue string `json:"old_value" yaml:"old_value"` // current value
	NewValue string `json:"new_value" yaml:"new_value"` // value after release
}

type PlanOptions struct {
	// base ref to compare from (default: latest tag)
	FromRef string
	// target ref to compare to (default: HEAD)
	ToRef string
	// only follow first parent in merge commits
	FirstParent bool
	// path to repository (default: current directory)
	RepoPath string
	// output format (text, json, yaml)
	OutputFormat string
	// path to mutations config file (optional)
	MutationsConfig string
	// release mode: "auto" (default), "api", "local"
	Mode ReleaseMode
	// GitHub API client for API mode tag/commit discovery (optional)
	ReleaseAPI ReleaseService
	// branch name used as head for API compare (required for API mode)
	Branch string
	// GitHub token; when set and ReleaseAPI is nil, an API client is built from it
	// (lets API mode discover tags/commits without a full local clone)
	Token string
}

type PublishOptions struct {
	RepoPath  string // path to git repo (for remote detection)
	Tag       string // specific tag to publish (mutually exclusive with Latest and ReleaseID)
	Latest    bool   // find latest draft (mutually exclusive with Tag and ReleaseID)
	ReleaseID int64  // publish by numeric release ID — works with GitHub App tokens
	// Note: --tag and --latest require a user token; GitHub App tokens cannot discover
	// draft releases via list/search endpoints. Use --release-id for App token workflows.
	Token      string         // GitHub token (required)
	DryRun     bool           // preview only, don't publish
	ReleaseAPI ReleaseService // optional; created from Token if nil
}

type PublishResult struct {
	TagName    string `json:"tag_name"`
	ReleaseURL string `json:"release_url"`
	ReleaseID  int64  `json:"release_id"`
	Published  bool   `json:"published"` // always true on success
	DryRun     bool   `json:"dry_run"`
}

type ReleaseMode string

type ReleasePlan struct {
	// metadata
	GeneratedAt time.Time `json:"generated_at" yaml:"generated_at"`
	Repository  string    `json:"repository" yaml:"repository"`

	// version info
	CurrentVersion string `json:"current_version" yaml:"current_version"`
	NextVersion    string `json:"next_version" yaml:"next_version"`
	BumpType       string `json:"bump_type" yaml:"bump_type"` // major/minor/patch/none

	// commits
	Commits         []version.ParsedCommit `json:"commits" yaml:"commits"`
	BreakingChanges []string               `json:"breaking_changes" yaml:"breaking_changes"`

	// changelog
	ChangelogPreview string `json:"changelog_preview" yaml:"changelog_preview"`

	// file mutations
	FileMutations []FileMutation `json:"file_mutations,omitempty" yaml:"file_mutations,omitempty"`

	// status
	ReleaseNeeded bool   `json:"release_needed" yaml:"release_needed"`
	Reason        string `json:"reason,omitempty" yaml:"reason,omitempty"`
}

type ReleaseService interface {
	// release operations
	GetReleaseByTag(ctx context.Context, owner, repo, tag string) (*gogithub.RepositoryRelease, *gogithub.Response, error)
	GetRelease(ctx context.Context, owner, repo string, id int64) (*gogithub.RepositoryRelease, *gogithub.Response, error)
	CreateRelease(ctx context.Context, owner, repo string, release *gogithub.RepositoryRelease) (*gogithub.RepositoryRelease, *gogithub.Response, error)
	UpdateRelease(ctx context.Context, owner, repo string, id int64, release *gogithub.RepositoryRelease) (*gogithub.RepositoryRelease, *gogithub.Response, error)
	ListReleases(ctx context.Context, owner, repo string, opts *gogithub.ListOptions) ([]*gogithub.RepositoryRelease, *gogithub.Response, error)
	UploadReleaseAsset(ctx context.Context, owner, repo string, id int64, opts *gogithub.UploadOptions, file *os.File) (*gogithub.ReleaseAsset, *gogithub.Response, error)
	// read operations (tag discovery, commit comparison, branch validation)
	ListTags(ctx context.Context, owner, repo string, opts *gogithub.ListOptions) ([]*gogithub.RepositoryTag, *gogithub.Response, error)
	CompareCommits(ctx context.Context, owner, repo, base, head string, opts *gogithub.ListOptions) (*gogithub.CommitsComparison, *gogithub.Response, error)
	GetBranch(ctx context.Context, owner, repo, branch string, maxRedirects int) (*gogithub.Branch, *gogithub.Response, error)
	// git data operations. Commits created via the API are auto-signed/verified by GitHub
	// (SLSA v1.2); annotated tag objects are NOT signed (see createAnnotatedTagViaAPI).
	CreateTree(ctx context.Context, owner, repo, baseTree string, entries []*gogithub.TreeEntry) (*gogithub.Tree, *gogithub.Response, error)
	CreateCommit(ctx context.Context, owner, repo string, commit gogithub.Commit, opts *gogithub.CreateCommitOptions) (*gogithub.Commit, *gogithub.Response, error)
	CreateTag(ctx context.Context, owner, repo string, tag gogithub.CreateTag) (*gogithub.Tag, *gogithub.Response, error)
	CreateRef(ctx context.Context, owner, repo string, ref gogithub.CreateRef) (*gogithub.Reference, *gogithub.Response, error)
	UpdateRef(ctx context.Context, owner, repo, ref string, updateRef gogithub.UpdateRef) (*gogithub.Reference, *gogithub.Response, error)
	DeleteRef(ctx context.Context, owner, repo, ref string) (*gogithub.Response, error)
}