Reference and Map
This page is the index to the codebase: the commands a user can run, the packages that back them, and the types that recur across the subsystem pages.
Where it lives
cmd: the entire CLI, one file per command, built on choria-io/fisk. main is in
cmd/ccm.go. Shared plumbing, including manager construction and the .env reader, is in
cmd/util.go.
Command surface
Every ccm command builds a manager and drives a subsystem covered elsewhere in this map. The
global flags --debug and --info set log verbosity.
| Command | Purpose | Drives |
|---|---|---|
ccm ensure <type> | Manage one resource imperatively: archive, exec, file, package, scaffold, service | Resource-Provider Model |
ccm ensure api piped | Apply a resource sent as JSON or YAML on stdin | Resource-Provider Model |
ccm apply <manifest> | Apply a manifest from a file, obj://, or https:// tarball | Apply Engine |
ccm agent --config <file> | Run the continuous manifest daemon | The Agent |
ccm facts [query] | Show system facts, with an optional gjson query | Data, Facts, and Templates |
ccm hiera parse <input> | Resolve a Hiera input against facts | Data, Facts, and Templates |
ccm registration create / query / watch / rm / init | Publish, read, watch, remove entries, or provision the stream | Registration and Discovery |
ccm session new / report | Create a session store or summarize one | Observability |
ccm status <type> <name> | Read the current state of a resource | Resource-Provider Model |
Every ensure subcommand and the piped API funnel through one factory,
resources.NewResourceFromProperties, so the CLI, manifests, and the wire API run identical
resource logic. The status command’s valid types are generated at run time from the registry,
so it tracks whatever providers are registered.
Source map
| Package | Contents |
|---|---|
cmd/ | The fisk CLI surface, main, one file per command, shared helpers in util.go. |
agent/ | The continuous runner: config, worker loop, and NATS, HTTP, and object-store sources. |
facts/ | System fact collectors backed by gopsutil, plus file-based facts. |
hiera/ | The hierarchical data resolver and comment-driven validation. |
templates/ | The render environment and the expr, Jet, and Go template engines. |
manager/ | The concrete model.Manager (type CCM), its options, and logger adapters. |
model/ | Core interfaces and shared structs; per-resource property types; modelmocks/. |
registration/ | Service registration over JetStream: stream, subjects, publish, lookup, watch. |
resources/ | Resource implementations, the shared base, the apply engine, and provider subpackages. |
internal/registry/ | The global provider directory and FindSuitableProvider. |
internal/session/ | The directory and memory session stores. |
internal/metrics/ | Prometheus collectors and the /metrics server. |
internal/healthcheck/ | The goss and nagios health-check runners. |
internal/ (other) | cmdrunner, backoff, fs (embedded schemas), and util helpers. |
Key types
| Type | Role | Explained in |
|---|---|---|
model.Manager (CCM) | The orchestrator every layer programs against | Architecture |
model.Provider / ProviderFactory | The provider seam and its registration unit | Architecture |
model.Resource / ResourceProperties | A managed thing and its declarative desired state | Resource-Provider Model |
base.Base / EmbeddedResource | The shared apply flow and its callback interface | Resource-Provider Model |
model.Apply / TransactionEvent | A parsed manifest and the per-resource result record | Apply Engine |
hiera.Resolve / templates.Env | Data resolution and the render environment | Data, Facts, and Templates |
model.RegistrationEntry | A published service-discovery entry | Registration and Discovery |
model.SessionStore / SessionSummary | Event storage and run aggregation | Observability |
agent.Agent | The continuous loop and its workers | The Agent |
Glossary
- Resource
- A system component to manage: a package, file, service, exec, archive, or scaffold. Declares a desired state.
- Provider
- The platform-specific implementation for a resource type, such as apt, dnf, systemd, or posix. Selected at run time by facts.
- Ensure
- The desired state of a resource, such as present, absent, running, or a package version.
- Manifest
- A YAML document of data, a hierarchy, and a list of resources, applied as a unit.
- Facts
- Gathered truths about the host, used to select providers and drive the data hierarchy.
- Hiera
- The hierarchical data resolver that merges layered data blocks, chosen by facts, into one resolved map.
- Session
- The record of a run: a sequence of events, stored in memory or on disk, that drives require and subscribe.
- Noop
- Dry-run mode. No change is made, but the event still reports what would have changed.
- Require
- A fail-gate: a resource is skipped if a named prior resource failed. Not a scheduler.
- Subscribe / refresh
- A resource, in practice a service, restarts when a named prior resource changed.
- register_when_stable
- A resource property that publishes a discovery entry once the resource is stable and healthy.
Back to the start
Return to the Code Map overview for the mental model and the full page list.