cuetry

package
v0.3.7 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 2, 2026 License: MIT Imports: 40 Imported by: 0

Documentation

Overview

Package cuetry parses, validates, and resolves CUE remote recipes for honey.

Index

Constants

View Source 
const (
	KindCommand       = "command"
	KindScript        = "script"
	KindPut           = "put"
	KindGet           = "get"
	KindAgentTransfer = "agent_transfer"
	KindSummarize     = "summarize"
	KindAI            = "ai"
	KindTemplate      = "template"
	KindPlugin        = "plugin"
	KindTunnel        = "tunnel"
	KindK8s           = "k8s"
	KindDocker        = "docker"
	KindOpensearch    = "opensearch"
	KindPostgres      = "postgres"
	KindPackage       = "package"
	KindService       = "service"
	KindRecipe        = "recipe"
	KindOPA           = "opa"
)

Step kind identifiers. These replace the old StepKind enum; using strings avoids the zero-value enum footgun (iota 0 silently meaning "command").

View Source 
const DefaultRecipeAISystemPrompt = `` /* 731-byte string literal not displayed */

DefaultRecipeAISystemPrompt is used when neither recipe ai.system_prompt nor config defaults.ai_system_prompt is set.

View Source 
const MatchAllSearchHosts = "*"

MatchAllSearchHosts is a recipe step host value meaning: run this step on every host in the current search result set that has a PrimaryIP (same filter as parallel SSH in the UI).

View Source 
const MatchHostRegexPrefix = "re:"

MatchHostRegexPrefix starts a host value interpreted as a Go regexp (RE2) matched against each search row's Name. Example: re:^prod-kafka-.+$ Use (?i) inside the pattern for case-insensitive matching.

View Source 
const MatchLocalAIHost = "_"

MatchLocalAIHost is the only valid host value for local steps (ai, template).

Variables

This section is empty.

Functions

func ApplyJSONToCUEAST added in v0.3.6 

func ApplyJSONToCUEAST(originalCUE []byte, updatedJSON []byte) ([]byte, error)

ApplyJSONToCUEAST is the boundary for mapping JSON structural edits back onto raw CUE.

func BuildBackOff added in v0.3.0 

func BuildBackOff(r RecipeStepRetry) backoff.BackOff

BuildBackOff returns a backoff strategy for the given retry config.

func BuildEnvMapForWhen added in v0.3.0 

func BuildEnvMapForWhen(ctx context.Context, resolveSecrets bool, resolver SecretResolver, step *StepBase, defaults *RecipeDefaults, cliEnv map[string]string, host *hosts.Record) (map[string]string, error)

BuildEnvMapForWhen merges recipe defaults/step env, CLI overrides, and host env for CEL when.

func BuildRecipeVarMap added in v0.3.0 

func BuildRecipeVarMap(capture *RecipeOutputCapture, env map[string]string) map[string]string

BuildRecipeVarMap merges capture names and env (later keys win).

func BuildSecretsMapForWhen added in v0.2.9 

func BuildSecretsMapForWhen(ctx context.Context, resolve bool, resolver SecretResolver, step *StepBase, defaults *RecipeDefaults) (map[string]string, error)

BuildSecretsMapForWhen merges defaults and step secret keys into a map for CEL (resolved or redacted).

func BuildStepJSONSchema added in v0.3.6 

func BuildStepJSONSchema() map[string]any

BuildStepJSONSchema reflects each registered concrete step kind into its own definition, so every kind exposes exactly its own fields (e.g. template/ai have no ssh_port / max_parallel). The result is consumed by the RecipeStudio frontend.

func CountRecipeStreamResults added in v0.2.8 

func CountRecipeStreamResults(recipe Recipe, records []hosts.Record) (int, error)

CountRecipeStreamResults returns how many HostExecResult values a streaming recipe run would emit for the given host rows (one per expanded target per step, or one per agent_transfer step).

func DeclaredSecretKeys added in v0.2.9 

func DeclaredSecretKeys(step *StepBase, defaults *RecipeDefaults) map[string]struct{}

DeclaredSecretKeys returns union of secret keys from defaults and step.

func DefaultFacts added in v0.3.4 

func DefaultFacts() map[string]any

DefaultFacts returns the default fallback facts map with unknown values.

func EffectiveEnv 

func EffectiveEnv(step *StepBase, defaults *RecipeDefaults) (map[string]string, error)

EffectiveEnv merges recipe.defaults.env with step.env (step wins on duplicate keys). Literal env only (no secrets).

func EffectiveEnvForRemoteHook added in v0.2.8 

func EffectiveEnvForRemoteHook(ctx context.Context, resolveSecrets bool, resolver SecretResolver, step *StepBase, defaults *RecipeDefaults, hook *RecipeStepHook, cliEnv map[string]string, r *hosts.Record) (map[string]string, error)

EffectiveEnvForRemoteHook merges defaults env/secrets, step env/secrets, hook env/secrets, then cliEnv, then host variables.

func EffectiveEnvForRun 

func EffectiveEnvForRun(ctx context.Context, resolveSecrets bool, resolver SecretResolver, step *StepBase, defaults *RecipeDefaults, cliEnv map[string]string, r *hosts.Record) (map[string]string, error)

EffectiveEnvForRun merges defaults.env → resolved defaults.secrets → step.env → resolved step.secrets → cliEnv → host HONEY_HOST_*. When resolveSecrets is false (dry-run / plan), secret values are replaced with redacted placeholders and resolver may be nil.

func EffectiveEnvForRunEx added in v0.2.9 

func EffectiveEnvForRunEx(ctx context.Context, resolveSecrets bool, resolver SecretResolver, step *StepBase, defaults *RecipeDefaults, cliEnv map[string]string, r *hosts.Record, opts *EffectiveEnvForRunOpts) (map[string]string, error)

EffectiveEnvForRunEx merges env like EffectiveEnvForRun with env_from and HONEY_STEP_ID.

func EffectiveEnvForRunWithVarExpand added in v0.3.0 

func EffectiveEnvForRunWithVarExpand(ctx context.Context, resolveSecrets bool, resolver SecretResolver, step *StepBase, defaults *RecipeDefaults, cliEnv map[string]string, r *hosts.Record, strict bool) (map[string]string, error)

EffectiveEnvForRunWithVarExpand merges env then expands ${VAR} in values using merged map as vars.

func EffectiveEnvHostOnly added in v0.2.9 

func EffectiveEnvHostOnly(r *hosts.Record) (map[string]string, error)

EffectiveEnvHostOnly returns only HONEY_HOST_* variables derived from r (no recipe env or secrets).

func EffectiveHookWhere added in v0.3.4 

func EffectiveHookWhere(hook *RecipeStepHook) string

EffectiveHookWhere returns the hook execution location. Empty defaults to remote.

func EffectiveRunAs 

func EffectiveRunAs(step *StepBase, defaults *RecipeDefaults) string

EffectiveRunAs returns step-level run_as, else recipe defaults.run_as, else "".

func EffectiveSSHPort added in v0.2.9 

func EffectiveSSHPort(defaults *RecipeDefaults, step *RemoteExec, r hosts.Record) int

EffectiveSSHPort returns the TCP port for SSH to r using recipe precedence: step.ssh_port, then defaults.ssh_port, then record meta.ssh_port, else 0 (use ~/.ssh/config / 22 only).

func EffectiveSSHPrivateKey added in v0.2.9 

func EffectiveSSHPrivateKey(defaults *RecipeDefaults, step *RemoteExec) string

EffectiveSSHPrivateKey returns the private key path for SSH using recipe precedence: step.ssh_private_key, then defaults.ssh_private_key, else "" (use ssh_config / env / ~/.ssh).

func EffectiveTunnelMode added in v0.3.0 

func EffectiveTunnelMode(t *RecipeStepTunnel) string

EffectiveTunnelMode returns normalized tunnel mode (local, remote, dynamic, udp, tun).

func EnvForDockerInteractive added in v0.3.0 

func EnvForDockerInteractive(r *hosts.Record) ([]string, error)

EnvForDockerInteractive returns a small env slice for docker exec TTY sessions. Full EffectiveEnvForRun includes every meta label and can exceed Engine limits or break shells.

func EnvMapForDockerExec added in v0.3.0 

func EnvMapForDockerExec(env map[string]string) ([]string, error)

EnvMapForDockerExec formats env for Moby ExecCreateOptions.Env (KEY=value entries).

func EvalJQ added in v0.3.0 

func EvalJQ(jsonDoc, query string) (string, error)

EvalJQ runs a jq query against a JSON document string. Scalar results are formatted as strings; arrays and objects are compact JSON.

func EvalJQArray added in v0.3.4 

func EvalJQArray(jsonDoc, query string) ([]string, error)

EvalJQArray runs a jq query against a JSON document string, returning a list of strings. If the result is a JSON array, it returns each element formatted as a string. If it's a single value, it returns a single-element list.

func EvalResultBoolExpr added in v0.3.4 

func EvalResultBoolExpr(expr string, ctx ResultExprContext) (bool, error)

EvalResultBoolExpr compiles and evaluates a result override expression.

func EvalWhen added in v0.2.9 

func EvalWhen(prog *WhenProgram, opts WhenEvalOpts) (bool, error)

EvalWhen evaluates a compiled when program; false means skip the host/step.

func ExpandMatrixSteps added in v0.3.6 

func ExpandMatrixSteps(r *Recipe) error

ExpandMatrixSteps evaluates matrix definitions and replaces them with Cartesian expanded steps.

func ExpandPluginConfigJSON added in v0.3.0 

func ExpandPluginConfigJSON(config []byte, vars map[string]string, dryRun bool) ([]byte, error)

ExpandPluginConfigJSON expands ${VAR} in string values of plugin config JSON.

func ExpandRecipeEnvValues added in v0.3.0 

func ExpandRecipeEnvValues(env map[string]string, vars map[string]string, strict bool) error

ExpandRecipeEnvValues expands ${VAR} in env map values (keys unchanged).

func ExpandRecipeVars added in v0.3.0 

func ExpandRecipeVars(s string, vars map[string]string, strict bool) (string, error)

ExpandRecipeVars replaces ${NAME} in s using vars. When strict is true, unknown names return an error; otherwise they are left literal.

func ExpandRecipeVarsInData added in v0.3.0 

