kit

func AddBox ¶ added in v0.2026193.1241

func AddBox(dir, name, base string, layers []string) error

AddBox writes a new box to its discovered per-box file box/<name>/charly.yml as a node-form IMAGE — `<name>: {candy: {base: …}}`. The base argument is the value of the image's `base:` field (an external URL or the name of another box). If layers is non-nil it populates the image's `candy:` composition list. Errors if box/<name>/charly.yml exists.

func AddCandyDeployment ¶ added in v0.2026190.848

func AddCandyDeployment(paths *LedgerPaths, candyName, deployID string, update func(*CandyRecord)) error

AddCandyDeployment adds deployID to candy.DeployedBy and writes the record. Used at install time.

A candy record is SHARED by every deploy that uses it (refcounted by DeployedBy), so its reverse_ops must be the UNION of the ops each deploy contributed — a replacement would lose an earlier deploy's teardown and leak its resource. The callback's `rec.ReverseOps = …` is therefore treated as DECLARING THIS deploy's ops and merged (content-dedup) over the ops already recorded, rather than replacing them; see MergeReverseOps and charly#687.

func AddCandyDeploymentVia ¶ added in v0.2026190.848

func AddCandyDeploymentVia(exec spec.DeployExecutor, paths *LedgerPaths, candyName, deployID string, update func(*CandyRecord)) error

