Development Guide

Development Guide

This page combines AGENTS.md, CONTRIBUTING.md, docs/CONTROLLER_GUIDE.md, and PLUGIN_DEVELOPMENT.md into a concise contributor workflow across all three repositories.

Repository Layout (streamspace)

• controller/: Kubebuilder project; controllers in controllers/, APIs under api/v1alpha1, helpers in pkg/.
• api/: Go service with cmd/main.go, internal/ packages (auth, middleware, db, webhook). Tests live next to source.
• ui/: React + Vite app using TS, MUI, React Query, Zustand. Components under src/, hooks in src/hooks/, tests *.test.tsx.
• chart/, manifests/, terraform/: Deployment assets. scripts/ contains helper automation.
• Docs live in root (README.md, QUICKSTART.md, DEPLOYMENT.md, etc.) and docs/.

Tooling & Commands

• make dev-setup – checks Go/Node/Docker/kubectl/Helm and installs Go modules + npm deps.
• make fmt – gofmt controllers/API, run UI formatter (npm run format).
• make lint – golangci-lint for Go, ESLint for UI (install golangci-lint locally).
• make test – runs Go tests with coverage and UI tests (npm test -- --coverage --watchAll=false).
• Component builds: make build-controller, make build-api, make build-ui. Docker targets available via make docker-build-*.
• UI dev server: cd ui && npm run dev; backend binaries via go run ./cmd/main.go.

Coding Conventions

• Go: gofmt tabs, idiomatic package names, table-driven tests, context.Context for external calls. Controllers follow <resource>_controller.go naming.
• TypeScript: Strict typing, PascalCase components, camelCase props/hooks, co-located Emotion/MUI styling. Keep components focused and reuse hooks.
• Commits: Conventional Commits (feat(repos): ..., docs(site): ...). Use imperative tense under 72 chars.
• PRs: Describe scope, link issues/ROADMAP items, include screenshots or CLI output for visible changes, and note make fmt lint test status.

Plugin Development (streamspace-plugins + docs/PLUGIN_API.md)

• Plugin directories live under official/ or community/ with manifest.json, index.js/ts, optional config schema, and assets.
• Supported types: extension UI widgets, webhook handlers, API integrations, UI themes. Events include session/user/template lifecycle and system notifications.
• catalog.yaml lists discoverable plugins with metadata consumed by the controller/UI.
• Use the Plugin API’s streamspace global (session/user/template APIs, notifications, email, storage, commands, logging). Lifecycle hooks onLoad/onUnload manage registrations.
• Test plugins locally via the StreamSpace CLI or UI plugin sandbox before submitting PRs to streamspace-plugins.

Template Contributions (streamspace-templates)

• Organize templates by category directories (browsers/, development/, etc.). File names should be lowercase kebab-case (firefox-browser.yaml).
• Follow the stream.space/v1alpha1 Template spec: include metadata, displayName, description, category, icon, image, resources, env vars, ports, VNC config, and tags.
• Update catalog.yaml with new entries, validate with kubectl apply --dry-run=client -f <file> and CRD server dry-run.

See Testing-and-QA for verification expectations and Security-and-Compliance for required hardening steps when touching auth or infrastructure-sensitive code.