# Contribute to Casama

Casama is open source, and bug reports, docs fixes, tests and features are all welcome. This page
gets a development machine running, shows how to run every test suite, and explains how to send a
change. For a map of the code, read [How Casama is built](https://docs.casama.ai/develop/architecture.md) first.

- Found a bug? [Open an issue](https://github.com/stackwares/casama/issues/new/choose) with steps to
  reproduce it.
- Planning a large change? Start a [discussion](https://github.com/stackwares/casama/discussions)
  first, so you agree on the approach before you write it.
- Found a security issue? Don't open an issue. Follow
  [SECURITY.md](https://github.com/stackwares/casama/blob/main/SECURITY.md).

## What you need

| Tool                                  | Version                          | Used for                                    |
| ------------------------------------- | -------------------------------- | ------------------------------------------- |
| Node.js                               | 24 or newer (see `.nvmrc`)       | The API, worker, supervisor and packages    |
| pnpm                                  | 12 (`packageManager` in `package.json`) | JavaScript dependencies              |
| Docker                                | recent                           | Supabase, computers, the self-host stack    |
| Supabase CLI                          | recent                           | Local Postgres, Auth, Realtime and Storage  |
| Dart                                  | 3 (stable)                       | The CLI, SDK and `computerd`                |
| Flutter                               | 3.50                             | The app                                     |
| PostgreSQL 17 with pgvector and pgTAP | 17                               | Tests start a throwaway database from it    |

On macOS:

```sh
brew install node pnpm supabase/tap/supabase postgresql@17 pgvector pgtap
```

Then install Docker Desktop and Flutter.

## Run the backend

Clone the repository, install dependencies and start Supabase:

```sh
git clone https://github.com/stackwares/casama.git
cd casama
pnpm install
supabase start          # Postgres on :54322, the Supabase API on :54321, Studio on :54323
cp .env.example .env
```

Fill in `.env` from the output of `supabase status`: the API needs at least `DATABASE_URL`,
`SUPABASE_URL` and `SUPABASE_ANON_KEY`. The comments in `.env.example` explain every setting.

Start the API and the worker, each in its own terminal:

```sh
pnpm --filter @casama/server dev          # the API on http://localhost:8787
pnpm --filter @casama/server dev:worker   # the worker
```

Node.js runs the TypeScript directly, so there's no build step, and both restart when you save a
file. The API serves its reference at `http://localhost:8787/docs`, and
`curl http://localhost:8787/readyz` tells you it's up.

**No model key?** Set `CASAMA_MODEL_FIXTURES=apps/server/test/fixtures/chat.json` in `.env`, and
the worker replays recorded model answers instead of calling a provider.

**Computers** need the supervisor, the egress proxy, the TURN relay and the computer images. Run
them next to Supabase:

```sh
docker compose -f infra/compose/docker-compose.dev.yml up --build
```

On a Mac, `scripts/dev-up.sh` does all of this in one command: it starts Docker and Supabase,
builds the computer images on first run, starts the computer services, then runs the API and
worker until you press Ctrl-C. `scripts/dev-up.sh --down` stops Supabase and the computer services
too.

## Run the app

```sh
cd client
flutter run -d macos --dart-define=CASAMA_API_URL=http://localhost:8787
```

Use `-d chrome`, an iOS simulator or an Android emulator instead of `macos` if you prefer. The app
gets the Supabase address and key from the API, so the API address is the only setting.

On a physical phone, `localhost` is the phone itself. Give the app an address that reaches your
computer instead: an https tunnel, `adb reverse tcp:8787 tcp:8787` for an Android phone on USB, or
your computer's LAN address (iOS blocks plain http unless you allow it). The `SUPABASE_URL` in your
`.env` must be reachable from the phone too, because the app signs in there.

## Run the CLI

```sh
cd dart/cli
dart run bin/casama.dart config --api-url http://localhost:8787
dart run bin/casama.dart signup --email you@example.com
dart run bin/casama.dart org create "My team"
dart run bin/casama.dart org use my-team
dart run bin/casama.dart credential add --provider openrouter
dart run bin/casama.dart bot create Ada --credential <id>
dart run bin/casama.dart chat Ada "What can you do?"
```

See [CLI](https://docs.casama.ai/develop/cli.md) for every command.

## Run the docs

```sh
pnpm --filter @casama/docs dev      # http://localhost:5173
pnpm --filter @casama/docs build    # fails on broken links
```

## Run the tests

Run everything that applies to your change before you push. CI runs all of it.

```sh
pnpm lint                              # Biome
pnpm typecheck                         # TypeScript, every package
pnpm test                              # unit and API tests, every package
pnpm --filter @casama/db test:pgtap    # row-level security tests in supabase/tests
pnpm gen && git diff --exit-code       # generated code is up to date
(cd dart && dart pub get && dart analyze && dart test cli casama_sdk)
(cd client && flutter pub get && flutter gen-l10n && flutter analyze && flutter test)
```

Some things to know:

- **Tests start their own Postgres.** Server and database tests start a throwaway cluster from
  your PostgreSQL 17 binaries and apply every migration. They look in Homebrew's
  `postgresql@17` folder; set `PG_BIN` if yours is elsewhere, or set `TEST_DATABASE_URL` to use a
  database you already run. On macOS, set `LC_ALL=en_US.UTF-8` if Postgres refuses to start.
- **No test calls a real model.** Model calls replay recorded fixtures. `scripts/live-check.sh`
  runs the few live checks against a real model with your own key.
- **Computer tests need Docker.** The sandbox and computer tests, `dart test computerd`, and the
  CLI end-to-end run (`scripts/e2e-cli.sh`) need the computer images built.
- **The web build** in CI is `scripts/build-web.sh`.

## Rules for every change

1. **Contracts first.** Change routes and schemas in `packages/contracts`, run `pnpm gen`, then
   implement. Never hand-write duplicate types or edit the generated Dart client.
2. **Database changes only through migrations** in `supabase/migrations`. Turn on row-level
   security for every new table in the same migration, add pgTAP tests in `supabase/tests`, and
   grant the worker access with `public.allow_worker` if it needs the table.
3. **No secrets** in code, logs, prompts, fixtures or test output.
4. **Tests with every change.** If a test fails, fix the cause; don't skip the test.
5. **Text in the app** goes in `client/lib/l10n/app_en.arb`.
6. **New dependencies** at their latest compatible version, listed in `THIRD_PARTY_NOTICES.md`.
   Put upgrades in their own commit.
7. **Docs change with the behavior** they describe. User docs live in `docs-site/`.
8. **Format only what you touch.** Run `npx biome check --write <files>` on TypeScript you changed
   and `dart format <files>` on Dart you changed. Don't reformat whole folders.

## How decisions are recorded

`docs/DECISIONS.md` is the decision log. Each entry has a number (`D-001` onward), what was
decided and why. When your change makes a choice the code doesn't explain by itself, add a short
entry. Before you change a behavior that looks deliberate, search the log for it; there's usually
a reason, and the entry tells you what to weigh.

`docs/ARCHITECTURE.md` maps each feature to the files behind it. Update it when you add a feature
or move one.

## Send a change

1. Fork the repository and create a branch from `main`.
2. Make your change in small, focused commits, with tests.
3. Sign off every commit:

   ```sh
   git commit -s -m "Add bot budget checks"
   ```

   This adds a `Signed-off-by` line certifying the
   [Developer Certificate of Origin](https://developercertificate.org/): that you wrote the change
   or have the right to submit it. Casama uses the DCO instead of a contributor license agreement.
4. Open a pull request and fill in the template: what changed, why, and how you tested it.

A maintainer reviews it, usually within a few days. Small pull requests get reviewed fastest.

## Licenses

Everything in the repository is Apache-2.0, except the `ee/` folder, which is under the Casama
Enterprise License: you can read it and try it, and production use needs a license key. By
contributing, you agree your contribution is licensed under Apache-2.0, or under the Casama
Enterprise License for changes inside `ee/`.
