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
	// HookName is the key used for this hook in the component's hooks map.
	// It is separate from Hook.Name, which is a store-kind field.
	HookName string

	// Outcome is the lifecycle operation result this hook fires around
	// (success/failure, exit code, error). Set by RunAll. Distinct from the
	// ExitCode/CommandError fields below, which a command engine sets for its
	// own subprocess. Engines expose this to their work (e.g. the step bridge
	// sets ATMOS_HOOK_STATUS and injects `.status` into the template context).
	Outcome Outcome

	// 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 Finding struct {
	// Path is the file the finding refers to, relative to the scanned root.
	Path string
	// Line is the 1-based line number; 0 when unknown (anchor at file level).
	Line int
	// Severity is the normalized bucket: critical | high | medium | low | info.
	Severity string
	// RuleID is the tool's rule identifier (e.g. "CKV_AWS_21").
	RuleID string
	// Message is the human-readable finding description.
	Message string
}

type GitCommitSpec struct {
	// Message is the commit message; empty selects the engine default
	// ("Update artifacts for <component> in <stack>").
	Message string `yaml:"message,omitempty"`
	// Paths are repo-relative paths staged for the commit.
	Paths []string `yaml:"paths,omitempty"`
}

type Hook struct {
	// Kind selects the engine that runs this hook. Built-in kinds:
	// "store" (existing semantics), "command" (generic binary execution),
	// plus step-backed kinds like "step" and "steps", and 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"`

	// When selects whether this hook runs. Empty defaults to success-only,
	// preserving the original behavior where after-* hooks fired only when the
	// operation succeeded.
	When schema.Condition `yaml:"when,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 / parsing hint for generic kinds. Accepts
	// "markdown" (render the artifact inline), "sarif" (parse the output as
	// SARIF — giving a custom `kind: command` hook the same findings summary,
	// CI annotations, and SARIF upload as the built-in scanner kinds), or
	// empty (= downloadable artifact, no inline render).
	Format string `yaml:"format,omitempty"`

	// Results names the file a `format: sarif` command writes its SARIF to,
	// relative to $ATMOS_OUTPUT_DIR, for tools that write a fixed filename
	// into a directory rather than to $ATMOS_OUTPUT_FILE. When empty, the
	// SARIF is read from $ATMOS_OUTPUT_FILE.
	Results string `yaml:"results,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"`

	// Git-kind specific (kind: git; see pkg/hooks/kinds/git).
	//
	// Repository names a managed repository under the top-level
	// git.repositories config. Empty targets the current repository.
	Repository string `yaml:"repository,omitempty"`
	// Commit configures the commit the git kind creates.
	Commit *GitCommitSpec `yaml:"commit,omitempty"`
	// Push pushes the created commit to the remote when true.
	Push bool `yaml:"push,omitempty"`

	// Step-kind specific (kind: step; see pkg/hooks/step_engine.go).
	//
	// Type names the step-registry step type to run (e.g. "container",
	// "toast", "http"). Required for kind: step.
	Type string `yaml:"type,omitempty"`
	// With holds the kind-specific payload. For kind: step it is the step's
	// parameter map, decoded into one WorkflowStep. For kind: steps it is an
	// ordered list of WorkflowStep objects. Rendered (templates + YAML
	// functions) by resolveHookForExecution before the engine sees it.
	With any `yaml:"with,omitempty"`
	// Retry wraps the step execution in retry.Do. Same schema as a
	// workflow step's retry block; interpreted by the bridge, not the step.
	Retry *schema.RetryConfig `yaml:"retry,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 Outcome struct {
	// Status is the operation outcome: success or failure.
	Status RunStatus
	// Err is the operation error on failure; nil on success.
	Err error
	// ExitCode is the operation exit code (0 on success).
	ExitCode int
}

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

	// Aggregate carries command-specific aggregate result data for hook events
	// that summarize more than one component.
	Aggregate any
}

type RunStatus string

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
	// Findings is the optional structured, line-anchored findings behind the
	// summary (populated by SARIF-producing kinds). The engine maps these to
	// CI annotations; left nil by kinds that produce no findings (e.g. cost).
	Findings []Finding
	// SARIF is the optional raw SARIF document the kind produced (passed
	// through verbatim for upload to a CI security store). Left nil by
	// non-SARIF kinds. Kept separate from Findings so a clean (zero-finding)
	// SARIF can still be uploaded to mark previously-open alerts as fixed.
	SARIF []byte
}

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)