build

type ArchiveArtifactPlan struct {
	Name    string
	Format  string
	Path    string
	Version string
}

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

	// Target is the build target this archive packages.
	Target Target

	// 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 BinaryArtifactPlan struct {
	Name      string
	OS        string
	Arch      string
	Path      string
	Toolchain string
	Version   string
}

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

	// Version info for template resolution
	Version *VersionInfo

	// RootDir is the repo root, for filesystem-derived facts in arg templates
	// (e.g. {project.module} reads the build manifest — go.mod / Cargo.toml / …).
	RootDir string

	// 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

	// kind: binary, builder: node — containerized build. The build Command runs
	// INSIDE Image (repo mounted); Output is the produced-artifact glob. Lets SF
	// ship things it can't compile natively (e.g. an Electron .exe via wine).
	Image string
}

type BuildPlan struct {
	Steps []BuildStep
}

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

type BuildStep struct {
	Name          string
	Dockerfile    string
	Context       string
	ContextDigest string // content hash of the Dockerfile + build context (see HashBuildContext); folds source content into the build identity so a code change is not invisible to NormalizeBuildPlan
	Target        string
	Platforms     []string
	BuildArgs     map[string]string
	// Secrets are id → in-repo path, mounted for a RUN and left out of the image.
	Secrets        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
	MetadataFile   string           // temp file for buildx --metadata-file (digest capture)
	OCILayoutDir   string           // --output type=oci,dest=<dir> for content-store persistence; additive to Load/Push
	CacheFrom      []CacheRef       // --cache-from references
	CacheTo        []CacheRef       // --cache-to references
	SkippedTargets []TargetSkip     // registry targets excluded by when:, with the matcher's reason (narrated)
}

type CacheRef struct {
	Type      string // "registry", "local"
	Ref       string // registry ref or local path
	Mode      string // "max", "min" (export only)
	Direction string // "import" or "export" — determines local key (src vs dest)
}

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 CargoBuild struct {
	Verbose bool
	Stdout  io.Writer
	Stderr  io.Writer
}

type CargoBuildOpts struct {
	ManifestDir string            // dir containing Cargo.toml (cmd.Dir)
	BinName     string            // the [[bin]]/package name → target/<profile>/<BinName>
	OutputPath  string            // canonical output (DistDir/<slug>/<name>) — the binary is copied here
	Release     bool              // --release (release profile)
	TargetDir   string            // CARGO_TARGET_DIR (where target/ lives); "" = ManifestDir/target
	Args        []string          // raw args before nothing (e.g. ["--features", "x"])
	Env         map[string]string // additional env (e.g. CARGO_HOME)
	CargoBin    string            // resolved cargo binary; "" falls back to "cargo" on $PATH (dev only)
}

type CargoBuildResult struct {
	Path   string
	Size   int64
	SHA256 string
}

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)
}

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)
	GoBin      string            // resolved go binary (from the toolchain subsystem); "" falls back to "go" on $PATH
}

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 PerformNode struct {
	Build    *config.BuildConfig // non-nil → run this build
	ScribeID string              // non-empty → render this scribe content item
}

type PlanToOutputsOpts struct {
	GeneratedAt  string // RFC3339; if empty, Finalize defaults to UTC now
	Commit       string
	Pipeline     *artifact.Pipeline
	BinaryPlans  []BinaryArtifactPlan  // plan-time binary descriptors
	ArchivePlans []ArchiveArtifactPlan // plan-time archive descriptors
}

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 PushObservation struct {
	Host   string
	Path   string
	Tag    string
	Digest string
}

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)

	// SigningProfile is the resolved trust profile published images are signed
	// under — the synthesized `legacy` default (implicit COSIGN_KEY signing) when
	// the target names no signing_profile. Resolved at lowering, consumed by the
	// publish-phase image signer.
	SigningProfile *config.ResolvedSigningProfile
}

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

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 (raw refs for display)
	Publications []PushObservation // structured publish records — v2 wire to ResultsBuilder
	Artifacts    []string          // extracted file paths
	Layers       []LayerEvent      // parsed build layer events (from --progress=plain)
	Duration     time.Duration
	Error        error
}

type Target struct {
	OS   string `json:"os"`
	Arch string `json:"arch"`
	Libc string `json:"libc,omitempty"` // "", "gnu", "musl"
	ABI  string `json:"abi,omitempty"`  // optional/future (e.g. "eabihf")
}

type TargetSkip struct {
	TargetID string
	Reason   string
}

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-go" | "binary-rust" — the dispatch key
	Target  Target        `json:"target"`
	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