Documentation
¶
Overview ¶
Package state owns the .txco/<stack>.state.json file the txco CLI writes after a `pull` and reads on `push`. It pins which version of a stack a local workspace mirrors PER TARGET, so subsequent pushes set the right parent_version_number on the new draft and the fast-forward guard compares against the right chassis.
State files are tiny JSON blobs at the root of the local workspace alongside the OPS/ directory:
./OPS/hello-world/... ./.txco/hello-world.state.json
One file per stack, one entry per target key inside it ({"targets": {"<addr>|<tenant>": {...}}}). Before 2026-09-01 the file was a single flat entry with no record of WHICH chassis it mirrored, so every dev↔prod alternation read the other environment's number and the guard refused with a phantom rollback (onepony 0012 §7b trap 9). A legacy flat file reads as "no baseline" for every target and is rewritten in the keyed shape on the next Save — self-healing, one guard-blind window per stack.
Nested stack names (e.g. "website/canary") use a hyphen-separated filename ("website-canary.state.json") so we don't have to create nested directories under .txco/. Workspace roots are mutable; we don't try to detect renames.
Index ¶
Constants ¶
const Dir = ".txco"
Dir is the workspace-relative directory that holds state files.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type State ¶
type State struct {
// VersionNumber is the per-stack number this workspace mirrors —
// the same int users see in `txco versions <stack>` and in URLs.
VersionNumber int64 `json:"version_number"`
// ParentVersionNumber is what the next `push` will set as the new
// draft's parent_version_number. After a sync it equals VersionNumber.
// Both `pull` (fetch-based sync) and `push`/`apply` (which deploy the
// local files and activate them) record a synced row with parent ==
// version; `activate`/`draft` never write state (they don't establish
// local==version).
ParentVersionNumber int64 `json:"parent_version_number"`
// ManifestHash is the manifest of VersionNumber's code: the one the
// server reported at pull time, or the local build's when push, apply
// or sync found the tree to be that version. `apply --changed` and
// pull's dirty check key on it.
ManifestHash string `json:"manifest_hash"`
// TreeHash is the hash of the local tree as `txco status` builds it
// (ops as written, no derived rows), taken when the tree was known to
// be this version — so status can say "(clean)" without compiling.
// Empty when unknown (a pull, an older CLI): status compares
// ManifestHash instead.
TreeHash string `json:"tree_hash,omitempty"`
}
State is what the CLI persists per pulled stack.
func Load ¶
Load reads the state entry for `stack` under workspace `root`, for the target identified by `key` (see Key). Returns (nil, nil) when no entry exists for that target — callers default to "no parent" rather than failing, so a manual `txco push <stack>` against a hand-built OPS/ tree still works. A legacy flat file also reads as (nil, nil): its number is unattributable to any target, which is exactly the bug the keyed shape exists to fix.