func ExpandRecipeVarsInData(data map[string]any, vars map[string]string, strict bool) error

ExpandRecipeVarsInData expands ${VAR} in string values of data (top-level and nested maps).

func ExpandStepHosts 

func ExpandStepHosts(host string, records []hosts.Record) ([]hosts.Record, error)

ExpandStepHosts returns the host records one step should run against. If host is MatchAllSearchHosts, returns all records with a non-empty PrimaryIP (preserving search order). If host starts with MatchHostRegexPrefix, returns every record with PrimaryIP whose Name matches the regexp. Otherwise returns a single-element slice from ResolveHostFromRecords (literal IP or exact name match).

func FormatGraphWavesText added in v0.2.9 

func FormatGraphWavesText(r Recipe) (string, error)

FormatGraphWavesText returns a human-readable wave plan for graph recipes.

func GraphStepWaves added in v0.2.9 

func GraphStepWaves(r Recipe) ([][]int, error)

GraphStepWaves returns execution waves for a validated graph recipe.

func KVTunnelEnabled added in v0.2.8 

func KVTunnelEnabled(_ Step, _ *RecipeDefaults) bool

KVTunnelEnabled reports whether the step should enable the KV HTTP API on the remote (HONEY_KV_URL, HONEY_KV_TOKEN). Always true; recipe kv_tunnel fields are deprecated no-ops.

func LoopTemplateFuncMap added in v0.3.7 

func LoopTemplateFuncMap(store *StepResultStore, capture *RecipeOutputCapture) template.FuncMap

LoopTemplateFuncMap returns stepStdout/stepStdoutLines/outputStdout/ outputStdoutLines template functions backed by store and capture — used by loop: templates, and by internal/engine's templated command/script rendering.

func MatchLocalAIHostRecord added in v0.3.0 

func MatchLocalAIHostRecord() hosts.Record

MatchLocalAIHostRecord is the synthetic host row for MatchLocalAIHost expansion.

func MergeEnvFromInto added in v0.2.9 

func MergeEnvFromInto(dst map[string]string, step *StepBase, store *StepOutputStore, capture *RecipeOutputCapture, kv KVReader, hostName string, dryRun bool, matrixExpansions map[string][]string) error

MergeEnvFromInto resolves env_from into dst (execute mode). Fails if a mapped value is missing.

func MergeEnvFromIntoTemplateData added in v0.3.0 

func MergeEnvFromIntoTemplateData(data map[string]any, step *StepBase, store *StepOutputStore, capture *RecipeOutputCapture, kv KVReader, hostName string, dryRun bool, matrixExpansions map[string][]string) error

MergeEnvFromIntoTemplateData overlays env_from-resolved keys onto template data (graph mode).

func MergeResolvedSecretsInto added in v0.2.9 

func MergeResolvedSecretsInto(ctx context.Context, resolve bool, resolver SecretResolver, dst map[string]string, secrets map[string]RecipeSecret, label string) error

MergeResolvedSecretsInto validates secret refs and merges resolved values into dst (or redacted placeholders when resolve is false).

func OutputNamesReferencedByEnvFrom added in v0.3.0 

func OutputNamesReferencedByEnvFrom(r Recipe) map[string]struct{}

OutputNamesReferencedByEnvFrom returns template.output names referenced via from_output.

func OutputTemplateFuncMap added in v0.3.4 

func OutputTemplateFuncMap(capture *RecipeOutputCapture) template.FuncMap

OutputTemplateFuncMap returns template helpers for named recipe outputs.

func OverlapEnvSecrets added in v0.2.9 

func OverlapEnvSecrets(env map[string]string, secrets map[string]RecipeSecret) error

OverlapEnvSecrets returns an error if the same key appears in both env and secrets maps.

func ParseEnvKeyValuePairs 

func ParseEnvKeyValuePairs(pairs []string) (map[string]string, error)

ParseEnvKeyValuePairs parses repeated "KEY=value" strings (first '=' separates key from value). Empty entries are skipped. Later duplicates overwrite earlier ones.

func PostgresExtractKVKey added in v0.3.0 

func PostgresExtractKVKey(baseKey, name string) (string, error)

PostgresExtractKVKey returns the KV key for an extract variable name.

func PrepareTemplateData added in v0.3.0 

func PrepareTemplateData(data map[string]any, step *StepBase, store *StepOutputStore, capture *RecipeOutputCapture, kv KVReader, hostName string, extraEnv map[string]string, dryRun bool, matrixExpansions map[string][]string) error

PrepareTemplateData merges env_from and expands ${VAR} in data values (not the Go template body).

func RecipeHasKVTunnel added in v0.2.9 

func RecipeHasKVTunnel(_ Recipe) bool

RecipeHasKVTunnel reports whether the recipe run uses stepkv (always true; kv_tunnel is always on).

func RecipeHasTemplateStep added in v0.3.0 

func RecipeHasTemplateStep(r Recipe) bool

RecipeHasTemplateStep reports whether any step uses template rendering.

func RecipeNeedsStepOutputCapture added in v0.2.9 

func RecipeNeedsStepOutputCapture(r Recipe) bool

RecipeNeedsStepOutputCapture reports whether any step may need stdout capture.

func RecipeUsesKVInWhen added in v0.2.9 

func RecipeUsesKVInWhen(r Recipe) bool

RecipeUsesKVInWhen reports whether any when expression calls kv_get or kv_has.

func RecipeUsesWhen added in v0.2.9 

func RecipeUsesWhen(r Recipe) bool

RecipeUsesWhen reports whether any step has a when expression.

func RecordForSSHDial added in v0.2.9 

func RecordForSSHDial(defaults *RecipeDefaults, step *RemoteExec, r hosts.Record) hosts.Record

RecordForSSHDial returns r unchanged or a shallow copy with recipe SSH dial options (meta ssh_port, ssh_identity_file) so hostexec and SSHClientCacheKey see effective settings.

func RedactedSecretValueForDryRun added in v0.2.9 

func RedactedSecretValueForDryRun(ref string) string

RedactedSecretValueForDryRun returns a safe placeholder for dry-run / plans (truncated ref, never resolved material).

func RegisterStep added in v0.3.5 

func RegisterStep(kind string, actionKeys []string, ctor func() Step)

RegisterStep registers a concrete step kind, the JSON action keys that select it, and a constructor. Idempotent: re-registering a kind replaces the prior entry.

func RenderLoopTemplate added in v0.3.4 

func RenderLoopTemplate(opts RenderLoopTemplateOpts) ([]string, error)

RenderLoopTemplate renders a Sprig-backed template and decodes its JSON array output.

func RenderTemplate added in v0.3.0 

func RenderTemplate(opts RenderTemplateOpts) (string, error)

RenderTemplate evaluates a Go text/template with slim-sprig.

func ResolveHostFromRecords 

func ResolveHostFromRecords(host string, records []hosts.Record) (hosts.Record, error)

ResolveHostFromRecords maps recipe "host" to a record with PrimaryIP. If host looks like an IP address, it returns a synthetic record (Name=host). Otherwise it matches Record.Name with case-insensitive equality; multiple matches are an error.

func ResolveLocalAgainstRecipe 

func ResolveLocalAgainstRecipe(recipeDir, local string) (string, error)

ResolveLocalAgainstRecipe returns an absolute local path: absolute paths are unchanged; relative paths are joined to recipeDir.

func ResolveStepKVBaseKey added in v0.3.7 

func ResolveStepKVBaseKey(base string, perHost bool, hostName string) (string, error)

ResolveStepKVBaseKey returns a step's kv_key with optional per-host suffix. Shared by any step kind that supports kv_key/kv_key_per_host (postgres, plugin, ...) — the logic has never been postgres-specific.

func SanitizeKVHostSuffix added in v0.3.0 

func SanitizeKVHostSuffix(hostName string) string

SanitizeKVHostSuffix maps host names to a single stepkv key segment.

func ScriptRunAfterUpload 

func ScriptRunAfterUpload(remotePath, runAs string, env map[string]string, interpreter string) (string, error)

ScriptRunAfterUpload builds the remote shell command to execute an uploaded file with POSIX sh (after SFTP). Optional run_as wraps the run like command steps. Optional env is applied as export assignments before `sh remotePath` (same as command steps). Scripts should be compatible with `sh` (or rely on a shebang if the kernel honors it when executed as argument to sh — use POSIX sh syntax for portability).

func ShellExportPrefixForRemote 

func ShellExportPrefixForRemote(env map[string]string, inner string) (string, error)

ShellExportPrefixForRemote prepends stable `export KEY='value'; ` assignments before inner (remote shell).

func ShouldRetryHostResult added in v0.3.0 

func ShouldRetryHostResult(success, skipped bool) bool

ShouldRetryHostResult reports whether a host exec result should be retried.

func StepIDsReferencedByEnvFrom added in v0.2.9 

func StepIDsReferencedByEnvFrom(r Recipe) map[string]struct{}

StepIDsReferencedByEnvFrom returns step ids that should capture stdout (sources in env_from).

func StepIDsReferencedByTunnelStep added in v0.3.0 

func StepIDsReferencedByTunnelStep(r Recipe) map[string]struct{}

StepIDsReferencedByTunnelStep returns step ids referenced by plugin tunnel_step config.

func StepIDsReferencedByWhen added in v0.2.9 

func StepIDsReferencedByWhen(r Recipe) map[string]struct{}

StepIDsReferencedByWhen returns step ids referenced as steps['id'] in when expressions.

func StepKinds added in v0.3.5 

func StepKinds() []string

StepKinds returns the registered kind identifiers in registration order.

func StepOutputName added in v0.3.4 

func StepOutputName(s Step) string

StepOutputName returns the step-level or legacy nested capture name.

func ValidateAndApplyPromptDefaults added in v0.3.6 

func ValidateAndApplyPromptDefaults(prompts map[string]RecipePrompt, cliEnv map[string]string) (map[string]string, error)

ValidateAndApplyPromptDefaults merges prompt defaults into cliEnv and returns an error if any required prompt has neither a supplied value nor a default. Returns a new map; never mutates cliEnv.

func ValidateHostField 

func ValidateHostField(host string) error

ValidateHostField checks host syntax (empty, regex compile). Call from ParseRemoteRecipe; ExpandStepHosts enforces match counts at runtime.

