got-feedBack/feedBack
1
0
Fork 0
mirror of https://github.com/got-feedBack/feedBack.git synced 2026-09-13 01:48:30 +00:00
Code Issues Actions 1 Packages Projects Releases Wiki Activity

chore: update PR 332 tooling for capability model

Browse Source
This commit is contained in:
barlind
2026-06-18 00:40:12 -07:00
committed by Bret Mogilefsky
parent b45751164f
commit 26dba55d7e
15 changed files with 777 additions and 62 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/PLUGIN_AUTHORING.md
+5
View File
@@ -26,12 +26,16 @@ The minimum viable plugin is a `plugin.json` with just `id` and `name`. Everythi
}
```
Capability-aware plugins should also declare the `capability-pipelines.v1` standard and the domains they participate in. Legacy fields such as `nav`, `screen`, `settings`, `type: "visualization"`, shortcuts, overlays, and mixer faders still work, but native metadata lets diagnostics, the Capability Inspector, and migration tooling explain plugin behavior without scraping private globals.
## Topics
| Topic | Doc | When to read |
|---|---|---|
| **Manifest reference** | [plugin-manifest.md](plugin-manifest.md) | Field-by-field reference for `plugin.json`. Read first. |
| **Capability declarations** | [plugin-manifest.md#capabilities](plugin-manifest.md#capabilities) | Declaring provider/requester/observer intent with `capability-pipelines.v1`. |
| **Visualization contracts** | [plugin-visualization-contracts.md](plugin-visualization-contracts.md) | Building a highway renderer (setRenderer), an overlay layer, or a note-state provider. |
| **Plugin styles** | [plugin-styles.md](plugin-styles.md) | Shipping a plugin-owned prebuilt stylesheet via `styles: "assets/plugin.css"`. |
| **Audio mixer faders** | [plugin-audio-mixer.md](plugin-audio-mixer.md) | Plugin produces audio outside the song `<audio>` element. |
| **Backend logging** | [plugin-logging.md](plugin-logging.md) | Plugin has a `routes.py`. Use `context["log"]`, never `print()`. |
| **Diagnostics contribution** | [plugin-diagnostics.md](plugin-diagnostics.md) | Adding plugin state to the Export Diagnostics bundle. |
@@ -45,6 +49,7 @@ The minimum viable plugin is a `plugin.json` with just `id` and `name`. Everythi
## General guidelines
- Wrap your plugin code in an IIFE: `(function () { 'use strict'; ... })();`
- Declare `standards: ["capability-pipelines.v1"]` and native `capabilities` when your plugin participates in a Slopsmith capability domain.
- Use `localStorage` for user-facing settings, prefixed with your plugin id.
- If hooking `window.playSong`, always call the original and `await` it.
- If hooking `window.showScreen`, clean up your state when leaving the player screen.
docs/plugin-manifest.md
+110 -1
View File
@@ -10,10 +10,12 @@ Every plugin lives in `plugins/<name>/` and must declare a `plugin.json` manifes
"name": "My Plugin",
"version": "1.0.0",
"private": false,
"standards": ["capability-pipelines.v1", "plugin-runtime-idempotent.v1"],
"type": "visualization",
"nav": { "label": "My Plugin", "screen": "plugin-my_plugin" },
"screen": "screen.html",
"script": "screen.js",
"styles": "assets/plugin.css",
"routes": "routes.py",
"settings": {
"html": "settings.html",
@@ -22,6 +24,24 @@ Every plugin lives in `plugins/<name>/` and must declare a `plugin.json` manifes
"diagnostics": {
"server_files": ["my_plugin.diag.json"],
"callable": "diagnostics:collect"
},
"settings_schema": {
"schema_version": "1",
"packable_keys": ["enabled"]
},
"ui": {
"settings": [{ "id": "my-plugin-settings", "region": "plugin-settings", "label": "My Plugin" }]
},
"capabilities": {
"library": {
"roles": ["provider"],
"operations": ["query-page", "query-artists", "query-stats"],
"mode": "active",
"compatibility": "none",
"ownership": "multi-provider",
"safety": "safe",
"version": 1
}
}
}
```
@@ -46,6 +66,20 @@ Plain semver string. Advisory only — the plugin loader does not consume this.
Advisory metadata for plugin authors. Not consumed by the loader.
### `standards` (string[], optional)
Versioned contracts the plugin participates in. New capability-aware plugins should declare `"capability-pipelines.v1"` when they include native `capabilities`, `ui`, `runtime_domains`, or related metadata.
Declare `"plugin-runtime-idempotent.v1"` only when repeated script hydration cannot duplicate wrappers, listeners, timers, DOM roots, diagnostics contributors, jobs, media nodes, or capability participants.
### `capability_api` (object, optional)
Explicit capability API marker. Most plugins can use the compact `standards` form instead:
```json
{ "capability_api": { "standard": "capability-pipelines.v1", "version": 1 } }
```
### `type` (string, optional — role hint, slopsmith#36)
Supported values:
@@ -64,6 +98,10 @@ Path to HTML file (relative to plugin dir). Mounted at `#plugin-<id>` in the SPA
Path to JS file (relative to plugin dir). Loaded via `<script>` tag in global scope. Wrap in an IIFE.
### `styles` (string, optional)
Path to a plugin-owned compiled stylesheet under `assets/`, for example `"assets/plugin.css"`. Use this when a plugin ships Tailwind utilities that core's prebuilt stylesheet cannot know about, especially arbitrary-value classes in runtime-installed plugins. The stylesheet must be built ahead of time with Tailwind `preflight: false`; Slopsmith injects one versioned `<link>` for the plugin. See [plugin-styles.md](plugin-styles.md).
### `routes` (string, optional)
Path to Python file exporting `setup(app, context)`. See "Backend routes" below.
@@ -95,6 +133,77 @@ Path to Python file exporting `setup(app, context)`. See "Backend routes" below.
See [plugin-diagnostics.md](plugin-diagnostics.md) for full diagnostics integration patterns.
### `settings_schema` (object, optional)
Redaction-safe settings metadata for support tooling and capability diagnostics. Use this to describe schema/version and packable key names; do not store user settings values, paths, tokens, or plugin-private payloads here.
### `ui` / `ui_contributions` (object, optional)
Native UI contribution declarations keyed by UI domain or surface. These let Slopsmith attribute plugin UI to stable contribution records while legacy `nav`, `screen`, `settings`, visualization picker entries, shortcuts, overlays, player panels, and tours continue to work through compatibility bridges.
Example:
```json
{
"ui": {
"settings": [{ "id": "my-plugin-settings", "region": "plugin-settings", "label": "My Plugin" }],
"ui.player-overlays": [{ "id": "my-plugin-overlay", "region": "player.overlays.highway", "label": "My Overlay" }]
}
}
```
Contribution ids must be stable and unique per plugin. Keep metadata redaction-safe: no settings values, DOM handles, local paths, callbacks, or private payloads.
### `capabilities` (object, optional)
Native `capability-pipelines.v1` declarations keyed by capability domain. They describe what the plugin owns, provides, requests, observes, or emits before the runtime script hydrates.
```json
{
"standards": ["capability-pipelines.v1"],
"capabilities": {
"library": {
"roles": ["provider"],
"operations": ["query-page", "query-artists", "query-stats", "tuning-names", "get-art", "sync-song"],
"description": "Adds a browsable library source.",
"mode": "active",
"compatibility": "none",
"ownership": "multi-provider",
"safety": "safe",
"version": 1
},
"playback": {
"roles": ["observer"],
"observes": ["loading", "ready", "stopped", "ended"],
"description": "Observes playback lifecycle without wrapping window.playSong.",
"mode": "active",
"compatibility": "shim-allowed",
"ownership": "observer-only",
"safety": "safe",
"version": 1
}
}
}
```
Supported declaration fields include:
- `roles`: `owner`, `coordinator`, `provider`, `observer`, `requester`, `transformer`, `handler`, `validator`, `short-circuiter`, `contributor`
- `commands`, `operations`, `requests`, `observes`, `emits`, `events`: string arrays naming public commands, provider operations, or events
- `kind`: `command`, `provider-coordinator`, `event`, `diagnostic`, `privileged`
- `mode`: `active`, `optional`, `legacy-shim`, `disabled`
- `compatibility`: `none`, `shim-allowed`, `degrade-noop`, `required`, `legacy-window-shim`
- `ownership`: `exclusive-owner`, `multi-provider`, `observer-only`, `requester-only`, `privileged`, `diagnostic-only`
- `safety`: `safe`, `privileged`, `sensitive`, `diagnostic-only`
- `description` / `summary`: short redaction-safe text for local tooling
- `version`: `1`
Invalid capability metadata is rejected by schema validation and ignored by runtime capability tooling; legacy plugin fields still load through their existing app paths.
### `runtime_domains` / `domains` (object, optional)
Legacy bridge declarations for older runtime-domain metadata. Prefer `capabilities` for new native declarations.
### `license` (string, optional but recommended)
SPDX identifier. For curated plugins, must be AGPL-3.0-or-later or AGPL-compatible (MIT, BSD-2-Clause, BSD-3-Clause, Apache-2.0). See [CONTRIBUTING.md](../CONTRIBUTING.md).
@@ -127,7 +236,7 @@ def setup(app, context):
## Validation
Run the local validator skill `/plugin-validate` (Claude Code) or the CI workflow `.github/workflows/validate-plugins.yml`. Both consume [`schema/plugin.schema.json`](../schema/plugin.schema.json).
Run the local validator skill `/plugin-validate` (Claude Code) or the CI workflow `.github/workflows/validate-plugins.yml`. Both consume [`schema/plugin.schema.json`](../schema/plugin.schema.json), including capability-pipelines metadata.
## Related
docs/plugin-manifest.schema.json
+341 -40
View File
@@ -3,62 +3,363 @@
"$id": "https://slopsmith.local/contracts/plugin-manifest-capabilities.schema.json",
"title": "Slopsmith Plugin Manifest Capability Contract",
"type": "object",
"required": ["id", "name"],
"required": [
"id",
"name"
],
"properties": {
"id": { "type": "string", "minLength": 1, "pattern": "^[A-Za-z0-9_.-]+$" },
"name": { "type": "string", "minLength": 1 },
"version": { "type": ["string", "null"] },
"private": { "type": "boolean" },
"standards": { "type": "array", "items": { "type": "string", "minLength": 1 }, "uniqueItems": true },
"id": {
"type": "string",
"minLength": 1,
"pattern": "^[A-Za-z0-9_.-]+$"
},
"name": {
"type": "string",
"minLength": 1
},
"version": {
"type": [
"string",
"null"
]
},
"private": {
"type": "boolean"
},
"standards": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
},
"uniqueItems": true
},
"capability_api": {
"type": "object",
"properties": { "standard": { "const": "capability-pipelines.v1" }, "version": { "const": 1 } },
"properties": {
"standard": {
"const": "capability-pipelines.v1"
},
"version": {
"const": 1
}
},
"additionalProperties": false
},
"capabilities": {
"type": "object",
"propertyNames": { "$ref": "#/$defs/domainName" },
"additionalProperties": { "$ref": "#/$defs/capabilityDeclaration" }
"propertyNames": {
"$ref": "#/$defs/domainName"
},
"additionalProperties": {
"$ref": "#/$defs/capabilityDeclaration"
}
},
"ui_contributions": { "type": "object", "propertyNames": { "$ref": "#/$defs/domainName" }, "additionalProperties": { "$ref": "#/$defs/contributionList" } },
"ui": { "type": "object", "propertyNames": { "$ref": "#/$defs/domainName" }, "additionalProperties": { "$ref": "#/$defs/contributionList" } },
"runtime_domains": { "type": "object", "propertyNames": { "$ref": "#/$defs/domainName" }, "additionalProperties": { "$ref": "#/$defs/domainDeclaration" } },
"domains": { "type": "object", "propertyNames": { "$ref": "#/$defs/domainName" }, "additionalProperties": { "$ref": "#/$defs/domainDeclaration" } },
"settings_schema": { "type": "object" },
"nav": {}, "screen": {}, "script": {}, "routes": {}, "settings": {}, "diagnostics": {}, "type": { "type": "string" }, "tour": {},
"description": { "type": "string", "description": "Short one-sentence summary of the plugin, surfaced on the v3 Pedalboard Plugins page (clamped to ~2 lines). Optional and additive." },
"category": { "type": "string", "description": "Which pedalboard the plugin sits on in the v3 Plugins page. Suggested values: 'audio', 'creation', 'practice', 'game', 'tools'. Free-form; unknown/absent values fall back to a curated default then 'other'. Optional and additive." },
"icon": { "type": "string", "minLength": 1, "pattern": "^assets/(?!.*\\.\\.)[^\\\\?#]+$", "description": "Plugin-root-relative path under assets/ (e.g. 'assets/thumb.png') to a thumbnail (~square, ~256x256 PNG/SVG) shown as the pedal graphic on the v3 Plugins page. Same containment rule as `styles`. If omitted, the loader auto-detects assets/thumb.png; failing that the UI shows a default pedal graphic. Optional and additive." },
"styles": { "type": "string", "minLength": 1, "pattern": "^assets/(?!.*\\.\\.)[^\\\\?#]+$", "description": "Plugin-root-relative path under assets/ (e.g. 'assets/plugin.css') to a compiled, preflight-off Tailwind stylesheet the frontend injects as a <link>. Must stay under assets/ with no '..', backslash, or query/fragment. See docs/plugin-styles.md." }
"ui_contributions": {
"type": "object",
"propertyNames": {
"$ref": "#/$defs/domainName"
},
"additionalProperties": {
"$ref": "#/$defs/contributionList"
}
},
"ui": {
"type": "object",
"propertyNames": {
"$ref": "#/$defs/domainName"
},
"additionalProperties": {
"$ref": "#/$defs/contributionList"
}
},
"runtime_domains": {
"type": "object",
"propertyNames": {
"$ref": "#/$defs/domainName"
},
"additionalProperties": {
"$ref": "#/$defs/domainDeclaration"
}
},
"domains": {
"type": "object",
"propertyNames": {
"$ref": "#/$defs/domainName"
},
"additionalProperties": {
"$ref": "#/$defs/domainDeclaration"
}
},
"settings_schema": {
"type": "object"
},
"nav": {},
"screen": {},
"script": {},
"routes": {},
"settings": {},
"diagnostics": {},
"type": {
"type": "string"
},
"tour": {},
"description": {
"type": "string",
"description": "Short one-sentence summary of the plugin, surfaced on the v3 Pedalboard Plugins page (clamped to ~2 lines). Optional and additive."
},
"category": {
"type": "string",
"description": "Which pedalboard the plugin sits on in the v3 Plugins page. Suggested values: 'audio', 'creation', 'practice', 'game', 'tools'. Free-form; unknown/absent values fall back to a curated default then 'other'. Optional and additive."
},
"icon": {
"type": "string",
"minLength": 1,
"pattern": "^assets/(?!.*\\.\\.)[^\\\\?#]+$",
"description": "Plugin-root-relative path under assets/ (e.g. 'assets/thumb.png') to a thumbnail (~square, ~256x256 PNG/SVG) shown as the pedal graphic on the v3 Plugins page. Same containment rule as `styles`. If omitted, the loader auto-detects assets/thumb.png; failing that the UI shows a default pedal graphic. Optional and additive."
},
"styles": {
"type": "string",
"minLength": 1,
"pattern": "^assets/(?!.*\\.\\.)[^\\\\?#]+$",
"description": "Plugin-root-relative path under assets/ (e.g. 'assets/plugin.css') to a compiled, preflight-off Tailwind stylesheet the frontend injects as a <link>. Must stay under assets/ with no '..', backslash, query, or fragment. See docs/plugin-styles.md."
}
},
"additionalProperties": true,
"$defs": {
"domainName": { "type": "string", "minLength": 1, "pattern": "^[A-Za-z0-9_.:-]+$" },
"domainName": {
"type": "string",
"minLength": 1,
"pattern": "^[A-Za-z0-9_.:-]+$"
},
"capabilityDeclaration": {
"type": "object",
"properties": {
"roles": { "type": "array", "items": { "enum": ["owner", "provider", "observer", "requester", "transformer", "handler", "validator", "short-circuiter", "contributor"] }, "uniqueItems": true },
"commands": { "type": "array", "items": { "type": "string", "minLength": 1 }, "uniqueItems": true },
"operations": { "type": "array", "items": { "type": "string", "minLength": 1 }, "uniqueItems": true },
"requests": { "type": "array", "items": { "type": "string", "minLength": 1 }, "uniqueItems": true },
"observes": { "type": "array", "items": { "type": "string", "minLength": 1 }, "uniqueItems": true },
"emits": { "type": "array", "items": { "type": "string", "minLength": 1 }, "uniqueItems": true },
"events": { "type": "array", "items": { "type": "string", "minLength": 1 }, "uniqueItems": true },
"kind": { "enum": ["command", "provider-coordinator", "event", "diagnostic", "privileged"] },
"mode": { "enum": ["active", "optional", "legacy-shim", "disabled"] },
"compatibility": { "enum": ["none", "shim-allowed", "degrade-noop", "required", "legacy-window-shim"] },
"ownership": { "enum": ["exclusive-owner", "multi-provider", "observer-only", "requester-only", "privileged", "diagnostic-only"] },
"safety": { "enum": ["safe", "privileged", "sensitive", "diagnostic-only"] },
"order": { "type": "object", "properties": { "fixed": { "type": "boolean" }, "before": { "type": "array", "items": { "type": "string", "minLength": 1 }, "uniqueItems": true }, "after": { "type": "array", "items": { "type": "string", "minLength": 1 }, "uniqueItems": true } }, "additionalProperties": false },
"provider_policy": { "type": "object" },
"settings": { "type": "array", "description": "Declarative per-instance control descriptors (toggle / range / select) a participant exposes for a consuming host to render generically. Domain-agnostic in shape; how a host applies a chosen value is defined by each capability domain's contract (the visualization domain requires an applySetting(key, value) method on the renderer instance).", "items": { "type": "object", "required": ["key", "type"], "properties": { "key": { "type": "string", "minLength": 1 }, "label": { "type": "string" }, "type": { "enum": ["toggle", "range", "select"] }, "default": {}, "min": { "type": "number" }, "max": { "type": "number" }, "step": { "type": "number" }, "options": { "type": "array", "items": { "type": "object", "required": ["id"], "properties": { "id": { "type": "string", "minLength": 1 }, "label": { "type": "string" } }, "additionalProperties": false } } }, "additionalProperties": false } },
"description": { "type": "string" },
"summary": { "type": "string" },
"version": { "const": 1 }
"roles": {
"type": "array",
"items": {
"enum": [
"owner",
"coordinator",
"provider",
"observer",
"requester",
"transformer",
"handler",
"validator",
"short-circuiter",
"contributor"
]
},
"uniqueItems": true
},
"commands": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
},
"uniqueItems": true
},
"operations": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
},
"uniqueItems": true
},
"requests": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
},
"uniqueItems": true
},
"observes": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
},
"uniqueItems": true
},
"emits": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
},
"uniqueItems": true
},
"events": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
},
"uniqueItems": true
},
"kind": {
"enum": [
"command",
"provider-coordinator",
"event",
"diagnostic",
"privileged"
]
},
"mode": {
"enum": [
"active",
"optional",
"legacy-shim",
"disabled"
]
},
"compatibility": {
"enum": [
"none",
"shim-allowed",
"degrade-noop",
"required",
"legacy-window-shim"
]
},
"ownership": {
"enum": [
"exclusive-owner",
"multi-provider",
"observer-only",
"requester-only",
"privileged",
"diagnostic-only"
]
},
"safety": {
"enum": [
"safe",
"privileged",
"sensitive",
"diagnostic-only"
]
},
"order": {
"type": "object",
"properties": {
"fixed": {
"type": "boolean"
},
"before": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
},
"uniqueItems": true
},
"after": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
},
"uniqueItems": true
}
},
"additionalProperties": false
},
"provider_policy": {
"type": "object"
},
"description": {
"type": "string"
},
"summary": {
"type": "string"
},
"version": {
"const": 1
}
},
"additionalProperties": false
},
"domainDeclaration": { "oneOf": [{ "type": "object", "properties": { "role": { "type": "string", "minLength": 1 }, "roles": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "ownership": { "enum": ["exclusive-owner", "multi-provider", "observer-only", "requester-only", "privileged", "diagnostic-only"] }, "safety": { "enum": ["safe", "privileged", "sensitive", "diagnostic-only"] }, "legacy_source": { "type": "string", "minLength": 1 } }, "additionalProperties": true }, { "type": "array" }] },
"contributionList": { "type": "array", "items": { "type": "object", "required": ["id"], "properties": { "id": { "type": "string", "minLength": 1 }, "region": { "type": "string", "minLength": 1 }, "label": { "type": "string" }, "order": { "type": ["number", "integer", "string"] } }, "additionalProperties": true } }
"domainDeclaration": {
"oneOf": [
{
"type": "object",
"properties": {
"role": {
"type": "string",
"minLength": 1
},
"roles": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"ownership": {
"enum": [
"exclusive-owner",
"multi-provider",
"observer-only",
"requester-only",
"privileged",
"diagnostic-only"
]
},
"safety": {
"enum": [
"safe",
"privileged",
"sensitive",
"diagnostic-only"
]
},
"legacy_source": {
"type": "string",
"minLength": 1
}
},
"additionalProperties": true
},
{
"type": "array"
}
]
},
"contributionList": {
"type": "array",
"items": {
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"minLength": 1
},
"region": {
"type": "string",
"minLength": 1
},
"label": {
"type": "string"
},
"order": {
"type": [
"number",
"integer",
"string"
]
}
},
"additionalProperties": true
}
}
}
}