@skill-map/spec 0.12.0 → 0.13.1

package/schemas/api/rest-envelope.schema.json

@@ -0,0 +1,170 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://skill-map.dev/spec/v0/api/rest-envelope.schema.json",
+  "title": "RestEnvelope",
+  "description": "Wrapper shape for REST responses under `/api/*` (Step 14.2). Three variants distinguished by the `kind` discriminator and which payload field is present (`items` for list kinds, `item` for single-resource kinds, `value` for `kind: 'config'`). The `/api/scan` and `/api/health` responses are exempt — they carry the underlying `ScanResult` / `IHealthResponse` shape directly. The `/api/graph` response is also exempt — it returns the formatter's native textual output (text/plain or text/markdown). Step 14.5.d adds the required `kindRegistry` field on every payload-bearing variant so the UI can render Provider-declared kinds (label, color, icon) without hardcoding visuals; sentinel kinds (`health`, `scan`, `graph`) stay exempt because they don't carry an envelope payload. The change keeps `schemaVersion` at `'1'` — the BFF is greenfield (no released consumers run against `'1'` without `kindRegistry`), so a versioned migration buys nothing.",
+  "type": "object",
+  "required": ["schemaVersion", "kind"],
+  "properties": {
+    "schemaVersion": {
+      "type": "string",
+      "const": "1",
+      "description": "Envelope shape version. Bumped only on breaking changes. The Step 14.5.d addition of `kindRegistry` keeps the version at `'1'` because there are no released consumers in the wild."
+    },
+    "kind": {
+      "type": "string",
+      "enum": ["nodes", "links", "issues", "plugins", "config", "graph", "node", "health", "scan"],
+      "description": "Discriminator. List kinds (`nodes`, `links`, `issues`, `plugins`) carry `items`. The `node` kind carries `item`. The `config` kind carries `value`. The `health` / `scan` / `graph` values are reserved for documentation parity with the routes that DON'T use this envelope."
+    },
+    "items": {
+      "type": "array",
+      "description": "Present when `kind` is one of the list kinds (`nodes`, `links`, `issues`, `plugins`). Empty array is valid and means the filter matched zero rows."
+    },
+    "item": {
+      "type": "object",
+      "description": "Present when `kind` is `'node'`. Single-resource envelope payload."
+    },
+    "value": {
+      "type": "object",
+      "description": "Present when `kind` is `'config'`. Carries the merged effective config object."
+    },
+    "filters": {
+      "type": "object",
+      "description": "Echo of the URL filters the server applied, normalized into a JSON-friendly shape (arrays for multi-value filters, `null` for absent ones). Helps the client correlate the response with the request."
+    },
+    "kindRegistry": {
+      "type": "object",
+      "description": "Catalog of node kinds active in the current scope, keyed by kind name. Built once per server boot from every enabled Provider's `kinds` map and embedded into every payload-bearing envelope so the UI can render kind tags / palette swatches / graph nodes against Provider-declared visuals (label, color, icon) without ever hardcoding a closed kind enum. Sentinel envelopes (`health`, `scan`, `graph`) are exempt.",
+      "additionalProperties": {
+        "type": "object",
+        "required": ["providerId", "label", "color"],
+        "additionalProperties": false,
+        "properties": {
+          "providerId": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Id of the Provider that contributed this kind. Lets the UI scope kind ownership and disambiguate when two Providers happen to declare the same kind name (kernel surfaces this as `provider-ambiguous` but the UI may still receive the merged registry during the conflict window)."
+          },
+          "label": { "type": "string", "minLength": 1 },
+          "color": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" },
+          "colorDark": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" },
+          "emoji": { "type": "string", "minLength": 1, "maxLength": 8 },
+          "icon": {
+            "oneOf": [
+              {
+                "type": "object",
+                "required": ["kind", "id"],
+                "additionalProperties": false,
+                "properties": {
+                  "kind": { "const": "pi" },
+                  "id": { "type": "string", "pattern": "^pi-[a-z0-9]+(-[a-z0-9]+)*$" }
+                }
+              },
+              {
+                "type": "object",
+                "required": ["kind", "path"],
+                "additionalProperties": false,
+                "properties": {
+                  "kind": { "const": "svg" },
+                  "path": { "type": "string", "minLength": 1 }
+                }
+              }
+            ]
+          }
+        }
+      }
+    },
+    "counts": {
+      "type": "object",
+      "required": ["total", "returned"],
+      "properties": {
+        "total": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Total rows after filtering, before pagination is applied."
+        },
+        "returned": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Rows actually carried in `items` (≤ `limit`)."
+        },
+        "page": {
+          "type": "object",
+          "required": ["offset", "limit"],
+          "properties": {
+            "offset": {
+              "type": "integer",
+              "minimum": 0,
+              "description": "Pagination window offset (zero-based)."
+            },
+            "limit": {
+              "type": "integer",
+              "minimum": 0,
+              "description": "Maximum items the page may carry."
+            }
+          },
+          "additionalProperties": false,
+          "description": "Pagination window. Present when the endpoint paginates (today: `/api/nodes` only)."
+        }
+      },
+      "additionalProperties": false,
+      "description": "Tally + paging info. Present on every list / single envelope; absent on `health` / `scan` / `graph` responses (which don't use this envelope)."
+    }
+  },
+  "oneOf": [
+    {
+      "description": "List envelope — `items` payload + `counts` + `kindRegistry`.",
+      "required": ["items", "counts", "filters", "kindRegistry"],
+      "properties": {
+        "kind": { "enum": ["nodes", "links", "issues", "plugins"] }
+      },
+      "not": {
+        "anyOf": [
+          { "required": ["item"] },
+          { "required": ["value"] }
+        ]
+      }
+    },
+    {
+      "description": "Single-resource envelope — `item` payload + `kindRegistry`, no `counts` / `filters`.",
+      "required": ["item", "kindRegistry"],
+      "properties": {
+        "kind": { "const": "node" }
+      },
+      "not": {
+        "anyOf": [
+          { "required": ["items"] },
+          { "required": ["value"] }
+        ]
+      }
+    },
+    {
+      "description": "Value envelope — `value` payload + `kindRegistry`, no `counts` / `filters`.",
+      "required": ["value", "kindRegistry"],
+      "properties": {
+        "kind": { "const": "config" }
+      },
+      "not": {
+        "anyOf": [
+          { "required": ["items"] },
+          { "required": ["item"] }
+        ]
+      }
+    },
+    {
+      "description": "Sentinel kinds — reserved for routes that do NOT carry an envelope payload at the wire level (`health`, `scan`, `graph`). They do not carry `kindRegistry` either; clients that need it must call any payload-bearing endpoint at boot.",
+      "properties": {
+        "kind": { "enum": ["health", "scan", "graph"] }
+      },
+      "not": {
+        "anyOf": [
+          { "required": ["items"] },
+          { "required": ["item"] },
+          { "required": ["value"] },
+          { "required": ["kindRegistry"] }
+        ]
+      }
+    }
+  ],
+  "additionalProperties": false
+}