func ValidateJQQuery added in v0.3.0 

func ValidateJQQuery(query string) error

ValidateJQQuery parses a jq query for static validation.

func ValidateParsedRecipe added in v0.2.8 

func ValidateParsedRecipe(r Recipe, records []hosts.Record) error

ValidateParsedRecipe runs the same per-step validators that ParseRemoteRecipe applies after CUE decoding, but on an already-decoded Recipe value (e.g. constructed from JSON via RecipeFromJSON or supplied inline by an API caller). It does not re-parse CUE text, so callers that bypass the CUE compiler must invoke this to ensure the Recipe is well-formed before handing it to a runner.

func ValidateRecipeEnvMap 

func ValidateRecipeEnvMap(m map[string]string) error

ValidateRecipeEnvMap checks every key/value pair for safe use in POSIX export assignments.

func ValidateRecipeGraph added in v0.2.9 

func ValidateRecipeGraph(r Recipe) error

ValidateRecipeGraph checks graph/linear rules for ids, depends, ai, and kv_tunnel.

func ValidateRecipeSecretsRefMap added in v0.2.9 

func ValidateRecipeSecretsRefMap(m map[string]RecipeSecret) error

ValidateRecipeSecretsRefMap checks secret map keys and ref strings (refs are resolved at execute time).

func ValidateRecipeSecretsRefMapPrefixes added in v0.2.9 

func ValidateRecipeSecretsRefMapPrefixes(m map[string]RecipeSecret, allowedPrefixes []string) error

ValidateRecipeSecretsRefMapPrefixes allows secure:v1 refs and optional plugin-registered prefixes.

func ValidateRemoteRecipe 

func ValidateRemoteRecipe(cueBytes []byte) error

ValidateRemoteRecipe checks that cueBytes is valid CUE and conforms to #Recipe.

func ValidateRetry added in v0.3.0 

func ValidateRetry(r RecipeStepRetry) error

ValidateRetry returns an error for invalid retry configuration.

func ValidateRunAsUser 

func ValidateRunAsUser(user string) error

ValidateRunAsUser restricts remote account names to a safe POSIX-like subset to avoid shell metacharacters in sudo -u.

func WithRecipeDir added in v0.2.9 

func WithRecipeDir(ctx context.Context, absDir string) context.Context

WithRecipeDir attaches the absolute recipe directory to ctx (for age-file and similar).

func WrapRemoteShell 

func WrapRemoteShell(runAs, innerCommand string) (string, error)

WrapRemoteShell runs the inner command as SSH login user; if runAs is set, wraps with: sudo -n -u '<runAs>' -- sh -lc '<inner>' (non-interactive sudo).

Types

type AIStep added in v0.3.5 

type AIStep struct {
	StepBase
	AI        *RecipeAI `json:"ai,omitempty"`
	Templated bool      `json:"templated,omitempty"`
}

AIStep runs a single local LLM completion. Unlike summarize:, it has no positional restriction, no at-most-one-per-recipe rule, and nothing stops another step from depending on it — it behaves like template: with an LLM call instead of a template render.

func (*AIStep) Clone added in v0.3.5 

func (s *AIStep) Clone() Step

Clone returns a deep copy of the step (safe for loop fan-out mutation).

func (*AIStep) Kind added in v0.3.5 

func (s *AIStep) Kind() string

Kind returns the step kind identifier.

func (*AIStep) Validate added in v0.3.5 

func (s *AIStep) Validate(vc StepValidateCtx) error

Validate checks this step's kind-specific fields; shared rules run separately.

type AgentTransferStep added in v0.3.5 

type AgentTransferStep struct {
	StepBase
	RemoteExec
	AgentTransfer *RecipeAgentTransfer `json:"agent_transfer,omitempty"`
}

AgentTransferStep stages a file through cloud storage from a source to a dest host.

func (*AgentTransferStep) Clone added in v0.3.5 

func (s *AgentTransferStep) Clone() Step

Clone returns a deep copy of the step (safe for loop fan-out mutation).

func (*AgentTransferStep) Kind added in v0.3.5 

func (s *AgentTransferStep) Kind() string

Kind returns the step kind identifier.

func (*AgentTransferStep) Validate added in v0.3.5 

func (s *AgentTransferStep) Validate(vc StepValidateCtx) error

Validate checks this step's kind-specific fields; shared rules run separately.

type Assertion added in v0.3.6 

type Assertion struct {
	Regex         string `json:"regex,omitempty"`
	NotRegex      string `json:"not_regex,omitempty"`
	JSONPath      string `json:"json_path,omitempty"`
	ExpectedValue string `json:"expected_value,omitempty"`
	ExitCode      *int   `json:"exit_code,omitempty"`
}

Assertion defines validation rules for a step's output and exit code.

type CommandStep added in v0.3.5 

type CommandStep struct {
	StepBase
	RemoteExec
	Command     string `json:"command,omitempty"`
	Interpreter string `json:"interpreter,omitempty"`
	Templated   bool   `json:"templated,omitempty"`
}

CommandStep runs a shell command on remote hosts.

func (*CommandStep) Clone added in v0.3.5 

func (s *CommandStep) Clone() Step

Clone returns a deep copy of the step (safe for loop fan-out mutation).

func (*CommandStep) Kind added in v0.3.5 

func (s *CommandStep) Kind() string

Kind returns the step kind identifier.

func (*CommandStep) Validate added in v0.3.5 

func (s *CommandStep) Validate(_ StepValidateCtx) error

Validate checks this step's kind-specific fields; shared rules run separately.

type DockerBuild added in v0.3.4 

type DockerBuild struct {
	Context    string            `json:"context"`
	Dockerfile string            `json:"dockerfile,omitempty"`
	Tags       []string          `json:"tags,omitempty"`
	BuildArgs  map[string]string `json:"build_args,omitempty"`
}

DockerBuild configures an image build operation.

type DockerExec added in v0.3.4 

type DockerExec struct {
	Container string   `json:"container"`
	Command   []string `json:"command"`
}

DockerExec configures executing a command inside a running container.

type DockerPull added in v0.3.4 

type DockerPull struct {
	Image string `json:"image"`
}

DockerPull configures pulling an image from a registry.

type DockerPush added in v0.3.4 

type DockerPush struct {
	Image string `json:"image"`
}

DockerPush configures pushing an image to a registry.

type DockerRun added in v0.3.4 

type DockerRun struct {
	Image   string            `json:"image"`
	Name    string            `json:"name,omitempty"`
	Command []string          `json:"command,omitempty"`
	Ports   []string          `json:"ports,omitempty"`
	Volumes []string          `json:"volumes,omitempty"`
	Env     map[string]string `json:"env,omitempty"`
	Detach  bool              `json:"detach,omitempty"`
	Rm      bool              `json:"rm,omitempty"`
}

DockerRun configures running a command in a new container.

type DockerStep added in v0.3.5 

type DockerStep struct {
	StepBase
	RemoteExec
	Docker *RecipeStepDocker `json:"docker,omitempty"`
}

DockerStep performs a Docker engine action.

func (*DockerStep) Clone added in v0.3.5 

func (s *DockerStep) Clone() Step

Clone returns a deep copy of the step (safe for loop fan-out mutation).

func (*DockerStep) Kind added in v0.3.5 

func (s *DockerStep) Kind() string

Kind returns the step kind identifier.

func (*DockerStep) Validate added in v0.3.5 

func (s *DockerStep) Validate(_ StepValidateCtx) error

Validate checks this step's kind-specific fields; shared rules run separately.

type DockerStop added in v0.3.4 

type DockerStop struct {
	Container string `json:"container"`
	Rm        bool   `json:"rm,omitempty"`
}

DockerStop configures stopping a running container.

type EffectiveEnvForRunOpts added in v0.2.9 

type EffectiveEnvForRunOpts struct {
	Recipe        *Recipe
	OutputStore   *StepOutputStore
	OutputCapture *RecipeOutputCapture
	KV            KVReader
	DryRun        bool
}

EffectiveEnvForRunOpts carries optional recipe-level context for env merge.

type EnvFromRef added in v0.2.9 

type EnvFromRef struct {
	Step       string            `json:"step,omitempty"`
	FromOutput string            `json:"from_output,omitempty"`
	Map        map[string]string `json:"map,omitempty"`
	Extract    map[string]string `json:"extract,omitempty"`
	Kv         map[string]string `json:"kv,omitempty"`
}

EnvFromRef maps an environment variable from a dependency step's captured output, jq extract, or KV.

type ExecutionMode added in v0.2.9 

type ExecutionMode int

ExecutionMode is how recipe steps are ordered at run time. 

const (
	// ExecutionModeLinear runs steps in array order (default).
	ExecutionModeLinear ExecutionMode = iota
	// ExecutionModeGraph runs steps by id/depends DAG with parallel waves.
	ExecutionModeGraph
)

func RecipeExecutionMode added in v0.2.9 

func RecipeExecutionMode(r Recipe) (ExecutionMode, error)

RecipeExecutionMode returns linear (default) or graph from recipe.type.

type GetStep added in v0.3.5 

type GetStep struct {
	StepBase
	RemoteExec
	Get *RecipeFileTransfer `json:"get,omitempty"`
}

GetStep downloads a remote file to the local machine via SFTP.

func (*GetStep) Clone added in v0.3.5 

func (s *GetStep) Clone() Step

Clone returns a deep copy of the step (safe for loop fan-out mutation).

func (*GetStep) Kind added in v0.3.5 

func (s *GetStep) Kind() string

Kind returns the step kind identifier.

func (*GetStep) Validate added in v0.3.5 

func (s *GetStep) Validate(vc StepValidateCtx) error

Validate checks this step's kind-specific fields; shared rules run separately.

type GraphPlanEdge added in v0.2.9 

type GraphPlanEdge struct {
	From string `json:"from"`
	To   string `json:"to"`
}

GraphPlanEdge is a depends edge between step ids.

type GraphPlanNode added in v0.2.9 

type GraphPlanNode struct {
	Index    int    `json:"index"`
	ID       string `json:"id"`
	Kind     string `json:"kind"`
	Host     string `json:"host"`
	Wave     int    `json:"wave,omitempty"`
	When     string `json:"when,omitempty"`
	Retry    string `json:"retry,omitempty"`
	Notify   bool   `json:"notify,omitempty"`
	KVTunnel bool   `json:"kv_tunnel,omitempty"`
	Preview  string `json:"preview,omitempty"`
}

