/

Ambitwin · source-available, not open source · © 2026 Nicolò Ghignatti

Build System

Keywords on this page
WordMeaningExample
PinOne exact version written in a filepython = "3.14.8"
PATHThe list of folders the shell searches for a program/usr/bin, ~/.cargo/bin
Ambient toolA tool found on the machine’s own PATH, installed by someone elseA Node from nvm
ActivationA shell hook that puts the pinned tools on PATH whenever the shell is inside the repomise activate bash
mise execRun one command with the pinned tools first on PATHmise exec -- cargo test
BackendWhere mise downloads a tool fromubi:moonrepo/moon is a GitHub release
ProjectOne package registered with moontelemetry at backend/telemetry
TaskA named job of one projectbuild, test, lint
TargetProject and task written togethertelemetry:test; :test means every project’s test
InputsThe files a task depends onsrc/**/*, Cargo.toml
HashA fingerprint of the command, its inputs and its environment6bcfbfb3…
Cache hitSame hash as a passed run, so the old result is replayed8 ms
AffectedA task with at least one changed input fileEditing src/main.rs affects telemetry:test
Inherited taskA task defined once per language, given to every project of that languagecargo clippy for every Rust project
RecipeA named list of commands in a just fileaffected in just/test.just
ModuleA file of recipes, reached by its nametest is just/test.just
DependencyA recipe that runs before anotherdev runs env first
ParameterA value passed to a recipeservice in just stack logs telemetry
[doc]The one-line help text just --list shows“Run only tests for services affected…”
[private]A recipe hidden from the listcheck-version

Three tools build Ambitwin. Each has one job:

