MoonJust is a MoonBit implementation of the user-visible behavior of
just, targeting Native and wasm1 through the
MoonBit host runtime. The compatibility baseline is pinned to just 1.57.0;
the upstream Rust library API is not part of MoonJust's public API.
Current status
Phase 0-9 exits have passed, including protected-main CI. MoonJust
0.7.0-alphaimplements the Phase 10 platform, interactive, terminal, Markdown and compatibility-convergence contracts; remote CI and the required second review are still pending.
The completed phases establish a usable and auditable foundation:
| Area | Current capability |
|---|---|
| Language core | UTF-8 byte spans, diagnostics, lexer, parser, AST, formatter, semantic compilation |
| Loading | justfile discovery, explicit paths, stdin, imports, optional imports, modules and canonical graph identity |
| Evaluation | lazy scopes, recipe parameters, typed values, 83 builtins, explicit host effects, bounded hashing |
| Query CLI | check, format, init, list, show, summary, usage, groups, variables, evaluate, dump and JSON inspection |
| Filesystem | Native atomic transactions and policy-aware wasm1 transaction adapter |
| Environment | dotenv parsing/discovery, required/list/command modes, overrides, shell/tempdir and child-environment composition |
| Invocation | positional/variadic parameters, recipe-local options, flags, repetition, patterns and stable usage errors |
| Working directory | invocation, project, module, evaluation and recipe directory model with no-cd and recipe overrides |
| Executor | bounded jobs, parallel/serial dependency fences, scripts, cache, dry-run, deterministic output/failure and cancellation cleanup |
| Platform and terminal | real Native OS/architecture/TTY facts, signal-aware statuses, deterministic color and Unicode display width |
| Interactive and Markdown | confirm/yes, chooser/editor workflows and automatic source-aware Markdown extraction |
| Wasm boundary | separate read-only inspect and process-enabled execution policies |
The CLI validates the complete recipe graph before execution, then runs ready tasks through a bounded FIFO scheduler. Cache entries are BLAKE3-keyed, versioned, locked across processes and atomically published after output checks.
- Upstream:
just 1.57.0, commite01a6bd7e7a30baf86bc86d2b95b0998ebbdc36f. - Required targets:
nativeandwasm(wasm1undermoonrun/moonx). - Validated upstream registrations: 1,844 executable family rows.
- Registered compatibility differences: 526 unsupported rows with exact reasons and tracking ownership in the machine map.
- Explicitly excluded or not applicable: 35 shell-completion rows and 12 Rust-internal or product-maintenance rows.
- Deferred or unclassified upstream registrations: zero.
- Browser, arbitrary WASI, wasm-gc process execution and child-process sandboxing are not supported claims.
The complete decision record is in the
Phase 0-10 strict audit. Machine-readable scope and
phase contracts live under compat/; the pinned corpus provenance
is in tests/upstream/NOTICE.md.
The repository currently uses:
moon 0.1.20260803
moonc 0.10.6+62c2592d1
moonrun 0.1.20260803
Install the matching MoonBit toolchain, then enable the repository hook:
git config core.hooksPath .githooksmoon check --target all --warn-list +73
moon build --target native cmd/just
moon build --target wasm cmd/just
moon run --target native cmd/just -- --help
moon run --target native cmd/just -- --versionThe Wasm executable requires an explicit MoonBit host policy. The published inspection policy is intentionally read-only:
moonrun --policy policies/inspect.toml \
_build/wasm/debug/build/cmd/just/just.wasm --help./tools/check.shThe gate checks architecture boundaries, pinned upstream metadata, the differential harness, all stable backends, Wasm policy, Phase 7 differentials, Phase 8-10 runtime gates, the pinned Markdown oracle, public interfaces, and the complete Native/wasm1 test matrix.
MoonJust keeps behavior-bearing logic in pure or capability-parameterized packages and isolates platform details at adapter leaves:
argv / stdin / cwd / explicit host facts
|
v
CLI composition and validation
|
v
loader -> source -> lexer -> parser -> semantic model
|
v
evaluator / invocation / query
|
v
working directory + environment configuration
|
v
Phase 10 platform-aware executor boundary
The core never reads process-global environment or filesystem state directly.
HostFs, HostEnv, HostClock, HostRandom, HostProcess, HostTerminal,
HostSignal and HostPlatform make those inputs explicit and testable. The
Wasm inspection adapter receives only the capabilities its policy allows.
| Path | Responsibility |
|---|---|
src/source, src/diagnostic, src/path |
target-independent source coordinates, diagnostics and lexical paths |
src/lexer, src/parser, src/syntax, src/formatter |
language front end and Markdown tangle |
src/semantic, src/loader, src/evaluator, src/builtin |
compilation, graph loading, evaluation and typed builtins |
src/host, src/host_native, src/host_wasm |
explicit host contracts and platform adapters |
src/cli, src/application, src/invocation, src/workdir, src/environment |
CLI composition and Phase 6-7 models |
cmd/just |
Native/wasm1 executable composition root |
compat/ |
machine-readable compatibility inventories and phase contracts |
tests/upstream/ |
pinned upstream corpus, ownership map and provenance |
tools/ |
deterministic gates, oracle builders and differential probes |
docs/ |
plan, ADRs, phase reports and strict audit |
A justfile is executable code. Passing through Wasm does not automatically
sandbox a spawned child process, and granting a moonrun process policy does
not make an untrusted recipe safe. Review untrusted justfiles and use an
operating-system or container sandbox when isolation is required. Report
potential command injection, path escape, secret disclosure, cache poisoning
or process-isolation vulnerabilities privately as described in
SECURITY.md.
Environment and override containers deliberately avoid Debug derivations.
Diagnostics redact dotenv values, command arguments, child stderr and host
environment entries. Atomic writes use one reserved same-directory temporary
name per digest, mode 0600, synchronization before commit and typed cleanup
failures. The next matching lease and full cache clean remove that name only
while holding the digest lock; lookalike files are preserved. Child stdout and
stderr are drained concurrently;
retained streams have a 16 MiB per-stream limit, and overflow cancels the
child with a deterministic error.
Every behavior change must identify its compatibility tier, upstream reference, supported targets, and regression evidence. Use the existing package boundaries and ADRs before introducing a new abstraction.
moon check --target all --warn-list +73
moon test --target native
moon test --target wasm
moon info
moon fmt
./tools/check.shBefore opening a PR, review generated .mbti diffs, run the applicable
differential gate, and confirm that unsupported behavior is rejected explicitly
instead of silently ignored. See CONTRIBUTING.md for the
definition of ready and required PR evidence.
- Project plan: scope, architecture, compatibility tiers and future phases.
- Phase 0-9 strict audit: current cross-phase verdict and publication evidence.
- Phase 0 report through Phase 7 report: phase-local delivery records.
- Architecture: package boundaries and capability flow.
- ADR index: accepted design decisions.
- Security policy: threat model and disclosure boundary.
- Changelog: user-visible project history.
MoonJust is licensed under Apache-2.0. The pinned upstream just fixtures are
CC0-1.0 and retain their source, commit, license and modification provenance in
tests/upstream/NOTICE.md. MoonJust is an
independent project and is not sponsored or endorsed by the upstream authors.