GraphPlanNode is one step in a recipe graph plan (API / viewer).

type HostStepResult added in v0.2.9 

type HostStepResult struct {
	Succeeded bool
	Skipped   bool
	ExitCode  int
	Stdout    string
}

HostStepResult is the per-host outcome of a completed or skipped step.

type K8sApply added in v0.3.4 

type K8sApply struct {
	Manifest   string `json:"manifest"`
	Force      bool   `json:"force,omitempty"`
	ServerSide bool   `json:"server_side,omitempty"`
}

K8sApply applies a YAML/JSON manifest via server-side apply.

type K8sCreateJob added in v0.3.4 

type K8sCreateJob struct {
	Name          string            `json:"name"`
	Image         string            `json:"image"`
	Command       []string          `json:"command,omitempty"`
	Args          []string          `json:"args,omitempty"`
	Env           map[string]string `json:"env,omitempty"`
	RestartPolicy string            `json:"restart_policy,omitempty"`
	Wait          bool              `json:"wait,omitempty"`
	TTLSeconds    int32             `json:"ttl_seconds,omitempty"`
}

K8sCreateJob creates a batch job and optionally waits for completion.

type K8sDelete added in v0.3.4 

type K8sDelete struct {
	Resource string `json:"resource"`
	Wait     bool   `json:"wait,omitempty"`
}

K8sDelete deletes a resource by kind/name (e.g. "deployment/app").

type K8sExec added in v0.3.4 

type K8sExec struct {
	Pod       string   `json:"pod"`
	Container string   `json:"container,omitempty"`
	Command   []string `json:"command"`
	TTY       bool     `json:"tty,omitempty"`
}

K8sExec runs a command in an existing pod container via the exec subresource.

type K8sGet added in v0.3.4 

type K8sGet struct {
	Resource      string `json:"resource"`
	LabelSelector string `json:"label_selector,omitempty"`
	Format        string `json:"format,omitempty"`
}

K8sGet fetches a resource and writes JSON/YAML to stdout.

type K8sRolloutRestart added in v0.3.4 

type K8sRolloutRestart struct {
	Resource string `json:"resource"`
	Wait     bool   `json:"wait,omitempty"`
}

K8sRolloutRestart triggers a rolling restart by patching the restart annotation.

type K8sScale added in v0.3.4 

type K8sScale struct {
	Resource string `json:"resource"`
	Replicas int32  `json:"replicas"`
}

K8sScale sets replica count on a scalable resource (e.g. "deployment/app").

type K8sStep added in v0.3.5 

type K8sStep struct {
	StepBase
	RemoteExec
	K8s *RecipeStepK8s `json:"k8s,omitempty"`
}

K8sStep performs a Kubernetes API action.

func (*K8sStep) Clone added in v0.3.5 

func (s *K8sStep) Clone() Step

Clone returns a deep copy of the step (safe for loop fan-out mutation).

func (*K8sStep) Kind added in v0.3.5 

func (s *K8sStep) Kind() string

Kind returns the step kind identifier.

func (*K8sStep) Validate added in v0.3.5 

func (s *K8sStep) Validate(vc StepValidateCtx) error

Validate checks this step's kind-specific fields; shared rules run separately.

type K8sWait added in v0.3.4 

type K8sWait struct {
	Resource string `json:"resource"`
	For      string `json:"for"`
	Timeout  string `json:"timeout,omitempty"`
}

K8sWait polls a resource until a condition is met (e.g. "condition=available").

type KVReader added in v0.2.9 

type KVReader interface {
	Get(key string) (value string, found bool, err error)
}

KVReader reads operator-local stepkv keys for CEL kv_get/kv_has.

type OPAStep added in v0.3.6 

type OPAStep struct {
	StepBase
	OPA *RecipeOPA `json:"opa,omitempty"`
}

OPAStep evaluates an OPA/rego policy inline during recipe execution. It runs locally (host must be "_") and fails when the policy denies, so authors can gate later steps via depends / when on this step's success.

func (*OPAStep) Clone added in v0.3.6 

func (s *OPAStep) Clone() Step

Clone returns a deep copy of the step (safe for loop fan-out mutation).

func (*OPAStep) Kind added in v0.3.6 

func (s *OPAStep) Kind() string

Kind returns the step kind identifier.

func (*OPAStep) Validate added in v0.3.6 

func (s *OPAStep) Validate(vc StepValidateCtx) error

Validate checks this step's kind-specific fields; shared rules run separately.

type OpensearchStep added in v0.3.5 

type OpensearchStep struct {
	StepBase
	RemoteExec
	Opensearch *RecipeStepOpensearch `json:"opensearch,omitempty"`
}

OpensearchStep performs an OpenSearch API action.

func (*OpensearchStep) Clone added in v0.3.5 

func (s *OpensearchStep) Clone() Step

Clone returns a deep copy of the step (safe for loop fan-out mutation).

func (*OpensearchStep) Kind added in v0.3.5 

func (s *OpensearchStep) Kind() string

Kind returns the step kind identifier.

func (*OpensearchStep) Validate added in v0.3.5 

func (s *OpensearchStep) Validate(vc StepValidateCtx) error

Validate checks this step's kind-specific fields; shared rules run separately.

type PackageStep added in v0.3.7 

type PackageStep struct {
	StepBase
	RemoteExec
	Package *RecipeStepPackage `json:"package,omitempty"`
}

PackageStep manages system packages.

func (*PackageStep) Clone added in v0.3.7 

func (s *PackageStep) Clone() Step

Clone returns a deep copy of the step.

func (*PackageStep) Kind added in v0.3.7 

func (s *PackageStep) Kind() string

Kind returns the step kind identifier.

func (*PackageStep) Validate added in v0.3.7 

func (s *PackageStep) Validate(vc StepValidateCtx) error

Validate checks this step's kind-specific fields.

type ParseOptions added in v0.2.9 

type ParseOptions struct {
	PluginManager *plugins.Manager
}

ParseOptions configures recipe parsing (optional WASM cue_transform chain).

type PluginStep added in v0.3.5 

type PluginStep struct {
	StepBase
	RemoteExec
	Plugin *RecipeStepPlugin `json:"plugin,omitempty"`
}

PluginStep invokes a WASM custom_step plugin.

func (*PluginStep) Clone added in v0.3.5 

func (s *PluginStep) Clone() Step

Clone returns a deep copy of the step (safe for loop fan-out mutation).

func (*PluginStep) Kind added in v0.3.5 

func (s *PluginStep) Kind() string

Kind returns the step kind identifier.

func (*PluginStep) Validate added in v0.3.5 

func (s *PluginStep) Validate(_ StepValidateCtx) error

Validate checks this step's kind-specific fields; shared rules run separately.

type PostgresStep added in v0.3.5 

type PostgresStep struct {
	StepBase
	RemoteExec
	Postgres *RecipeStepPostgres `json:"postgres,omitempty"`
}

PostgresStep performs a PostgreSQL action.

func (*PostgresStep) Clone added in v0.3.5 

func (s *PostgresStep) Clone() Step

Clone returns a deep copy of the step (safe for loop fan-out mutation).

func (*PostgresStep) Kind added in v0.3.5 

func (s *PostgresStep) Kind() string

Kind returns the step kind identifier.

func (*PostgresStep) Validate added in v0.3.5 

func (s *PostgresStep) Validate(vc StepValidateCtx) error

Validate checks this step's kind-specific fields; shared rules run separately.

type PutStep added in v0.3.5 

type PutStep struct {
	StepBase
	RemoteExec
	Put *RecipeFileTransfer `json:"put,omitempty"`
}

PutStep uploads a local file to remote hosts via SFTP.

func (*PutStep) Clone added in v0.3.5 

func (s *PutStep) Clone() Step

Clone returns a deep copy of the step (safe for loop fan-out mutation).

func (*PutStep) Kind added in v0.3.5 

func (s *PutStep) Kind() string

Kind returns the step kind identifier.

func (*PutStep) Validate added in v0.3.5 

func (s *PutStep) Validate(vc StepValidateCtx) error

Validate checks this step's kind-specific fields; shared rules run separately.

type Recipe 

type Recipe struct {
	Name             string                    `json:"name"`
	Type             string                    `json:"type,omitempty"`
	Webhooks         map[string]RecipeWebhook  `json:"webhooks,omitempty"`
	Schedules        map[string]RecipeSchedule `json:"schedules,omitempty"`
	Notification     *RecipeNotification       `json:"notification,omitempty"`
	Defaults         *RecipeDefaults           `json:"defaults,omitempty"`
	Steps            []StepWrapper             `json:"steps"`
	Handlers         []StepWrapper             `json:"handlers,omitempty"`
	MatrixExpansions map[string][]string       `json:"-"` // internal tracking, not unmarshaled
}

Recipe is the decoded "recipe" block from a CUE document.

func ParseRemoteRecipe 

func ParseRemoteRecipe(cueBytes []byte, records []hosts.Record) (Recipe, error)

ParseRemoteRecipe validates cueBytes and decodes the recipe into Go values.

func ParseRemoteRecipeOpts added in v0.2.9 

func ParseRemoteRecipeOpts(cueBytes []byte, records []hosts.Record, opts ParseOptions) (Recipe, error)

ParseRemoteRecipeOpts is like ParseRemoteRecipe with plugin transforms and prefix-aware secret validation.

func RecipeFromJSON added in v0.2.8 

func RecipeFromJSON(raw []byte) (Recipe, error)

RecipeFromJSON deserializes a canonical (or near-canonical) JSON payload back into a Recipe value. Run cuetry.ValidateRemoteRecipe (or the equivalent per-step validators) after this to ensure the result is well-formed.

func (Recipe) CanonicalJSON added in v0.3.6 

func (r Recipe) CanonicalJSON() ([]byte, error)

CanonicalJSON returns deterministic JSON (sorted keys, no extra whitespace) for the given Recipe. Two Recipes that resolve to the same plan produce the same bytes here.

func (Recipe) HashJSON added in v0.3.6 

func (r Recipe) HashJSON() (string, error)

HashJSON returns "sha256:" + hex(sha256(r.CanonicalJSON())). Used to compare a recording's recipe to a disk recipe and decide "edited?".