ToolJobConfig
miseInstalls every language and CLI at a pinned version.mise.toml
moonRuns build, test, lint and deps per project, with cache and affected detection.moon/, each moon.yml
justThe commands a person typesJustfile, just/*.just

just is the only door for a person. just calls mise exec, and mise exec runs moon or a language tool with the pinned versions.

flowchart LR
    P["person"] --> J["just"]
    J --> M["mise exec"]
    M --> Mo["moon"]
    Mo --> L["cargo, go, npm, uv"]
    J --> D["docker compose"]
    J --> K["kubectl, k3d"]
    J --> Q["quarkdown"]

GitHub Actions calls the language tools directly, without moon or just, but reads the same pins. See GitHub Actions CI.


Part 1: Versions (mise)

mise installs every language and CLI Ambitwin uses, at the version pinned in .mise.toml. It puts exactly those versions on PATH for a command. One file answers “which version?” for every machine and for CI.

The pins

[tools]
node = "24"
python = "3.14.8"
rust = "1.99.1"
go = "1.27.3"
"ubi:moonrepo/moon" = "2.6.4"
uv = "0.13.5"
istioctl = "1.31.3"

[env]
QUARKDOWN_VERSION = "2.7.0"
PinUsed forAlso read by
node = "24"frontend, sensor-simulator, eslint-configOnly the major is pinned: mise takes the newest 24, today 24.21.0
python = "3.14.8"agent, simulators, ap-collector, scripts/*.pyCI reads .python-version instead
rust = "1.99.1"The six Rust services and four schema cratesCI’s setup-rust action; cd-registry.yml builds the Rust base image with it
go = "1.27.3"The four Go services and three Go librariesCI’s setup-go action; the golang tag in the four Go Dockerfiles must match by hand
ubi:moonrepo/moonmoon itself, from its GitHub release
uvPython packages and virtual environments
istioctljust k8s istio-install
QUARKDOWN_VERSIONNot a tool: an environment variablejust docs build and the docs workflows compare the installed Quarkdown to it

Quarkdown is not a mise tool. Its release is a 92 MB zip with its own Java runtime, and the mise backends keep only the launcher script, which then cannot find its classes. So it is installed separately, and only its version lives here.

How a command gets its tools

Every just recipe that calls a pinned tool starts with mise exec --. Here is what that does for mise exec -- cargo --version:

sequenceDiagram
    autonumber
    participant S as shell
    participant Mi as mise
    participant F as mise.toml
    participant St as mise store
    participant C as cargo
    S->>Mi: mise exec -- cargo --version
    Mi->>F: read the tools section
    F-->>Mi: rust 1.99.1, go 1.27.3, node 24, ...
    Mi->>St: is each version installed?
    alt missing
        Mi->>St: download and install it first
    end
    Mi->>Mi: new PATH with each tool's folder first
    Mi->>Mi: set RUSTUP_TOOLCHAIN=1.99.1 and similar
    Mi->>C: start cargo with that environment
    C-->>S: cargo 1.99.1
    Note over C: every child of cargo inherits the same environment
StepWhat happensReal value on a developer machine
2–3mise finds .mise.toml by walking up from the current folder/home/…/ambitwin/.mise.toml
4Each tool sits in its own folder in the store~/.local/share/mise/installs/rust/1.99.1
6Those folders go first on PATH, ahead of anything installed by hand
7Rust is handed to rustup through an environment variableRUSTUP_TOOLCHAIN=1.99.1
8–9The command runscargo 1.99.1
noteChildren inherit it: moon, then cargo, then build scriptsmise exec -- moon --version gives moon 2.6.4

Example. A laptop has Rust 1.85 from rustup as its default.

Two ways to get the tools

WayWhenHow
mise exec --Recipes, scripts, anywhere a shell setup cannot be assumedWraps one command
ActivationTyping commands by handmise activate bash, zsh, fish or pwsh in the shell profile

Activation is optional. A fresh clone with only just and mise installed runs every recipe, because each one wraps its tool.

flowchart TD
    A["a command needs a tool"] --> B{"run by a just recipe?"}
    B -- yes --> C["recipe already uses mise exec"]
    B -- no --> D{"shell has mise activated?"}
    D -- yes --> E["pinned tool on PATH"]
    D -- no --> F["ambient tool, maybe the wrong version, maybe missing"]
    F --> G["prefix with mise exec --"]

Who uses mise, and who does not

CallerUses miseHow it gets versions
Every just recipe calling moon, uv, python3, npx, istioctl or a scriptYesmise exec --
moon and every task it runsYes, through its parentInherited PATH
docker, k3d, kubectl, quarkdownNoInstalled by hand; not managed
CI per-language workflowsNosetup-rust and setup-go read .mise.toml with grep; setup-node asks for 24.x; setup-python reads .python-version
ci-acceptance.ymlYesjdx/mise-action
Docker imagesNoTheir own base image tags, kept equal to the pins by hand

Changing a version

A version bump is its own commit, because CI reads the same numbers and lint rules can change with them.

  1. Edit .mise.toml.
  2. mise install.
  3. For Go: change the golang tag in the four Go Dockerfiles too.
  4. For Python: change .python-version too.
  5. just lint all and just test all: a new clippy or go vet can fail code that passed before.

Part 2: Tasks (moon)

moon runs the per-project tasks of the whole repository: install, build, test, lint, audit. It knows every project, skips what did not change, and replays results it already has.

Version 2.6.4, pinned in .mise.toml, always started through mise exec.

Why moon

Without itWith it
A script loops over 25 folders, one language at a timemoon run :test runs every project’s test, in parallel
Every run starts from zeroAn unchanged task is replayed in milliseconds
“Test what I touched” means remembering which folders--affected asks git
Each project repeats its build and test commandsCommands are written once per language and inherited

Configuration

FileHolds
.moon/workspace.ymlThe list of projects, and git as the source of changes, default branch master
.moon/toolchain.ymlOnly: Node’s package manager is npm. No versions: those are mise’s
.moon/tasks/rust.yml, go.yml, typescript.yml, python.yml, javascript.ymlThe tasks each language gives its projects
<project>/moon.ymlThe project’s language, and only what differs from it
.moon/cache/Hashes, outputs, the last run report. Not committed

The 25 projects

LanguageProjects
rustchat, digital-twin, notification, socket, dashboard, telemetry, telemetry-schema, claims-schema, twin-schema, notification-schema
goclaims-gateway, tenancy, registry, provisioner, auth-contracts, auth-middleware, auth-policy
typescriptfrontend, sensor-simulator
pythonagent, ap-simulator, aq-simulator, ap-collector, acceptance
javascripteslint-config

A project missing from .moon/workspace.yml does not exist for moon: no install, no test, no lint.

Tasks per language

Taskrustgotypescriptpythonjavascript
buildcargo buildgo build ./...npm run build
testcargo testgo test ./...npm testnpm test
lintcargo clippy -- -D warningsgofmt -l must be empty, then go vet ./...npm run lintnpm run lint
lint-fixnpm run lint:fixnpm run lint:fix
depscargo fetchgo mod downloadnpm ciuv sync --lockednpm ci
deps-checkcargo check
auditcargo audit, failure allowednpm audit --audit-level=high --omit=devuv audit
relockdelete lockfile, npm install --package-lock-only --cpu=x64 --os=linuxuv locksame as typescript

What projects change

ProjectChangeWhy
chat, notificationtest = cargo test --lib --test architecture_fitnessThe other tests/*.rs need MongoDB or Redis
socket, telemetrytest = cargo test --lib --test architectureSame reason
dashboard, digital-twintest = cargo test --libSame reason
Those sixadd test-integration = bash test-integration.shStarts throwaway databases, runs every test, removes them
registry, tenancyadd test-integration = go test -tags=integration -count 1 ./...Postgres through testcontainers
frontendown build and test inputs, test = npm run test:unit, lint inputs track eslint.config.tsVite and Vitest
ap-simulator, aq-simulator, ap-collectortest, lint, lint-fix as uv scriptsThe root .gitignore ignores package.json
agenttest gets TESTCONTAINERS_RYUK_DISABLED=trueRyuk cannot start under rootless podman
acceptanceinherited test, lint, lint-fix excludedIts suite needs a full stack: just test integration

Merging. A project’s task is merged with the inherited one. mergeArgs: replace and mergeInputs: replace replace the inherited value instead of adding to it. frontend replaces its test inputs, so it lists the fixture folders again itself.

What moon does on affected

sequenceDiagram
    autonumber
    participant J as just
    participant Mi as mise
    participant Mo as moon
    participant G as git
    participant Ca as moon cache
    participant T as cargo, go, npm, uv
    J->>Mi: mise exec -- moon run :test --affected
    Mi->>Mo: start with pinned tools
    Mo->>Mo: read workspace.yml, each language tasks file, every moon.yml
    Mo->>Mo: build the graph: 25 projects, their tasks
    Mo->>G: which files changed?
    G-->>Mo: local changes in the working tree
    Mo->>Mo: keep each test whose inputs match a changed file
    loop each kept task, in parallel
        Mo->>Mo: hash command, args, env, input file contents
        Mo->>Ca: seen this hash with a pass?
        alt hit
            Ca-->>Mo: replay stored output
        else miss
            Mo->>T: run the command in the project folder
            T-->>Mo: exit code and output
            Mo->>Ca: store the hash and output, if it passed
        end
    end
    Mo-->>J: summary, non-zero exit if any task failed
StepWhat happensExample
3–4Reads the config into one graph25 projects
5–6Asks git for changed files. By default these are the local, uncommitted changesbackend/agent/evals/dataset.json
7Keeps only tasks whose inputs matchagent:test watches app/**/*, tests/**/*, pyproject.toml: the dataset is none of them, so it is skipped
9Hashes everything the result depends on6bcfbfb3…
10–11Hit: prints (cached, 6bcfbfb3)8 ms
12–14Miss: runs the tool, saves the result5.9 s
16Any failure fails the whole run

