Typed-component output system — the sole interface for terminal output
across cfgd. See .claude/specs/2026-05-14-output-system-redesign-design.md
for the design.
Display adapter returned by PathDisplayExt::posix. On Windows,
renders the path with \ → / substitution; on Unix it’s
indistinguishable from Path::display().
RAII guard returned by with_test_home_guard — restores the prior
override on drop. Used by test harnesses (like TestEnvBuilder) that want
to install an override without wrapping the whole test in a closure.
Named exponential-histogram bucket presets for latency metrics. Kept in
cfgd-core so the SLO-adjacent choice is auditable in one place rather
than divergent inline calls in cfgd-operator and cfgd-csi. Consumers
feed the triple into prometheus_client::metrics::histogram::exponential_buckets(start, factor, length).
Grace period between SIGTERM and SIGKILL when a watchdog kills a child.
A SIGTERM-trapping child gets a chance to clean up; if it’s still alive
past this window the watchdog escalates to SIGKILL so the daemon can
reclaim the slot regardless of what the child does.
Display-only extension for human-facing path output. On Windows, folds
\ → / so a status subject or error message shows POSIX-form paths
consistently across runners. On Unix, passes through unchanged — a
legitimate \ in a Unix filename survives byte-for-byte.
Like capture_file_state, but follows symlinks to capture the resolved
content. For symlinks, is_symlink and symlink_target are recorded AND
the actual file content behind the symlink is read. This is used for
post-apply snapshots where we need to know both the link target and the
content that was accessible through the symlink at the time of capture.
Check if a command is available on the system via PATH lookup.
On Windows, tries common executable extensions (.exe, .cmd, .bat, .ps1, .com)
since executables require an extension to be found.
Like command_available but also returns true when the env-var seam
points at an existing file. Use in is_available() checks where the
caller wants a bool, not a Result.
Run a [Command] with a timeout. On timeout the watchdog sends SIGTERM,
waits KILL_GRACE_PERIOD for the child to exit cleanly, then escalates
to SIGKILL (Unix) / TerminateProcess retry (Windows).
Create a symbolic link. On Unix, uses std::os::unix::fs::symlink.
On Windows, uses symlink_file or symlink_dir based on the source type.
If symlink creation fails on Windows due to insufficient privileges,
returns an error with guidance to enable Developer Mode or run as admin.
Escape a value for use inside bash/zsh double quotes (single pass).
Escapes \, ", `, and ! — the four characters with special
meaning inside double-quoted strings.
Send an uncatchable kill signal to a process by PID after the graceful
terminate window has elapsed. Unix: SIGKILL. Windows: a second
TerminateProcess call (idempotent — Windows kills are already uncatchable).
User-input path tolerance: accept C:\foo, C:/foo, ~/foo, ./foo.
Folds \ → / and expands a leading ~ via expand_tilde. Use when
loading config fields where a Linux author may write / and a Windows
author may write \ for the same logical location.
Build a Command for git suitable for LOCAL operations (config get/set,
tag verify, add, commit, log). Sets GIT_TERMINAL_PROMPT=0 to prevent
any prompt-driven hang, but does NOT set GIT_SSH_COMMAND because no
network is involved. Use git_cmd_safe for any operation that talks to
a remote.
Strip filename-unsafe characters (:, -, T, Z) from an ISO 8601
timestamp so it can be used as a path segment. Helper extracted from three
inline replace calls in oci/build, cli/module/keys, and gateway/api/drift.
Merge env vars by name: later entries override earlier ones with the same name.
Used by config layer merging, composition, and reconciler module merge.
Composite normalizer for snapshot tests: CRLF→LF, fold \→/, then
substitute each (path, placeholder) pair. Substitutions are applied
longest-first to handle nested temp paths correctly (e.g. when
<BARE>/inner and <BARE_ROOT> both match, longest wins). Each path is
posixified before substitution so the captured text and the substitution
keys share the same separator convention.
Parse a potentially loose version string into a semver Version.
Handles “1.28” → “1.28.0”, “1” → “1.0.0”, and a leading v/V prefix
(v1.10.0 → 1.10.0) so callers can feed git/OCI tag names directly.
Collapse OS-specific std::io::Error text in captured snapshot output.
Linux emits ... File exists (os error 17) for ErrorKind::AlreadyExists;
Windows emits ... Cannot create a file when that file already exists. (os error 183) for the same kind. Both fold to a stable <os error>
placeholder so a single golden file works on both.
Fold \ → / in free-form text that may contain native-separator paths.
Cow so the unix path stays borrowed; only Windows captures pay for the
allocation.
Verify cosign is available, honoring the CFGD_COSIGN_BIN test seam.
Delegates to [require_tool_with_seam] to share the env-var-override logic
with every other shimmable tool in cfgd-core.
Check that a CLI tool is available on PATH, returning a unified error
string otherwise. Before this helper, six if !command_available("X")
gates across oci.rs and cli/module.rs each produced a slightly
different “not found” message; strings had diverged in production. Pass
install_hint (a short imperative like “install it from https://…”)
to make the hint specific; None falls back to a generic “install it
or add it to PATH”.
Resolve a relative path against a base directory with traversal validation.
Absolute paths are returned as-is. Relative paths are joined to base and
validated with validate_no_traversal. Returns Err if the relative path
contains .. components.
Sanitize a string for use as a Kubernetes object name (RFC 1123 DNS label).
Lowercases, replaces underscores with hyphens, filters non-alphanumeric chars,
and trims leading/trailing hyphens.
Build a file:// URL that round-trips through url::Url::parse on both
unix (file:///home/foo) and Windows (file:///C:/Users/foo). Replaces
every hand-rolled format!("file://{}", path.display()) callsite that
silently emits backslashes and a missing third slash on Windows.
Always-fold POSIX form of a path. Use anywhere a path crosses into JSON,
YAML, SQLite, gateway API, OCI annotations, file:// URLs, or snapshot
goldens. Backslash is treated as a separator; legitimate backslash-in-
filename on POSIX is sacrificed for cross-OS state portability (see the
path-handling consolidation spec for the fold-policy rationale).
Resolve an external tool’s binary path, honoring a per-tool env-var test
seam. Production code reads no env var and gets default (which Command
resolves via PATH); tests set env_var to an absolute path of a shim
binary. This is the SOLE supported override pattern for external CLIs.
Build a Command for an external tool, honoring tool_binary_name’s
env-var override. Sets stderr to piped so callers can surface the
tool’s stderr in error messages without spamming the user’s terminal.
Build a tracing_subscriber::EnvFilter from RUST_LOG if set, falling
back to default. Consolidates the four identical
EnvFilter::try_from_default_env().unwrap_or_else(|_| EnvFilter::new(..))
scaffolds in cfgd/main.rs, cfgd/cli/plugin.rs, cfgd-operator/main.rs,
and cfgd-csi/main.rs.
Install a HOME override for the current thread and return a guard that
restores the prior value on drop. Use in test builders that need the
override to outlive a single closure call.