Documentation
¶
Overview ¶
Package status reports what should be present, where it should have come from, and what's missing or different (phase-8 step 47 slice 3 — `writ status` replaces `writ reconcile`).
Status is report-only: it mutates nothing, and each finding names the lifecycle command that repairs it (missing → `writ deploy`; stale → `writ upgrade`; modified → `writ upgrade --force`; orphan → `writ decommission`). The report has four sections: the registered layer tree (the "where from"), the deployed inventory per scope (the fold, classified against the live filesystem), the package operations writ's runs performed (fact-of-record), and store health (the run index's missing-piece detection). A missing run index is a hard error per the settled design — status refuses to report from silence. Drift attribution (stale vs. modified) reads the run's recorded as-deployed content identity (step 48); runs traced before the capture report differing targets as modified-or-stale (indeterminate). Document-signature verification is `writ verify` (step 46).
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Config ¶
type Config struct {
// Projects filters the inventory section; empty reports every project.
Projects []string
// JSON emits the report as JSON instead of human-readable text.
JSON bool
// Verbose narrates store detail via the shared console narrator.
Verbose bool
// Segments are the platform/custom segments for the freshness comparison.
Segments segment.Segments
// Vars are the user-configured template variables for the freshness comparison.
Vars map[string]any
}
Config carries the resolved settings for one status report.
type Entry ¶
type Entry struct {
// Target is the absolute deployed path.
Target string `json:"target"`
// Source is the absolute source path the target was deployed from.
Source string `json:"source"`
// Project is the owning project.
Project string `json:"project"`
// Layer is the contributing layer, or "" in single-source mode.
Layer string `json:"layer,omitempty"`
// Scope is the target scope ("system" / "home", or "" for unscoped runs).
Scope string `json:"scope,omitempty"`
// Action is the target-producing action name.
Action string `json:"action"`
// State is the classification against the live filesystem.
State State `json:"state"`
// Repair names the lifecycle command that repairs the finding, or "" when none applies.
Repair string `json:"repair,omitempty"`
// Message elaborates the classification for human readers.
Message string `json:"message,omitempty"`
}
Entry is one classified inventory row.
type Health ¶
type Health struct {
// Runs is the number of traces folded into the inventory.
Runs int `json:"runs"`
// Findings are the missing-piece detections (index entries whose documents are gone, documents the index
// never recorded).
Findings []string `json:"findings,omitempty"`
}
Health is the store's self-report.
type Layer ¶
type Layer struct {
// Name is the layer name: "base", "team", or "personal".
Name string `json:"name"`
// Path is the layer's location under the writ layers directory.
Path string `json:"path"`
// State is "absent", "directory", "link", or "broken-link".
State string `json:"state"`
// Target is the resolved link target when State is "link".
Target string `json:"target,omitempty"`
}
Layer is one conventional layer's registration status.
type Report ¶
type Report struct {
// Layers is the registered layer tree — the "where from".
Layers []Layer `json:"layers"`
// Entries is the classified deployed inventory, sorted by target.
Entries []Entry `json:"entries"`
// Packages records the package operations writ's runs performed, fact-of-record.
Packages []readback.PackageRecord `json:"packages,omitempty"`
// Health is the store's self-report: folded runs and missing-piece findings.
Health Health `json:"health"`
}
Report is the four-section status report.
func BuildReport ¶
BuildReport derives the four-section status report from the store and the live filesystem.
Parameters:
- `ctx`: the context for the store fold.
- `cfg`: the resolved status configuration.
Returns:
- `*Report`: the assembled report.
- `error`: non-nil when the run index is missing or the fold fails.
type State ¶
type State int
State classifies one inventory entry against the live filesystem.
const ( // StateLinked means the symlink exists and resolves to its source. StateLinked State = iota // StateCopied means the copied file is present (and matches a fresh result when comparable). StateCopied // StateMissing means the deployed target is gone. StateMissing // StateConflict means something else occupies the target (wrong kind, wrong link endpoint, unreadable). StateConflict // StateOrphan means the target exists but its source is gone. StateOrphan // StateModifiedOrStale means a comparable copied target differs from a fresh result and the run predates // the step-48 recorded identity — a source change and a local edit are indistinguishable. StateModifiedOrStale // StateStale means the target is unchanged since deployment (its digest equals the recorded as-deployed // identity) and the source moved; `writ upgrade` regenerates it freely. StateStale // StateModified means the target was edited locally after deployment (its digest differs from the // recorded identity); `writ upgrade --force` overwrites. StateModified )
func (State) Label ¶
Label returns the machine-readable classification name.
Returns:
- `string`: the lowercase label.
func (State) MarshalJSON ¶
MarshalJSON encodes the state as its label.
Returns:
- `[]byte`: the JSON-encoded label.
- `error`: any error from json.Marshal.
Source Files