Real numbers. moon run auth-contracts:lint, the same files both times:

RunOutputTime
Firstauth-contracts:lint (5s 902ms, 6bcfbfb3)5.9 s
Secondauth-contracts:lint (cached, 6bcfbfb3)8 ms

Real affected example. With uncommitted edits to backend/notification/CLAUDE.md, backend/chat/openapi.yaml and backend/agent/evals/dataset.json, moon query affected lists projects notification, chat and agent as touched. No test or lint is affected: none of those files is a test or lint input. Only agent:lint-fix and agent:relock are, because they declare no inputs and so match any file of their project.

Will a task run?

flowchart TD
    S["target, like :test"] --> A{"--affected given?"}
    A -- no --> H
    A -- yes --> B{"a changed file matches its inputs?"}
    B -- no --> Skip["skipped"]
    B -- yes --> H{"cache: false?"}
    H -- yes --> Run["run"]
    H -- no --> C{"same hash passed before?"}
    C -- yes --> Rep["replay, a few ms"]
    C -- no --> Run
    Run --> P{"exit code 0?"}
    P -- yes --> Save["save to the cache"]
    P -- no --> Fail["run fails"]

--force skips the cache and the affected check.

Inspecting without running

mise exec -- moon query projects            # every project, its language
mise exec -- moon query tasks               # every task of every project
mise exec -- moon task telemetry:test       # one task: command, inputs, where it came from
mise exec -- moon query affected            # what the current changes touch
mise exec -- moon query changed-files       # the files moon sees as changed