AddCandyDeploymentVia is the executor-routed variant of AddCandyDeployment. When exec is nil or a local executor, it falls back to operator-side file I/O (today's behaviour). When exec is a non-local DeployExecutor (SSHExecutor / NestedExecutor), the ledger I/O goes through exec.GetFile + exec.RunUser so the ledger lands on the substrate's filesystem under the substrate's ~/.config/charly/charly.yml — matching the install's actual venue (arch-vm.arch-host writes in the arch VM guest; sway-pod with nested pods writes in the parent pod; etc.).

func AnnotateNeverHangKill ¶ added in v0.2026229.1907

func AnnotateNeverHangKill(msg string, bound time.Duration) string

AnnotateNeverHangKill names the per-attempt never-hang bound in a step's failure message. The exec layer reports only "process terminated by signal (signal: killed)", which describes the mechanism of death and not its cause — so a step killed by the bound reads as a crash in whatever the step was running, and the reader goes looking for a bug in their own command. The bound is known at the moment the deadline fires; not saying so is what makes it a diagnostic dead end.

A legitimately slow step raises the ceiling with `timeout:`, which ProbeNeverHang honours over the floor — the mechanism's own parameter, not a workaround.

func AnnotateNeverHangKillWithEvidence ¶ added in v0.2026282.1057

func AnnotateNeverHangKillWithEvidence(msg string, ev KillEvidence) string

AnnotateNeverHangKillWithEvidence appends the bound-and-remedy line the never-hang kill always carries, and — when a local observation exists — one more line naming the absent signal: the process was still alive and silent, or it was already gone. It is the ONE implementation; AnnotateNeverHangKill is its unobserved case.

func AppendUnique ¶ added in v0.2026198.345

func AppendUnique(dst []string, items ...string) []string

AppendUnique appends items to dst, skipping any already present in dst.

func ApplyPortOverrides ¶ added in v0.2026190.848

func ApplyPortOverrides(ports []string, overrides []string) ([]string, error)

ApplyPortOverrides modifies port mappings based on --port flags. Each override is "newHost:containerPort". It replaces the host port for the matching container port in the ports list. Preserves protocol suffixes like /udp.

func AtomicWriteFile ¶ added in v0.2026192.1709

func AtomicWriteFile(path string, data []byte, perm os.FileMode) error

AtomicWriteFile writes data to path atomically: a temp file in the SAME dir (same filesystem, so rename is atomic) is written, chmod'd, then renamed over path. A concurrent reader sees either the old complete file or the new complete file, never a partial write; concurrent writers of identical content converge (last rename wins, bytes identical). Relocated from charly core (P8) so the build render engine (sdk/deploykit) and charly's staging primitives share it.

func BareVolumeName ¶ added in v0.2026197.1320

func BareVolumeName(volumeName, boxName, instance string) string

BareVolumeName strips the "charly-<box>[-<instance>]-" prefix from a resolved volume name.

P12a: relocated from sdk/deploykit/quadlet.go (a pure string helper with no deploykit-specific coupling) so this file's mergeRuntimeVars can call it without a kit→deploykit import (deploykit already imports kit — the reverse direction would cycle). deploykit's own caller now calls kit.BareVolumeName.

func BuildActivityDir ¶ added in v0.2026205.1618

func BuildActivityDir() (string, error)

BuildActivityDir is the user-scope directory of live build-activity locks — one flocked nonce file per in-flight `charly box build` engine run.

func BuildArchExports ¶

func BuildArchExports() string

BuildArchExports emits the BUILD_ARCH=$(uname -m) + ARCH=<buildkit-triplet> shell preamble so a cmd:/download: body can template ${ARCH}/${BUILD_ARCH} at deploy-time the same way the container build gets them from BuildKit's TARGETARCH.

func BuildCommandLine ¶ added in v0.2026269.700

func BuildCommandLine(command string, sudo bool, marker string) string

BuildCommandLine composes the line typed for a command: the command (prefixed with sudo when requested), a terminating `; echo <marker>`, so the shell echoes marker only after the command has finished. The prefix is appended with `;` so it runs regardless of the command's own exit status.

It is PURE, so the exact line the engine types is unit-locked without a device.

func BuilderCollectContext ¶

func BuilderCollectContext(word string, in spec.BuilderCollectInput) map[string]any

BuilderCollectContext returns the builder-specific stage-context keys for `word` given the host-supplied candy descriptor. An unknown word returns nil (a custom candy builder with no plugin keeps base-only context — the host never invokes a plugin for it).

func BuilderResolve ¶

func BuilderResolve(word string, in spec.BuilderResolveInput) (spec.BuilderResolveReply, error)

BuilderResolve renders `word`'s build-time multi-stage from the host-supplied context, returning the pieces the host splices into the Containerfile: Stage (pre-main-FROM), CopyArtifacts + CopyBinary (post-main-FROM), or InlineFragment (in-candy, inline builders). An unknown word is a LOUD error (never a silent empty stage). This is the ONE render both the box-build plugin OpResolve and the in-proc pod-overlay build-emit call (R3).

func BuilderReverse ¶

func BuilderReverse(word string, in spec.BuilderReverseInput) []spec.ReverseOp

BuilderReverse returns the teardown ops for `word` given its resolved stage context (the BuilderCollectContext output the host stored on the BuilderStep). An unknown word, or a context missing the keys a builder needs, returns nil (no teardown — the same best-effort the in-proc builders had).

func CargoLdConfPath ¶ added in v0.2026240.2049

func CargoLdConfPath(candy string) string

CargoLdConfPath returns the ld.so.conf.d drop-in that puts CargoLibDir on the loader path. Without it a per-candy directory would be invisible to the dynamic loader, which is the price of making the install identifiable — so the drop-in is emitted with it, never separately.

func CargoLibDir ¶ added in v0.2026240.2049

func CargoLibDir(candy string) string

CargoLibDir returns the directory a cargo LIBRARY crate's artifacts install into for a given candy. Per-candy rather than a flat /usr/local/lib so the install is identifiable and therefore reversible: BuilderReverse can remove exactly this directory, where a flat install would leave charly unable to tell its own .so files from anyone else's.

func CloseHostCleanups ¶ added in v0.2026197.1537

func CloseHostCleanups(cleanups []func())

CloseHostCleanups tears down any ssh -L forwards opened while resolving ${HOST:<member>} address variables. Safe to call on a nil/empty slice.

func CloseTerminal ¶ added in v0.2026269.700

func CloseTerminal(ctx context.Context, tr ConsoleTransport) (string, error)

CloseTerminal exits an open terminal. The generic `close-terminal` (R3).

func CollectAnyStrings ¶ added in v0.2026191.2033

func CollectAnyStrings(v any) []string

CollectAnyStrings returns every string within a plugin_input value (scalar string / nested map / list), depth-first. The READ-ONLY analogue of ExpandAnyVars: it lets the ${HOST:…} cross-member scan (collectHostRefs) reach a plugin verb's authored fields, which live in the opaque PluginInput map rather than StringFields.

func CollectHostRefs ¶ added in v0.2026197.1537

func CollectHostRefs(checks []spec.Op) []string

CollectHostRefs returns the distinct ${HOST:<member>} variable keys referenced across every string field of every check (keys in the "NAME:arg" form used by ExpandTestVars).

func ConsolePreview ¶ added in v0.2026266.2315

func ConsolePreview(s string, n int) string

ConsolePreview clips s to a single line of at most n characters, for an error message. It collapses ALL whitespace runs (newlines included) to single spaces and appends an ellipsis when it truncates. It is the ONE such clip in the SDK — artifact.go's error paths call it too, so OCR text is rendered the same way wherever it is quoted back.

func ContainerPortsFromMappings ¶ added in v0.2026190.848

func ContainerPortsFromMappings(mappings []string) []int

ContainerPortsFromMappings extracts the container-side port number from each mapping. "auto" sentinels are skipped (they have no container port to extract — they ARE the request to allocate one). Unparseable entries are silently dropped (the loud-skip warning lives in CheckPortAvailability).

func DecodeInput ¶

func DecodeInput(in map[string]any, out any)

DecodeInput decodes an Op's plugin_input (map[string]any) into a candy's CUE-generated typed params struct via a JSON round-trip. A nil/empty input leaves out at its zero value; the host has already validated the input against the served schema.

func DeleteCandyRecord ¶ added in v0.2026190.848

func DeleteCandyRecord(paths *LedgerPaths, layer string) error

DeleteCandyRecord removes ledger.candies[layer].

func DeleteDeployRecord ¶ added in v0.2026190.848

func DeleteDeployRecord(paths *LedgerPaths, id string) error

DeleteDeployRecord removes ledger.deploys[id]; silently ignores not-found (teardown is idempotent).

func DirectDeployMarkerDir ¶ added in v0.2026198.345

func DirectDeployMarkerDir() (string, error)

DirectDeployMarkerDir returns ~/.config/charly/direct/, the registry directory for direct-mode deploys (the equivalent of ~/.config/containers/systemd/ for quadlet deploys).

func DirectDeployMarkerPath ¶ added in v0.2026198.345

func DirectDeployMarkerPath(box, instance string) (string, error)

DirectDeployMarkerPath returns the marker JSON path for a deploy.

func DiscoverRemoteCandy ¶ added in v0.2026192.1026

func DiscoverRemoteCandy(repoDir string) ([]string, error)

DiscoverRemoteCandy returns the list of candy names in a remote repo directory

func EffectiveStepID ¶ added in v0.2026191.2205

func EffectiveStepID(s *spec.Step, origin string, stepIdx int) string

EffectiveStepID returns the step's author id when set, else a derived id.

func EffectiveTags ¶ added in v0.2026191.1413

func EffectiveTags(stepTags []string) []string

EffectiveTags normalizes and de-dups a step's tags, preserving first-seen order. (Per-step tags only — there is no group-level tag inheritance.)

func EnableUnit ¶ added in v0.2026276.152

func EnableUnit(ctx context.Context, exec DeployExecutor, unit string, scope spec.Scope) error

EnableUnit runs `systemctl [--user] enable --now <unit>` on the venue. Exported for the workflow/lowering path, which enables a generated TIMER unit beside the engine's own deploy steps — the deployment walk and the workflow lowering must drive systemd through ONE call site (R3).

func EnsureSshConfigInclude ¶ added in v0.2026186.739

func EnsureSshConfigInclude(home string) error

EnsureSshConfigInclude inserts the managed `Include ~/.config/charly/ssh_config` directive at the TOP of the user's ~/.ssh/config (creating it if needed) — the Include MUST be outside any Host block (ssh_config(5) lexical scoping), so it is PREPENDED. Idempotent.

func EnvPairsToMap ¶ added in v0.2026190.848

func EnvPairsToMap(pairs []string) map[string]string

EnvPairsToMap converts KEY=VALUE pairs (the CLI -e / label wire form) into the map form the deploy schema stores since the env-shape unification.

func EnvdDir ¶

func EnvdDir(home string) string

EnvdDir returns the directory where per-candy env files live under a home.

func EnvdFilePath ¶

func EnvdFilePath(home, candyName string) string

EnvdFilePath returns the env file path for a given candy under a home.

func ExpandAnyVars ¶ added in v0.2026191.2033

func ExpandAnyVars(v any, env map[string]string) (any, []string)

ExpandAnyVars expands ${VAR} references in every string within a plugin_input value (scalar string / nested map / list), mutating maps and slices in place, and returns the (possibly rewritten) value plus the unresolved var names. Non-string scalars pass through untouched.

func ExpandOpVars ¶ added in v0.2026191.2033

func ExpandOpVars(c *spec.Op, env map[string]string) []string

ExpandOpVars rewrites every ${...} reference on an Op in place using the supplied environment map. Returns the combined (sorted) list of unresolved refs encountered across all string fields.

func ExpandTestVars ¶ added in v0.2026191.2033

func ExpandTestVars(s string, env map[string]string) (string, []string)

ExpandTestVars substitutes ${NAME} and ${NAME:arg} references using the supplied environment map.

Keys in env for plain refs use just the name: env["HOME"] = "/home/user". Keys for parameterized refs combine name and argument with a colon: env["HOST_PORT:6379"] = "16379", env["VOLUME_PATH:workspace"] = "/var/lib/…".

Returns the substituted string and a list of unresolved refs (in encounter order, deduplicated). The caller decides whether unresolved refs are an error (build-time validation) or a skip reason (runtime).

func FillReverseUninstallCmds ¶ added in v0.2026190.848

func FillReverseUninstallCmds(ops []ReverseOp, renderUninstall func(format string, packages []string) string)

FillReverseUninstallCmds renders the host-venue uninstall command for every ReverseOpPackageRemove op in the slice from the format's uninstall_template (the embedded build vocabulary, charly/charly.yml), in place. Called at install/record time by the local deploy target and the external vm deploy (R3 — one shared filler) when the DistroConfig is in hand, so the persisted ledger op carries the exact removal command the teardown will run. Ops whose format declares no uninstall_template, or whose format isn't in the config, are left with an empty UninstallCmd (teardown then errors loudly rather than silently running a wrong command). The renderUninstall seam maps (format, packages) → the format's uninstall command, or "" when the format has no uninstall template. It keeps this function free of the buildkit DistroConfig/RenderTemplate dependency (which would cycle kit→buildkit→kit once reverse_ops lives in kit) — the caller (candy/plugin-fleet/deploy_target.go, S3b — was charly core's deploy_target_external.go before the deploy-dispatch cluster moved) closes over DistroCfg + RenderTemplate.