package/schemas/extensions/provider.schema.json

@@ -31,7 +31,7 @@
       },
       "additionalProperties": {
         "type": "object",
-        "required": ["schema", "defaultRefreshAction"],
+        "required": ["schema", "defaultRefreshAction", "ui"],
         "additionalProperties": false,
         "properties": {
           "schema": {
@@ -43,6 +43,66 @@
             "type": "string",
             "pattern": "^[a-z][a-z0-9]*(-[a-z0-9]+)*/[a-z][a-z0-9]*(-[a-z0-9]+)*$",
             "description": "Qualified action id (`<plugin-id>/<action-id>`) the UI's probabilistic-refresh surface (`🧠 prob`) dispatches for nodes of this kind. The action MUST exist in the registry by the time the graph is queried; a dangling reference disables the Provider with status `invalid-manifest`."
+          },
+          "ui": {
+            "type": "object",
+            "required": ["label", "color"],
+            "additionalProperties": false,
+            "description": "Presentation metadata the UI uses to render nodes of this kind (palette swatches, list tags, graph nodes, filter chips). Required so the UI never has to invent visuals for a kind a Provider declares. The Provider declares intent (label + base color, optional dark variant + emoji + icon); the UI derives bg/fg tints from `color` per theme via a deterministic helper. Reaches the UI via the `kindRegistry` field embedded in REST envelopes (`api/rest-envelope.schema.json`).",
+            "properties": {
+              "label": {
+                "type": "string",
+                "minLength": 1,
+                "description": "Plural human-readable label for groups of this kind (e.g. `'Skills'`, `'Agents'`, `'Cursor Rules'`). Used in filter dropdowns, palette tooltips, and any list grouping."
+              },
+              "color": {
+                "type": "string",
+                "pattern": "^#[0-9a-fA-F]{6}$",
+                "description": "Base hex color (light theme). The UI derives `bg` and `fg` tints from this value at runtime; declaring a single base value (instead of three) keeps the manifest small and lets the UI control accessibility-driven contrast."
+              },
+              "colorDark": {
+                "type": "string",
+                "pattern": "^#[0-9a-fA-F]{6}$",
+                "description": "Optional dark-theme variant of `color`. When absent, the UI falls back to `color`. Declared explicitly because a luminosity flip rarely matches the brand intent for kinds that should stand out in dark mode."
+              },
+              "emoji": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 8,
+                "description": "Optional decorative emoji used as a fallback when `icon` is absent or fails to render. Bound to a small length so the UI can lay it out predictably alongside text."
+              },
+              "icon": {
+                "description": "Optional discriminated icon descriptor. The UI prefers `icon` over `emoji`; when both are absent, the UI falls back to the first letter of `label` colored with `color`.",
+                "oneOf": [
+                  {
+                    "type": "object",
+                    "required": ["kind", "id"],
+                    "additionalProperties": false,
+                    "properties": {
+                      "kind": { "const": "pi" },
+                      "id": {
+                        "type": "string",
+                        "pattern": "^pi-[a-z0-9]+(-[a-z0-9]+)*$",
+                        "description": "PrimeIcons identifier (e.g. `pi-cog`, `pi-bolt`). Matched verbatim against the `pi pi-<id>` class the UI emits."
+                      }
+                    }
+                  },
+                  {
+                    "type": "object",
+                    "required": ["kind", "path"],
+                    "additionalProperties": false,
+                    "properties": {
+                      "kind": { "const": "svg" },
+                      "path": {
+                        "type": "string",
+                        "minLength": 1,
+                        "description": "Raw SVG path data (the `d` attribute of one or more `<path>` elements, joined). The UI wraps it in `<svg viewBox=\"0 0 24 24\"><path d=\"...\"/></svg>` and tints it with `currentColor`."
+                      }
+                    }
+                  }
+                ]
+              }
+            }
           }
         }
       }