func (Recipe) PromptDefs added in v0.3.6 

func (r Recipe) PromptDefs() map[string]RecipePrompt

PromptDefs returns the recipe's prompt definitions, or nil when unset. Safe to call on a zero-value Recipe.

type RecipeAI added in v0.2.8 

type RecipeAI struct {
	Prompt          string `json:"prompt"`
	SystemPrompt    string `json:"system_prompt,omitempty"`
	Model           string `json:"model,omitempty"`
	MaxOutputTokens int    `json:"max_output_tokens,omitempty"`
	MaxInputChars   int    `json:"max_input_chars,omitempty"`
}

RecipeAI configures a plain, freely-positionable local LLM-completion step (host must be "_").

type RecipeAgentTransfer added in v0.2.8 

type RecipeAgentTransfer struct {
	DestHost        string                    `json:"dest_host"`
	SourcePath      string                    `json:"source_path"`
	DestPath        string                    `json:"dest_path"`
	Cloud           *RecipeAgentTransferCloud `json:"cloud"`
	CloudBackendRef *RecipeCloudBackendRef    `json:"cloud_backend_ref,omitempty"`
	KeepObject      bool                      `json:"keep_object,omitempty"`
	MaxRetries      int                       `json:"max_retries,omitempty"`
	AgentRemoteDir  string                    `json:"agent_remote_dir,omitempty"`
}

RecipeAgentTransfer is source host (top-level host) → cloud → destination (dest_host), same flow as the web UI.

type RecipeAgentTransferCloud added in v0.2.8 

type RecipeAgentTransferCloud struct {
	Provider string `json:"provider"`
	Bucket   string `json:"bucket"`
	Prefix   string `json:"prefix,omitempty"`
	Object   string `json:"object,omitempty"`
	Region   string `json:"region,omitempty"`
	Endpoint string `json:"endpoint,omitempty"`
}

RecipeAgentTransferCloud is the staging object location (S3/GCS, etc.).

type RecipeCloudBackendRef added in v0.2.8 

type RecipeCloudBackendRef struct {
	Kind  string `json:"kind"`
	Name  string `json:"name,omitempty"`
	Index *int   `json:"index,omitempty"`
}

RecipeCloudBackendRef selects a backend entry from honey YAML for signing hints (AWS profile, GCP project).

type RecipeDefaults 

type RecipeDefaults struct {
	RunAs         string                  `json:"run_as,omitempty"`
	Env           map[string]string       `json:"env,omitempty"`
	Secrets       map[string]RecipeSecret `json:"secrets,omitempty"`
	Prompts       map[string]RecipePrompt `json:"prompts,omitempty"`
	K8sDebugImage string                  `json:"k8s_debug_image,omitempty"`
	KVTunnel      *bool                   `json:"kv_tunnel,omitempty"`
	MaxParallel   int                     `json:"max_parallel,omitempty"`
	SSHPort       int                     `json:"ssh_port,omitempty"`
	SSHPrivateKey string                  `json:"ssh_private_key,omitempty"`
	Retry         *RecipeStepRetry        `json:"retry,omitempty"`
	GatherFacts   *bool                   `json:"gather_facts,omitempty"`
}

RecipeDefaults holds recipe-level defaults (optional fields).

type RecipeEmailNotification added in v0.3.6 

type RecipeEmailNotification struct {
	SendOn    *RecipeMailOn     `json:"send_on,omitempty"`
	OnSuccess *RecipeMailConfig `json:"on_success,omitempty"`
	OnFailure *RecipeMailConfig `json:"on_failure,omitempty"`
}

RecipeEmailNotification configures email alerts for successes and failures.

type RecipeFileTransfer 

type RecipeFileTransfer struct {
	Local  string `json:"local"`
	Remote string `json:"remote"`
}

RecipeFileTransfer is a local ↔ remote path pair for SFTP put/get steps.

type RecipeGraphPlan added in v0.2.9 

type RecipeGraphPlan struct {
	Type    string            `json:"type"`
	Waves   [][]GraphPlanNode `json:"waves,omitempty"`
	Nodes   []GraphPlanNode   `json:"nodes"`
	Edges   []GraphPlanEdge   `json:"edges"`
	Mermaid string            `json:"mermaid,omitempty"`
}

RecipeGraphPlan is a structured DAG view of a graph recipe.

func BuildRecipeGraphPlan added in v0.2.9 

func BuildRecipeGraphPlan(r Recipe) (*RecipeGraphPlan, error)

BuildRecipeGraphPlan builds a graph plan from a validated graph recipe.

type RecipeLoop added in v0.3.4 

type RecipeLoop struct {
	Step    string `json:"step"`
	Extract string `json:"extract"` // jq expression to extract a JSON array
}

RecipeLoop configures dynamic runtime fan-out based on a previous step's captured output.

type RecipeMailConfig added in v0.3.6 

type RecipeMailConfig struct {
	From       string   `json:"from"`
	To         []string `json:"to"`
	Prefix     string   `json:"prefix,omitempty"`
	AttachLogs bool     `json:"attach_logs,omitempty"`
}

RecipeMailConfig defines the email template and recipients.

type RecipeMailOn added in v0.3.6 

type RecipeMailOn struct {
	Success bool `json:"success,omitempty"`
	Failure bool `json:"failure,omitempty"`
}

RecipeMailOn defines conditions under which emails are sent at the end of a run.

type RecipeNotification added in v0.3.6 

type RecipeNotification struct {
	Email *RecipeEmailNotification `json:"email,omitempty"`
}

RecipeNotification defines the notification routing configuration for a recipe.

type RecipeNotify added in v0.2.8 

type RecipeNotify struct {
	NotifySubject string                `json:"notify_subject,omitempty"`
	Message       string                `json:"message,omitempty"`
	Services      *RecipeNotifyServices `json:"services,omitempty"`
}

RecipeNotify is optional per-step notification (env receivers). A present `notify` object in CUE means enabled, even if empty.

type RecipeNotifyHTTP added in v0.2.8 

type RecipeNotifyHTTP struct{}

RecipeNotifyHTTP marks HTTP default JSON POST URLs (HONEY_NOTIFY_HTTP_URL) as selected in notify.services.

type RecipeNotifyServices added in v0.2.8 

type RecipeNotifyServices struct {
	HTTP     *RecipeNotifyHTTP     `json:"http,omitempty"`
	Slack    *RecipeNotifySlack    `json:"slack,omitempty"`
	Telegram *RecipeNotifyTelegram `json:"telegram,omitempty"`
}

RecipeNotifyServices selects notifier backends when non-nil (allowlist). Omitted keys are off for this step.

type RecipeNotifySlack added in v0.2.8 

type RecipeNotifySlack struct {
	ChannelID string `json:"channel_id,omitempty"`
}

RecipeNotifySlack marks Slack incoming webhook (HONEY_NOTIFY_SLACK_WEBHOOK_URL); optional channel_id overrides payload channel.

type RecipeNotifyTelegram added in v0.2.8 

type RecipeNotifyTelegram struct{}

RecipeNotifyTelegram marks Telegram (bot token + chat IDs from env).

type RecipeOPA added in v0.3.6 

type RecipeOPA struct {
	// Policy is a path to a .rego file (package honey), relative to the recipe
	// directory unless absolute.
	Policy string `json:"policy"`
	// Input is an arbitrary object merged into the OPA input document under the
	// caller-supplied keys, alongside the built-in actor and recipe fields.
	Input map[string]any `json:"input,omitempty"`
}

RecipeOPA is the opa step's action block: which policy to load and what extra input to pass alongside the actor identity.

type RecipeOutputCapture added in v0.3.0 

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

RecipeOutputCapture holds rendered stdout keyed by template.output capture names.

func NewRecipeOutputCapture added in v0.3.0 

func NewRecipeOutputCapture() *RecipeOutputCapture

NewRecipeOutputCapture creates an empty capture registry.

func (*RecipeOutputCapture) All added in v0.3.0 

func (c *RecipeOutputCapture) All() map[string]string

All returns a copy of all capture name → stdout mappings.

func (*RecipeOutputCapture) Get added in v0.3.0 

func (c *RecipeOutputCapture) Get(name string) (string, bool)

Get returns captured stdout for name.

func (*RecipeOutputCapture) Set added in v0.3.0 

func (c *RecipeOutputCapture) Set(name, stdout string)

Set stores trimmed stdout for a capture name.

func (*RecipeOutputCapture) View added in v0.3.4 

func (c *RecipeOutputCapture) View() map[string]any

View returns template/CEL-friendly named output metadata.

type RecipePluginHook added in v0.2.9 

type RecipePluginHook struct {
	ID     string          `json:"id"`
	Action string          `json:"action"`
	Config json.RawMessage `json:"config,omitempty"`
}

RecipePluginHook configures a WASM plugin for a local hook (xor with command).

type RecipePrompt added in v0.3.6 

type RecipePrompt struct {
	Description     string   `json:"description,omitempty"`
	Type            string   `json:"type,omitempty"`
	Required        bool     `json:"required,omitempty"`
	Choices         []string `json:"choices,omitempty"`
	ChoicesURL      string   `json:"choices_url,omitempty"`
	ChoicesJSONPath string   `json:"choices_json_path,omitempty"`
	Default         string   `json:"default,omitempty"`
	Multi           bool     `json:"multi,omitempty"`
	Regex           string   `json:"regex,omitempty"`
}

RecipePrompt defines metadata for UI form generation.

type RecipeSchedule added in v0.3.6 

type RecipeSchedule struct {
	Cron     string            `json:"cron"`               // 5-field cron expression, e.g. "0 2 * * *"
	TimeZone string            `json:"timezone,omitempty"` // IANA tz name, e.g. "America/New_York"; defaults to UTC
	Env      map[string]string `json:"env,omitempty"`      // static env vars injected at execution time
}

RecipeSchedule defines a cron-based trigger for a recipe.

type RecipeSecret added in v0.3.7 

type RecipeSecret struct {
	Ref   string             `json:"-"`
	Vault *RecipeSecretVault `json:"vault,omitempty"`
	Aws   *RecipeSecretAws   `json:"aws,omitempty"`
	Gcp   *RecipeSecretGcp   `json:"gcp,omitempty"`
}

RecipeSecret provides a polymorphic way to specify a secret ref as a string or via a backend-specific struct.

