# Contributing to MAESTRO

Thanks for your interest in contributing! This guide covers how to build, run,
test, and submit changes.

## Code of Conduct

This project is governed by our [Code of Conduct](CODE_OF_CONDUCT.md). By
participating, you are expected to uphold it.

## Prerequisites

- **Node.js 22+**
- An **OpenAI-compatible LLM endpoint** for running the app (e.g. [Ollama](https://ollama.com/) at `http://localhost:11434/v1`, or vLLM). Not required just to build/test.
- Optional, for the Bash tool sandbox: `bwrap` (bubblewrap) with unprivileged
  user namespaces, plus `python3`/`pip` for the pre-baked tool packages.

## Setup

```bash
git clone <your fork or the repo URL> maestro
cd maestro
npm ci                 # backend deps
npm --prefix ui ci     # UI deps
cp config.yaml.example config.yaml   # then edit provider/workers
```

## Build & run

```bash
scripts/build-all.sh        # builds backend (dist/) and UI (ui/dist/)
scripts/server.sh start     # build + start with PID management
scripts/server.sh logs      # tail logs
scripts/server.sh stop
# open http://localhost:9876
```

`scripts/build-all.sh` also pre-bakes the Python packages the Bash sandbox uses
(`runtime/python-requirements.txt`). Pass `--skip-python` to skip that step, or
run `scripts/prebake-python.sh` separately (may need `sudo` to write to the
system Python). See `docs/operations/bash-sandbox-provisioning.md`.

During UI development, `cd ui && npm run dev` runs Vite with HMR.

## Tests

```bash
npm test                                   # all backend tests (vitest)
npx vitest run src/engine/tools/core.test.ts   # a single file
```

- Backend tests live next to their source as `*.test.ts` (vitest auto-discovers).
- DOM-dependent UI tests need a browser-like environment and may not run in a
  headless sandbox.

## Conventions

- **Config keys are snake_case in YAML** (`max_concurrency`) and **camelCase in
  code** (`maxConcurrency`); `src/config.ts`'s `transformKeys` converts between them.
- New config options must be reflected in `config.yaml.example` **and**
  `docs/configuration.md`.
- New tools: add a module under `src/engine/tools/`, register it in
  `tools/index.ts`, list it in the relevant Piece's `allowed_tools`, and add a
  one-line description plus `docs/tools/<name>.md`. See `docs/maintenance-checklist.md`.
- DB schema changes: update `src/db/schema.sql` and add an idempotent migration in
  `src/db/migrate.ts`.

## Translations

Documentation is **English-first**, with a Japanese sibling using a `.ja.md`
suffix (e.g. `README.md` / `README.ja.md`, `docs/docker.md` / `docs/docker.ja.md`).
English is canonical: a `.md` page is the source of truth and its `.ja.md`
sibling is the translation.

If you change an English page, update the `.ja.md` sibling when you can. If you
can't, note in the PR that the translation needs updating — a stale translation
should not block an English fix. New docs should land in English first; a
translation can follow in a later PR.

## Architecture

See `AGENTS.md` for a contributor-oriented architecture overview and
`docs/architecture.md` for the execution flow in depth.

## Submitting changes

1. Branch from `main` (e.g. `feat/...`, `fix/...`).
2. Keep changes focused; add/adjust tests for behavior you change.
3. Ensure `npx tsc --noEmit` is clean and the relevant tests pass.
4. Open a pull request describing the change and how you verified it.

## License

By contributing, you agree that your contributions are licensed under the
project's [Apache-2.0](LICENSE) license.