actions

type Action string

type ActionCategory string

type ActionDefinition struct {
	Type        string                    `json:"type"`
	Description string                    `json:"description"`
	Properties  map[string]PropertySchema `json:"properties"`
	Required    []string                  `json:"required"`
}

type ActionMetadata struct {
	// Name is the action name as it appears in YAML (e.g., "shell", "file", "notify")
	Name string

	// Description is a human-readable description of what this action does
	Description string

	// Category groups related actions (command, file, system, etc.)
	Category ActionCategory

	// SupportsDryRun indicates whether this action can be executed in dry-run mode
	SupportsDryRun bool

	// SupportsBecome indicates whether this action supports privilege escalation (sudo)
	SupportsBecome bool

	// EmitsEvents lists the event types this action emits (e.g., "file.created", "notify.sent")
	EmitsEvents []string

	// Version is the action implementation version (semantic versioning)
	Version string

	// SupportedPlatforms lists the operating systems this action supports.
	// Valid values: "linux", "darwin", "windows", "freebsd", "openbsd", "netbsd", "dragonfly", "solaris", "aix"
	// Empty list means all platforms are supported
	SupportedPlatforms []string

	// RequiresSudo indicates whether this action typically requires elevated privileges.
	// This is informational - actual privilege requirements may vary based on the operation.
	RequiresSudo bool

	// ImplementsCheck indicates whether this action implements idempotency checks.
	// Actions with idempotency checks verify current state before making changes.
	ImplementsCheck bool
}

type Context interface {
	// GetTemplate returns the template renderer for processing Jinja2-like templates.
	//
	// Use this to render:
	//   - Path strings with variables: "{{ home }}/{{ item }}"
	//   - Content with logic: "{% if os == 'linux' %}...{% endif %}"
	//   - Filters: "{{ path | expanduser }}"
	//
	// The renderer has access to all variables in scope (step vars, globals, facts).
	GetTemplate() template.Renderer

	// GetEvaluator returns the expression evaluator for conditions.
	//
	// Use this to evaluate:
	//   - when: "os == 'linux' && arch == 'amd64'"
	//   - changed_when: "result.rc == 0 and 'changed' in result.stdout"
	//   - failed_when: "result.rc != 0 and result.rc != 5"
	//
	// Returns interface{} which should be cast to bool for conditions.
	GetEvaluator() expression.Evaluator

	// GetLogger returns the logger for handler output.
	//
	// Use levels appropriately:
	//   - Infof: User-visible progress ("Installing package nginx")
	//   - Debugf: Detailed info ("Command: apt install nginx")
	//   - Warnf: Non-fatal issues ("File already exists, skipping")
	//   - Errorf: Failures ("Failed to create directory: permission denied")
	//
	// Output is formatted for TUI or text mode automatically.
	GetLogger() logger.Logger

	// GetVariables returns all variables in the current scope.
	//
	// Includes:
	//   - Step-level vars (defined in step.Vars)
	//   - Global vars (from vars actions)
	//   - System facts (os, arch, cpu_cores, memory_total_mb, etc.)
	//   - Registered results (from register: field on previous steps)
	//   - Loop context (item, item_index when in with_items/with_filetree)
	//
	// Keys are strings, values are interface{} (string, int, bool, []interface{}, map[string]interface{}).
	GetVariables() map[string]interface{}

	// GetEventPublisher returns the event publisher for observability.
	//
	// Emit events for:
	//   - State changes (EventFileCreated, EventServiceStarted)
	//   - Progress tracking (custom events for long operations)
	//   - Artifact generation (paths to created files)
	//
	// Events are consumed by:
	//   - Artifact collector (for rollback support)
	//   - External observers (CI/CD integrations)
	//   - Audit logs
	GetEventPublisher() events.Publisher

	// Mode reports the dispatch mode for this context. Handlers
	// implementing Runner consult this to decide whether to perform side
	// effects (ModeExecute) or only inspect state (ModePlan).
	Mode() Mode

	// Effects returns a Performer wired to this context. Handlers
	// implementing Runner should call Performer methods instead of os.*
	// directly so that ModePlan vs ModeExecute is decided in one place.
	// The returned Performer is cheap to construct and may be called
	// multiple times.
	Effects() Performer

	// GetCurrentStepID returns the unique ID of the currently executing step.
	//
	// Format: "step-{global_step_number}"
	//
	// Use this when:
	//   - Emitting events (so they're associated with the step)
	//   - Creating temporary files (include step ID to avoid conflicts)
	//   - Logging (though step ID is usually added automatically)
	GetCurrentStepID() string
}

type Effect struct {
	Action      Action
	Path        string
	Reason      string
	Performed   bool
	WouldChange bool
	AlreadyOk   bool
	Err         error
	Detail      any
}