func (*RecipeSecret) MarshalJSON added in v0.3.7 

func (rs *RecipeSecret) MarshalJSON() ([]byte, error)

MarshalJSON marshals back to a string ref if provided, or the structured object.

func (*RecipeSecret) StringRef added in v0.3.7 

func (rs *RecipeSecret) StringRef() string

StringRef compiles the struct representation into a standard honey secure URI ref.

func (*RecipeSecret) UnmarshalJSON added in v0.3.7 

func (rs *RecipeSecret) UnmarshalJSON(data []byte) error

UnmarshalJSON unmarshals either a string ref or a structured secret object.

type RecipeSecretAws added in v0.3.7 

type RecipeSecretAws struct {
	SecretID string `json:"secret_id"`
	Version  string `json:"version,omitempty"`
	Key      string `json:"key,omitempty"`
}

RecipeSecretAws configures an AWS Secrets Manager secret resolution.

type RecipeSecretGcp added in v0.3.7 

type RecipeSecretGcp struct {
	Project string `json:"project,omitempty"`
	Secret  string `json:"secret"`
	Version string `json:"version,omitempty"`
	Key     string `json:"key,omitempty"`
}

RecipeSecretGcp configures a GCP Secret Manager secret resolution.

type RecipeSecretVault added in v0.3.7 

type RecipeSecretVault struct {
	Path string `json:"path"`
	Key  string `json:"key,omitempty"`
}

RecipeSecretVault configures a Vault secret resolution.

type RecipeStep 

type RecipeStep struct {
	StepBase
	Recipe *RecipeSubRecipe `json:"recipe,omitempty"`
}

RecipeStep executes another recipe as a sub-recipe.

func (*RecipeStep) Clone added in v0.3.6 

func (s *RecipeStep) Clone() Step

Clone returns a deep copy of the step (safe for loop fan-out mutation).

func (*RecipeStep) Kind added in v0.3.6 

func (s *RecipeStep) Kind() string

Kind returns the step kind identifier.

func (*RecipeStep) Validate added in v0.3.6 

func (s *RecipeStep) Validate(vc StepValidateCtx) error

Validate checks this step's kind-specific fields; shared rules run separately.

type RecipeStepDocker added in v0.3.4 

type RecipeStepDocker struct {
	Socket string       `json:"socket,omitempty"`
	Action string       `json:"action"`
	Output string       `json:"output,omitempty"`
	Build  *DockerBuild `json:"build,omitempty"`
	Push   *DockerPush  `json:"push,omitempty"`
	Pull   *DockerPull  `json:"pull,omitempty"`
	Run    *DockerRun   `json:"run,omitempty"`
	Exec   *DockerExec  `json:"exec,omitempty"`
	Stop   *DockerStop  `json:"stop,omitempty"`
}

RecipeStepDocker configures a Docker engine API step.

type RecipeStepHook added in v0.2.8 

type RecipeStepHook struct {
	Where   string                  `json:"where"`
	Command string                  `json:"command,omitempty"`
	Plugin  *RecipePluginHook       `json:"plugin,omitempty"`
	RunAs   string                  `json:"run_as,omitempty"`
	Env     map[string]string       `json:"env,omitempty"`
	Secrets map[string]RecipeSecret `json:"secrets,omitempty"`
	Notify  *RecipeNotify           `json:"notify,omitempty"`
}

RecipeStepHook runs once per target host after that host's main step result is known.

type RecipeStepHooks added in v0.2.8 

type RecipeStepHooks struct {
	OnSuccess *RecipeStepHook `json:"on_success,omitempty"`
	OnFailure *RecipeStepHook `json:"on_failure,omitempty"`
}

RecipeStepHooks configures optional per-host hooks after the main step outcome (command/script only).

type RecipeStepK8s added in v0.3.4 

type RecipeStepK8s struct {
	Namespace      string             `json:"namespace,omitempty"`
	Output         string             `json:"output,omitempty"`
	Apply          *K8sApply          `json:"apply,omitempty"`
	Delete         *K8sDelete         `json:"delete,omitempty"`
	Scale          *K8sScale          `json:"scale,omitempty"`
	RolloutRestart *K8sRolloutRestart `json:"rollout_restart,omitempty"`
	Wait           *K8sWait           `json:"wait,omitempty"`
	Get            *K8sGet            `json:"get,omitempty"`
	Exec           *K8sExec           `json:"exec,omitempty"`
	CreateJob      *K8sCreateJob      `json:"create_job,omitempty"`
}

RecipeStepK8s configures a Kubernetes API step. Exactly one action field (Apply/Delete/Scale/RolloutRestart/Wait/Get/Exec/CreateJob) must be set. Output, when non-empty, stores the action result in RecipeOutputCapture for downstream env_from.

type RecipeStepOpensearch added in v0.3.4 

type RecipeStepOpensearch struct {
	Addresses []string       `json:"addresses,omitempty"`
	Username  string         `json:"username,omitempty"`
	Password  string         `json:"password,omitempty"`
	APIKey    string         `json:"api_key,omitempty"`
	Insecure  bool           `json:"insecure,omitempty"`
	Index     string         `json:"index"`
	Action    string         `json:"action"` // "get", "search", "index"
	DocID     string         `json:"doc_id,omitempty"`
	Body      map[string]any `json:"body,omitempty"`
	Output    string         `json:"output,omitempty"`
}

RecipeStepOpensearch configures an OpenSearch engine API step.

type RecipeStepPackage added in v0.3.7 

type RecipeStepPackage struct {
	Name  string `json:"name"`
	State string `json:"state"` // "present", "absent", "latest"
}

RecipeStepPackage configures a package management step.

type RecipeStepPlugin added in v0.2.9 

type RecipeStepPlugin struct {
	ID           string          `json:"id"`
	Action       string          `json:"action"`
	Config       json.RawMessage `json:"config,omitempty"`
	KVKey        string          `json:"kv_key,omitempty"`
	KVKeyPerHost bool            `json:"kv_key_per_host,omitempty"`
}

RecipeStepPlugin configures a custom_step plugin action (wasm or docker runtime).

type RecipeStepPostgres added in v0.3.4 

type RecipeStepPostgres struct {
	DSNSecret     string            `json:"dsn_secret"`
	Action        string            `json:"action"` // "query", "exec", "migrate"
	SQL           string            `json:"sql,omitempty"`
	Params        json.RawMessage   `json:"params,omitempty"`
	TimeoutMS     int               `json:"timeout_ms,omitempty"`
	Readonly      *bool             `json:"readonly,omitempty"`
	KVKey         string            `json:"kv_key,omitempty"`
	KVKeyPerHost  bool              `json:"kv_key_per_host,omitempty"`
	Extract       map[string]string `json:"extract,omitempty"`
	Host          string            `json:"host,omitempty"`
	Port          string            `json:"port,omitempty"`
	TunnelStep    string            `json:"tunnel_step,omitempty"`
	MigrationsDir string            `json:"migrations_dir,omitempty"`
	Files         []string          `json:"files,omitempty"`
	Output        string            `json:"output,omitempty"`
}

RecipeStepPostgres configures a PostgreSQL engine API step.

type RecipeStepRetry added in v0.3.0 

type RecipeStepRetry struct {
	Attempts   int    `json:"attempts,omitempty"`
	DelayMS    int    `json:"delay_ms,omitempty"`
	MaxDelayMS int    `json:"max_delay_ms,omitempty"`
	Backoff    string `json:"backoff,omitempty"`
}

RecipeStepRetry configures per-step retry for remote actions.

func EffectiveRetry added in v0.3.0 

func EffectiveRetry(step *StepBase, defaults *RecipeDefaults) RecipeStepRetry

EffectiveRetry merges step and recipe defaults; applies defaults when a retry block is present.

func (RecipeStepRetry) Enabled added in v0.3.0 

func (r RecipeStepRetry) Enabled() bool

Enabled reports whether step retry is active (more than one total attempt).

type RecipeStepService added in v0.3.7 

type RecipeStepService struct {
	Name    string `json:"name"`
	State   string `json:"state"`             // "started", "stopped", "restarted", "reloaded", "status"
	Enabled *bool  `json:"enabled,omitempty"` // enable/disable on boot
}

RecipeStepService configures a service management step.

type RecipeStepTemplate added in v0.3.0 

type RecipeStepTemplate struct {
	Template string         `json:"template"`
	Data     map[string]any `json:"data,omitempty"`
	Output   string         `json:"output,omitempty"`
}

RecipeStepTemplate configures a local Go text/template render step (host must be "_").

type RecipeStepTunnel added in v0.3.0 

type RecipeStepTunnel struct {
	Mode           string            `json:"mode,omitempty" jsonschema:"default=local"`
	RemoteHost     string            `json:"remote_host,omitempty"`
	RemotePort     int               `json:"remote_port,omitempty"`
	LocalPort      int               `json:"local_port,omitempty"`
	Bind           string            `json:"bind,omitempty"`
	RemoteBind     string            `json:"remote_bind,omitempty"`
	RemoteListen   int               `json:"remote_listen_port,omitempty"`
	LocalHost      string            `json:"local_host,omitempty"`
	LocalTarget    int               `json:"local_target_port,omitempty"`
	UseSSHConfig   bool              `json:"use_ssh_config,omitempty"`
	SSHConfigMatch string            `json:"ssh_config_match,omitempty"`
	SSHConfigEnv   map[string]string `json:"ssh_config_env,omitempty"`
	ShareKey       string            `json:"share_key,omitempty"`
	Protocol       string            `json:"protocol,omitempty" jsonschema:"default=tcp"`
	TunLocal       int               `json:"tun_local,omitempty"`
	TunRemote      int               `json:"tun_remote,omitempty"`
	RemoteSocat    bool              `json:"remote_socat,omitempty"`
}

RecipeStepTunnel configures an operator-side port forward for a recipe step.

type RecipeSubRecipe added in v0.3.6 

type RecipeSubRecipe struct {
	Path    string            `json:"path"`
	Prompts map[string]string `json:"prompts,omitempty"`
}

RecipeSubRecipe configures a step that invokes another recipe.

type RecipeSummarize added in v0.3.7 

