core/CONTRIBUTING.md

Contributing to Armature

Development Setup

Requirements: Go 1.23+, Node.js 20+ (for frontend tests), SQLite (local dev).

Build from source:

cd server
go build -o armature .
DB_DRIVER=sqlite DATABASE_URL=/tmp/armature.db ./armature

Docker (recommended):

docker compose up --build
# open http://localhost:3000  (default login: admin / admin)

Data persists in the sb_data named volume. Reset with docker compose down -v.

Project Structure

server/          Go backend (handlers, store, config, auth, workflow engine)
src/js/          Browser SDK and built-in surface JS
packages/        Extension packages (surfaces, libraries, browser extensions)
  build.sh       Builds each subdirectory into a .pkg archive
docs/            Documentation markdown (served at /api/v1/docs)
k8s/             Kubernetes manifests and Helm chart

Running Tests

Backend: cd server && go test ./...

Frontend: node --test src/js/__tests__/

Code Conventions

• Go: Standard formatting via gofmt. Handlers in server/handlers/, persistence in server/store/. Database access goes through the store interface, never directly from handlers.
• Browser JS: Vanilla ES modules + Preact via CDN. No build step for browser code (except the CM6 editor bundle). SDK lives at src/js/sw/.
• Extensions: IIFE pattern (see packages/*/js/script.js). Register with sw.renderers or sw.slots via the sw:ready event.

Creating a Package

A package is a ZIP archive (.pkg) containing manifest.json and optional js/, css/, assets/, and script.star files. The build script (packages/build.sh) automates this. See docs/PACKAGE-FORMAT.md for the full manifest spec and docs/TUTORIAL-FIRST-EXTENSION.md for a walkthrough.

Pull Request Process

1. Create a feature branch from main.
2. Make your changes. Keep commits focused.
3. Run both Go and JS test suites and confirm they pass.
4. Submit a PR with a clear description of what changed and why.
5. Address review feedback, then squash-merge when approved.