The Toolchain: mise, moon & just

CrowdVision is a polyglot monorepo: TypeScript services, a Python AI agent, a Rust contracts service, and shared JavaScript tooling. To keep that manageable on any operating system, the developer experience rests on three cooperating layers, each with a single, well-defined responsibility.

Dependency installation is a moon task like any other (:deps, :relock). There is no separate script layer: everything is mise plus moon, fronted by just.

flowchart TD
  dev([Developer]) --> just["just (recipe)"]
  just --> mise["mise exec — injects pinned tools onto PATH"]
  mise --> moon["moon — task graph, caching, affected"]
  moon --> tasks["build, test, lint, audit, deps, deps-check, relock"]
  cfgA["mise.toml"] -->|versions| mise
  cfgB["moon/workspace.yml"] -->|package list| moon

The problem this solves

Before this setup, tools were resolved from whatever happened to be on the developer’s PATH. That is fragile: a globally installed Node (from nvm) or Rust (from rustup) silently shadows the versions the project expects, and a tool with no global fallback — notably uv — simply fails:

'uv' is not recognized as an internal or external command

The governing principle of this page follows from that failure: never trust the ambient PATH. Resolve every tool through mise, and let one configuration file be the source of truth for each concern.

just — the task entrypoint

just is a command runner: a Justfile of named recipes that wrap the longer commands a developer would otherwise memorise. It is the only layer a contributor interacts with directly; mise and moon sit behind it.

Two design points matter:

• Cross-platform shell. The Justfile selects bash on Unix and PowerShell on Windows, so the same recipe name works on every machine.
• Tools are always wrapped. Every recipe that calls a mise-managed tool prefixes it with mise exec -- (see below). Tools that mise does not manage — docker, k3d, kubectl — are invoked directly.

Run just --list to see every recipe. The recipe catalogue is documented in Running the Application.

mise — the toolchain manager

mise pins every language runtime and CLI to an exact version, per project, across platforms. The pins live in .mise.toml at the repository root:

[tools]
node = "24"
python = "3.14.7"
rust = "1.98.1"
go = "1.27.1"
"ubi:moonrepo/moon" = "2.5.4"
uv = "0.12.10"
istioctl = "1.31.0"

Running mise install once after cloning fetches every tool at the pinned version into mise’s own store, independent of anything else on the machine.

How tools are resolved

mise can place those tools on the PATH in two ways. The project is designed to work with or without the first.

The same rule inside moon

just launches moon as mise exec -- moon …, and mise exec exports the pinned tools onto PATH for the command and every child process it spawns. Every task moon runs — npm ci, cargo fetch, uv sync — therefore inherits the same resolved toolchain. moon’s own toolchain management stays off: mise remains the single source of truth for versions.

moon — the task orchestrator

moon runs the per-project tasks — build, test, lint, lint-fix, audit, deps, deps-check, relock — across the whole monorepo, with two capabilities a hand-rolled script set never had:

• Caching — a task’s result is hashed by its inputs. If nothing it depends on changed, the cached result is replayed in milliseconds instead of re-running.
• Affected detection — --affected runs a task only for the projects touched on the current branch.

One project registry

Every package is registered once in .moon/workspace.yml. This is the single list of packages in the repository; nothing else maintains a parallel copy.

projects:
  frontend: "frontend"
  digital-twin: "backend/digital-twin"
  # … the other services …
  dashboard: "backend/dashboard"
  sensor-simulator: "simulators/sensor-simulator"
  # Support packages: deps-only, no build/test/lint
  eslint-config: "tooling/eslint-config"
  acceptance: "backend/acceptance"

Tasks defined once per language

Rather than repeat the same build/test/lint configuration in a dozen moon.yml files, the pipeline is defined once per language in .moon/tasks/*.yml, each scoped with inheritedBy so it applies only to projects of that language.

A language file is scoped by its inheritedBy block:

# .moon/tasks/typescript.yml
inheritedBy:
  language: 'typescript'
tasks:
  test:
    command: 'npm test'
    inputs: ['src/**/*', '__tests__/**/*', 'package.json', '/schemas/fixtures/**/*', '/schemas/json/**/*']
  audit:
    command: 'npm audit --audit-level=high --omit=dev'
    options: { cache: false }
  # … build, lint, lint-fix, deps …

Every language’s test inputs include /schemas/fixtures/**/* and /schemas/json/**/* (/ is workspace-relative). Contract tests read those files, and moon hashes a task by its inputs: without them a fixture edit replays a cached pass and --affected selects nothing. Rust’s test also lists tests/**/*, where every crate keeps its conformance tests.

Each project’s moon.yml is minimal

Because the pipeline is inherited, a standard service’s entire moon configuration is a single line declaring its language; the tasks come from the language file. Projects declare only what genuinely differs:

.tablebyrows {.headers}
    - - `frontend`
      - Uses Vite/Vitest: overrides `build` inputs and `test` (to `npm run test:unit`), with `mergeArgs: replace` / `mergeInputs: replace` so the overrides replace the inherited values rather than appending — which is why its `test` re-lists the fixture and schema inputs itself.
    - - `sensor-simulator`, `aq-simulator`
      - Each asserts `schemas/fixtures/ingest-batch.json`: they hand-build the batch telemetry hand-parses, so the fixture is the only thing holding the three languages to one shape. The Python one overrides `test`/`lint` to call `uv` directly, because the inherited tasks shell out to `npm` and the root `.gitignore` ignores every `package.json`.
    - - `ap-simulator`
      - Serves a fake ubus endpoint rather than producing telemetry, so it has no fixture to assert and excludes the inherited `test` task; its CI leg runs `smoke.py` instead.
    - - `tooling`, `eslint-config`
      - Tagged `language: 'javascript'` so they inherit only `deps`. (`acceptance` is `language: 'python'` and excludes the inherited `test`/`lint` tasks: its pytest suite runs via `just test integration` against a composed stack, never as a moon `:test`.)
    - - `claims-gateway`, `tenancy`, `registry`, `provisioner`
... (1 more lines)

Inspecting the graph

These read-only commands print resolved configuration without running anything:

mise exec -- moon task digital-twin:test   # one task: command, inputs, inheritance
mise exec -- moon query projects           # every project moon knows (id + language)
mise exec -- moon query tasks              # which projects expose each task

How the layers cooperate

The payoff of the design is that each fact lives in exactly one place.

Crucially, install and clean-install are moon runs, not a parallel hand-written package list:

just setup install        # mise exec -- moon run :deps
just setup clean-install  # mise exec -- moon run :relock, then :deps
just setup deps-check     # mise exec -- moon run :deps :deps-check

So just setup install installs exactly the packages moon knows about; no drift is possible, and unchanged projects are skipped by moon’s affected-detection.

Adding a new service or package

Thanks to the single registry, onboarding a package is a one-place change:

1. Register it in .moon/workspace.yml under projects:.
2. Add a minimal moon.yml in the package with its language: (and any genuine task overrides).
3. It now flows automatically into whichever tasks its language file defines (:build / :test / :lint / :deps, and :audit for every language except go), and into just setup install / just setup clean-install via :deps / :relock. Nothing else to register.

Troubleshooting