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. 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 with the major pinned in .node-version. The compatibility
floors remain in the package metadata, and Corepack reads the exact pnpm version
from frontend/package.json. CI reads both runtime pins.
Docker base-image majors remain reviewed copies because FROM must resolve before
a build can COPY repository version files.
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)pnpm validate prepares generated OpenAPI artifacts once; standalone commands
prepare their own. The canonical OpenAPI JSON, UI slice and TypeScript client
are ignored build artifacts generated from Python source before frontend tests, development, type
checks and production builds, including Docker and CI.
Python contract tests and inventory scripts also derive schemas from source.
After a backend contract change, run (cd frontend && pnpm generate:openapi)
and commit only the agent contract. CI still rejects drift in that runtime contract.
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.
Follow testing style for local safety
module selection, the Q778 focused PR pilot and the full candidate merge gate.
Follow AGENTS.md for source delivery and 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.