type RecipeSummarize struct {
	Prompt          string `json:"prompt"`
	SystemPrompt    string `json:"system_prompt,omitempty"`
	Model           string `json:"model,omitempty"`
	MaxOutputTokens int    `json:"max_output_tokens,omitempty"`
	MaxInputChars   int    `json:"max_input_chars,omitempty"`
}

RecipeSummarize configures the terminal local LLM summarizer step (must be last in recipe; host must be "_").

func (*RecipeSummarize) ResolveSystemPrompt added in v0.3.7 

func (s *RecipeSummarize) ResolveSystemPrompt(configDefault string) string

ResolveSystemPrompt returns the system message for a recipe summarize step. Precedence: non-empty summarize.system_prompt in CUE, then config defaults.ai_system_prompt, then built-in default.

type RecipeWebhook added in v0.3.6 

type RecipeWebhook struct {
	AuthSecret string `json:"auth_secret,omitempty"`
	// Actor is a gjson path into the webhook payload whose value becomes the OPA
	// actor (e.g. "sender.login"). Lower priority than a trusted header / JWT.
	Actor          string            `json:"actor,omitempty"`
	Extract        map[string]string `json:"extract,omitempty"`
	Async          *bool             `json:"async,omitempty"`
	IdempotencyKey string            `json:"idempotency_key,omitempty"`
	IdempotencyTTL string            `json:"idempotency_ttl,omitempty"`
}

RecipeWebhook defines a webhook trigger for a recipe.

type RemoteExec added in v0.3.5 

type RemoteExec struct {
	SSHPort       int    `json:"ssh_port,omitempty" jsonschema:"default=22"`
	SSHPrivateKey string `json:"ssh_private_key,omitempty"`
	MaxParallel   int    `json:"max_parallel,omitempty" jsonschema:"default=0"`
	Serial        int    `json:"serial,omitempty"`
}

RemoteExec holds SSH / fan-out options for steps that target remote hosts.

func (*RemoteExec) EffectiveMaxParallel added in v0.3.6 

func (r *RemoteExec) EffectiveMaxParallel(defaults *RecipeDefaults) int

EffectiveMaxParallel returns host-level parallelism for a step (SSH/SFTP batch). Step max_parallel overrides defaults; zero means caller should use its package default (32).

func (*RemoteExec) Remote added in v0.3.5 

func (r *RemoteExec) Remote() *RemoteExec

Remote lets a *RemoteExec (and thus every embedding remote step) satisfy RemoteStep.

type RemoteStep added in v0.3.5 

type RemoteStep interface {
	Step
	Remote() *RemoteExec
}

RemoteStep is implemented by steps that run against remote hosts and therefore carry SSH / fan-out options. Template and AI steps (local-only) do not implement it.

type RenderLoopTemplateOpts added in v0.3.4 

type RenderLoopTemplateOpts struct {
	Template string
	Store    *StepResultStore
	Capture  *RecipeOutputCapture
}

RenderLoopTemplateOpts configures dynamic loop item rendering.

type RenderTemplateOpts added in v0.3.0 

type RenderTemplateOpts struct {
	Template string
	Data     map[string]any
	KV       KVReader
	Funcs    template.FuncMap
}

RenderTemplateOpts configures a template render.

type ResultExprContext added in v0.3.4 

type ResultExprContext struct {
	Stdout    string
	Stderr    string
	ExitCode  int
	Succeeded bool
	Changed   bool
	Host      map[string]any
	Facts     map[string]any
	Steps     map[string]StepView
	Outputs   map[string]any
	Item      string
}

ResultExprContext is the CEL-facing context for one step result.

type ResultExprProgram added in v0.3.4 

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

ResultExprProgram is a compiled changed_when / failed_when expression.

func CompileResultBoolExpr added in v0.3.4 

func CompileResultBoolExpr(expr string) (*ResultExprProgram, error)

CompileResultBoolExpr validates and compiles a result override expression.

func (*ResultExprProgram) Eval added in v0.3.4 

func (p *ResultExprProgram) Eval(ctx ResultExprContext) (bool, error)

Eval evaluates a compiled result expression.

type RiskReport added in v0.3.6 

type RiskReport struct {
	Score    int      `json:"score"`
	Level    string   `json:"level"`
	Findings []string `json:"findings"`
}

RiskReport represents a summary of destructive or high concurrency operations.

func AnalyzeRecipeRisk added in v0.3.6 

func AnalyzeRecipeRisk(r Recipe) RiskReport

AnalyzeRecipeRisk computes a risk score and extracts findings of dangerous steps.

type ScriptStep added in v0.3.5 

type ScriptStep struct {
	StepBase
	RemoteExec
	Script      *RecipeFileTransfer `json:"script,omitempty"`
	Interpreter string              `json:"interpreter,omitempty"`
	Templated   bool                `json:"templated,omitempty"`
}

ScriptStep uploads a local script and executes it on remote hosts.

func (*ScriptStep) Clone added in v0.3.5 

func (s *ScriptStep) Clone() Step

Clone returns a deep copy of the step (safe for loop fan-out mutation).

func (*ScriptStep) Kind added in v0.3.5 

func (s *ScriptStep) Kind() string

Kind returns the step kind identifier.

func (*ScriptStep) Validate added in v0.3.5 

func (s *ScriptStep) Validate(_ StepValidateCtx) error

Validate checks this step's kind-specific fields; shared rules run separately. Templated is not syntax-checked here (unlike CommandStep): the rendered body is the local script *file's content*, not a field available at recipe-parse time — a bad template only surfaces at render/execute time.

type SecretResolver added in v0.2.9 

type SecretResolver interface {
	Handles(ref string) bool
	Resolve(ctx context.Context, ref string) (string, error)
}

SecretResolver resolves recipe secret refs (secure:v1:…) to plaintext at execute time.

func NewSecretResolver added in v0.2.9 

func NewSecretResolver(opts SecretResolverOptions) (SecretResolver, error)

NewSecretResolver builds the default resolver for recipe execution.

func NewSecretResolverWithPlugins added in v0.2.9 

func NewSecretResolverWithPlugins(opts SecretResolverOptions, mgr *plugins.Manager) (SecretResolver, error)

NewSecretResolverWithPlugins appends WASM plugin secret backends when mgr is non-nil.

type SecretResolverOptions added in v0.2.9 

type SecretResolverOptions struct {
	SymmetricDataKey []byte
	SecretsProvider  string
	EncryptedKey     string
	AgeIdentityFile  string
}

SecretResolverOptions configures the default secret resolver.

func SecretResolverOptionsFromHoney added in v0.2.9 

func SecretResolverOptionsFromHoney(cfg *config.File) SecretResolverOptions

SecretResolverOptionsFromHoney maps honey YAML defaults into resolver options.

type ServiceStep added in v0.3.7 

type ServiceStep struct {
	StepBase
	RemoteExec
	Service *RecipeStepService `json:"service,omitempty"`
}

ServiceStep manages system services.

func (*ServiceStep) Clone added in v0.3.7 

func (s *ServiceStep) Clone() Step

Clone returns a deep copy of the step.

func (*ServiceStep) Kind added in v0.3.7 

func (s *ServiceStep) Kind() string

Kind returns the step kind identifier.

func (*ServiceStep) Validate added in v0.3.7 

func (s *ServiceStep) Validate(vc StepValidateCtx) error

Validate checks this step's kind-specific fields.

type StaticSecretResolver added in v0.3.6 

type StaticSecretResolver map[string]string

StaticSecretResolver provides a static map of secrets for testing and simple use cases.

func (StaticSecretResolver) Handles added in v0.3.6 

func (m StaticSecretResolver) Handles(ref string) bool

Handles returns true if the reference exists in the static map.

func (StaticSecretResolver) Resolve added in v0.3.6 

func (m StaticSecretResolver) Resolve(_ context.Context, ref string) (string, error)

Resolve returns the value from the static map if it exists.

type Step added in v0.3.5 

type Step interface {
	Kind() string
	Base() *StepBase
	Clone() Step
	Validate(vc StepValidateCtx) error
}

Step is one recipe action (command, template, postgres, …). Concrete types embed StepBase (cross-cutting fields) and, for remotely-executed kinds, RemoteExec.

The interface is intentionally small: identity (Kind), shared-field access (Base), deep-copy for loop fan-out (Clone), and self-validation. Execution lives in internal/ui behind its own registry — a method here would create an import cycle (internal/ui imports internal/cuetry, not the reverse).

type StepBase added in v0.3.5 

type StepBase struct {
	ID            string                  `json:"id,omitempty"`
	Depends       []string                `json:"depends,omitempty"`
	Host          string                  `json:"host" jsonschema:"default=*"`
	Env           map[string]string       `json:"env,omitempty"`
	Secrets       map[string]RecipeSecret `json:"secrets,omitempty"`
	EnvFrom       []EnvFromRef            `json:"env_from,omitempty"`
	RunAs         string                  `json:"run_as,omitempty"`
	When          string                  `json:"when,omitempty"`
	ChangedWhen   string                  `json:"changed_when,omitempty"`
	FailedWhen    string                  `json:"failed_when,omitempty"`
	Retry         *RecipeStepRetry        `json:"retry,omitempty"`
	Timeout       string                  `json:"timeout,omitempty"`
	IgnoreErrors  bool                    `json:"ignore_errors,omitempty" jsonschema:"default=false"`
	CheckCmd      string                  `json:"check_cmd,omitempty"`
	Output        string                  `json:"output,omitempty"`
	Loop          string                  `json:"loop,omitempty"`
	LoopFrom      *RecipeLoop             `json:"loop_from,omitempty"`
	Reduce        string                  `json:"reduce,omitempty"`
	Notify        *RecipeNotify           `json:"notify,omitempty"`
	Hooks         *RecipeStepHooks        `json:"hooks,omitempty"`
	NotifyHandler []string                `json:"notify_handler,omitempty"`
	KVTunnel      *bool                   `json:"kv_tunnel,omitempty" jsonschema:"default=false"`
	Matrix        map[string][]string     `json:"matrix,omitempty"`
	Assert        []Assertion             `json:"assert,omitempty"`
	TriggerRule   string                  `json:"trigger_rule,omitempty" jsonschema:"default=all_success"`
	Rescue        []string                `json:"rescue,omitempty"`
}

StepBase holds the cross-cutting fields shared by every step kind. It is embedded (anonymously) by each concrete step, so these fields flatten into the step's JSON.