Adding a project

  1. Register it in .moon/workspace.yml.
  2. Add moon.yml with its language, and only the changes it really needs.
  3. Register it in .github/services.json too, for CI.
  4. Check: mise exec -- moon query projects.

Pick the language on purpose

The language decides the inherited tasks. javascript gives only deps and relock, for support packages. A Python project with no package.json must replace test and lint, or they fail calling npm.


Part 3: Commands (just)

just is the only command line a person needs. Every workflow is just <module> <recipe>. A recipe is a short, named wrapper around the real command, so nobody has to remember the long one.

Why just

Without itWith it
mise exec -- moon run :test --affected typed by handjust test affected
Commands kept in a README that driftsThe recipe is the command; just --list is always current
A MakefileNo file-timestamp rules to fight, readable errors, arguments and modules built in
One way per languageOne door for Rust, Go, TypeScript, Python, Docker, Kubernetes and docs

Layout

The root Justfile only declares modules and the shell:

set shell := ["bash", "-c"]
set windows-shell := ["powershell.exe", "-NoLogo", "-Command"]

mod setup 'just/setup.just'
mod stack 'just/stack.just'
mod test 'just/test.just'
mod db 'just/db.just'
mod agent 'just/agent.just'
mod docs 'just/docs.just'
mod lint 'just/lint.just'
mod k8s 'just/k8s.just'

Each module file starts with set working-directory := '..', so every recipe runs from the repo root, whatever folder just was typed in. Bare just runs just --list.

