build

type ArchiveOpts struct {
	// Format is "tar.gz", "zip", or "auto" (zip for windows, tar.gz otherwise).
	Format string

	// OutputDir is where archives are written.
	OutputDir string

	// NameTemplate is the archive filename template (without extension).
	// Supports: {id}, {version}, {os}, {arch}
	NameTemplate string

	// BinaryPath is the path to the compiled binary to include.
	BinaryPath string

	// BinaryName is the filename inside the archive (may differ from physical path basename).
	BinaryName string

	// IncludeFiles lists extra files to bundle (relative to repo root).
	IncludeFiles []string

	// RepoRoot is the root directory for resolving include files.
	RepoRoot string

	// Platform is the target platform for this archive.
	Platform Platform

	// BuildID is used for template resolution.
	BuildID string

	// Version info for template resolution.
	Version *VersionInfo
}

type ArchiveResult struct {
	Path     string // archive file path
	Format   string // actual format used
	Size     int64
	SHA256   string
	Contents []string // files inside the archive
}

type ArtifactRef struct {
	Path string `json:"path"`
	Type string `json:"type"` // "binary", "image", "archive", "metadata"
}

type BuildConfig struct {
	ID         string
	Kind       string
	Platforms  []Platform
	BuildMode  string
	SelectTags []string
	DependsOn  string

	// Version info for template resolution
	Version *VersionInfo

	// kind: docker fields
	Dockerfile string
	Context    string
	Target     string
	BuildArgs  map[string]string
	Tags       []string
	Registries []RegistryTarget

	// kind: binary fields
	Builder  string
	Command  string
	From     string
	Output   string
	Args     []string
	Env      map[string]string
	Compress bool
}

type BuildPlan struct {
	Steps []BuildStep
}

type BuildResult struct {
	Steps    []StepResult
	Duration time.Duration
}

type BuildStep struct {
	Name         string
	Dockerfile   string
	Context      string
	Target       string
	Platforms    []string
	BuildArgs    map[string]string
	Labels       map[string]string // OCI labels injected via --label
	Tags         []string
	Output       OutputMode
	Extract      []ExtractRule    // artifact mode only
	Registries   []RegistryTarget // image mode only
	Load         bool             // --load into daemon
	Push         bool             // --push to registries
	SavePath     string           // save image tarball here after build (for security scanning)
	MetadataFile string           // temp file for buildx --metadata-file (digest capture)
}

type Capabilities struct {
	SupportsCrossCompile bool `json:"supports_cross_compile"`
	SupportsCrucible     bool `json:"supports_crucible"`
	ProducesArchives     bool `json:"produces_archives"`
	ProducesOCI          bool `json:"produces_oci"`
}

type DSSEEnvelope struct {
	PayloadType string          `json:"payloadType"`
	Payload     string          `json:"payload"` // base64-encoded ProvenanceStatement
	Signatures  []DSSESignature `json:"signatures"`
}

type DSSESignature struct {
	KeyID string `json:"keyid,omitempty"`
	Sig   string `json:"sig"`
}

type Detection struct {
	RootDir      string // absolute path to repo root
	Dockerfiles  []DockerfileInfo
	Language     string   // "go", "rust", "node", "python", ""
	Lockfiles    []string // relative paths: go.mod, Cargo.toml, etc.
	MainPackages []string // detected main package paths (Go: cmd/foo, bar, .)
	GitInfo      *GitInfo
}

type DockerfileInfo struct {
	Path        string  // relative path from repo root
	Stages      []Stage // parsed multistage stages
	Args        []string
	Expose      []string
	Healthcheck *string
}

type Engine interface {
	Name() string
	Detect(ctx context.Context, rootDir string) (*Detection, error)
	Plan(ctx context.Context, cfg interface{}, det *Detection) (*BuildPlan, error)
	Execute(ctx context.Context, plan *BuildPlan) (*BuildResult, error)
}

type EngineV2 interface {
	// Name returns the engine's identifier (e.g., "binary", "image").
	Name() string

	// Capabilities declares what this engine supports.
	Capabilities() Capabilities

	// Detect inspects a repo and returns build-relevant information.
	Detect(ctx context.Context, rootDir string) (*Detection, error)

	// Plan converts a build config into a list of universal steps.
	// Core owns config synthesis — Plan receives normalized config, not detection guesses.
	Plan(ctx context.Context, cfg BuildConfig) ([]UniversalStep, error)

	// ExecuteStep runs a single step and returns its result.
	// The engine must not: write publish manifests, attach release assets,
	// manage concurrency, resolve dependencies, or print logs directly.
	ExecuteStep(ctx context.Context, step UniversalStep) (*UniversalStepResult, error)
}

type ExtractRule struct {
	From string // path inside the container
	To   string // local destination path
}

type GitInfo struct {
	Remote    string // origin URL
	Branch    string // current branch
	LatestTag string
	SHA       string
}

type GoBuild struct {
	Verbose bool
	Stdout  io.Writer
	Stderr  io.Writer
}