func (*StepBase) Base added in v0.3.5 

func (b *StepBase) Base() *StepBase

Base lets a *StepBase (and thus every embedding step) satisfy the shared part of Step.

func (*StepBase) NotifyEnabled added in v0.3.5 

func (b *StepBase) NotifyEnabled() bool

NotifyEnabled reports whether the recipe author included a notify block (including notify: {}).

type StepGraph added in v0.2.9 

type StepGraph struct {
	IDToIndex      map[string]int
	IndexToID      []string
	Depends        [][]int // step index -> dependency indices
	Children       [][]int // reverse edges
	TopoOrder      []int
	Waves          [][]int
	SummarizeIndex int // >=0 when recipe has a summarize step
}

StepGraph is a validated DAG over recipe steps (graph mode only).

func BuildStepGraph added in v0.2.9 

func BuildStepGraph(steps []StepWrapper) (*StepGraph, error)

BuildStepGraph validates ids and depends, detects cycles, and computes topo order and waves.

func BuildStepGraphFromRecipe added in v0.2.9 

func BuildStepGraphFromRecipe(r *Recipe) (*StepGraph, error)

BuildStepGraphFromRecipe builds the step graph when mode is graph.

func (*StepGraph) AncestorHistoryOrder added in v0.2.9 

func (sg *StepGraph) AncestorHistoryOrder(aiIndex int, succeeded map[int]bool) []int

AncestorHistoryOrder returns succeeded step indices in topological order for ai transcript.

func (*StepGraph) MarkSkippedDescendants added in v0.2.9 

func (sg *StepGraph) MarkSkippedDescendants(from int, state []StepRunState)

MarkSkippedDescendants marks all transitive children of from as skipped in state.

type StepOutputStore added in v0.2.9 

type StepOutputStore = StepResultStore

StepOutputStore is the historical name for StepResultStore.

type StepResultStore added in v0.2.9 

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

StepResultStore holds per-step per-host results (stdout, success, skip, exit code).

func NewStepOutputStore added in v0.2.9 

func NewStepOutputStore() *StepResultStore

NewStepOutputStore is an alias for backward compatibility with env_from capture.

func NewStepResultStore added in v0.2.9 

func NewStepResultStore() *StepResultStore

NewStepResultStore creates an empty result store.

func (*StepResultStore) FirstStdout added in v0.3.0 

func (s *StepResultStore) FirstStdout(stepID string) (string, bool)

FirstStdout returns the first non-empty stdout captured for stepID across any host.

func (*StepResultStore) Get added in v0.2.9 

func (s *StepResultStore) Get(stepID, hostName string) (string, bool)

Get returns captured stdout for stepID and hostName.

func (*StepResultStore) HostResult added in v0.2.9 

func (s *StepResultStore) HostResult(stepID, hostName string) (HostStepResult, bool)

HostResult returns the full result for stepID and hostName.

func (*StepResultStore) Record added in v0.2.9 

func (s *StepResultStore) Record(stepID, hostName, stdout string)

Record stores trimmed stdout for a host after a successful capture step.

func (*StepResultStore) RecordHost added in v0.2.9 

func (s *StepResultStore) RecordHost(stepID, hostName string, r HostStepResult)

RecordHost stores a full host result for a step id.

func (*StepResultStore) StepsTemplateData added in v0.3.4 

func (s *StepResultStore) StepsTemplateData() map[string]any

StepsTemplateData builds a template-facing aggregate view of prior step results.

func (*StepResultStore) StepsViewAggregated added in v0.2.9 

func (s *StepResultStore) StepsViewAggregated() map[string]StepView

StepsViewAggregated builds a per-step view across all hosts (any succeeded, first stdout).

func (*StepResultStore) StepsViewForHost added in v0.2.9 

func (s *StepResultStore) StepsViewForHost(hostName string) map[string]StepView

StepsViewForHost builds the steps map for CEL for one host name.

type StepRunState added in v0.2.9 

type StepRunState int

StepRunState is the scheduler state for one step in graph mode. 

const (
	// StepRunPending means dependencies are not yet satisfied.
	StepRunPending StepRunState = iota
	// StepRunReady means the step may be scheduled.
	StepRunReady
	// StepRunRunning means the step is executing.
	StepRunRunning
	// StepRunSucceeded means the step completed without fatal failure.
	StepRunSucceeded
	// StepRunFailed means the step failed or all hosts had transient SSH errors.
	StepRunFailed
	// StepRunSkipped means a dependency failed and this step was not run.
	StepRunSkipped
)

type StepSummary added in v0.2.8 

type StepSummary struct {
	Index   int      `json:"index"`
	ID      string   `json:"id,omitempty"`
	Depends []string `json:"depends,omitempty"`
	Wave    int      `json:"wave,omitempty"`
	Kind    string   `json:"kind"`
	Host    string   `json:"host"`
	RunAs   string   `json:"run_as,omitempty"`
	When    string   `json:"when,omitempty"`
	Retry   string   `json:"retry,omitempty"`
	Notify  bool     `json:"notify,omitempty"`
	Preview string   `json:"preview"`
}

StepSummary is a host-agnostic one-line summary of a recipe step. It backs the wizard's Plan view and any other UI that wants a per-step digest without resolving target hosts.

func RenderDryRunPlan added in v0.2.8 

func RenderDryRunPlan(r Recipe) (string, []StepSummary, error)

RenderDryRunPlan returns a host-agnostic plan summary for r: one line per step plus a structured per-step list. It does not expand step.host against records, so callers can validate Recipe structure before any host resolution. The line format mirrors the per-target dry-run text in internal/ui — same "step N: kind=… host=… run_as=… preview=…" shape, minus per-host detail.

type StepValidateCtx added in v0.3.5 

type StepValidateCtx struct {
	Index          int
	NumSteps       int
	Defaults       *RecipeDefaults
	Records        []hosts.Record
	SecretPrefixes []string
	Mode           ExecutionMode
}

StepValidateCtx carries everything the per-step validators need. It replaces the long positional parameter list of the old validateDecodedRecipeStep.

type StepView added in v0.2.9 

type StepView struct {
	Succeeded bool
	Skipped   bool
	Stdout    string
	ExitCode  int
}

StepView is the CEL-facing view of a prior step for one host.

type StepWrapper added in v0.3.5 

type StepWrapper struct {
	Step Step
}

StepWrapper is the polymorphic JSON boundary: it decodes a raw step object into the correct concrete Step by inspecting which action key is present.

func (StepWrapper) MarshalJSON added in v0.3.5 

func (w StepWrapper) MarshalJSON() ([]byte, error)

MarshalJSON emits the underlying concrete step (flattened base + action fields).

func (*StepWrapper) UnmarshalJSON added in v0.3.5 

func (w *StepWrapper) UnmarshalJSON(data []byte) error

UnmarshalJSON inspects the raw object's top-level keys, finds the single matching action key in the registry, constructs the concrete step, and decodes into it.

type SummarizeStep added in v0.3.7 

type SummarizeStep struct {
	StepBase
	Summarize *RecipeSummarize `json:"summarize,omitempty"`
}

SummarizeStep runs the terminal local LLM summarizer (must be last; host must be "_").

func (*SummarizeStep) Clone added in v0.3.7 

func (s *SummarizeStep) Clone() Step

Clone returns a deep copy of the step (safe for loop fan-out mutation).

func (*SummarizeStep) Kind added in v0.3.7 

func (s *SummarizeStep) Kind() string

Kind returns the step kind identifier.

func (*SummarizeStep) Validate added in v0.3.7 

func (s *SummarizeStep) Validate(vc StepValidateCtx) error

Validate checks this step's kind-specific fields; shared rules run separately.

type TemplateStep added in v0.3.5 

type TemplateStep struct {
	StepBase
	Template *RecipeStepTemplate `json:"template,omitempty"`
	Render   string              `json:"render,omitempty"`
}

TemplateStep renders a Go text/template locally.

func (*TemplateStep) Clone added in v0.3.5 

func (s *TemplateStep) Clone() Step

Clone returns a deep copy of the step (safe for loop fan-out mutation).

func (*TemplateStep) Kind added in v0.3.5 

func (s *TemplateStep) Kind() string

Kind returns the step kind identifier.

func (*TemplateStep) Validate added in v0.3.5 

func (s *TemplateStep) Validate(vc StepValidateCtx) error

Validate checks this step's kind-specific fields; shared rules run separately.

type TunnelStep added in v0.3.5 

type TunnelStep struct {
	StepBase
	RemoteExec
	Tunnel *RecipeStepTunnel `json:"tunnel,omitempty"`
}

TunnelStep establishes SSH port forwarding.

func (*TunnelStep) Clone added in v0.3.5 

func (s *TunnelStep) Clone() Step

Clone returns a deep copy of the step (safe for loop fan-out mutation).

func (*TunnelStep) Kind added in v0.3.5 

func (s *TunnelStep) Kind() string

Kind returns the step kind identifier.

func (*TunnelStep) Validate added in v0.3.5 

func (s *TunnelStep) Validate(vc StepValidateCtx) error

Validate checks this step's kind-specific fields; shared rules run separately.

type WhenEvalOpts added in v0.2.9 

type WhenEvalOpts struct {
	RecipeName string
	Execute    bool
	Host       hosts.Record
	Dest       *hosts.Record
	Steps      map[string]StepView
	Secrets    map[string]string
	Env        map[string]string
	KV         KVReader
	Facts      map[string]any
}

WhenEvalOpts carries per-evaluation context for CEL when.

type WhenProgram added in v0.2.9 

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

WhenProgram is a compiled CEL when expression.

func CompileWhen added in v0.2.9 

func CompileWhen(expr string) (*WhenProgram, error)

CompileWhen validates and compiles a when expression.

Source Files

View all Source files

Directories

Path Synopsis
Package secrets resolves CUE recipe secret refs.
 Package secrets resolves CUE recipe secret refs.
stack
Package stack implements symmetric secure:v1 encryption for recipe secrets.
 Package stack implements symmetric secure:v1 encryption for recipe secrets.
stackunwrap
Package stackunwrap unwraps stack data keys from secretsprovider URLs (KMS, keyring, age, etc.).
 Package stackunwrap unwraps stack data keys from secretsprovider URLs (KMS, keyring, age, etc.).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.