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. By participating, you are expected to uphold it.

Prerequisites

Node.js 22+
An OpenAI-compatible LLM endpoint for running the app (e.g. Ollama 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

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

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

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

Branch from main (e.g. feat/..., fix/...).
Keep changes focused; add/adjust tests for behavior you change.
Ensure npx tsc --noEmit is clean and the relevant tests pass.
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.

3.5 KiB Raw Permalink Blame History