hooks

type Artifact struct {
	// Name is the filename inside the upload bundle (e.g. "breakdown.json").
	Name string
	// Body is the artifact content.
	Body []byte
	// Format is the optional generic-renderer hint ("markdown" or "").
	// For named kinds, Pro derives rendering from the kind name, so this
	// remains empty.
	Format string
	// Metadata is arbitrary tags attached to the artifact.
	Metadata map[string]string
}

type Command interface {
	GetName() string
	RunE(hook *Hook, event HookEvent, cmd *cobra.Command, args []string) error
}

type CommandEngine struct{}

type Engine interface {
	// Run executes the hook with the given context.
	// Implementations that produce no structured output return (nil, err).
	Run(ctx *ExecContext) (*Output, error)
}

type ExecContext struct {
	// Hook is the resolved hook (kind defaults applied; user overrides preserved).
	Hook *Hook
	// Kind is the registered kind handling this hook.
	Kind *Kind
	// Event is the lifecycle event triggering the hook.
	Event HookEvent
	// AtmosConfig is the global Atmos configuration.
	AtmosConfig *schema.AtmosConfiguration
	// Info carries component and stack information.
	Info *schema.ConfigAndStacksInfo
	// Cmd is the cobra command currently executing.
	Cmd *cobra.Command
	// Args are the command-line args passed to Cmd.
	Args []string

	// ToolchainPATH is the PATH fragment containing directories for any
	// dependencies.tools that were auto-installed for this component's
	// hooks. Populated by Hooks.preflight; consumed by CommandEngine
	// so the installed pinned versions take precedence over the operator's
	// PATH. Empty when the component declares no hook dependencies.
	ToolchainPATH string

	// OutputFile is the temp file path the tool wrote structured output to.
	// Populated by CommandEngine before calling ResultHandler.
	OutputFile string
	// OutputDir is the temp directory containing OutputFile. Exposed for
	// directory-output tools (e.g., KICS writes results.sarif into a dir).
	OutputDir string
	// ExitCode is the subprocess exit code (0 = success).
	ExitCode int
	// CommandError is the subprocess error, if any.
	CommandError error
}

type Hook struct {
	// Kind selects the engine that runs this hook. Built-in kinds:
	// "store" (existing semantics), "command" (generic binary execution),
	// plus named tool kinds like "infracost", "checkov", "trivy", "kics".
	//
	// For back-compat, the legacy `command:` YAML key is accepted as an
	// alias when `kind:` is absent. See UnmarshalYAML.
	Kind string `yaml:"kind,omitempty"`

	Events []string `yaml:"events,omitempty"`

	// Generic command-kind fields. Used by the command engine and by named
	// tool kinds via their defaults.
	//
	// Command is the binary to execute (resolved via the toolchain). For
	// named kinds it defaults to the kind's binary; users may override.
	Command string            `yaml:"command,omitempty"`
	Args    []string          `yaml:"args,omitempty"`
	Env     map[string]string `yaml:"env,omitempty"`
	// Format is the inline rendering hint for generic kinds. v1 accepts
	// "markdown" or empty (= downloadable artifact, no inline render).
	Format string `yaml:"format,omitempty"`

	// OnFailure is the failure mode. "warn" (default for tool kinds),
	// "fail" (propagate non-zero exit), or "ignore" (swallow).
	OnFailure string `yaml:"on_failure,omitempty"`

	// Store-kind specific (existing, unchanged semantics).
	Name    string            `yaml:"name,omitempty"`
	Outputs map[string]string `yaml:"outputs,omitempty"`
}

type HookEvent string

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

type Kind struct {
	// Name is the kind discriminator (e.g. "store", "command", "infracost").
	Name string

	// Defaults for the generic command engine. Named kinds set these;
	// user Hook fields override.
	Command     string
	DefaultArgs []string
	DefaultEnv  map[string]string

	// OnFailure is the default failure mode if the hook doesn't override.
	OnFailure string

	// Engine runs hooks of this kind.
	Engine Engine

	// ResultHandler parses structured output into a Summary. Optional.
	ResultHandler ResultHandler
}

type Output struct {
	// Artifact is the opaque blob produced by the hook (tool output file,
	// rendered report, etc.). May be nil.
	Artifact *Artifact
	// Summary is the typed envelope used for run pages, PR comments, and
	// terminal rendering. May be nil.
	Summary *Summary
}

type ResultHandler func(ctx *ExecContext) (*Summary, error)

type RunCIHooksOptions struct {
	// Event is the hook event (e.g., "after.terraform.deploy").
	Event HookEvent

	// AtmosConfig is the Atmos configuration.
	AtmosConfig *schema.AtmosConfiguration

	// Info contains component and stack information.
	Info *schema.ConfigAndStacksInfo

	// Output is the captured command output to process.
	Output string

	// ForceCIMode forces CI mode even when environment detection fails (--ci flag).
	ForceCIMode bool

	// CommandError is the error from the command execution, if any (nil on success).
	CommandError error

	// ExitCode is the exit code from the command execution. This is the
	// authoritative signal plugins use to determine success/failure and (for
	// `terraform plan` with -detailed-exitcode) change detection. Pass 0 on success.
	ExitCode int
}

type StoreCommand struct {
	Name string
	// contains filtered or unexported fields
}

type Summary struct {
	// Kind is the registered kind name (Pro selects its renderer from this).
	Kind string
	// Status is success | warning | failure.
	Status SummaryStatus
	// Title is the short headline (e.g. "+$47.20/mo" or "2 HIGH, 5 MED").
	Title string
	// Counts is an optional grouped breakdown (e.g. {"high": 2, "medium": 5}).
	Counts map[string]int
	// Body is the single markdown rendering used in every surface that
	// renders markdown: terminal, Pro run page, PR comments, step summaries.
	Body string
}

type SummaryStatus string

type TerraformOutputGetter func(
	atmosConfig *schema.AtmosConfiguration,
	stack string,
	component string,
	output string,
	skipCache bool,
	authContext *schema.AuthContext,
	authManager any,
) (any, bool, error)