ModuleRecipesWhat they drive
setupinstall, clean-install, audit, deps-checkmise install, moon
stackenv, dev, start, down, logsscripts/env/*.sh, scripts/compose/compose-run.py, docker compose
testall, affected, one per project, <svc>-integration, frontend-e2e, agent-integration, eval, integrationmoon, uv, Playwright, backend/acceptance/run-integration-tests.sh
lintall, affected, fix, workflowsmoon, scripts/check-workflow-registry.py
dbclear, clear-telemetrymongosh and psql inside the running containers
agentingestscripts/ops/ingest-docs.py
docsbuild, preview, serveQuarkdown, scripts/check-docs-links.sh, scripts/docs-meta.py
k8screate, setup, apply, validate, secrets, build, push, load, restart, logs, …k3d, kubectl, istioctl, docker

just --list <module> shows one module, like just --list k8s.

Recipes that run others first

A recipe can name others to run first.

RecipeRuns firstWhy
just lint all, just lint affectedworkflowsA workflow with a broken needs: fails on GitHub with no logs at all; this catches it locally
just stack dev, just stack startenvThe stack needs .env
just db clear, clear-telemetryruntimeNeeds compose.runtime.yml, written by the last just stack run
just docs buildcheck-version, check-layersQuarkdown must match QUARKDOWN_VERSION; Quarkdown’s DOM names may appear only in two files
just docs servebuildServes what was just built
just k8s setupcreate, gateway-api, istio-installA cluster first, then its parts
just k8s build-pushbuild, push

Example: just stack dev --no-agent

sequenceDiagram
    autonumber
    participant J as just
    participant E as env recipe
    participant Sc as scripts/env
    participant Py as compose-run.py
    participant D as docker compose
    J->>E: dependency first
    E->>Sc: create.sh, vapid.sh, token.sh, config.sh, ...
    Sc-->>E: env file filled, existing keys kept
    J->>Py: mise exec -- python3 scripts/compose/compose-run.py dev --no-agent
    Py->>Py: collect docker-compose.yml and docker-compose.dev.yml of each folder
    Py->>Py: drop folders matching agent
    Py->>Py: write compose.runtime.yml with an include list
    Py->>D: remove stopped leftovers of the same containers
    Py->>D: docker compose -f compose.runtime.yml up --watch --remove-orphans, minus agent
    D-->>J: services running, files watched
StepWhat happens
2Eleven scripts, each adds only the keys .env lacks: VAPID keys, eval token secret, Keycloak, Langfuse, control plane, gateway signing key, ingest key, telemetry database, Rust settings
5Root docker-compose.yml, then each folder in backend/, simulators/, devices/, then frontend/. In dev mode each folder’s docker-compose.dev.yml is added
6--no-agent is a group: it drops every name containing agent. Bare words work too: just stack dev socket drops socket
7compose.runtime.yml is generated and ignored by git. just db and just stack logs read it
9dev adds --watch, so file changes reach the containers. start uses up --build -d instead

Groups: --no-agent, --no-metrics (Prometheus, Grafana), --no-simulators, --no-devices (ap-collector). --build rebuilds images, --dry-run prints the command and stops.

Rules for recipes


One command, end to end: just test affected

The three tools in order. The person types one line; the rest runs underneath.

sequenceDiagram
    autonumber
    participant P as person
    participant J as just
    participant Mi as mise
    participant Mo as moon
    participant T as cargo, go, npm, uv
    P->>J: just test affected
    J->>J: find module test, load just/test.just
    J->>J: working directory = repo root
    J->>Mi: mise exec -- moon run :test --affected
    Mi->>Mo: moon with pinned tools on PATH
    Mo->>Mo: keep tests whose inputs match a changed file
    Mo->>T: run each kept task, or replay it from cache
    T-->>Mo: exit code
    Mo-->>Mi: exit code
    Mi-->>J: same exit code
    J-->>P: stop at the first failing line
StepToolWhat happens
2–4justFinds the module, moves to the repo root (the folder above just/)
5justThe recipe body is one line, run by bash -c
6misePuts the pinned tool versions first on PATH
7–9moonPicks the affected tests, hashes them, runs or replays them
10justA line that exits non-zero stops the recipe. Later lines do not run

Traps

mise

SymptomCauseFix
uv: command not foundA command ran outside misemise exec -- uv …, or activate mise
Local lint passes, CI failsA different Rust or Go ran locallyRun through just or mise exec
mise WARN mise version … availablemise itself is older than the latestHarmless; mise self-update
link.exe not found (Windows)Rust needs the MSVC linkerInstall Visual Studio Build Tools, “Desktop development with C++”
Linker errors on Linux or macOSNo C compilerbuild-essential, or xcode-select --install
quarkdown … installed, but .mise.toml pins …Quarkdown version differs from QUARKDOWN_VERSIONInstall the pinned build

moon

SymptomCauseFix
A fixture changed but tests still “pass” from cacheA project replaced its test inputs and dropped /schemas/fixtures/**/*List the fixture folders in the replaced inputs, like frontend does
A Go integration run says [no test files] and passesA packed go test -tags=integration … string loses the tagWrite command: go and the flags as args, as registry and tenancy do
An integration suite passes without touching DockerGo served a cached pass-count 1 in the args
just test all fails with no database runningA project’s test runs tests/*.rs that need infraNarrow its test, move the rest to test-integration
A new service is never testedMissing from .moon/workspace.yml, or wrong languagemoon query projects
just setup install reinstalls everythingExpected: deps has cache: false and runs without --affected

CI does not run moon. Each workflow calls the language tools directly, with the same commands: CI.

just

SymptomCauseFix
A recipe fails on Windowswindows-shell is set, but many recipes use bash syntax: test -f, sed, #!/usr/bin/env bash bodiesRun from WSL or Git Bash
A recipe works locally but CI says the Justfile does not parsejust is not pinned: CI installs 1.42.4, a laptop may have a newer one with newer syntaxKeep to features 1.42.4 knows; CI runs just --summary to catch it
compose.runtime.yml not foundjust db … before any just stack runjust stack dev first
Recipe runs in the wrong folderA module file without set working-directory := '..'Add it
command not found inside a recipeThe tool is pinned but the line lacks mise exec --Add the prefix

Each module’s recipes in use: Run the Application.