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.

Underneath, two small Node scripts (scripts/install.mjs, scripts/clean.mjs) handle dependency installation, the one job that does not fit moon’s model. Everything else 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"]
  mise --> scripts["scripts/install.mjs, clean.mjs"]
  moon --> tasks["build, test, lint, audit, deps"]
  scripts --> query["moon query projects"]
  cfgA["mise.toml"] -->|versions| mise
  cfgB["moon/workspace.yml"] -->|package list| moon
  cfgB -->|package list| query

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.12"
rust = "stable"
"ubi:moonrepo/moon" = "latest"
uv = "latest"

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 scripts

The Node scripts that just launches (install, clean) spawn tools of their own. They route those through the same gate with a small helper, scripts/lib/mise.mjs:

// Resolve a command's tool through mise — unless a mise-provided environment is
// already present (the Justfile launches scripts under `mise exec`, which exports
// __MISE_DIFF), in which case we avoid wrapping it twice.
export function withMise(cmd) {
  const inside = process.env.__MISE_DIFF || process.env.MISE_SHELL;
  return inside ? cmd : `mise exec -- ${cmd}`;
}

A script therefore works both when launched via just (already under mise exec) and when run directly as node scripts/install.mjs on a shell that never activated mise.

moon — the task orchestrator

moon runs the per-project tasks — build, test, lint, lint-fix, audit, deps — 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"
  twin-service: "backend/twin-service"
  # … the other services …
  contracts-service: "backend/contracts-service"
  sensor-simulator: "simulators/sensor-simulator"
  # Support packages: deps-only, no build/test/lint
  eslint-config: "tooling/eslint-config"
  tests: "backend/tests"

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']
  audit:
    command: 'npm audit --audit-level=high --omit=dev'
    options: { cache: false }
  # … build, lint, lint-fix, deps …

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:

Inspecting the graph

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

mise exec -- moon task twin-service: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 derive their package list from moon rather than keeping a parallel hand-written list. scripts/lib/workspaces.mjs shells out to moon query projects and buckets the result by language:

const { projects } = JSON.parse(execSync(withMise('moon query projects')));

So just setup install installs exactly the packages moon knows about; no drift is possible.

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 — for typescript, python, and rust — into just setup install / just setup clean-install (both derive from moon query projects, but scripts/install.mjs doesn’t have a go bucket, so a new Go package needs its modules fetched manually the first time; see Setting Up the Environment.

Troubleshooting