feat(client): deliver items only to clients with a matching label

- 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>
This commit is contained in:
m3ta-chironandClaude Opus 5.5 committed 2026-11-14 10:36:07 +01:00
1 parent 39952ceb02
commit 59735c3b24
16 files changed
+904 -38

No files matched your search

+128
View File
@@ -0,0 +1,128 @@
// Package labels parses the optional work-repository file that restricts
// items to clients carrying a matching label.
//
// Semantics: an item that appears under no label is delivered to every
// client; an item that appears under one or more labels is delivered to a
// client that carries at least one of them. Entries are deployed item names
// and match across types (a skill and a command of the same name are both
// covered by one entry).
package labels
import (
"bytes"
"encoding/json"
"fmt"
"regexp"
"sort"
)
// FileName is the labels file at the work-repository root.
const FileName = "agent-lib.labels.json"
// Version is the only file format version this binary understands.
const Version = 1
var labelForm = regexp.MustCompile(`^[a-z0-9][a-z0-9-]*$`)
// ValidLabel reports whether s has the required label form.
func ValidLabel(s string) bool { return labelForm.MatchString(s) }
// File is a parsed labels file.
type File struct {
Version int `json:"version"`
Labels map[string][]string `json:"labels"`
byItem map[string][]string
}
// Parse decodes and validates a labels file strictly: unknown keys, an
// unsupported version, malformed labels, empty lists and empty names are
// errors. A file that does not validate must never be applied.
func Parse(data []byte) (*File, error) {
dec := json.NewDecoder(bytes.NewReader(data))
dec.DisallowUnknownFields()
var f File
if err := dec.Decode(&f); err != nil {
return nil, fmt.Errorf("%s is not valid: %w", FileName, err)
}
if dec.More() {
return nil, fmt.Errorf("%s is not valid: trailing data after the JSON object", FileName)
}
if f.Version != Version {
return nil, fmt.Errorf("%s: unsupported version %d (this binary understands version %d)", FileName, f.Version, Version)
}
if f.Labels == nil {
return nil, fmt.Errorf("%s: \"labels\" is required (use {} for no restrictions)", FileName)
}
f.byItem = map[string][]string{}
for _, label := range f.SortedLabels() {
names := f.Labels[label]
if !ValidLabel(label) {
return nil, fmt.Errorf("%s: label %q must match %s", FileName, label, labelForm)
}
if len(names) == 0 {
return nil, fmt.Errorf("%s: label %q has an empty item list (remove the label instead)", FileName, label)
}
for _, name := range names {
if name == "" {
return nil, fmt.Errorf("%s: label %q contains an empty item name", FileName, label)
}
if !contains(f.byItem[name], label) {
f.byItem[name] = append(f.byItem[name], label)
}
}
}
return &f, nil
}
// SortedLabels returns the declared labels in stable order.
func (f *File) SortedLabels() []string {
out := make([]string, 0, len(f.Labels))
for l := range f.Labels {
out = append(out, l)
}
sort.Strings(out)
return out
}
// Names returns every item name the file mentions, sorted and unique.
func (f *File) Names() []string {
out := make([]string, 0, len(f.byItem))
for n := range f.byItem {
out = append(out, n)
}
sort.Strings(out)
return out
}
// LabelsOf returns the labels an item carries (nil = unlabeled).
func (f *File) LabelsOf(name string) []string {
if f == nil {
return nil
}
return f.byItem[name]
}
// Selected reports whether an item goes to a client carrying clientLabels.
// Unlabeled items always do; a nil file restricts nothing.
func (f *File) Selected(name string, clientLabels []string) bool {
itemLabels := f.LabelsOf(name)
if len(itemLabels) == 0 {
return true
}
for _, l := range itemLabels {
if contains(clientLabels, l) {
return true
}
}
return false
}
func contains(list []string, s string) bool {
for _, v := range list {
if v == s {
return true
}
}
return false
}