Documentation
¶
Overview ¶
Package config implements the `da config` command subtree.
Per spec config-distribution-model §10 and proposal `.agents/proposals/config-explain-live-surface.md`, this subtree is the operator-facing surface for inspecting the effective configuration of a repository — what value won, which layer set it, and how to extract one specific field for scripts.
The first commands in this subtree are `da config explain` and `da config verify`. The remaining siblings (`sync`, `lint`) are scoped to other tasks (config-v2-migration/p4c).
The subtree intentionally consumes a minimal snapshot view of the manifest. Once the layered resolver from config-v2-migration/p1 / p1b lands in `internal/config/snapshot.go`, the snapshot helpers in this package are expected to delegate to it without changing the command surface.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrNoManifest = errors.New("no manifest")
Exported error sentinel used by tests to assert the "missing manifest" branch without string matching. Kept as a var (not const) because errors.Is expects a typed sentinel.
Functions ¶
func NewConfigCmd ¶
NewConfigCmd builds the `da config` command tree.
Types ¶
type Deps ¶
type Deps struct {
ErrorWithHints func(message string, hints ...string) error
UsageError func(message string, hints ...string) error
MaximumNArgsWithHints func(n int, hints ...string) cobra.PositionalArgs
ExactArgsWithHints func(n int, hints ...string) cobra.PositionalArgs
// JSON reports the resolved global `--json` flag, so `da config` honors the
// same persistent flag as every other command (status, workflow, kg) rather
// than defining its own local `--json`. Nil is treated as false.
JSON func() bool
// DryRun reports the resolved global `--dry-run` flag. Only the mutating
// `da config sync` consumes it (explain/verify/lint are read-only); sync
// short-circuits before the force re-resolve + lock rewrite when it is set,
// honoring the documented "preview mutations without applying" contract.
// Nil is treated as false, matching the mcp/settings DryRun wiring.
DryRun func() bool
}
Deps carries UX helpers from the root `commands` package without an import cycle (the same shape used by other subtrees like `commands/agents` and `commands/hooks`).
type FieldExplanation ¶
type FieldExplanation struct {
Field string `json:"field"`
Value any `json:"value"`
ActiveLayer string `json:"active_layer,omitempty"`
Layers []LayerValue `json:"layers"`
}
FieldExplanation is the JSON shape emitted by `da config explain <path> --json`. The shape is documented in the proposal at `.agents/proposals/config-explain-live-surface.md` and intentionally kept stable so scripts can pin against it.
type LayerValue ¶
type LayerValue struct {
Layer string `json:"layer"`
Value any `json:"value"`
Active bool `json:"active"`
}
LayerValue is one slot in a single field's provenance stack.
Active=true on exactly one entry per field, except when no layer sets the field (all entries Active=false, all Value=nil).
type LintReport ¶ added in v0.4.0
type LintReport struct {
OK bool `json:"ok"`
Results []LintResult `json:"results"`
}
LintReport is the stable JSON shape emitted by `da config lint --json`. OK is false iff any layer failed validation; skipped layers do not flip OK.
type LintResult ¶ added in v0.4.0
type LintResult struct {
// File is the layer's display label: "repo-local" for the project manifest,
// or the layer ref ("acme:org/base.json") for a declared extends layer.
File string `json:"file"`
// Path is the absolute path that was read (omitted for skipped remote layers
// with no local path).
Path string `json:"path,omitempty"`
Status string `json:"status"` // pass | fail | skip
// Detail carries the validation error on fail, or a short reason on skip.
Detail string `json:"detail,omitempty"`
}
LintResult is one validated file in the lint report.
type MigrateReport ¶ added in v0.4.1
type MigrateReport struct {
OK bool `json:"ok"`
Manifest string `json:"manifest"`
Backup string `json:"backup,omitempty"`
AlreadyV2 bool `json:"already_v2"`
FromVersion int `json:"from_version"`
ToVersion int `json:"to_version"`
FoldedKeys []string `json:"folded_keys,omitempty"`
WroteFile bool `json:"wrote_file"`
WroteBackup bool `json:"wrote_backup"`
DryRun bool `json:"dry_run,omitempty"`
}
MigrateReport is the stable JSON shape emitted by `da config migrate --json`. It mirrors cfg.MigrationResult's user-relevant fields so the machine-readable output is decoupled from the internal result struct.
type SyncReport ¶ added in v0.4.0
type SyncReport struct {
OK bool `json:"ok"`
Lockfile string `json:"lockfile"`
Layer string `json:"layer,omitempty"` // the --layer scope, if any
Layers []SyncedLayer `json:"layers"`
// DryRun is true when the report is a --dry-run preview: no layers were
// re-fetched and the lock was NOT rewritten. The Layers/SHA/FetchedAt fields
// reflect the CURRENT lock state (what WOULD be re-fetched), not a fresh fetch.
DryRun bool `json:"dry_run,omitempty"`
}
SyncReport is the stable JSON shape emitted by `da config sync --json`. OK is false only when the re-resolve itself failed (a fetch/transport/schema error on a non-optional layer); a project with no declared layers still re-resolves the local stack and reports OK with an empty Layers list.
type SyncedLayer ¶ added in v0.4.0
type SyncedLayer struct {
Ref string `json:"ref"`
SourceID string `json:"source_id,omitempty"`
SourceType string `json:"source_type,omitempty"`
SHA string `json:"sha,omitempty"`
FetchedAt string `json:"fetched_at,omitempty"`
Targeted bool `json:"targeted"`
Note string `json:"note,omitempty"`
}
SyncedLayer is one declared `extends` layer's outcome in a sync report: the ref, its source, the SHA + fetch timestamp recorded in the lockfile after the re-resolve, and whether this run actually targeted it. When `--layer` scopes the run to a single ref, the other declared layers report Targeted=false with a Note explaining they were left to their existing lock state.
type VerifyCheck ¶
type VerifyCheck struct {
Name string `json:"name"`
Status string `json:"status"` // pass | warn | fail
Detail string `json:"detail,omitempty"`
}
VerifyCheck is one line in the verify report.
type VerifyReport ¶
type VerifyReport struct {
OK bool `json:"ok"`
Checks []VerifyCheck `json:"checks"`
}
VerifyReport is the stable JSON shape emitted by `da config verify --json`. OK is false iff any check failed (warnings do not flip OK), so CI can gate on the top-level boolean without parsing individual checks.
Source Files