Run a moon workspace with Putnami
@putnami/moon turns each project of a moon workspace into a Putnami project,
with an edge to each project moon says it depends on. Putnami selects what a
change affects and gives the verdict; what runs each task depends on the mode
the workspace adopted moon in.
Adopt it
@putnami/moon is not published yet: until its first release, putnami init --from moon stops at the extension install, after it has written the
workspace files, and a workspace loads the extension from a source checkout.
At the root of the repository, where .moon/workspace.yml lies:
putnami init --from moonIn a terminal, init asks the mode, with import preselected. Without a
terminal, in CI or from an agent, it imports unless --mode delegate is
given; --mode import or --mode delegate skips the question. init writes
a workspace that declares @putnami/moon with the mode under
options["@putnami/moon"].mode, installs it, runs putnami projects sync,
then installs the language extensions the sync declared. The sync declares a
language extension only when a task moves to it: a project none of whose
tasks moves runs on moon alone. A TypeScript project then installs with the
package manager the repository declares, npm, pnpm, Yarn or Bun, which keeps
its lockfile. When no task moves, init installs nothing more, leaves the
lockfile as it was, and says that --mode delegate gives the same result.
Rerun in a workspace, init --from moon prints the diff of what the sync
would write and changes nothing; --apply writes it.
The two modes
| Import | Delegate | |
|---|---|---|
| A task of a TypeScript, Go, Python, PHP, Ruby or Rust project that runs the tool its extension runs | runs @putnami/<language> |
runs moon run |
| Any other task of such a project | runs moon run |
runs moon run |
| Any other project | runs moon run |
runs moon run |
| Cache | Putnami's for the tasks that moved, moon's for the others | moon's, local and remote |
An import never changes the tool that checks the code (D-070): a task moves
only when the language extension runs its tool, read from its script, else
its command and args:
| Language | Tools the extension runs |
|---|---|
| TypeScript | bun build, or tsc alone when it is the build script of package.json; bun test, Vitest or Jest without an argument that picks a configuration or a subset; Biome or a bare eslint |
| Go | go build, go test |
| Rust | cargo build; cargo nextest or cargo llvm-cov nextest |
| Python | pytest |
| Ruby | rspec, rubocop |
| PHP | phpunit, phpstan |
A Go, Rust or Python lint stays on moon, since the extension's lint checks
more than the task did (staticcheck beside golangci-lint, cargo fmt --check
beside clippy, ruff format --check beside ruff check), and so does a cargo test, since the Rust extension tests with
nextest, which runs no doctest. A TypeScript test records its runner, bun
included. The extension runs the program under its own arguments and drops the
task's, so a task moves only with arguments that choose the whole project or
only change the output, such as ./..., -v or --locked.
A task that selects build tags, a release profile, a package or a subset of
the suite, such as go test -tags integration ./..., cargo build --release
or pytest tests/unit, stays on moon, and so do go test . and go build .,
since the Go extension tests and builds ./...; the sync names the arguments.
A runner prefix such as bundle exec, uv run or npx, or a path such as
vendor/bin/, does not change the tool. A task chained with another command
stays on moon. A TypeScript task also stays when the project's package.json
scripts would lead @putnami/typescript to another tool: a Bun build beside a
tsc build script, a Biome lint beside an ESLint lint script.
No task runs both: no Putnami cache sits over moon's. Switching mode is a
change to options["@putnami/moon"].mode and a putnami projects sync;
putnami init --from moon --mode delegate --apply also removes from the
workspace each language extension no putnami.json names any more.
A workspace that records no mode imports, as init does without a terminal;
a value other than import or delegate fails the sync and the probe with
stacks.adoption_mode_invalid.
For each project moon runs, the sync also writes, as filePatterns, the root
files every moon task reads: .moon/workspace.yml, .moon/tasks.yml,
.moon/tasks/**, .moon/toolchain.yml, .prototools, and the root lockfile
of each language moon runs (npm, pnpm, Yarn, Bun, Cargo, Go workspaces, uv,
Poetry, Composer, Bundler) with .npmrc and pnpm-workspace.yaml, those the
root holds. A change to one of them
selects every such project, as moon's own hashes do. Each edge the sync writes is attributed to moon's project graph (build-graph),
so workspace.declared_edge does not warn about it and putnami deps prune
leaves it in place. This holds for a project imported into a language
extension too: moon's probe attributes its edges without claiming the
project, so an edge its manifests do not state, such as a TypeScript project's
edge to a Rust one or to a devDependencies build tool, keeps ordering the
build.
Projects and tasks
The extension reads moon-graph.json at the root when the CI wrote it
(moon project-graph --json > moon-graph.json), else .moon/workspace.yml
and each project's moon.yml.
A workspace that infers tasks from package.json scripts
(inferTasksFromScripts under javascript in .moon/toolchains.yml, or under
node in .moon/toolchain.yml) states those tasks nowhere but in moon. With
no moon-graph.json, the sync then runs moon project-graph --json at the
root, with node_modules/.bin/moon, else the moon on PATH, and reads the
tasks moon lists. When the repository's moon fails, as in a repository that
ships moon itself, the sync runs the moon on PATH. A moon that fails fails
the sync and validate, and the error names each moon the sync ran. Without
moon, the sync and validate warn with moon.tasks_inferred.
A project's tasks are the export's, or its moon.yml tasks over the ones it
inherits from .moon/tasks.yml and .moon/tasks/*.yml: by file name (node,
<language>, <stack>, <language>-<layer>, tag-<tag>) or by
inheritedBy, after its workspace.inheritedTasks include, exclude and
rename. Without an export, an inheritedBy condition on languages, stacks,
layers or tags decides, a tags clause matches no project, and one on
toolchains or files constrains nothing. A task two files define takes the
upper command whole, and its args and tags append to the lower ones unless
the upper task's mergeArgs, mergeTags or merge says otherwise.
moon 2.x writes no tasks in its
export, only each project's taskTargets and the task files moon matched
for it, under inherited: the targets name the project's tasks, each with
the command and tags its moon.yml and those files state. A task moon infers
from a script states no command, so it keeps running through moon run.
The moon projects are the ones the workspace's projects setting or the
export names. putnami projects sync asks the extension about the
directories that hold a moon.yml or a language manifest moon reads
(package.json, tsconfig.json, deno.json, go.mod, Cargo.toml,
pyproject.toml, requirements.txt, composer.json, Gemfile), and about
those that hold a putnami.json, so a moon project with none of those files
joins once the sync has written its putnami.json.
putnami lint, putnami test and putnami build run the moon task named
lint, test or build, else the first one, by name, tagged that way. A
project with no such task has that command in disable.jobs. Every other
task is listed by the sync and keeps running through moon.
A moon project at the workspace root, such as moon's root, becomes no
Putnami project: a project there would own every file no deeper project
claims. The sync names it and the tasks that keep running through
moon run root:<task>.
What the sync writes
putnami projects sync runs the extension's sync task. In each project's
putnami.json it writes:
- the tag
moon, for selection; options["@putnami/moon"].graphSync, which marks the project as the sync's, whatever extension it runs: a project the team tagsmoonis not the sync's;- the extension the mode maps it to, and in import mode
@putnami/moonbeside its language extension when a task stays on moon; - its
dependencieson the other moon projects, as project IDs; build,lintortestindisable.jobswhen the project has no task for it, and for a project that runs both extensions, the command qualified by the one that does not run it, such as@putnami/moon:testfor a test that moved and@putnami/go:lintfor a lint that stays;- for a task moon runs that is tagged rather than named, the step under
options["@putnami/moon"].tasks.<command>.steps; - for a TypeScript project, the runner of a test that moved,
bun,vitestorjest, underoptions["@putnami/typescript:test"].runner, withtypes: falsethere, since the task type-checked nothing, andeslintunderoptions["@putnami/typescript"].lint.linterfor an ESLint lint that moved; - for a TypeScript project,
fix: falseunderoptions["@putnami/typescript:lint"]for a lint that moved and whose command passes no write flag (--write,--fix,--apply): it checks and rewrites no file. When a Biome lint moves and the repository root holds nobiome.jsonorbiome.jsonc, the sync writes a rootbiome.jsonthat sets nothing, so the lint keeps Biome's defaults, and lists it; - for a TypeScript project, the conventions of D-066: a
tsconfig.jsonthat extends the root's when it holds notsconfig*.json, and"exports": { ".": "./src/index.ts" }when its build moves to the Bun build, itspackage.jsonis private and itsmainnames a build output. Abun buildtask whose entry the sync does not rewrite stays on moon. - in import mode, for each
build,testorlinttask that moved to its language extension, thedepsmoon gives it undercommands.<command>.dependsOn: a task of a project it depends on (^:build, ortypes:buildwhen it depends ontypes) as^build, and one of its own (~:build,build) asbuild. A moved test then waits for the build moon runs before it, and its key folds that build's would-be key, so an edit totypesmoves it. A dep on a tag, on another task or on a project outside its dependencies is listed and not written.
It keeps every other member, the project's own steps included: it writes a
step only where none is set or where it wrote the one there. It retracts a
project moon no longer lists, keeping the language extension the project
runs, and in import mode adds the language extensions to the workspace's
extensions, in its list or object form.
Import sets each project's extension from moon's language: a JavaScript
project runs @putnami/moon even when its putnami.json named
@putnami/typescript, and a TypeScript project whose tasks all moved loses
@putnami/moon. The sync lists each task it keeps on moon with its reason.
putnami validate fails with moon.sync_stale when a sync would change a
putnami.json, in both modes: moon infers edges from manifests and task
inputs, and a task's command decides where it runs, so an edit can change
them.
Reports
A delegated test task reads the JUnit and coverage reports the project
names in its own options, as the stack core reads any report:
{
"options": {
"@putnami/moon": {
"tasks": {
"test": {
"reports": {
"junit": ["{root}/apps/api/reports/junit.xml"],
"coverage": [{ "format": "lcov", "paths": ["{root}/apps/api/coverage/lcov.info"] }]
}
}
}
}
}
}Without them the result is moon's exit code alone, and the sync lists the project.
Toolchain
Each task checks moon --version against the moon version .prototools
pins; without one it warns and runs. The extension never installs moon.