func FilterHostVars ¶ added in v0.2026191.2205

func FilterHostVars(missing []string) []string

FilterHostVars returns the ${HOST:…} cross-member references among the unresolved keys. An unresolved ${HOST:…} means the member is unreachable — a real failure, never a SKIP (a skip on an unreachable dependency is a fake pass). Other unresolved vars (a deploy-only var under build scope, an unmounted volume) stay a legitimate skip — this function does not decide that; ClassifyUnresolved does.

func FindMappingValue ¶

func FindMappingValue(m *yaml.Node, key string) *yaml.Node

FindMappingValue returns the value node for key in a YAML mapping node, or nil. (Like MapValue, but requires the key node to be a scalar — the form the migration transforms + the core loader's legacy-shape detection both use.)

func FindPortOwner ¶ added in v0.2026190.848

func FindPortOwner(port int, engine string) (owner string, ownerType string)

FindPortOwner checks running containers to identify what is using a port.

func FirstUnmetDepStep ¶ added in v0.2026201.1934

func FirstUnmetDepStep(s spec.Step, verdictByID map[string]string) string

FirstUnmetDepStep returns the first dep id in s.DependsOn whose verdict is anything other than "pass" (or that is unknown / not yet run). Returns "" if every dep passed (or the step has no deps).

func FormatPortConflicts ¶ added in v0.2026190.848

func FormatPortConflicts(conflicts []PortConflict, image string) string

FormatPortConflicts produces a user-friendly error message with remediation suggestions.

func HammingDistance ¶ added in v0.2026269.700

func HammingDistance(a, b ScreenSignature) int

HammingDistance returns the number of differing bits between two signatures (0 = identical fingerprint, 64 = opposite).

func HumanBytes ¶ added in v0.2026202.1944

func HumanBytes(n int64) string

HumanBytes renders a byte count as a compact human-readable string.

func IsAutoPort ¶ added in v0.2026190.848

func IsAutoPort(mapping string) bool

IsAutoPort reports whether a port-list entry is the literal "auto" sentinel. Authors write `port: [auto]` (or `port: [auto, "8443:443"]` to mix auto-allocation with explicit pins) in charly.yml.

func IsDirectDeploy ¶ added in v0.2026198.345

func IsDirectDeploy(box, instance string) bool

IsDirectDeploy reports whether the named deploy was created in direct mode (i.e. has a marker file). Used by lifecycle commands.

func IsGitSubmoduleDir ¶

func IsGitSubmoduleDir(p, root string) bool

IsGitSubmoduleDir reports whether p (≠ root) contains a .git entry (a nested submodule/repo boundary).

func IsNotFound ¶ added in v0.2026277.352

func IsNotFound(err error) bool

IsNotFound reports whether err means "the path does not exist". It is the ONE classifier for a missing file read back over the DeployExecutor reverse channel, shared by every GetFile caller that must tolerate absence: the env.d managed-block read above, the substrate deploy ledger (install_ledger.go, where a fresh guest legitimately has no charly.yml yet), and deploykit's `optional:` artifact retrieval. It recognizes a local not-found sentinel (`errors.Is(err, fs.ErrNotExist)`, so a wrapped one counts too) as well as the text a remote read produces — `ssh cat` reports "No such file or directory", `ls` reports "cannot access", and a tool that names the path without the errno wording reports a bare "not found".

Anything else is NOT tolerated: a permission denial, a broken channel, or a syntax error in the substrate's charly.yml stays a loud failure, because treating it as "absent" would let the caller silently overwrite a file it could not read.

func IsRuntimeOnlyVar ¶ added in v0.2026191.2033

func IsRuntimeOnlyVar(key string) bool

IsRuntimeOnlyVar reports whether the given variable key (as returned by TestVarRefs) refers to a runtime-only value. The check matches on name prefix because parameterized vars share a common prefix with their arg.

func KeywordOf ¶ added in v0.2026191.2205

func KeywordOf(s *spec.Step) spec.StepKeyword

KeywordOf returns the populated step keyword, or "" when none is set.

func LUKSUnlock ¶ added in v0.2026269.700

func LUKSUnlock(ctx context.Context, tr ConsoleTransport, passphrase string, success, failure []string, timeoutSec int, artifact string) (string, error)

LUKSUnlock enters a disk-encryption passphrase at the initramfs prompt and waits for a success anchor; a failure anchor FAILS fast. It is the generic `luks-unlock` (R3).

func LedgerTxLockPath ¶ added in v0.2026250.154

func LedgerTxLockPath(paths *LedgerPaths) string

LedgerTxLockPath returns the LEDGER TRANSACTION lock path for one LedgerPaths: the config path + ".ledger.lock". This is NOT paths.LockFile, and the separation is load-bearing (the deploy-del self-deadlock, RCA 2026-09-07): paths.LockFile guards the per-host charly.yml read-modify-write — the SAME brief exclusion every writer of that FILE shares (writeLedger here, deploykit.MutateDeployConfig/SaveDeployConfig, spec/refs GitClient.save's cache section). The ledger TRANSACTION lock is a different logical resource: the deploy-del/add transaction bracket (resolve → members-down → node-del-dispatch) holds it for the WHOLE operation — minutes, network fetches included. Collapsing both onto charly.yml.lock made every in-process nested config RMW under a transaction hold contend with the holder's own fd (flock is per-open-file-description; two acquires of one path in ONE process conflict): the del's resolve-phase GitClient.save and teardown-phase MutateDeployConfig each stalled the full lockTimeout against the del's own transaction hold, silently dropping their writes — the cache never persisted, so the next run re-stalled. Deterministic, 7/7-reproducible deploy-del hang.

The dedicated file restores the genesis semantics (the pre-sdk ledger lock was a dedicated ~/.config/opencharly/installed/.lock — NEVER the config lock): the transaction lock orders deploy flows against EACH OTHER; brief config-file writers stay ordered by charly.yml.lock and legitimately interleave inside a transaction (each RMW re-reads the current file under the config lock and preserves the other sections).

func ListCandyNames ¶ added in v0.2026241.1032

func ListCandyNames(paths *LedgerPaths) []string

ListCandyNames returns every candy name in the `ledger:` section, sorted. The candy-side counterpart of ListDeployIDs; see that doc for why it exists.

func ListCandyNamesStrict ¶ added in v0.2026241.1051

func ListCandyNamesStrict(paths *LedgerPaths) ([]string, error)

ListCandyNamesStrict is ListCandyNames with the same malformed-ledger contract as ListDeployIDsStrict.

func ListDeployIDs ¶ added in v0.2026241.1032

func ListDeployIDs(paths *LedgerPaths) []string

ListDeployIDs returns every deploy id in the `ledger:` section, sorted.

This is the enumeration half of the ledger API. Before the relocation, a consumer enumerated by listing *.json stems under LedgerPaths.Deploys; that directory no longer exists, so without this an out-of-tree consumer cannot discover what is deployed at all — it can only ReadDeployRecord an id it already knows. Absent/corrupt file yields an empty slice, matching readLedger's best-effort contract (and the old empty-directory case).

func ListDeployIDsStrict ¶ added in v0.2026241.1051

func ListDeployIDsStrict(paths *LedgerPaths) ([]string, error)

ListDeployIDsStrict is ListDeployIDs but reports a malformed ledger instead of reading it as an empty one. Prefer it wherever a user-facing command would otherwise print "nothing deployed" for a file it simply could not parse.

func ListVmSshAliases ¶ added in v0.2026186.739

func ListVmSshAliases(home string) ([]string, error)

ListVmSshAliases returns the alias names in the managed fragment, sorted.

func ManagedBlockBody ¶

func ManagedBlockBody(shell ShellKind, home string) string

ManagedBlockBody returns the shell-specific loop that sources the env.d directory under a home. POSIX-sh for bash/zsh, fish syntax for fish.

func ManagedBody ¶ added in v0.2026186.739

func ManagedBody(text string) string

ManagedBody returns just the contents between the begin/end fence markers (the global, untagged managed block) in text. Returns "" when the markers are absent.

func MapValue ¶

func MapValue(m *yaml.Node, key string) *yaml.Node

MapValue returns the value node for key in a YAML mapping node, or nil.

func MappingChild ¶ added in v0.2026186.1019

func MappingChild(m *yaml.Node, key string) *yaml.Node

MappingChild looks up a key in a mapping node. Returns the value node or nil if missing. yaml mapping nodes store [key, value, key, value, …].

func MarkersForTag ¶

func MarkersForTag(marker string) (begin, end string)

MarkersForTag returns the begin/end fence pair for a marker tag. Empty tag → the global-block fence; non-empty → a per-candy fence so multiple candies coexist.

func MergeAnswers ¶ added in v0.2026266.2315

func MergeAnswers(envVars, secrets, authored map[string]string, envName, secretName func(string) string) map[string]string

MergeAnswers resolves the three answer sources into one map. Precedence (lowest first): env < secret < authored. `envName` reads an ENVIRONMENT VARIABLE name; `secretName` reads a credential-store key. An unresolved env var or secret is left OUT (so a missing var fails visibly as an unsubstituted {{placeholder}} rather than silently empty). PURE over its inputs — the caller owns the readers.

func MergeReverseOps ¶ added in v0.2026269.1752

func MergeReverseOps(existing, incoming []spec.ReverseOp) []spec.ReverseOp

MergeReverseOps returns existing plus every op in incoming not already present. Dedup is by CONTENT (reflect.DeepEqual: ReverseOp carries an Extra map, so `==` cannot compare it). A shared candy record's reverse_ops are the UNION of every deploy's ops, because teardown replays the whole list only when the refcount empties — so an overwrite silently drops an earlier deploy's teardown.

charly#687: two `deploy:kindcluster` deploys (a root + its member) each record `kind delete cluster --name <that deploy's cluster>` against the SHARED `plugin-kube` provider candy. The second write overwrote the first, so teardown deleted only the member's cluster and left the root's running. Merging keeps both, and dedup makes a re-run (same deploy, same op) idempotent.

func MigrateCandidateYAMLFiles ¶

func MigrateCandidateYAMLFiles(dir string, treeSubdirs []string) []string

MigrateCandidateYAMLFiles is the ONE candidate-file scanner the multi-document doc-migration steps share AND the core loader's legacy-vocab rejection scan uses: every `.yml`/`.yaml` under each of treeSubdirs (walked recursively, skipping nested git submodules + any `testdata` dir) plus the root-level YAML siblings in dir. Sorted, deduplicated.

func NodeShapedValue ¶

func NodeShapedValue(val *yaml.Node) bool

NodeShapedValue reports whether a mapping node carries a reserved kind word as a key (i.e. it is a name-first node-form value).

func NormalizeTag ¶ added in v0.2026191.1413

func NormalizeTag(t string) string

NormalizeTag strips a single leading '@' so `@smoke` and `smoke` are identical — authors commonly write `@smoke` from Gherkin habit, but the sigil is optional in the YAML surface.

func OCRBytes ¶ added in v0.2026266.2315

func OCRBytes(pngBytes []byte) (string, error)

OCRBytes runs tesseract over a PNG held in memory and returns its text, with the console upscale applied (ConsoleOCRScale). It is the ONE OCR implementation in the SDK — the console transports AND the artifact validator (RunArtifactValidators' artifact_contains_text, via OCRBytesScaled) all call it, so there is exactly one tesseract invocation to keep correct (R3). The bytes are written to a temp file because tesseract reads a path.

FAILING TO RUN IS NOT FAILING TO MATCH: a missing engine, or missing language data (tesseract writes the complaint to stderr and can still exit 0 with EMPTY stdout), returns an error that NAMES the cause — never an empty string a caller would read as "the text is absent".

func OCRBytesScaled ¶ added in v0.2026266.2315

func OCRBytesScaled(pngBytes []byte, scale int) (string, error)

OCRBytesScaled is OCRBytes with an explicit nearest-neighbour upscale factor applied first (1 = none). The artifact validator upscales a screen-resolution capture (see sdk's ocrUpscale); a framebuffer console reads at 1.

func OpUnifyCandidateFiles ¶

func OpUnifyCandidateFiles(dir string) []string

OpUnifyCandidateFiles is the candidate-file set the op/plan-unify migrators AND the core loader's legacy-test-vocab rejection scan walk (candy/ + box/ trees + root siblings).

func OpenTerminal ¶ added in v0.2026269.700

func OpenTerminal(ctx context.Context, tr ConsoleTransport, o TerminalOpen) (string, error)

OpenTerminal opens a terminal on the transport and waits for a shell prompt. It is the generic `open-terminal`: the transport sends the combo, the shared engine waits for a prompt anchor. One implementation, either transport (R3).

func ParseContainerPort ¶ added in v0.2026190.848

func ParseContainerPort(mapping string) (int, error)

ParseContainerPort extracts the container port from a mapping. Accepts every form ParsePortMapping does, including the IP:H:C bind-address form.

func ParseHostPort ¶ added in v0.2026190.848

func ParseHostPort(mapping string) (int, error)

ParseHostPort extracts the host port from a mapping. Accepts every form ParsePortMapping does, including the IP:H:C bind-address form.

func ParseTaskMode ¶

func ParseTaskMode(mode string, def uint32) uint32

ParseTaskMode parses a candy task mode string ("0644","0o755") into a uint32 file mode, falling back to def when empty/unparseable.

func PopulateSystemInfo ¶ added in v0.2026241.1140

func PopulateSystemInfo() error

PopulateSystemInfo detects the host identity and writes it into the `system:` section of the per-host charly.yml, preserving every other key (deploy:, provides:, cache:, ledger:). It is the "refresh the local system snapshot" operation — called by `charly status` (and available to any command that needs the host identity persisted).

func PosArtifact ¶

func PosArtifact(c *spec.Op) []string

func PosCommandFields ¶

func PosCommandFields(c *spec.Op) []string

PosCommandFields splits the input `command` into argv slots, prefixed with `--` so kong does not treat embedded -flags as its own (libvirt:guest/exec). For shell metachars use `command: "sh -c '<full>'"`.

func PosKeyNameSplit ¶

func PosKeyNameSplit(c *spec.Op) []string

PosKeyNameSplit splits the input `key` on whitespace (libvirt send-key: "ctrl alt F2" → 3 slots).

func PosLibvirtQmp ¶

func PosLibvirtQmp(c *spec.Op) []string

PosLibvirtQmp emits a QMP method name + optional JSON args (input text = method, input = JSON).

func PosTarget ¶

func PosTarget(c *spec.Op) []string

func PosText ¶

func PosText(c *spec.Op) []string

func ReadLedger ¶ added in v0.2026241.1311

func ReadLedger(paths *LedgerPaths) (map[string]DeployRecord, map[string]CandyRecord, error)

ReadLedger returns the FULL ledger maps (deploys + candies) in ONE read of the per-host charly.yml. The status collector uses this to avoid re-reading the config once per record (measured: 186 reads of a 310KB config per status run). STRICT: a malformed ledger is an error (never reported as an empty one).

func ReloadDaemon ¶ added in v0.2026276.152

func ReloadDaemon(ctx context.Context, exec DeployExecutor, scope spec.Scope) error

ReloadDaemon runs `systemctl [--user] daemon-reload` so a freshly-written unit/drop-in is picked up before enable. Exported alongside EnableUnit (R3): one daemon-reload call site.

func RemoveEnvdFile ¶ added in v0.2026206.837

func RemoveEnvdFile(home, candyName string) error

RemoveEnvdFile deletes an env.d entry. Silently succeeds when absent.

func RemoveImagesByReference ¶ added in v0.2026186.831

func RemoveImagesByReference(engineBin, reference string)

RemoveImagesByReference best-effort removes every local image whose repository BASENAME exactly equals `reference` (e.g. "<deploy>-overlay") via `<engineBin> images … | rmi`. Silent on error (image cleanup is best-effort). engineBin is the resolved engine binary (the host resolves "podman"/"docker"/"auto" and passes the concrete binary — kit does no detection).

The `--filter reference=<reference>` glob is NOT trusted alone: podman lists EVERY repo:tag of any matched image ID, so a base image or a cross-deploy image that shares content (same image ID as the overlay) leaks into the output. rmi'ing those blindly would destroy the base + unrelated deploys' images. So the emitted repo is re-checked in Go and only the EXACT `<reference>` repo is removed.

func RemoveManagedBlockAt ¶ added in v0.2026190.848

func RemoveManagedBlockAt(path, marker string) error

RemoveManagedBlockAt strips the managed block (tagged with marker) from the file at path, in place. A file left empty is removed; a missing file is a no-op. The file-level counterpart to StripManagedBlock (the pure string op).

func RemoveSshConfigInclude ¶ added in v0.2026186.739

func RemoveSshConfigInclude(home string) error

RemoveSshConfigInclude removes the managed Include line from ~/.ssh/config. Idempotent.

func RemoveVmSshStanza ¶ added in v0.2026186.739

func RemoveVmSshStanza(home string, alias string) (remaining int, err error)

RemoveVmSshStanza drops the named alias and returns the remaining count (0 → the caller also removes the Include). Idempotent.

func RenderDownloadScript ¶

func RenderDownloadScript(op *spec.Op, candyVars map[string]string) string

RenderDownloadScript emits a shell snippet that fetches op.Download to a temp file, optionally extracts it into op.To, then cleans up — honoring the same flags the container build path respects (extract format, strip_components, include, mode, env). candyVars are exported alongside op.Env so a vars: key referenced in the URL resolves at deploy time.

func RenderEnvdBody ¶

func RenderEnvdBody(candyName string, envVars map[string]string, pathAdd []string) string

RenderEnvdBody produces the deterministic, shell-agnostic POSIX-sh fragment for a candy's env vars + PATH additions. Sorted keys guarantee stable output.

func RenderFlowEvidence ¶ added in v0.2026269.700

func RenderFlowEvidence(res ConsoleFlowResult) string

RenderFlowEvidence renders a flow run's per-node evidence, including the OCR-read output of any command action, so "read the results via OCR" is visible in the verdict. Shared so both transports render it identically (R3).

func RenderManagedBlockStrip ¶ added in v0.2026190.848

func RenderManagedBlockStrip(path, marker string) string

RenderManagedBlockStrip is the remote analogue of RemoveManagedBlockAt: a POSIX-sh snippet that drops the marker's begin/end fence pair (and its body) from the file IN PLACE on the venue. The fences come from MarkersForTag so they match exactly what the forward walk wrote, and awk index() matches them LITERALLY (no regex). The final `cat > "$f"` rewrites in place to preserve the rc file's perms/owner.

func RenderOpCommand ¶

func RenderOpCommand(op *spec.Op, ctxPath string, candyVars map[string]string) (string, bool)

RenderOpCommand turns an op into a shell command suitable for sudo/user execution. It handles every plugin-renderable verb EXCEPT copy (staged via the executor's PutFile) and the act-`plugin:` verb (whose ProvisionActor shell needs the in-proc registry — package main / RunHostStep render those). Returns (cmd, handled): handled=false means the op is a copy or an act-`plugin:` verb the caller must route elsewhere; handled=true with an empty cmd never occurs (every handled verb yields a body).

func ReplaceOrAppendManagedBlock ¶

func ReplaceOrAppendManagedBlock(existing, body, marker string) string

ReplaceOrAppendManagedBlock replaces the begin/end fence pair's body (tagged with marker, empty for the global block) in existing, appending a fresh block at EOF when absent.

func ReplaceOrPrependManagedBlock ¶ added in v0.2026186.739

func ReplaceOrPrependManagedBlock(existing, body, marker string) string

ReplaceOrPrependManagedBlock replaces the marker-tagged managed block in place, or PREPENDS it (with a blank-line separator before the rest of the file) when absent. Used for the ssh-config Include line, which MUST be at the TOP of ~/.ssh/config (outside any Host block) — an appended Include would be gated on the last preceding Host stanza's match (ssh_config(5) lexical scoping).

func ResolveDeployPorts ¶ added in v0.2026190.848

func ResolveDeployPorts(containerPorts []int, pins, prior []string, occupied map[int]bool) ([]string, error)

ResolveDeployPorts maps each image-declared container port to a host:container publish mapping — the AUTO-PORT-MAPPING default. For every container port:

• an explicit deploy pin (host:container, matched by container port) wins;
• else a still-valid prior allocation (from a previous `charly config` — keeps a deploy's host ports STABLE across `charly update`) is reused;
• else a fresh free 127.0.0.1 host port is allocated.

`occupied` seeds host ports already taken by SIBLING deployments so concurrent beds never collide; every chosen host port is recorded back into it. Pins for container ports the image does not expose are honored too (an operator publishing an extra port). A stray `auto` token in `pins` is ignored (treated as "no pin" → allocate), so a not-yet-migrated `port: [auto]` still works. Returned mappings carry no bind address; localizePort prepends BindAddress (127.0.0.1 by default) at quadlet/run time so every published port is loopback.

func ResolveEntrypointFromMeta ¶ added in v0.2026198.345

func ResolveEntrypointFromMeta(meta *spec.BoxMetadata) []string

ResolveEntrypointFromMeta determines the entrypoint from image metadata (runtime mode). The build-resolved init contract is baked into the ai.opencharly.init_def label (meta.InitDef), so EVERY init system declared in the embedded `init:` vocabulary reaches runtime — including openrc and any custom one — with no table to register in.

func ResolveInitDefFromMeta ¶ added in v0.2026198.345

func ResolveInitDefFromMeta(meta *spec.BoxMetadata) (*spec.ResolvedInit, error)

ResolveInitDefFromMeta returns the init contract for management-command rendering, read from the ai.opencharly.init_def label. An image without that label errors: it predates the label and must be rebuilt.

func ResolveNetwork ¶ added in v0.2026198.345

func ResolveNetwork(configured, engine string) (string, error)

ResolveNetwork returns the network to use for a container. If configured is non-empty (explicit override like "host"), it is returned as-is. Otherwise, the shared "charly" network is ensured and returned.

func ResolveVmSshPort ¶ added in v0.2026201.1934

func ResolveVmSshPort(vm *spec.ResolvedVm, vmName string, persistedPort int) (int, error)

ResolveVmSshPort resolves the guest SSH host port from the resolved spec:

• ssh.port_auto: true → reuse persistedPort when the caller already resolved one (idempotent across rebuilds), else allocate a free host port.
• ssh.port: N → that fixed port.
• neither → 2222.

The persisted-state READ is the caller's concern (it differs by placement: charly core reads its project config directly; an out-of-process plugin reads over a host seam) — this is the PURE resolution/allocation decision only.

func RunAgentOnce ¶ added in v0.2026197.1320

func RunAgentOnce(ctx context.Context, ai *spec.AgentExecSpec, prompt string, timeout time.Duration) (string, string, error)

RunAgentOnce launches the configured AI CLI exactly once with the given prompt and returns its stdout/stderr. It is the bounded, single-shot sibling of the harness loop's iteration launcher (candy/plugin-check/harness_loop.go) and of LocalCaptureVersion (candy/plugin-check/agent.go) — same host-exec shape, no iteration directories, no plateau state. ${PROMPT} in the AI's command argv (and a PromptVia: file temp file) is substituted with the prompt text.

func RunBootOrder ¶ added in v0.2026269.700

func RunBootOrder(ctx context.Context, tr ConsoleTransport, o BootOrder) (string, error)

RunBootOrder sets the UEFI boot order over the terminal. The generic `boot-order` (R3). Reading (list) needs no privilege; writing (next/set) does.

func RunCommands ¶ added in v0.2026269.700

func RunCommands(ctx context.Context, tr ConsoleTransport, cmds []ConsoleCommand, sudoPassword string, closeTerminal bool, promptAnchors []string) (string, error)

RunCommands runs ordered commands in an open terminal, reading each result by OCR. It is the generic `run-command`; sudoPassword is entered at a sudo prompt. closeTerminal sends `exit` afterwards. promptAnchors, when set, make every command verify a shell prompt first (the fast-fail guard against typing into a pager/menu/login screen). One implementation, either transport (R3).

func RunReverseOps ¶ added in v0.2026190.848

func RunReverseOps(ops []ReverseOp, exec ReverseExecutor)

RunReverseOps executes ops in REVERSE order (last-installed, first- removed). Idempotent where possible: a missing file is treated as "already removed" rather than an error.

func SameStringSlice ¶ added in v0.2026190.848

func SameStringSlice(a, b []string) bool

SameStringSlice reports whether two string slices are element-wise equal (order-sensitive) — used to skip a redundant resolved-port re-save.

func SanitizeDeployName ¶ added in v0.2026197.1320

func SanitizeDeployName(s string) string

func SaveYAMLNodeFile ¶ added in v0.2026193.1241

func SaveYAMLNodeFile(path string, root *yaml.Node) error

SaveYAMLNodeFile marshals a node tree back to an arbitrary file path, preserving comments + key order (the yaml.v3 Node round-trip). Shared by the scaffold/authoring engine (kit.AddBox) and charly core's box add-candy/rm-candy verbs — ONE marshal-to-file home (R3).

func ScaffoldCandy ¶ added in v0.2026193.1241

func ScaffoldCandy(dir, name string) error

ScaffoldCandy creates a new candy directory at dir/<DefaultCandyDir>/<name> with a placeholder manifest in the compact name-first node form. ADE mandates a description + at least one deterministic check: step, so the scaffold ships a minimal passing pair the author replaces. Errors if the candy already exists. The caller prints the created path.

func ScaffoldProject ¶ added in v0.2026193.1241

func ScaffoldProject(dir string) error

ScaffoldProject creates an empty charly project at dir. Idempotency: errors out if dir already contains an charly.yml so we never silently clobber an existing project. The dir itself may exist.

func ScreenMatches ¶ added in v0.2026269.700

func ScreenMatches(current, reference ScreenSignature, maxDistance int) bool

ScreenMatches reports whether the current frame's signature is within maxDistance of the reference (1..64). A maxDistance <= 0 (the Go zero value of an omitted optional field) uses ScreenDefaultMaxDistance — the documented tolerance of a clock tick, a cursor blink, or minor rendering noise. A caller wanting an (almost) exact match authors maxDistance 1; 0 is not meaningful because an omitted field and a literal 0 are indistinguishable in the decoded struct.

GEOMETRY GUARD: when both signatures carry dimensions and they differ by more than a factor of 2, the frames are almost certainly different screens (a resolution change / a different display) — reported as no-match regardless of the hash, rather than a coincidental near-hash.

func ScreenPreview ¶ added in v0.2026269.700

func ScreenPreview(s ScreenSignature) string

ScreenPreview renders a signature for an evidence line.

func SetByDotPath ¶ added in v0.2026186.1019

func SetByDotPath(path, dotpath, valueYAML string) error

SetByDotPath edits the file at path, navigating into the YAML structure via dotpath (dot-separated keys) and replacing the leaf value with valueYAML (parsed as YAML so callers can pass scalars, lists, or maps). Comments and key order are preserved.

func SetMappingKey ¶ added in v0.2026241.1032

func SetMappingKey(m *yaml.Node, key string, val *yaml.Node)

SetMappingKey sets (or replaces) a top-level key in a YAML mapping node. The ONE shared helper for the section-preserving per-host charly.yml writers (deploykit.SaveDeployConfig, the GitClient cache, the ledger I/O) — R3.

func ShDoubleQuote ¶

func ShDoubleQuote(v string) string

ShDoubleQuote wraps a string in double quotes for a shell context where variable expansion MUST still happen (e.g. download URLs that template ${BUILD_ARCH}). Escapes the metachars that break out of a double-quoted string, but deliberately does NOT escape `$` so authored ${FOO} / $FOO still expand.

func ShDoubleQuotePath ¶

func ShDoubleQuotePath(v string) string

ShDoubleQuotePath escapes a PATH-list value for use INSIDE double quotes, leaving `$` unescaped so `$PATH` expands at sourcing time.

func ShQuoteArg ¶

func ShQuoteArg(v string) string

ShQuoteArg single-quotes an argument for POSIX shell embedding.

func ShQuoteEnv ¶

func ShQuoteEnv(v string) string

ShQuoteEnv single-quotes a value for POSIX sh (env.d export values). Inside single quotes nothing needs escaping except the single quote itself.

func ShellInitFilePath ¶

func ShellInitFilePath(shell ShellKind, home string) string

ShellInitFilePath returns the init file the managed block lands in for each shell under a home.

func SidecarConfigDir ¶ added in v0.2026198.358

func SidecarConfigDir() (string, error)

SidecarConfigDir returns the per-user directory where sidecar companion config files live (e.g. charly-foo-tailscale-serve.json), used by the `charly config remove` sidecar-config sweep.

func SortStrings ¶

func SortStrings(s []string)

SortStrings sorts s in place (ascending). A small insertion-free bubble sort, kept identical to the original package-main helper.

func SplitHostKey ¶ added in v0.2026197.1537

func SplitHostKey(key string) (name, arg string, ok bool)

SplitHostKey splits a "HOST:web" / "HOST:web:8080" key into the variable name and the remaining argument(s) (everything after the FIRST colon).

func SshConfigPath ¶ added in v0.2026186.739

func SshConfigPath(home string) string

SshConfigPath returns ~/.ssh/config for the user's home dir.

func SshFragmentPath ¶ added in v0.2026186.739

func SshFragmentPath(home string) string

SshFragmentPath returns ~/.config/charly/ssh_config for the user's home dir.

func StepDoMode ¶ added in v0.2026191.2205

func StepDoMode(s *spec.Step) spec.DoMode

StepDoMode maps the step keyword to the act/assert/instruct dispatch enum.

func StepID ¶ added in v0.2026191.2205

func StepID(origin string, stepIdx int) string

StepID returns the stable identifier used for plan-overlay merge lookups, depends_on references, and ${STEP_ID} substitution — a deterministic id derived from origin + position.

func StripManagedBlock ¶

func StripManagedBlock(existing, marker string) string

StripManagedBlock removes the begin/end fence pair (tagged with marker) and its body.

func SubstituteConsoleAnswers ¶ added in v0.2026266.2315

func SubstituteConsoleAnswers(s string, answers map[string]string) string

SubstituteConsoleAnswers replaces `{{name}}` placeholders in s with answers[name], single-pass and literal. An unknown placeholder is left verbatim so a mis-authored recipe is visible in the failing step rather than silently typing an empty string.

func TaskShellPreamble ¶

func TaskShellPreamble(candyVars, opEnv map[string]string) string

TaskShellPreamble returns the BUILD_ARCH/ARCH exports plus any candy vars + op env (sorted for deterministic output) so cmd: bodies can reference ${ARCH} / ${MY_CANDY_VAR} at deploy-time the same way they do at build-time.

func TestVarRefs ¶ added in v0.2026191.2033

func TestVarRefs(s string) []string

TestVarRefs returns the set of ${NAME[:arg]} references in s, as their fully-qualified keys (matching the env-map format used by ExpandTestVars). Used by the validator to catch typos at config time.

func TransferToRootful ¶ added in v0.2026190.848

func TransferToRootful(imageRef string) error

TransferToRootful pipes an image from rootless podman storage into rootful (sudo podman) storage via `podman save | sudo podman load`. Idempotent — returns nil immediately when the image already exists in rootful storage.

Used by RunPrivileged when engine.rootful=sudo because rootless and rootful podman maintain separate container-storage trees (~/.local/share/containers vs /var/lib/containers). Without this transfer, sudo podman run against a locally-built image falls back to a registry pull (which 403s for build-only images that were never pushed).

Surfaced 2026-05 by the cachyos / cachyos-pacstrap-builder pair — the first time the bootstrap-builder framework was exercised end-to-end on a host with rootless build + sudo run.

func UpscalePNG ¶ added in v0.2026266.2315

func UpscalePNG(pngBytes []byte, scale int) ([]byte, error)

UpscalePNG returns the PNG enlarged by an integer nearest-neighbour factor (scale <= 1 returns the bytes unchanged). Nearest-neighbour keeps glyph edges hard, which is what tesseract thresholds against; a smoothing filter blurs thin UI type. Exposed because the ENLARGEMENT ITSELF is a behavior worth pinning — tesseract read ZERO words from a real 1280x800 desktop capture at 1x, 2x and 3x and read it once enlarged, so a test asserts the output geometry.

func ValidatePlanSteps ¶ added in v0.2026197.1320

func ValidatePlanSteps(desc string, plan []spec.Step, eid string) []string

planvalidate.go — ValidatePlanSteps, the SHARED static plan-block validator (P12a: relocated from charly/plan_validate.go). It lives here — not candy/plugin-check — because the externalized validators `charly box validate` (candy/plugin-box) and the check/feature surfaces call it directly, so it must be reachable without importing a plugin candy. One copy, R3.

• description non-empty
• every step has exactly one keyword (StepKind())
• run/check steps carry exactly one Op verb; agent-* steps carry none

Returns a list of human-readable error strings (empty if OK).

func ValidateTagExpr ¶ added in v0.2026201.1934

func ValidateTagExpr(tag string) error

ValidateTagExpr syntax-checks an optional --tag expression (rejecting a malformed one) without keeping the parsed *TagExpr — moved from charly/check_feature_run.go (CHECK-wave), a pure wrapper with zero core-state coupling. It does NOT apply the parsed expression as a step filter: kit.RunPlan (the walk both hostFeatureBox, still core, and candy/plugin-check's pluginCheckRunFeatureLive drive) takes no tag-filter parameter and walks every step unconditionally — a confirmed, RCA'd, non-blocking gap (per-tag filtering was never wired past this parse), routed to the next check-correctness thematic batch.

func WalkPlans ¶

func WalkPlans(ctx context.Context, exec DeployExecutor, plans []spec.InstallPlanView, opts WalkOpts) ([]spec.ReverseOp, error)

WalkPlans executes every plan's steps on the venue and returns the combined teardown ops (plugin-renderable kinds echo the host-computed view.ReverseOps; host-engine kinds return theirs from RunHostStep). The caller folds them into its DeployReply.

func WrapUnlessExists ¶ added in v0.2026269.1353

func WrapUnlessExists(cmd, guard, verb string) string

WrapUnlessExists and WrapUnlessExistsBlock wrap cmd in the `unless_exists` capability GATE, or return cmd unchanged when the guard is empty. They share the gate's SEMANTICS and differ only in how the guarded list is terminated, because their call sites sit in genuinely different lexical contexts:

• WrapUnlessExists `else { cmd; }; fi` — one line. EmitDownload's payload is a single-quoted argument on ONE Containerfile RUN line, where a literal newline would end the instruction, so `;` is the only terminator available.
• WrapUnlessExistsBlock `else {\ncmd\n}; fi` — a payload that is a heredoc body or a multi-line script, already multi-line by construction, where a newline costs nothing.

The gate is evaluated where the step runs: on a distro that packages the tool, `distro:` package sections compile into the plan before the `plan:` steps, so the guarded path already exists by the time the step runs. The guard is shell-quoted in BOTH positions so a path containing a double quote or `$(…)` cannot corrupt the test or the message.

verb names the step kind in the skip message ("download", "run"), because a log that prints "skipping: X already present" for three different reasons is worse than one that says which step declined to run.

func WrapUnlessExistsBlock ¶ added in v0.2026269.1353

func WrapUnlessExistsBlock(cmd, guard, verb string) string

WrapUnlessExistsBlock is the newline-terminated form, for a payload that is already multi-line.

func WriteCandyRecord ¶ added in v0.2026190.848

func WriteCandyRecord(paths *LedgerPaths, rec *CandyRecord) error

WriteCandyRecord serializes rec into the `ledger:` section under ledger.candies[rec.Candy].

func WriteDeployRecord ¶ added in v0.2026190.848

func WriteDeployRecord(paths *LedgerPaths, rec *DeployRecord) error

WriteDeployRecord serializes rec into the `ledger:` section under ledger.deploys[rec.DeployID].

func WriteDeployRecordVia ¶ added in v0.2026190.848

func WriteDeployRecordVia(exec spec.DeployExecutor, paths *LedgerPaths, rec *DeployRecord) error

WriteDeployRecordVia is the executor-routed variant of WriteDeployRecord. Same semantics as AddCandyDeploymentVia but for deploy records.

func WriteVmSshStanza ¶ added in v0.2026186.739

func WriteVmSshStanza(home string, s VmSshStanza) error

WriteVmSshStanza adds (or replaces) a Host stanza in the managed fragment. Idempotent.