cuetry

package
v0.3.5 Latest Latest
Warning

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

 Go to latest Published: Jun 13, 2026 License: MIT Imports: 35 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"
	KindAI            = "ai"
	KindTemplate      = "template"
	KindPlugin        = "plugin"
	KindTunnel        = "tunnel"
	KindK8s           = "k8s"
	KindDocker        = "docker"
	KindOpensearch    = "opensearch"
	KindPostgres      = "postgres"
)

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 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 BuildRecipeStepJSONSchema added in v0.3.5 

func BuildRecipeStepJSONSchema() map[string]any

BuildRecipeStepJSONSchema 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 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 CanonicalRecipeJSON added in v0.2.8 

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

CanonicalRecipeJSON 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 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 EffectiveMaxParallel added in v0.2.9 

func EffectiveMaxParallel(step *RemoteExec, 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 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 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 HashRecipeJSON added in v0.2.8 

func HashRecipeJSON(r Recipe) (string, error)

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

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 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) 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) 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]string, 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, secrets map[string]string) 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) 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 ResolvePostgresKVBaseKey added in v0.3.0 

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

ResolvePostgresKVBaseKey returns the kv_key with optional per-host suffix.

func ResolveRecipeAISystemPrompt added in v0.2.8 

func ResolveRecipeAISystemPrompt(ai *RecipeAI, configDefault string) string

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

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) (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 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]string) 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]string, 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"`
}

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

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 CommandStep added in v0.3.5 

type CommandStep struct {
	StepBase
	RemoteExec
	Command string `json:"command,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"`
}

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"`
}

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(_ 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(_ 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 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(_ StepValidateCtx) error

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

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(_ 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(_ 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"`
	Defaults *RecipeDefaults `json:"defaults,omitempty"`
	Steps    []StepWrapper   `json:"steps"`
	Handlers []StepWrapper   `json:"handlers,omitempty"`
}

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.

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 the terminal local LLM summarizer step (must be last in recipe; 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]string `json:"secrets,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 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 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 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 RecipeStepDocker added in v0.3.4 

type RecipeStepDocker struct {
	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]string `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 RecipeStepPlugin added in v0.2.9 

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

RecipeStepPlugin configures a WASM custom_step plugin action.

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 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 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) 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 ScriptStep added in v0.3.5 

type ScriptStep struct {
	StepBase
	RemoteExec
	Script *RecipeFileTransfer `json:"script,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.

type SecretResolver added in v0.2.9 

type SecretResolver = secrets.Resolver

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 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]string `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"`
	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"`
}

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
	AIIndex   int // >=0 when recipe has an ai 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 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.
cloud
Package cloud resolves cloud and enterprise secret refs (Vault, AWS), analogous to
 Package cloud resolves cloud and enterprise secret refs (Vault, AWS), analogous to
env
Package env resolves env:NAME refs from the process environment (local analogue of cloud:/aws-sm:/aws-kms:/k8s:/age:/age-b64:/age-file:/keyring:/vault).
 Package env resolves env:NAME refs from the process environment (local analogue of cloud:/aws-sm:/aws-kms:/k8s:/age:/age-b64:/age-file:/keyring:/vault).
k8s
Package k8s resolves Kubernetes Secret data keys.
 Package k8s resolves Kubernetes Secret data keys.
passphrase
Package passphrase resolves age-encrypted material.
 Package passphrase resolves age-encrypted material.
ref
Package ref holds shared contracts for recipe secret backends (similar in role to how honey centralizes crypto provider contracts).
 Package ref holds shared contracts for recipe secret backends (similar in role to how honey centralizes crypto provider contracts).
service
Package service resolves keyring:// refs via the OS credential store (Zalando keyring), analogous to cloud:/aws-sm:/aws-kms:/k8s:/age:/age-b64:/age-file:/keyring:/vault.
 Package service resolves keyring:// refs via the OS credential store (Zalando keyring), analogous to cloud:/aws-sm:/aws-kms:/k8s:/age:/age-b64:/age-file:/keyring:/vault.
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.