From 59735c3b246910e08c5781c4560523ef6d3ed14a Mon Sep 17 00:00:00 2001 From: m3ta-chiron Date: Sat, 14 Nov 2026 10:36:07 +0100 Subject: [PATCH] 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 --- .beads/issues.jsonl | 2 +- README.md | 62 ++++++++- docs/fleet-handoff.md | 4 + docs/proposals/client-labels.md | 18 ++- internal/cli/query.go | 4 + internal/client/config.go | 88 +++++++++++-- internal/client/config_test.go | 100 ++++++++++++++ internal/client/planner.go | 27 +++- internal/client/planner_test.go | 40 +++++- internal/client/status.go | 24 ++-- internal/client/sync.go | 105 ++++++++++++++- internal/e2e/labels_test.go | 166 ++++++++++++++++++++++++ internal/labels/labels.go | 128 ++++++++++++++++++ internal/labels/labels_test.go | 76 +++++++++++ internal/vendor/labels_validate_test.go | 61 +++++++++ internal/vendor/query.go | 37 ++++++ 16 files changed, 904 insertions(+), 38 deletions(-) create mode 100644 internal/e2e/labels_test.go create mode 100644 internal/labels/labels.go create mode 100644 internal/labels/labels_test.go create mode 100644 internal/vendor/labels_validate_test.go diff --git a/.beads/issues.jsonl b/.beads/issues.jsonl index 0ee87d8..506eba8 100644 --- a/.beads/issues.jsonl +++ b/.beads/issues.jsonl @@ -1,4 +1,4 @@ -{"_type":"issue","id":"agent_lib-fh4","title":"Client labels: deliver items only to clients with a matching label","description":"Design: docs/proposals/client-labels.md (proposed 14.11.2026).\n\nOptional repo file agent-lib.labels.json ({version:1, labels:{label:[item names]}}); unlabeled items go to everyone. Client config gains 'labels'; absent = no filtering, [] = only unlabeled. Admin default config's labels win over user/env config. Invalid labels file aborts sync before any disk change. Filter before planning (internal/client/sync.go loop over inv.Deployable()); deselected items reuse the upstream-deleted path with reason 'not selected for this client's labels'. status --json reports labels/source/filtered; validate checks the file (names resolve incl. MCP). Revises README non-goal 'client-side selection or profiles'.\n\nConsumer: az-agent-defaults (agent-lib.labels.json already prepared) + az-fleet agent_lib role.","acceptance_criteria":"Tests per proposal section 'Tests' green; README documents file format, config field, admin precedence; release tagged; second sync with labels is a byte-level no-op.","status":"open","priority":2,"issue_type":"feature","owner":"m3ta-chiron@agentmail.to","created_at":"2026-11-14T09:11:57Z","created_by":"m3ta-chiron","updated_at":"2026-11-14T09:11:57Z","dependency_count":0,"dependent_count":0,"comment_count":0} +{"_type":"issue","id":"agent_lib-fh4","title":"Client labels: deliver items only to clients with a matching label","description":"Design: docs/proposals/client-labels.md (proposed 14.11.2026).\n\nOptional repo file agent-lib.labels.json ({version:1, labels:{label:[item names]}}); unlabeled items go to everyone. Client config gains 'labels'; absent = no filtering, [] = only unlabeled. Admin default config's labels win over user/env config. Invalid labels file aborts sync before any disk change. Filter before planning (internal/client/sync.go loop over inv.Deployable()); deselected items reuse the upstream-deleted path with reason 'not selected for this client's labels'. status --json reports labels/source/filtered; validate checks the file (names resolve incl. MCP). Revises README non-goal 'client-side selection or profiles'.\n\nConsumer: az-agent-defaults (agent-lib.labels.json already prepared) + az-fleet agent_lib role.","acceptance_criteria":"Tests per proposal section 'Tests' green; README documents file format, config field, admin precedence; release tagged; second sync with labels is a byte-level no-op.","notes":"14.11.: implementiert auf Branch feat/client-labels (internal/labels, config labels + ApplyAdminLabels, Filter in prepare(), PlanOptions.Deselected, status/sync-Ausgabe, validate-Check, README/fleet-handoff). go test ./... grün, Windows-Build ok, echter Sync gegen az-agent-defaults geprüft. Offen: Review, Merge, Release-Tag. Nicht committet.","status":"in_progress","priority":2,"issue_type":"feature","assignee":"m3ta-chiron","owner":"m3ta-chiron@agentmail.to","created_at":"2026-11-14T09:11:57Z","created_by":"m3ta-chiron","updated_at":"2026-11-14T09:31:19Z","started_at":"2026-11-14T09:24:34Z","lease_expires_at":"2026-11-14T09:29:34Z","heartbeat_at":"2026-11-14T09:24:34Z","dependency_count":0,"dependent_count":0,"comment_count":0} {"_type":"issue","id":"agent-lib-u5t","title":"vendor rename: Vendor-Skills nachträglich umbenennen","description":"Kuratoren sollen vendored Items nachträglich (nicht nur bei vendor add) benutzerfreundlich umbenennen können. Neuer Befehl vendor rename \u003csource\u003e up=new / --reset; umbenannte Skills bekommen den name: im SKILL.md-Frontmatter angepasst (OpenCode verlangt name == Ordnername).","status":"closed","priority":2,"issue_type":"feature","assignee":"m3ta-chiron","owner":"m3ta-chiron@agentmail.to","created_at":"2026-11-05T07:43:31Z","created_by":"m3ta-chiron","updated_at":"2026-11-05T07:45:14Z","started_at":"2026-11-05T07:43:50Z","closed_at":"2026-11-05T07:45:14Z","close_reason":"vendor rename implemented with SKILL.md name rewrite, tests + README","dependency_count":0,"dependent_count":0,"comment_count":0} {"_type":"issue","id":"agent-lib-4wx.11","title":"Deliver end-to-end documentation and release gate","description":"Finish the MVP by documenting the full workflow and proving it through an offline end-to-end acceptance path. The slice should provide README content, quickstart, CLI reference, Home Manager examples, security/trust notes, troubleshooting, and a release gate that demonstrates init, Source add, inspect, snippet, Home Manager eval/render, target Manifests, and a green offline check.","acceptance_criteria":"- Documentation covers installation, quickstart, CLI reference, Home Manager configuration, Lockfile behavior, discovery conventions, security/trust model, troubleshooting, MVP scope, and non-goals\n- An offline end-to-end fixture workflow demonstrates initialization, Source discovery, selection, Pi and Opencode Rendered output, target Manifests, and no unmanaged overwrites\n- nix flake check is green without external network access and verifies the MVP acceptance criteria","notes":"E2E fixture check green. All steps verified: init creates lockfile, discover finds all items, lockfile has rev/narHash/HM-compatible schema, inspect/snippet/validate commands work, managed-file protection present. nix flake check passes.","status":"closed","priority":2,"issue_type":"feature","assignee":"m3ta-chiron","owner":"p@m3ta.dev","created_at":"2026-05-27T17:50:02Z","created_by":"m3tam3re","updated_at":"2026-05-28T08:13:15Z","started_at":"2026-05-28T07:46:50Z","closed_at":"2026-05-28T08:13:15Z","labels":["ready-for-agent"],"dependencies":[{"issue_id":"agent-lib-4wx.11","depends_on_id":"agent-lib-4wx","type":"parent-child","created_at":"2026-05-27T19:50:01Z","created_by":"m3tam3re","metadata":"{}"},{"issue_id":"agent-lib-4wx.11","depends_on_id":"agent-lib-4wx.1","type":"blocks","created_at":"2026-05-27T19:50:02Z","created_by":"m3tam3re","metadata":"{}"},{"issue_id":"agent-lib-4wx.11","depends_on_id":"agent-lib-4wx.10","type":"blocks","created_at":"2026-05-27T19:50:03Z","created_by":"m3tam3re","metadata":"{}"},{"issue_id":"agent-lib-4wx.11","depends_on_id":"agent-lib-4wx.2","type":"blocks","created_at":"2026-05-27T19:50:02Z","created_by":"m3tam3re","metadata":"{}"},{"issue_id":"agent-lib-4wx.11","depends_on_id":"agent-lib-4wx.3","type":"blocks","created_at":"2026-05-27T19:50:02Z","created_by":"m3tam3re","metadata":"{}"},{"issue_id":"agent-lib-4wx.11","depends_on_id":"agent-lib-4wx.4","type":"blocks","created_at":"2026-05-27T19:50:02Z","created_by":"m3tam3re","metadata":"{}"},{"issue_id":"agent-lib-4wx.11","depends_on_id":"agent-lib-4wx.5","type":"blocks","created_at":"2026-05-27T19:50:02Z","created_by":"m3tam3re","metadata":"{}"},{"issue_id":"agent-lib-4wx.11","depends_on_id":"agent-lib-4wx.6","type":"blocks","created_at":"2026-05-27T19:50:02Z","created_by":"m3tam3re","metadata":"{}"},{"issue_id":"agent-lib-4wx.11","depends_on_id":"agent-lib-4wx.7","type":"blocks","created_at":"2026-05-27T19:50:02Z","created_by":"m3tam3re","metadata":"{}"},{"issue_id":"agent-lib-4wx.11","depends_on_id":"agent-lib-4wx.8","type":"blocks","created_at":"2026-05-27T19:50:03Z","created_by":"m3tam3re","metadata":"{}"},{"issue_id":"agent-lib-4wx.11","depends_on_id":"agent-lib-4wx.9","type":"blocks","created_at":"2026-05-27T19:50:03Z","created_by":"m3tam3re","metadata":"{}"}],"dependency_count":10,"dependent_count":0,"comment_count":0} {"_type":"issue","id":"agent-lib-4wx.10","title":"Complete CLI operational workflows and snippets","description":"Complete the day-to-day CLI workflow around existing Sources, Profiles, and Targets. The slice should make update/review/switch workflows practical with added/removed Item reports, offline and fetch validation modes, minimal and full Nix snippets, JSON output, non-interactive defaults, and an optional interactive entry point without automatic Nix edits.","acceptance_criteria":"- source update and source update --all report added and removed Items without changing Home Manager selection\n- validate runs offline by default, validate --fetch performs explicit reachability checks, and list/inspect/validate support stable JSON output\n- snippet emits both minimal Profile include snippets and full example configuration, while the CLI remains non-interactive by default and never edits Nix files","status":"closed","priority":2,"issue_type":"feature","assignee":"m3ta-chiron","owner":"p@m3ta.dev","created_at":"2026-05-27T17:49:57Z","created_by":"m3tam3re","updated_at":"2026-05-28T07:46:28Z","started_at":"2026-05-28T07:39:36Z","closed_at":"2026-05-28T07:46:28Z","close_reason":"Closed","labels":["ready-for-agent"],"dependencies":[{"issue_id":"agent-lib-4wx.10","depends_on_id":"agent-lib-4wx","type":"parent-child","created_at":"2026-05-27T19:49:56Z","created_by":"m3tam3re","metadata":"{}"},{"issue_id":"agent-lib-4wx.10","depends_on_id":"agent-lib-4wx.3","type":"blocks","created_at":"2026-05-27T19:49:57Z","created_by":"m3tam3re","metadata":"{}"},{"issue_id":"agent-lib-4wx.10","depends_on_id":"agent-lib-4wx.5","type":"blocks","created_at":"2026-05-27T19:49:57Z","created_by":"m3tam3re","metadata":"{}"},{"issue_id":"agent-lib-4wx.10","depends_on_id":"agent-lib-4wx.7","type":"blocks","created_at":"2026-05-27T19:49:57Z","created_by":"m3tam3re","metadata":"{}"},{"issue_id":"agent-lib-4wx.10","depends_on_id":"agent-lib-4wx.8","type":"blocks","created_at":"2026-05-27T19:49:57Z","created_by":"m3tam3re","metadata":"{}"}],"dependency_count":4,"dependent_count":1,"comment_count":0} diff --git a/README.md b/README.md index c55328c..5b42695 100644 --- a/README.md +++ b/README.md @@ -45,6 +45,7 @@ agents/.md own OpenCode agents mcp/.yaml own MCP fragments (never deployed by the binary) external/// vendored content, mirrors the same four types agent-lib.lock.json lockfile v2 — pins every source +agent-lib.labels.json optional — restricts items to labeled clients ``` This layout is **exactly** what OpenCode natively consumes — agent-lib is @@ -291,6 +292,62 @@ agent-lib sync --repo https://github.com/you/your-agent-content.git The work repository must be a committed git repository (sync pulls it read-only via go-git; local uncommitted state is ignored). +### Client labels + +Not every client needs every item. Restrict items to clients that carry a +matching label with an optional `agent-lib.labels.json` at the work +repository root: + +```json +{ + "version": 1, + "labels": { + "sales": ["crm-agent", "quote-writer"], + "finance": ["officecli-financial-model", "crm-agent"] + } +} +``` + +- **Unlabeled items go to every client.** Only restricted items appear in + the file; a new item needs no entry to reach everyone. +- Entries are deployed item names (after renames) and match across types — + one entry covers a skill and a command of the same name. MCP fragment + names are allowed too (fleet tooling can scope MCP from the same file; + the binary never deploys MCP). +- An item under several labels reaches clients with any of them. +- Labels match `^[a-z0-9][a-z0-9-]*$`; lists must be non-empty; unknown + keys and unknown versions are errors. + +Clients opt in through `labels` in their config: + +| `labels` | Delivered | +|---|---| +| absent | everything — no filtering (default, backward compatible) | +| `[]` | unlabeled items only | +| `["sales", "lead"]` | unlabeled items plus items labeled `sales` or `lead` | + +**Admin-pinned:** when the admin default config exists and sets `labels`, +that value applies no matter which config supplied `repo_url` — a user-level +config, `AGENT_LIB_CONFIG` or `--config` can neither widen nor drop it. An +admin config that exists but cannot be parsed aborts the run. + +Sync filters before planning. An item that is no longer selected follows +the upstream-deletion rules: unmodified copies are removed, locally modified +copies are kept with a warning (`--force` removes them); the reason reads +"not selected for this client's labels". A labels file that does not +validate **aborts the sync before any change** — it never falls back to +delivering everything. Names that match no item only warn on the client; +`agent-lib validate` treats them as errors on the curator side. + +`sync` and `status` print the active selection +(`labels: sales (admin) — 12 item(s) not selected`); `status --json` adds a +`labels` object with `client`, `source`, `labels_file`, `not_selected` and +`unknown_names`. + +Labels are a relevance filter, **not access control**: every client still +fetches the whole revision into its cache. Keep confidential material in a +separately authenticated repository. + ### Notifications On Windows, a toast fires when (and only when) a sync kept local @@ -347,7 +404,10 @@ In scope: vendoring with selection/renames into any git work repository; OpenCode-only deployment with three-state protection; toast notifications; goreleaser/GitHub release pipeline. -Not in scope: client-side selection or profiles, additional targets (Pi, +Client-side selection is limited to label filtering (see Client labels) — +no per-client profiles, overrides or inheritance. + +Not in scope: additional targets (Pi, Hermes, Crush, Amp), MCP merge/vault (fleet-controller concern), binary self-update, git submodule sources, migration tooling from the Python-era lockfile. diff --git a/docs/fleet-handoff.md b/docs/fleet-handoff.md index 5b1eea8..04d9255 100644 --- a/docs/fleet-handoff.md +++ b/docs/fleet-handoff.md @@ -56,6 +56,10 @@ root-owned, mode 0644). - Employees must be able to read the config (sync runs in their context) but must not be able to alter it. - Per-run overrides for testing: `--config ` or `AGENT_LIB_CONFIG`. +- Optional `"labels": ["