# Contributing to Armature

## Development Setup

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

**Build from source:**

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

**Docker (recommended):**

```sh
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.