96 lines
3.5 KiB
Markdown
96 lines
3.5 KiB
Markdown
# 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.
|