Development setup

RequirementsCopy Anchor Link

• Git, with access to the orkstage organization.
• Node.js 24 or later and pnpm 12. Run corepack enable to get the pnpm version pinned in package.json.
• Docker, for Postgres, Redis, Mailpit, MiniStack and the OpenTofu runner containers.
• Nothing else for the CLI: its Rust builds run in a container.

The workspaceCopy Anchor Link

OrkStage lives in several repositories. The orkstage-dev workspace checks them out as git submodules and wires them together, so you can change the control plane and the console in one place.

git clone --recurse-submodules git@github.com:orkstage/orkstage-dev.git
cd orkstage-dev
pnpm bootstrap                 # git hooks, installs and builds (core first, then the console)
pnpm local:up                  # Postgres, Redis, Mailpit
cp orkstage/.env.example orkstage/.env
pnpm db:deploy && pnpm db:seed
pnpm dev                       # API on http://localhost:4000 and the worker
pnpm dev:console               # console on http://localhost:3000, in a second terminal

How it fits together:

• orkstage/ (the core) is a normal clone with its own pnpm workspace and lockfile. Inside it, every command works as in a standalone checkout. It does not use Turborepo: pnpm -r already runs scripts in dependency order (see ADR 0006). All code is ESM TypeScript 7 with module: NodeNext.
• The workspace root holds the console and the scan engine package. The console's @orkstage/* dependencies point to orkstage/packages through pnpm overrides, so a change in a shared package reaches the console after pnpm core:build, with nothing to publish.

Inside orkstage/, MINISTACK_E2E=1 pnpm --filter @orkstage/cloud-aws test runs the adapter contract tests against MiniStack, and pnpm format or pnpm format:check runs Prettier.

Pull requestsCopy Anchor Link

Every change reaches main through a pull request in the repository that owns the code:

1. Run pnpm sync so every submodule is on the latest main.
2. In the submodule you are changing, create a branch, commit and push it, then open a pull request. CI runs on the pull request.
3. Merge with a squash merge once CI is green. Merged branches are deleted automatically.
4. When a set of versions works together, commit the new submodule pins in orkstage-dev, also through a pull request.

The workspace pre-push hook refuses direct pushes to main from your machine. On the server, rulesets require pull requests and green CI on main once the GitHub plan allows them for private repositories.

Supply chain settingsCopy Anchor Link

• Only the packages listed under allowBuilds in pnpm-workspace.yaml may run build scripts. Telemetry that runs at install time is denied.
• pnpm's minimum release age keeps very recent releases out. If a dependency is too new, pin the newest older version that qualifies instead of adding an exemption.

The CLI and scan engine (Rust)Copy Anchor Link

Development machines may block unsigned native executables. So the CLI is built, tested and linted in containers:

cd orkstage-cli
docker build -t orkstage/cli-builder:1.99 -f docker/builder.Dockerfile docker
RUN="docker run --rm -v $PWD:/work -v orkstage-cargo-registry:/usr/local/cargo/registry -v orkstage-cli-target:/work/target -w /work orkstage/cli-builder:1.99"
$RUN cargo fmt --all --check
$RUN cargo clippy --workspace --all-targets -- -D warnings
$RUN cargo test --workspace
$RUN sh scripts/build-wasm.sh          # regenerates dist/scan-wasm (@orkstage/scan)

On Windows, Git Bash needs $(pwd -W) and MSYS_NO_PATHCONV=1. PowerShell needs ${PWD}.

Snapshot tests use insta. Fixtures live in crates/orkstage-scan/tests/fixtures/<kind>/<project>/.

OpenTofu also runs only in containers, started by the worker's runner. You do not need to install it.

This siteCopy Anchor Link

The website and docs live in the orkstage-site repository (orkstage-site/ in the workspace). The site is its own pnpm workspace:

cd orkstage-site
pnpm install
pnpm dev          # http://localhost:3100
pnpm build        # static export to out/
pnpm serve        # serve out/ locally on :4321

Docs are MDX files in content/docs/. Each section folder has a meta.json with "root": true, which turns the section into a sidebar tab. The API reference is generated from openapi/orkstage.json.