Skip to content

claude.md

Latest commit

 

History

History
204 lines (159 loc) · 7.76 KB

claude.md

File metadata and controls

204 lines (159 loc) · 7.76 KB

StreamSpace Plugins Repository — Context for AI Assistants

What this repo owns

This is the streamspace-plugins sibling of streamspace-dev/streamspace. It hosts the official + community plugin catalog for StreamSpace.

Plugins extend the platform with optional integrations (auth, storage, observability, billing, communication, etc.) without bloating the core. The control plane discovers plugins via the catalog defined here and consumes them at runtime.

Repository structure

streamspace-plugins/
├── official/                       # Officially maintained plugins
├── community/                      # Community submissions
├── streamspace-slack/              # Top-level layout for legacy plugins
├── streamspace-teams/              # (mid-migration into official/community split)
├── streamspace-discord/
├── streamspace-pagerduty/
├── streamspace-email/
├── streamspace-calendar/
├── streamspace-datadog/
├── streamspace-newrelic/
├── streamspace-sentry/
├── streamspace-elastic-apm/
├── streamspace-honeycomb/
├── streamspace-compliance/
├── streamspace-dlp/
├── streamspace-audit-advanced/
├── streamspace-recording/
├── streamspace-snapshots/
├── streamspace-multi-monitor/
├── streamspace-workflows/
├── streamspace-analytics-advanced/
├── streamspace-auth-saml/
├── streamspace-auth-oauth/
├── streamspace-storage-s3/
├── streamspace-storage-azure/
├── streamspace-storage-gcs/
├── streamspace-billing/
├── streamspace-node-manager/
├── catalog.yaml                    # Plugin discovery metadata
├── README.md
├── CONTRIBUTING.md
└── claude.md                       # This file

Most existing plugin directories are stubs (manifest.json + a small *_plugin.go skeleton + README.md). Fleshing them out into working implementations is tracked work — see the project board.

Plugin types

  1. Extension — UI widgets, dashboard panels, custom session actions
  2. Webhook — react to lifecycle events (session.created, user.login, template.updated, audit.violation, …)
  3. Integration — push data out to Slack/Teams/Discord/PagerDuty/Jira/etc.
  4. Theme — branding, color tokens, accessibility presets

Plugin shape

my-plugin/
├── manifest.json          # REQUIRED — metadata, permissions, entrypoints
├── index.js (or *.go)     # REQUIRED — lifecycle hooks
├── README.md              # REQUIRED — what it does, config keys
├── config.schema.json     # optional — config validation
├── package.json           # optional — Node deps
└── assets/                # optional — icons, screenshots

manifest.json (minimum):

{
  "name": "my-plugin",
  "version": "1.0.0",
  "displayName": "My Plugin",
  "description": "What it does",
  "type": "extension",
  "author": "Your Name",
  "license": "MIT",
  "permissions": ["read:sessions"],
  "entrypoints": { "main": "index.js" }
}

index.js lifecycle skeleton:

module.exports = {
  async onLoad({ api, config }) {
    // initialization
  },
  async onUnload() {
    // cleanup
  }
};

Plugin API

Available via the streamspace global (or the equivalent injected api for the JS shape):

  • api.sessions — list, get, terminate, hibernate, wake
  • api.users — list, get, group membership
  • api.templates — list, get
  • api.plugins — list, get
  • api.webhooks.on(event, handler) — subscribe to lifecycle events
  • api.notify(...) — toast/banner the user
  • api.email, api.storage, api.commands, api.log
  • config.get(key), config.set(key, value)

Permissions

Plugins must declare what they need:

  • read:sessions / write:sessions
  • read:users / write:users
  • read:templates / write:templates
  • admin (dangerous — only for genuine admin tooling)
  • network (dangerous — required for any external HTTP call)

Principle of least privilege: ask for the minimum and document why in the README.

Streaming protocol — Selkies-only

The platform is Selkies-GStreamer (WebRTC) only as of April 2026. Plugins that touch the streaming surface (recording, multi-monitor, etc.) should target the Selkies HTTP/WebRTC proxy at /api/v1/http/<session-id>/. The legacy /api/v1/vnc/ and /api/v1/vnc-viewer/ endpoints have been removed from the control plane.

Installation methods

Catalog sync (recommended)

# Helm values
repositories:
  plugins:
    enabled: true
    url: https://github.com/streamspace-dev/streamspace-plugins
    branch: main
    syncInterval: "1h"

CLI

streamspace plugin install <name>
streamspace plugin enable <name>
streamspace plugin configure <name>

Manual

kubectl apply -f https://raw.githubusercontent.com/streamspace-dev/streamspace-plugins/main/<plugin>/manifest.yaml

catalog.yaml

Central registry consumed by the control plane and the in-product plugin marketplace. Keep it in sync with the directory contents — every plugin needs an entry, with category, type, permissions, and a stable name.

Adding a new plugin

  1. Fork or branch this repo.
  2. Create community/<name>/ (or official/<name>/ if you have commit access and own maintenance).
  3. Implement the required files: manifest.json, the entry-point file, README.md.
  4. Add an entry to catalog.yaml.
  5. Open a PR. CI validates the manifest schema and the plugin's basic structure.
  6. After review and merge, the catalog sync picks it up on the next interval.

Security expectations

Every plugin is reviewed before inclusion in official/. The bar:

  • Sandboxed runtime — JS plugins run in an isolated context; Go plugins run in their own goroutine with limited control-plane access
  • Rate-limited API access — plugins can't DoS the control plane
  • No bundled secrets — config keys must come from the user, not be hard-coded
  • Vetted dependencies — npm audit / go vet clean
  • Signed releases — official plugins are signed with cosign keyless

Related repos

Working with Claude Code

When you make changes here:

  1. One plugin per PR, ideally — small reviewable scope.
  2. Validate the manifest against the schema before opening the PR.
  3. Never edit catalog.yaml by hand if the project has a generation script (check scripts/); regenerate it from the directory.
  4. Update the README when adding or removing a plugin.
  5. Don't commit node_modules/ or compiled binaries; the gitignore should already handle this but double-check.
  6. Don't reference the retired wave-based dev workflow (Wave 28, agent3-validator, …) in PRs or commit messages.

Migrating an existing stub plugin

The bulk of the directories above are skeletons. To turn one into a working plugin:

  1. Read <plugin>/manifest.json to see what permissions and config it claims.
  2. Implement the lifecycle in <plugin>/<name>_plugin.go (or index.js):
    • OnLoad / OnEnable — register handlers, validate config
    • OnDisable / OnUnload — deregister, flush state
  3. Add real test coverage (<name>_plugin_test.go).
  4. Update the plugin's README.md with usage and config docs.
  5. Open a PR titled feat(<plugin>): implement <feature>.