- Add internal/labels: parse and validate the optional work-repo file
agent-lib.labels.json (version 1; unlabeled items go to every client;
names match across types)
- Add "labels" to the client config: absent = no filtering, [] = unlabeled
items only; labels from the admin default config are pinned and cannot be
overridden by user, env or flag configs; a broken admin config aborts
- Filter in prepare() before planning; deselected items follow the
upstream-deletion rules (unmodified removed, modified kept + warn,
--force removes) with reason "not selected for this client's labels"
- Abort sync before any change when the labels file does not validate;
names that match no item only warn on the client
- Report the active selection in sync output and status (--json: labels
object with client, source, labels_file, not_selected, unknown_names)
- validate checks the labels file, including that every name resolves to
an own, vendored or MCP item
- Document in README ("Client labels"), fleet handoff and the proposal;
revise the "client-side selection" non-goal
- Tests: labels parser, config precedence, planner deselection, e2e for
filter/remove/keep-modified/abort/unknown names, validate
Refs: agent_lib-fh4
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
172 lines
5.1 KiB
Go
172 lines
5.1 KiB
Go
package client
|
|
|
|
import "sort"
|
|
|
|
// Action is one step of a sync plan.
|
|
type Action string
|
|
|
|
// The six sync actions. skip warns about managed items with local
|
|
// modifications; leave warns about self-created items agent-lib never
|
|
// managed; remove only ever touches unmodified managed copies.
|
|
const (
|
|
ActDeploy Action = "deploy"
|
|
ActUpdate Action = "update"
|
|
ActSkip Action = "skip+warn"
|
|
ActLeave Action = "leave+warn"
|
|
ActRemove Action = "remove"
|
|
ActKeep Action = "keep"
|
|
)
|
|
|
|
// ReasonNotSelected explains removals caused by the client's labels.
|
|
const ReasonNotSelected = "not selected for this client's labels"
|
|
|
|
// PlanOptions tune planning. Force overwrites/removes locally modified
|
|
// managed items; Deselected holds manifest keys filtered out by labels.
|
|
type PlanOptions struct {
|
|
Force bool
|
|
Deselected map[string]bool
|
|
}
|
|
|
|
// PlannedItem is one deployable inventory item with its repo-side hash.
|
|
type PlannedItem struct {
|
|
Type string
|
|
Name string
|
|
Origin string
|
|
RelPath string
|
|
Hash string
|
|
}
|
|
|
|
// DiskFact is the observed on-disk state of one deployed path.
|
|
type DiskFact struct {
|
|
Exists bool
|
|
Hash string
|
|
}
|
|
|
|
// PlanEntry is one decided action with everything the executor needs.
|
|
type PlanEntry struct {
|
|
Action Action
|
|
Type string
|
|
Name string
|
|
Origin string
|
|
RelPath string
|
|
DstPath string
|
|
NewHash string
|
|
Reason string
|
|
}
|
|
|
|
// Plan is a pure function from (inventory, manifest, on-disk facts) to an
|
|
// action plan. pathFor injects the target path mapping so the planner never
|
|
// touches the filesystem or the environment. The plan is sorted by
|
|
// (type, name) for deterministic execution and reporting. With force set,
|
|
// locally modified managed items are overwritten with the upstream version
|
|
// (and removed after upstream deletion) instead of being skipped; items
|
|
// agent-lib never managed are never touched, even with force.
|
|
//
|
|
// Deselected marks keys that exist upstream but are not selected for this
|
|
// client's labels. Planning treats them exactly like upstream deletions —
|
|
// only the reasons differ, so users learn why an item went away.
|
|
func Plan(items []PlannedItem, manifest *Manifest, disk map[string]DiskFact, pathFor func(typ, name string) string, opts PlanOptions) []PlanEntry {
|
|
force := opts.Force
|
|
invByKey := map[string]PlannedItem{}
|
|
for _, it := range items {
|
|
invByKey[manifestKey(it.Type, it.Name)] = it
|
|
}
|
|
|
|
var plan []PlanEntry
|
|
emit := func(a Action, it PlannedItem, reason string) {
|
|
e := PlanEntry{Action: a, Reason: reason, NewHash: it.Hash}
|
|
e.Type, e.Name, e.Origin, e.RelPath = it.Type, it.Name, it.Origin, it.RelPath
|
|
e.DstPath = pathFor(e.Type, e.Name)
|
|
plan = append(plan, e)
|
|
}
|
|
|
|
keys := map[string]bool{}
|
|
for key := range invByKey {
|
|
keys[key] = true
|
|
}
|
|
for key := range manifest.Items {
|
|
keys[key] = true
|
|
}
|
|
for key, fact := range disk {
|
|
if fact.Exists {
|
|
keys[key] = true
|
|
}
|
|
}
|
|
sorted := make([]string, 0, len(keys))
|
|
for key := range keys {
|
|
sorted = append(sorted, key)
|
|
}
|
|
sort.Strings(sorted)
|
|
|
|
for _, key := range sorted {
|
|
it, inInv := invByKey[key]
|
|
rec := manifest.Items[key]
|
|
fact := disk[key]
|
|
gone := "upstream deleted"
|
|
if opts.Deselected[key] {
|
|
gone = ReasonNotSelected
|
|
}
|
|
|
|
switch {
|
|
case inInv && rec == nil:
|
|
if fact.Exists {
|
|
emit(ActSkip, it, "path occupied by a local item agent-lib never deployed; deploy blocked")
|
|
} else {
|
|
emit(ActDeploy, it, "")
|
|
}
|
|
case inInv && it.Hash == rec.Hash:
|
|
decideAgainstDisk(it, rec, fact, emit, "unchanged", force)
|
|
case inInv:
|
|
decideAgainstDisk(it, rec, fact, emit, "changed", force)
|
|
case rec != nil && !fact.Exists:
|
|
emit(ActRemove, PlannedItem{Type: rec.Type, Name: rec.Name, Origin: rec.Origin}, "already gone from disk; dropping manifest record")
|
|
case rec != nil && fact.Hash == rec.Hash:
|
|
emit(ActRemove, PlannedItem{Type: rec.Type, Name: rec.Name, Origin: rec.Origin}, gone)
|
|
case rec != nil && force:
|
|
emit(ActRemove, PlannedItem{Type: rec.Type, Name: rec.Name, Origin: rec.Origin}, gone+"; forced removal of the locally modified copy")
|
|
case rec != nil:
|
|
emit(ActSkip, PlannedItem{Type: rec.Type, Name: rec.Name, Origin: rec.Origin},
|
|
gone+" but the local copy was modified; keeping it")
|
|
default:
|
|
emit(ActLeave, PlannedItem{Type: typeOfKey(key), Name: nameOfKey(key)},
|
|
"unmanaged local item; left untouched")
|
|
}
|
|
}
|
|
return plan
|
|
}
|
|
|
|
func decideAgainstDisk(it PlannedItem, rec *ManifestItem, fact DiskFact, emit func(Action, PlannedItem, string), upstreamState string, force bool) {
|
|
switch {
|
|
case !fact.Exists:
|
|
emit(ActUpdate, it, "managed item missing on disk; restoring")
|
|
case fact.Hash == rec.Hash:
|
|
if upstreamState == "unchanged" {
|
|
emit(ActKeep, it, "")
|
|
} else {
|
|
emit(ActUpdate, it, "")
|
|
}
|
|
case force:
|
|
emit(ActUpdate, it, "forced: locally modified copy overwritten")
|
|
default:
|
|
emit(ActSkip, it, "locally modified; keeping the local version (upstream "+upstreamState+")")
|
|
}
|
|
}
|
|
|
|
func typeOfKey(key string) string {
|
|
for i := len(key) - 1; i >= 0; i-- {
|
|
if key[i] == '/' {
|
|
return key[:i]
|
|
}
|
|
}
|
|
return key
|
|
}
|
|
|
|
func nameOfKey(key string) string {
|
|
for i := len(key) - 1; i >= 0; i-- {
|
|
if key[i] == '/' {
|
|
return key[i+1:]
|
|
}
|
|
}
|
|
return key
|
|
}
|