type GoBuildOpts struct {
	Entry      string // main package path (e.g., "cmd/planedc/main.go" or "./cmd/planedc")
	OutputPath string // output binary path
	GOOS       string
	GOARCH     string
	Args       []string          // raw args passed before entry (e.g., ["-tags", "banner_art", "-ldflags", "..."])
	Env        map[string]string // additional env vars (e.g., CGO_ENABLED=0)
}

type GoBuildResult struct {
	Path   string // absolute output path
	Size   int64
	SHA256 string
}

type ImagePlanInput struct {
	Cfg     *config.Config // full config
	BuildID string         // optional: build specific entry by ID (empty = all)
}

type LayerEvent struct {
	Stage       string        // "builder", "stage-1", "" (for internal steps)
	StageStep   string        // "1/7", "2/7", etc.
	Instruction string        // "FROM", "COPY", "RUN", "WORKDIR", "ENV", "ARG", "EXPOSE", "ADD"
	Detail      string        // instruction arguments (truncated)
	Cached      bool          // true if layer was a cache hit
	Duration    time.Duration // layer execution time (0 for cached layers)
	Image       string        // for FROM: the base image name (without digest)
}

type OutputMode string

type Platform struct {
	OS   string `json:"os"`
	Arch string `json:"arch"`
}

type ProducedArtifact struct {
	Path   string `json:"path"`
	Type   string `json:"type"` // "binary", "image", "archive", "metadata"
	Size   int64  `json:"size"`
	SHA256 string `json:"sha256"`
}

type ProvenanceBuilder struct {
	ID string `json:"id"`
}

type ProvenanceInvocation struct {
	ConfigSource map[string]any `json:"configSource,omitempty"`
	Parameters   map[string]any `json:"parameters,omitempty"`
	Environment  map[string]any `json:"environment,omitempty"`
}

type ProvenanceMaterial struct {
	URI    string            `json:"uri"`
	Digest map[string]string `json:"digest,omitempty"`
}

type ProvenanceMetadata struct {
	BuildStartedOn  string          `json:"buildStartedOn,omitempty"`
	BuildFinishedOn string          `json:"buildFinishedOn,omitempty"`
	Completeness    map[string]bool `json:"completeness,omitempty"`
	Reproducible    bool            `json:"reproducible"`
}

type ProvenancePredicate struct {
	BuildType    string               `json:"buildType"`
	Builder      ProvenanceBuilder    `json:"builder"`
	Invocation   ProvenanceInvocation `json:"invocation"`
	Metadata     ProvenanceMetadata   `json:"metadata"`
	Materials    []ProvenanceMaterial `json:"materials,omitempty"`
	StageFreight map[string]any       `json:"stagefreight,omitempty"`
}

type ProvenanceStatement struct {
	Type          string              `json:"_type"`
	PredicateType string              `json:"predicateType"`
	Subject       []ProvenanceSubject `json:"subject"`
	Predicate     ProvenancePredicate `json:"predicate"`
}

type ProvenanceSubject struct {
	Name   string            `json:"name"`
	Digest map[string]string `json:"digest,omitempty"`
}

type RegistryTarget struct {
	URL         string
	Path        string
	Tags        []string
	Credentials string                 // env var prefix for auth (e.g., "DOCKERHUB" → DOCKERHUB_USER/DOCKERHUB_PASS)
	Provider    string                 // registry vendor: dockerhub, ghcr, gitlab, jfrog, harbor, quay, gitea, generic
	Retention   config.RetentionPolicy // restic-style retention policy
	TagPatterns []string               // original unresolved tag templates for pattern matching during retention
	NativeScan  bool                   // trigger registry's own built-in scan after push (Harbor: built-in Trivy)
}

type Stage struct {
	Name      string // alias from "AS name", empty if unnamed
	BaseImage string // the FROM image reference
	Line      int    // line number of the FROM instruction
}

type StepMeta interface {
	StepMetaKind() string
}

type StepMetrics struct {
	Duration time.Duration `json:"duration"`
	Cached   bool          `json:"cached"`
}

type StepResult struct {
	Name      string
	Status    string       // "success", "failed", "cached"
	Images    []string     // pushed image references
	Artifacts []string     // extracted file paths
	Layers    []LayerEvent // parsed build layer events (from --progress=plain)
	Duration  time.Duration
	Error     error
}

type UniversalStep struct {
	BuildID  string        `json:"build_id"` // which build config this belongs to
	StepID   string        `json:"step_id"`  // unique: {build_id}-{variant}-{os}-{arch}
	Engine   string        `json:"engine"`   // "image" | "binary"
	Platform Platform      `json:"platform"`
	Inputs   []ArtifactRef `json:"inputs,omitempty"`
	Outputs  []ArtifactRef `json:"outputs,omitempty"`
	Meta     StepMeta      `json:"-"` // engine-specific typed metadata
}

type UniversalStepResult struct {
	Artifacts []ProducedArtifact `json:"artifacts"`
	Metadata  map[string]string  `json:"metadata,omitempty"` // e.g., {"toolchain": "go1.24.1"}
	Metrics   StepMetrics        `json:"metrics"`
}

type VersionInfo = gitver.VersionInfo