Ambitwin · source-available, not open source · © 2026 Nicolò Ghignatti
| Word | Meaning | Example |
|---|---|---|
| Pin | One exact version written in a file | python = "3.14.8" |
PATH | The list of folders the shell searches for a program | /usr/bin, ~/.cargo/bin |
| Ambient tool | A tool found on the machine’s own PATH, installed by someone else | A Node from nvm |
| Activation | A shell hook that puts the pinned tools on PATH whenever the shell is inside the repo | mise activate bash |
mise exec | Run one command with the pinned tools first on PATH | mise exec -- cargo test |
| Backend | Where mise downloads a tool from | ubi:moonrepo/moon is a GitHub release |
| Project | One package registered with moon | telemetry at backend/telemetry |
| Task | A named job of one project | build, test, lint |
| Target | Project and task written together | telemetry:test; :test means every project’s test |
| Inputs | The files a task depends on | src/**/*, Cargo.toml |
| Hash | A fingerprint of the command, its inputs and its environment | 6bcfbfb3… |
| Cache hit | Same hash as a passed run, so the old result is replayed | 8 ms |
| Affected | A task with at least one changed input file | Editing src/main.rs affects telemetry:test |
| Inherited task | A task defined once per language, given to every project of that language | cargo clippy for every Rust project |
| Recipe | A named list of commands in a just file | affected in just/test.just |
| Module | A file of recipes, reached by its name | test is just/test.just |
| Dependency | A recipe that runs before another | dev runs env first |
| Parameter | A value passed to a recipe | service 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 list | check-version |
Three tools build Ambitwin. Each has one job:
| Tool | Job | Config |
|---|---|---|
| mise | Installs every language and CLI at a pinned version | .mise.toml |
| moon | Runs build, test, lint and deps per project, with cache and affected detection | .moon/, each moon.yml |
| just | The commands a person types | Justfile, 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.
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.
[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"| Pin | Used for | Also read by |
|---|---|---|
node = "24" | frontend, sensor-simulator, eslint-config | Only the major is pinned: mise takes the newest 24, today 24.21.0 |
python = "3.14.8" | agent, simulators, ap-collector, scripts/*.py | CI reads .python-version instead |
rust = "1.99.1" | The six Rust services and four schema crates | CI’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 libraries | CI’s setup-go action; the golang tag in the four Go Dockerfiles must match by hand |
ubi:moonrepo/moon | moon itself, from its GitHub release | |
uv | Python packages and virtual environments | |
istioctl | just k8s istio-install | |
QUARKDOWN_VERSION | Not a tool: an environment variable | just 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.
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| Step | What happens | Real value on a developer machine |
|---|---|---|
| 2–3 | mise finds .mise.toml by walking up from the current folder | /home/…/ambitwin/.mise.toml |
| 4 | Each tool sits in its own folder in the store | ~/.local/share/mise/installs/rust/1.99.1 |
| 6 | Those folders go first on PATH, ahead of anything installed by hand | |
| 7 | Rust is handed to rustup through an environment variable | RUSTUP_TOOLCHAIN=1.99.1 |
| 8–9 | The command runs | cargo 1.99.1 |
| note | Children inherit it: moon, then cargo, then build scripts | mise exec -- moon --version gives moon 2.6.4 |
Example. A laptop has Rust 1.85 from rustup as its default.
cargo build in a plain shell uses 1.85. A newer clippy lint present in CI does not fire.mise exec -- cargo build uses 1.99.1, the same as CI.which cargo can still print ~/.cargo/bin/cargo under mise exec: that is rustup’s launcher, and RUSTUP_TOOLCHAIN picks the version behind it.| Way | When | How |
|---|---|---|
mise exec -- | Recipes, scripts, anywhere a shell setup cannot be assumed | Wraps one command |
| Activation | Typing commands by hand | mise 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 --"]| Caller | Uses mise | How it gets versions |
|---|---|---|
Every just recipe calling moon, uv, python3, npx, istioctl or a script | Yes | mise exec -- |
moon and every task it runs | Yes, through its parent | Inherited PATH |
docker, k3d, kubectl, quarkdown | No | Installed by hand; not managed |
| CI per-language workflows | No | setup-rust and setup-go read .mise.toml with grep; setup-node asks for 24.x; setup-python reads .python-version |
ci-acceptance.yml | Yes | jdx/mise-action |
| Docker images | No | Their own base image tags, kept equal to the pins by hand |
A version bump is its own commit, because CI reads the same numbers and lint rules can change with them.
.mise.toml.mise install.golang tag in the four Go Dockerfiles too..python-version too.just lint all and just test all: a new clippy or go vet can fail code that passed before.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.
| Without it | With it |
|---|---|
| A script loops over 25 folders, one language at a time | moon run :test runs every project’s test, in parallel |
| Every run starts from zero | An unchanged task is replayed in milliseconds |
| “Test what I touched” means remembering which folders | --affected asks git |
| Each project repeats its build and test commands | Commands are written once per language and inherited |
| File | Holds |
|---|---|
.moon/workspace.yml | The list of projects, and git as the source of changes, default branch master |
.moon/toolchain.yml | Only: Node’s package manager is npm. No versions: those are mise’s |
.moon/tasks/rust.yml, go.yml, typescript.yml, python.yml, javascript.yml | The tasks each language gives its projects |
<project>/moon.yml | The project’s language, and only what differs from it |
.moon/cache/ | Hashes, outputs, the last run report. Not committed |
| Language | Projects |
|---|---|
rust | chat, digital-twin, notification, socket, dashboard, telemetry, telemetry-schema, claims-schema, twin-schema, notification-schema |
go | claims-gateway, tenancy, registry, provisioner, auth-contracts, auth-middleware, auth-policy |
typescript | frontend, sensor-simulator |
python | agent, ap-simulator, aq-simulator, ap-collector, acceptance |
javascript | eslint-config |
A project missing from .moon/workspace.yml does not exist for moon: no install, no test, no lint.
| Task | rust | go | typescript | python | javascript |
|---|---|---|---|---|---|
build | cargo build | go build ./... | npm run build | ||
test | cargo test | go test ./... | npm test | npm test | |
lint | cargo clippy -- -D warnings | gofmt -l must be empty, then go vet ./... | npm run lint | npm run lint | |
lint-fix | npm run lint:fix | npm run lint:fix | |||
deps | cargo fetch | go mod download | npm ci | uv sync --locked | npm ci |
deps-check | cargo check | ||||
audit | cargo audit, failure allowed | npm audit --audit-level=high --omit=dev | uv audit | ||
relock | delete lockfile, npm install --package-lock-only --cpu=x64 --os=linux | uv lock | same as typescript |
deps, relock, audit, lint-fix and every test-integration have cache: false: they change files or depend on the outside world, so a replay would lie.test and lint call npm: backend/agent/package.json forwards them to uv run pytest and ruff plus pyright. Projects with no package.json replace them with uv scripts.test lists /schemas/fixtures/**/* and /schemas/json/**/* as inputs. A leading / means “from the repo root”. Contract tests read those files, so a fixture edit must re-run them.| Project | Change | Why |
|---|---|---|
chat, notification | test = cargo test --lib --test architecture_fitness | The other tests/*.rs need MongoDB or Redis |
socket, telemetry | test = cargo test --lib --test architecture | Same reason |
dashboard, digital-twin | test = cargo test --lib | Same reason |
| Those six | add test-integration = bash test-integration.sh | Starts throwaway databases, runs every test, removes them |
registry, tenancy | add test-integration = go test -tags=integration -count 1 ./... | Postgres through testcontainers |
frontend | own build and test inputs, test = npm run test:unit, lint inputs track eslint.config.ts | Vite and Vitest |
ap-simulator, aq-simulator, ap-collector | test, lint, lint-fix as uv scripts | The root .gitignore ignores package.json |
agent | test gets TESTCONTAINERS_RYUK_DISABLED=true | Ryuk cannot start under rootless podman |
acceptance | inherited test, lint, lint-fix excluded | Its 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.
affectedsequenceDiagram
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| Step | What happens | Example |
|---|---|---|
| 3–4 | Reads the config into one graph | 25 projects |
| 5–6 | Asks git for changed files. By default these are the local, uncommitted changes | backend/agent/evals/dataset.json |
| 7 | Keeps only tasks whose inputs match | agent:test watches app/**/*, tests/**/*, pyproject.toml: the dataset is none of them, so it is skipped |
| 9 | Hashes everything the result depends on | 6bcfbfb3… |
| 10–11 | Hit: prints (cached, 6bcfbfb3) | 8 ms |
| 12–14 | Miss: runs the tool, saves the result | 5.9 s |
| 16 | Any failure fails the whole run |
Real numbers. moon run auth-contracts:lint, the same files both times:
| Run | Output | Time |
|---|---|---|
| First | auth-contracts:lint (5s 902ms, 6bcfbfb3) | 5.9 s |
| Second | auth-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.
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.
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.moon/workspace.yml.moon.yml with its language, and only the changes it really needs..github/services.json too, for CI.mise exec -- moon query projects.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.
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.
| Without it | With it |
|---|---|
mise exec -- moon run :test --affected typed by hand | just test affected |
| Commands kept in a README that drifts | The recipe is the command; just --list is always current |
A Makefile | No file-timestamp rules to fight, readable errors, arguments and modules built in |
| One way per language | One door for Rust, Go, TypeScript, Python, Docker, Kubernetes and docs |
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.
| Module | Recipes | What they drive |
|---|---|---|
setup | install, clean-install, audit, deps-check | mise install, moon |
stack | env, dev, start, down, logs | scripts/env/*.sh, scripts/compose/compose-run.py, docker compose |
test | all, affected, one per project, <svc>-integration, frontend-e2e, agent-integration, eval, integration | moon, uv, Playwright, backend/acceptance/run-integration-tests.sh |
lint | all, affected, fix, workflows | moon, scripts/check-workflow-registry.py |
db | clear, clear-telemetry | mongosh and psql inside the running containers |
agent | ingest | scripts/ops/ingest-docs.py |
docs | build, preview, serve | Quarkdown, scripts/check-docs-links.sh, scripts/docs-meta.py |
k8s | create, setup, apply, validate, secrets, build, push, load, restart, logs, … | k3d, kubectl, istioctl, docker |
just --list <module> shows one module, like just --list k8s.
A recipe can name others to run first.
| Recipe | Runs first | Why |
|---|---|---|
just lint all, just lint affected | workflows | A workflow with a broken needs: fails on GitHub with no logs at all; this catches it locally |
just stack dev, just stack start | env | The stack needs .env |
just db clear, clear-telemetry | runtime | Needs compose.runtime.yml, written by the last just stack run |
just docs build | check-version, check-layers | Quarkdown must match QUARKDOWN_VERSION; Quarkdown’s DOM names may appear only in two files |
just docs serve | build | Serves what was just built |
just k8s setup | create, gateway-api, istio-install | A cluster first, then its parts |
just k8s build-push | build, push |
just stack dev --no-agentsequenceDiagram
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| Step | What happens |
|---|---|
| 2 | Eleven 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 |
| 5 | Root 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 |
| 7 | compose.runtime.yml is generated and ignored by git. just db and just stack logs read it |
| 9 | dev 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.
mise exec --. docker, k3d, kubectl and quarkdown are not pinned and are called directly.moon, not here. just only names it.sh or standard-library Python. No Node in scripts/.[doc]. That line is the only help just --list shows.just test affectedThe 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| Step | Tool | What happens |
|---|---|---|
| 2–4 | just | Finds the module, moves to the repo root (the folder above just/) |
| 5 | just | The recipe body is one line, run by bash -c |
| 6 | mise | Puts the pinned tool versions first on PATH |
| 7–9 | moon | Picks the affected tests, hashes them, runs or replays them |
| 10 | just | A line that exits non-zero stops the recipe. Later lines do not run |
| Symptom | Cause | Fix |
|---|---|---|
uv: command not found | A command ran outside mise | mise exec -- uv …, or activate mise |
| Local lint passes, CI fails | A different Rust or Go ran locally | Run through just or mise exec |
mise WARN mise version … available | mise itself is older than the latest | Harmless; mise self-update |
link.exe not found (Windows) | Rust needs the MSVC linker | Install Visual Studio Build Tools, “Desktop development with C++” |
| Linker errors on Linux or macOS | No C compiler | build-essential, or xcode-select --install |
quarkdown … installed, but .mise.toml pins … | Quarkdown version differs from QUARKDOWN_VERSION | Install the pinned build |
| Symptom | Cause | Fix |
|---|---|---|
| A fixture changed but tests still “pass” from cache | A 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 passes | A packed go test -tags=integration … string loses the tag | Write command: go and the flags as args, as registry and tenancy do |
| An integration suite passes without touching Docker | Go served a cached pass | -count 1 in the args |
just test all fails with no database running | A project’s test runs tests/*.rs that need infra | Narrow its test, move the rest to test-integration |
| A new service is never tested | Missing from .moon/workspace.yml, or wrong language | moon query projects |
just setup install reinstalls everything | Expected: 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.
| Symptom | Cause | Fix |
|---|---|---|
| A recipe fails on Windows | windows-shell is set, but many recipes use bash syntax: test -f, sed, #!/usr/bin/env bash bodies | Run from WSL or Git Bash |
A recipe works locally but CI says the Justfile does not parse | just is not pinned: CI installs 1.42.4, a laptop may have a newer one with newer syntax | Keep to features 1.42.4 knows; CI runs just --summary to catch it |
compose.runtime.yml not found | just db … before any just stack run | just stack dev first |
| Recipe runs in the wrong folder | A module file without set working-directory := '..' | Add it |
command not found inside a recipe | The tool is pinned but the line lacks mise exec -- | Add the prefix |
Each module’s recipes in use: Run the Application.