Launchplane is a control-plane service for release records, environment
operations, previews, promotion orchestration, and the merge train. Its Python
package is control_plane; its CLI is launchplane.
Read the Director's overall direction, then this repository's DIRECTION.md for purpose, priorities, roles, stop boundaries, and retired designs. Overall direction takes precedence; issues track work. AGENTS.md is the agent execution guide and the only agent-instruction filename, including any directory-specific guidance.
Use uv with the interpreter pinned in .python-version, and
Node 22.12 or later with the pnpm version in
frontend/package.json. CI uses the same Python pin.
From the repository root:
uv sync --extra dev
uv run launchplane --help
uv run launchplane service serve --help
(cd frontend && pnpm install --frozen-lockfile)
(cd frontend && pnpm validate)Frontend validation runs unit tests, the OpenAPI drift check, TypeScript, and the
production Vite build. The TypeScript OpenAPI client is an ignored build artifact;
development, type checks, browser checks, and production builds generate it from
the checked UI schema. After a backend contract change, run
(cd frontend && pnpm generate:openapi) and commit the schemas and agent contract.
CI rejects drift in those checked artifacts. Existing branches that still commit
the TypeScript client may need one final refresh to adopt its removal.
For IDE type resolution before the first build, run
(cd frontend && pnpm generate:openapi-types) once.
(cd frontend && pnpm test:browser) runs the Playwright
browser smoke. Use .github/github.json for current gates
and testing style for choosing proportionate tests:
uv run --extra dev python -m unittest tests.test_module_nameReplace tests.test_module_name with the module for the changed behavior.
During the Q326 trial, routine changes
use focused local tests plus lint, type checks, and IDE inspection; the full
sharded suite runs only in CI and must pass before gh-pr.py ready and merge.
The approved Q375 refinement keeps safety classifications and adds whole
modules for touched safety areas to local focused tests; testing style owns
the selection rules.
Implementation goes through a task branch and PR. Once required checks pass and review findings are accounted for, follow AGENTS.md to hand the PR to the merge train. Follow DIRECTION.md for merge and release authority.
The service exposes authenticated HTTP APIs and the browser UI at / and /ui.
Shared runtime truth is DB-backed, including deployment, promotion, inventory,
preview, runtime-environment, authorization, and encrypted managed-secret
records. File-backed records and local CLI operations support development,
rehearsal, and explicit bootstrap repair; they are not shared runtime authority.
Use the deployed service API or Launchplane UI for routine shared/runtime mutations. Direct DB mutation flags are local/bootstrap repair tools. See the configuration boundary, service boundary, and operations for supported paths and their prerequisites.
The container entrypoint, Dockerfile, and
compose definition package the service and built frontend.
Supply the minimal bootstrap inputs described in the
service deploy posture
before starting the service. That page owns OAuth setup, self-deploy workflow
configuration, immutable image digests, health checks, migrations, and rollback.
For a served-UI check use a browser or GET /ui; a failed HEAD /ui probe alone
does not establish that the UI is unavailable.
Start with docs/README.md, which indexes implemented contracts, targets, and retired compatibility surfaces. Key references:
- Architecture: control-plane and product-repository boundaries.
- Artifact provenance and event-driven deploys: the product build handoff.
- Client review and release review: release decisions and gated promotion.
- Records and secrets: persistence and secret handling.
- Merge train policy: train contracts and evidence.
- Public readiness: public-source posture and runtime-data boundaries.