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

+78 -10
View File
@@ -11,6 +11,7 @@ import (
"strings"
"github.com/m3tam3re/agent-lib/internal/gitsource"
"github.com/m3tam3re/agent-lib/internal/labels"
)
// ClientConfig is the client configuration for sync: fleet-provided or
@@ -20,6 +21,14 @@ type ClientConfig struct {
Ref string `json:"ref,omitempty"`
Token string `json:"token,omitempty"`
TokenUser string `json:"token_user,omitempty"`
// Labels restricts delivery to unlabeled items plus items carrying one
// of these labels (see the labels package). nil = no filtering; an
// empty list = only unlabeled items.
Labels *[]string `json:"labels,omitempty"`
// LabelSource names where Labels came from: "admin", "user", "env",
// "flag" or "" when no labels apply. Not part of the file format.
LabelSource string `json:"-"`
}
// ConfigEnv names the override environment variables.
@@ -115,50 +124,102 @@ func (e *MissingConfigError) Error() string {
// default — first existing file wins. Explicit flag/env paths that do not
// exist are hard errors; a completely empty chain yields *MissingConfigError.
func LoadClientConfig(flagPath string) (*ClientConfig, error) {
path, ok, err := resolveConfigPath(flagPath)
path, desc, ok, err := resolveConfigPath(flagPath)
if err != nil {
return nil, err
}
if !ok {
return nil, &MissingConfigError{Chain: ConfigSearchChain(flagPath)}
}
return readClientConfig(path)
cfg, err := readClientConfig(path)
if err != nil {
return nil, err
}
cfg.LabelSource = labelSourceFor(cfg, desc)
return cfg, nil
}
// LoadOptionalConfig behaves like LoadClientConfig but returns (nil, nil)
// when no config exists anywhere — for runs that carry their own --repo.
// Malformed existing configs are still hard errors.
func LoadOptionalConfig(flagPath string) (*ClientConfig, error) {
path, ok, err := resolveConfigPath(flagPath)
path, desc, ok, err := resolveConfigPath(flagPath)
if err != nil {
return nil, err
}
if !ok {
return nil, nil
}
return readClientConfig(path)
cfg, err := readClientConfig(path)
if err != nil {
return nil, err
}
cfg.LabelSource = labelSourceFor(cfg, desc)
return cfg, nil
}
// resolveConfigPath walks the search chain and returns the config to read.
// The flag and env legs must exist when set (explicit intent); the user and
// admin legs are skipped when absent.
func resolveConfigPath(flagPath string) (path string, found bool, err error) {
func resolveConfigPath(flagPath string) (path, source string, found bool, err error) {
if flagPath != "" {
return flagPath, true, nil
return flagPath, "flag", true, nil
}
if envPath := os.Getenv(ConfigEnv); envPath != "" {
return envPath, true, nil
return envPath, "env", true, nil
}
if p := UserConfigPath(); p != "" {
if _, statErr := os.Stat(p); statErr == nil {
return p, true, nil
return p, "user", true, nil
}
}
admin := DefaultConfigPath()
if _, statErr := os.Stat(admin); statErr == nil {
return admin, true, nil
return admin, "admin", true, nil
}
return "", false, nil
return "", "", false, nil
}
func labelSourceFor(cfg *ClientConfig, source string) string {
if cfg.Labels == nil {
return ""
}
return source
}
// ApplyAdminLabels enforces admin-pinned labels: when the admin default
// config at adminPath exists and sets "labels", that value replaces
// whatever the chosen config said — user-level, env and flag configs can
// neither widen nor drop an admin selection. A missing admin file (or one
// without "labels") leaves cfg untouched. An admin file that exists but
// cannot be read or parsed is a hard error: the admin's intent is unknown,
// so no selection may be guessed.
func ApplyAdminLabels(cfg *ClientConfig, adminPath string) error {
data, err := os.ReadFile(adminPath)
if err != nil {
if os.IsNotExist(err) {
return nil
}
return fmt.Errorf("reading admin config %s for labels: %w", adminPath, err)
}
var admin struct {
Labels *[]string `json:"labels"`
}
if err := json.Unmarshal(data, &admin); err != nil {
return fmt.Errorf("admin config %s is not valid JSON: %w", adminPath, err)
}
if admin.Labels == nil {
return nil
}
for _, l := range *admin.Labels {
if !labels.ValidLabel(l) {
return fmt.Errorf("admin config %s: label %q must be lowercase letters, digits and dashes", adminPath, l)
}
}
pinned := append([]string{}, (*admin.Labels)...)
cfg.Labels = &pinned
cfg.LabelSource = "admin"
return nil
}
func readClientConfig(path string) (*ClientConfig, error) {
@@ -173,6 +234,13 @@ func readClientConfig(path string) (*ClientConfig, error) {
if cfg.RepoURL == "" {
return nil, fmt.Errorf("client config %s: repo_url is required", path)
}
if cfg.Labels != nil {
for _, l := range *cfg.Labels {
if !labels.ValidLabel(l) {
return nil, fmt.Errorf("client config %s: label %q must be lowercase letters, digits and dashes", path, l)
}
}
}
return &cfg, nil
}