autoinit

type Decision struct {
	// RunInit reports whether `terraform init` should run at all.
	RunInit bool
	// Reconfigure reports whether `-reconfigure` should be added.
	Reconfigure bool
	// Upgrade reports whether `-upgrade` should be added.
	Upgrade bool
	// Reason explains RunInit.
	Reason Reason
	// Fingerprint is the computed fingerprint; zero when it was never computed (e.g. dry run, or
	// init.mode is never).
	Fingerprint Fingerprint
	// Marker is the previously recorded marker; nil when absent, malformed, or never read.
	Marker *Marker
}

type Diagnosis struct {
	// InitRequired reports whether the output indicates `init` must run again.
	InitRequired bool
	// ReconfigureRequired reports whether the backend configuration changed.
	ReconfigureRequired bool
	// UpgradeRequired reports whether provider/module constraints require `-upgrade`.
	UpgradeRequired bool
	// Matched is the signature substring that produced this Diagnosis, for debug logs.
	Matched string
}

type Fingerprint struct {
	// Hash is the sha256 hex digest over every input that can affect `terraform init`.
	Hash string
	// BackendHash is the sha256 hex digest over only the backend-relevant subset of files.
	BackendHash string
	// Files lists the relative file names that contributed to Hash, sorted, for debug logs.
	Files []string
}

type Inputs struct {
	// ComponentPath is the absolute component (or workdir) directory init would run in.
	ComponentPath string
	// DataDir is the Terraform data directory; if empty it is computed with
	// DataDir(ComponentPath, EnvLookup).
	DataDir string
	// VarFile is the varfile path (absolute, or relative to ComponentPath); hashed only when
	// PassVars is true.
	VarFile string
	// PassVars indicates whether Atmos is passing a varfile (and TF_VAR_* extras) to terraform.
	PassVars bool
	// Binary is the resolved terraform/tofu executable. Bare names are resolved via
	// exec.LookPath; on failure only the name itself is recorded.
	Binary string
	// EnvLookup models the subprocess environment Atmos is about to launch terraform/tofu with.
	// Its second return value distinguishes "key present with this value" (honored as-is, even
	// when the value is "") from "key absent" (falls back to os.Getenv). A nil EnvLookup falls
	// back to os.Getenv unconditionally.
	EnvLookup func(key string) (string, bool)
	// Extra holds caller-supplied records (e.g. TF_VAR_* values when PassVars is true) that
	// should participate in the fingerprint.
	Extra map[string]string
}

type Marker struct {
	// SchemaVersion is the on-disk schema version of this marker; compared against
	// MarkerSchemaVersion by Decide.
	SchemaVersion int `json:"schema_version"`
	// Fingerprint is the Fingerprint.Hash recorded at init time.
	Fingerprint string `json:"fingerprint"`
	// BackendFingerprint is the Fingerprint.BackendHash recorded at init time.
	BackendFingerprint string `json:"backend_fingerprint"`
	// InitArgs are the extra arguments (e.g. "-upgrade", "-reconfigure") the recorded init ran
	// with.
	InitArgs []string `json:"init_args"`
	// AtmosVersion is the Atmos version that performed the init.
	AtmosVersion string `json:"atmos_version"`
	// Binary is the terraform/tofu executable that performed the init.
	Binary string `json:"binary"`
	// Timestamp is when the recorded init completed, in UTC.
	Timestamp time.Time `json:"timestamp"`
}

type Reason string

type RecoverInitParams struct {
	// Output is the captured stdout+stderr (+ Err.Error()) from the failed init subprocess.
	Output string
	// Err is init's own error; RecoverInit never calls Rerun when Err is nil.
	Err         error
	Mode        schema.TerraformInitMode
	Reconfigure schema.TerraformInitReconfigure
	Upgrade     schema.TerraformInitUpgrade
	// Rerun retries init once with the recovery's flags.
	Rerun func(rec Recovery) error
	// Warn, if set, is called with a human-readable message (and structured key/value pairs,
	// mirroring log.Warn) before Rerun runs.
	Warn func(msg string, kv ...any)
}

type RecoverParams struct {
	// Output is the captured stdout+stderr (+ Err.Error()) from the failed main command.
	Output string
	// Err is the main command's own error; Recover never calls RunInit/Retry when Err is nil.
	Err error
	// Mode, Reconfigure, Upgrade are the caller's resolved atmos.yaml init policy (see
	// schema.Terraform's Effective* accessors).
	Mode        schema.TerraformInitMode
	Reconfigure schema.TerraformInitReconfigure
	Upgrade     schema.TerraformInitUpgrade
	// OptedOut reflects the caller's own opt-out signals (see OptedOut).
	OptedOut bool
	// Skip, when true, means recovery must not run at all (e.g. the command that failed was
	// itself `init` -- there is no "init required" fallback for init).
	Skip bool
	// RunInit forces one `terraform init` re-run with the flags rec calls for.
	RunInit func(rec Recovery) error
	// Retry re-runs the original failed command once, after RunInit succeeds.
	Retry func() error
	// Warn, if set, is called with a human-readable message before RunInit/Retry run.
	Warn func(string)
}

type Recovery struct {
	// Run reports whether init should be re-run.
	Run bool
	// WithReconfigure reports whether the re-run should add `-reconfigure`.
	WithReconfigure bool
	// WithUpgrade reports whether the re-run should add `-upgrade`.
	WithUpgrade bool
}

type Request struct {
	// Mode is the configured init mode; empty is treated as schema.TerraformInitModeAuto.
	Mode schema.TerraformInitMode
	// Reconfigure is the configured reconfigure policy; empty is treated as
	// schema.TerraformInitReconfigureAuto.
	Reconfigure schema.TerraformInitReconfigure
	// Upgrade is the configured upgrade policy; empty is treated as
	// schema.TerraformInitUpgradeAuto.
	Upgrade schema.TerraformInitUpgrade
	// Force short-circuits to RunInit=true regardless of the fingerprint, e.g. for the
	// workspace subcommand, a re-provisioned workdir, or an explicit `atmos terraform init`.
	Force bool
	// Inputs is nil on a dry run (no component on disk to fingerprint yet).
	Inputs *Inputs
}