setplan

type Document struct {
	FormatVersion string `json:"format_version"`
	// Roots are in the order the command was given them, whatever order
	// they finished in.
	Roots   []Root  `json:"roots"`
	Summary Summary `json:"summary"`
	// Digest is the set digest (#1754): one digest over every root's
	// planned changes, independent of root order, moving whenever any one
	// root's changes move. It is what an approval names and what
	// live-wave-apply checks the set against.
	Digest string `json:"digest"`
	// ExitCode is the code the command exits with, so a reader of a saved
	// document does not have to have watched the process.
	ExitCode int `json:"exit_code"`
	// PluginCacheDir is the one provider cache every root shared.
	PluginCacheDir string `json:"plugin_cache_dir"`
	// ParallelEstates is the bound the roots ran under.
	ParallelEstates int `json:"parallel_estates"`
}

type Exec struct {
	// Bin is the choudoufu executable, normally os.Executable().
	Bin string
	// Env is the children's whole environment. Build it with [ChildEnv].
	Env []string
	// EstateOf reads a root's live block. It is a function rather than a
	// child process because it is a parse, not a run: the command layer
	// owns the configuration loader.
	EstateOf func(dir string) (estate string, ok bool, err error)
}

type Options struct {
	// Roots are the root directories, as given.
	Roots []string
	// BaseDir is the directory Roots, OutDir and the document's paths are
	// relative to: the command's working directory.
	BaseDir string
	// OutDir receives one plan file and one log per root, named by root.
	OutDir string
	// Parallel bounds how many roots run at once. At least 1.
	Parallel int
	// PluginCacheDir is reported in the document; the Runner is what uses
	// it.
	PluginCacheDir string
	Runner         Runner
	// Now is the clock, for tests. Defaults to time.Now.
	Now func() time.Time
}

type Root struct {
	// Root is the root directory relative to the directory the command ran
	// in, with forward slashes.
	Root string `json:"root"`
	// Estate is the estate the root's live block names. Empty when the
	// root failed before its live block was read, or when the block names
	// none and the run derives it from the configuration's markers.
	Estate string `json:"estate"`
	Status Status `json:"status"`
	// Error is the failure, set when Status is failed and empty otherwise.
	Error string `json:"error"`
	// Stage is the stage that failed, set when Status is failed.
	Stage Stage `json:"stage,omitempty"`
	// Changes is what plan -detailed-exitcode said: true when the plan
	// proposes any change. False for a failed root.
	Changes bool `json:"changes"`
	// PlanFile is the saved plan, relative to the command's directory.
	// Set whenever the plan stage succeeded.
	PlanFile string `json:"plan_file"`
	// LogFile holds every stage's combined output for this root.
	LogFile string `json:"log_file"`
	// DurationMS is the root's wall time across all its stages.
	DurationMS int64 `json:"duration_ms"`
	// Plan is stock OpenTofu's machine-readable plan for this root, the
	// object "choudoufu show -json PLANFILE" prints. null for a failed root.
	Plan json.RawMessage `json:"plan"`
	// Digest is this root's digest (#1754): what [Document.Digest] is
	// computed over. internal/live/setdigest's package doc says what it covers.
	Digest string `json:"digest"`
}

type Runner interface {
	// Estate reads dir's estate from its live block. ok is false when dir
	// has no live block at all.
	Estate(ctx context.Context, dir string) (estate string, ok bool, err error)
	Init(ctx context.Context, dir string, log io.Writer) error
	// Plan writes planFile and reports whether the plan has changes.
	Plan(ctx context.Context, dir, planFile string, log io.Writer) (changes bool, err error)
	// Show returns the machine-readable form of planFile.
	Show(ctx context.Context, dir, planFile string, log io.Writer) (json.RawMessage, error)
}

type Stage string

type StageError struct {
	Stage  string
	Code   int
	Stderr string
}

type Status string

type Summary struct {
	Roots   int `json:"roots"`
	Planned int `json:"planned"`
	Changed int `json:"changed"`
	Failed  int `json:"failed"`
}