type Handler interface {
	// Metadata returns metadata describing this action type.
	Metadata() ActionMetadata

	// Validate checks if the step configuration is valid for this action.
	// Called before Run to fail fast on configuration errors.
	Validate(step *config.Step) error

	// Run executes the action when ctx.Mode() is ModeExecute, or
	// inspects state and returns a prediction when ctx.Mode() is
	// ModePlan. Implementations:
	//
	//   - emit appropriate events via ctx.GetEventPublisher() (execute mode)
	//   - render templates via ctx.GetTemplate()
	//   - use ctx.GetLogger() for logging
	//   - return Result with Changed=true (execute) or
	//     WouldChange=true (plan) when state would change
	//   - route filesystem mutations through ctx.Effects() so that
	//     plan and execute modes share the same predicates
	//
	// Returns an error only on unrecoverable failure.
	Run(ctx Context, step *config.Step) (Result, error)
}

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

type Mode int

type Performer interface {
	// Mode reports the mode the Performer will use for the next call.
	Mode() Mode

	// Mkdir ensures a directory exists at path with the given mode.
	// Parents are created as needed.
	Mkdir(path string, mode os.FileMode, opts PerformerOpts) Effect

	// WriteFile writes content to path with the given mode, creating
	// parent directories as needed. Idempotent: if existing content
	// already matches, AlreadyOk is set.
	WriteFile(path string, content []byte, mode os.FileMode, opts PerformerOpts) Effect

	// Symlink creates a symbolic link at path pointing to target. If a
	// link already exists with the correct target, AlreadyOk is set.
	Symlink(target, path string, opts PerformerOpts) Effect

	// Hardlink creates a hard link at path pointing to target.
	Hardlink(target, path string, opts PerformerOpts) Effect

	// Touch updates mtime, creating an empty file with the given mode
	// if absent. Not idempotent: WouldChange is always true in ModePlan.
	Touch(path string, mode os.FileMode, opts PerformerOpts) Effect

	// Remove deletes path. If recursive is true, removes directories
	// and their contents.
	Remove(path string, recursive bool, opts PerformerOpts) Effect

	// Chmod sets the permission bits on path.
	Chmod(path string, mode os.FileMode, opts PerformerOpts) Effect

	// Chown sets owner and group on path. Empty owner or group leaves
	// that side unchanged. Owner/group may be names or numeric IDs.
	Chown(path, owner, group string, opts PerformerOpts) Effect
}

type PerformerOpts struct {
	Become     bool
	BecomeUser string
}

type PropertySchema struct {
	Type        string `json:"type"`
	Description string `json:"description"`
	Pattern     string `json:"pattern,omitempty"`
}

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

type Result interface {
	// SetChanged marks whether this action modified system state.
	//
	// Set to true if the action:
	//   - Created/modified/deleted files or directories
	//   - Started/stopped/restarted services
	//   - Installed/removed packages
	//   - Executed commands that changed state
	//
	// Set to false if the action:
	//   - Found state already as desired (idempotent)
	//   - Only read/queried information
	//   - Failed before making changes
	//
	// Changed count is reported in run summary and used for idempotency tracking.
	SetChanged(changed bool)

	// SetStdout captures standard output from the action.
	//
	// Used primarily by shell/command actions. Output is:
	//   - Available in registered results as {{ result.stdout }}
	//   - Shown in TUI output view
	//   - Logged to artifacts
	//   - Used in changed_when/failed_when expressions
	SetStdout(stdout string)

	// SetStderr captures standard error from the action.
	//
	// Used primarily by shell/command actions. Error output is:
	//   - Available in registered results as {{ result.stderr }}
	//   - Shown in TUI output view (usually in red)
	//   - Logged to artifacts
	//   - Used in changed_when/failed_when expressions
	SetStderr(stderr string)

	// SetFailed marks the result as failed.
	//
	// Usually you should return an error instead of calling this. Use this when:
	//   - The action completed but didn't achieve desired state
	//   - failed_when expression evaluated to true
	//   - Assertion failed (assert action)
	//
	// Failed steps:
	//   - Increment failure count in run summary
	//   - Stop execution (unless ignore_errors: true)
	//   - Are highlighted in TUI
	SetFailed(failed bool)

	// SetData attaches custom data to the result.
	//
	// Data becomes available when the result is registered via register: field.
	//
	// Example:
	//
	//	result.SetData(map[string]interface{}{
	//	    "checksum": "sha256:abc123",
	//	    "size_bytes": 1024,
	//	    "format": "json",
	//	})
	//
	// Then in subsequent steps:
	//	  when: myfile.checksum == "sha256:abc123"
	//	  shell: echo "File size: {{ myfile.size_bytes }}"
	//
	// Keys should be snake_case. Values should be JSON-serializable.
	SetData(data map[string]interface{})

	// RegisterTo registers this result to the variables map.
	//
	// Called automatically by the executor when a step has register: field.
	// Creates a map in variables with:
	//   - changed: bool
	//   - failed: bool
	//   - stdout: string (if set)
	//   - stderr: string (if set)
	//   - rc: int (if applicable)
	//   - ...custom data from SetData()
	//
	// Handlers typically don't call this directly.
	RegisterTo(variables map[string]interface{}, name string)
}

type Runner interface {
	Run(ctx Context, step *config.Step) (Result, error)
}

type Schema struct {
	Definitions map[string]ActionDefinition `json:"definitions"`
}