chore: add a justfile that mirrors the CI gate

AGENTS.md

@@ -30,6 +30,14 @@ cargo run --bin gravity -- --world <world-name> --output <output.go> <input.wasm
 
 ## Testing
 
+`just check` runs the same steps as `.github/workflows/ci.yml`, in the same
+order: format check, build, unit tests, the Go example tests and the CLI
+snapshot tests. Each step is also its own recipe (`just lint`, `just test`,
+`just test-go`, `just test-cli`); `just --list` shows them all. The recipes
+ignore an inherited `RUSTUP_TOOLCHAIN` or `CARGO_TARGET_DIR`, so they use the
+toolchain pinned in `rust-toolchain.toml` and the `target/` directory that
+`examples/generate.go` reads from.
+
 ### Unit Tests
 
 Run all unit tests (does NOT include snapshot/CLI tests):
@@ -57,7 +65,7 @@ cargo test --test cli
 To update snapshot expectations when output changes intentionally:
 
 ```sh
-TRYCMD=overwrite cargo test --test cli
+just update-snapshots
 ```
 
 Snapshot files live in `cmd/gravity/tests/cmd/` (`.toml` for config, `.stdout`
@@ -200,8 +208,8 @@ Bump every example's pins with them.
 ## Style & Conventions
 
 - Use conventional commits: `feat:`, `fix:`, `docs:`, `test:`, `refactor:`, etc.
-- Format code before committing with `cargo fmt`
-- Lint with `cargo clippy`
+- Format code before committing with `just format`
+- Lint with `just clippy` (CI does not run clippy)
 - When adding new instruction handlers in `func.rs`, add corresponding entries
   in the `instructions` example and update snapshot tests
 - When changing codegen output, update snapshot `.stdout` files (or use
@@ -221,4 +229,4 @@ Bump every example's pins with them.
    - `<name>.stdout` — capture with
      `cargo run --bin gravity -- --world <name> <wasm-path> > <stdout-path>`
    - `<name>.stderr` — typically empty (`touch <stderr-path>`)
-6. Verify: `cargo test && cargo test --test cli && (cd examples && go generate ./... && go test ./...)`
+6. Verify: `just check`

justfile

@@ -0,0 +1,119 @@
+# Gravity command runner.
+# Run `just --list` to see available recipes, or `just <recipe>` to run one.
+#
+# `just check` runs the same steps as .github/workflows/ci.yml, in the same
+# order. Change both together.
+
+# show available recipes (default when no recipe is given)
+[private]
+default:
+    @just --list
+
+# rust-toolchain.toml pins the toolchain CI uses; an inherited override would
+# replace it.
+unexport RUSTUP_TOOLCHAIN
+
+# examples/generate.go builds into and reads from ../target, so a relocated
+# target directory makes `go generate` fail with "unable to read file".
+unexport CARGO_TARGET_DIR
+
+# styled header: bold cyan ✦, bold white label
+h := BOLD + CYAN + "✦" + WHITE + " "
+n := NORMAL
+
+# ─── Root commands ───────────────────────────────────────────────────────────────
+
+# run the full CI gate: format check, build, unit tests, Go example tests, CLI
+# snapshot tests
+[doc('run the full CI gate')]
+[group('ci')]
+check: lint build test test-go test-cli
+
+# install the toolchain, components and targets pinned in rust-toolchain.toml
+[group('setup')]
+install:
+    @echo '{{ h }}install: rustup toolchain{{ n }}'
+    @rustup toolchain install --no-self-update
+
+# auto-format Rust code and this justfile
+[group('format')]
+format:
+    @echo '{{ h }}format: cargo fmt{{ n }}'
+    @cargo fmt --all
+    @echo '{{ h }}format: justfile{{ n }}'
+    @just --fmt
+
+# check formatting of Rust code and this justfile
+[group('ci')]
+[group('lint')]
+lint:
+    @echo '{{ h }}lint: cargo fmt{{ n }}'
+    @cargo fmt --all --check
+    @echo '{{ h }}lint: justfile{{ n }}'
+    @just --fmt --check
+
+# lint with clippy. Not part of `check`, because CI does not run clippy.
+[doc('lint with clippy (not part of the CI gate)')]
+[group('lint')]
+clippy:
+    @echo '{{ h }}lint: cargo clippy{{ n }}'
+    @cargo clippy --workspace --all-targets --locked
+
+# ─── Build and test ──────────────────────────────────────────────────────────────
+
+# build the workspace
+[group('build')]
+[group('ci')]
+build:
+    @echo '{{ h }}build: cargo build{{ n }}'
+    @cargo build --locked
+
+# run the Rust unit tests. The CLI snapshot tests are excluded; see `test-cli`.
+[doc('run the Rust unit tests')]
+[group('ci')]
+[group('test')]
+test:
+    @echo '{{ h }}test: cargo test{{ n }}'
+    @cargo test --locked
+
+# build the example wasm and generate their Go bindings
+[group('build')]
+generate:
+    @echo '{{ h }}generate: example wasm and Go bindings{{ n }}'
+    @go generate ./...
+
+# run the Go example tests against freshly generated bindings
+[group('ci')]
+[group('test')]
+test-go: generate
+    @echo '{{ h }}test: go test{{ n }}'
+    @go test ./...
+
+# run the trycmd CLI snapshot tests. They read the example wasm that
+# `generate` builds.
+[doc('run the trycmd CLI snapshot tests')]
+[group('ci')]
+[group('test')]
+test-cli: generate
+    @echo '{{ h }}test: cargo test --test cli{{ n }}'
+    @cargo test --locked --test cli
+
+# rewrite the CLI snapshot .stdout and .stderr files from current output. Read
+# the diff before committing it. trycmd cannot create a snapshot file, so a new
+# test's files must exist first; see AGENTS.md.
+[doc('rewrite existing CLI snapshot files from current output')]
+[group('test')]
+update-snapshots: generate
+    @echo '{{ h }}test: cargo test --test cli (overwrite){{ n }}'
+    @TRYCMD=overwrite cargo test --locked --test cli
+
+# ─── Cleanup ─────────────────────────────────────────────────────────────────────
+
+# remove gitignored example output. After switching to a branch without an
+# example, its directory holds only generated files, and the examples/*
+# workspace glob then fails every cargo command with "failed to load manifest".
+[doc('remove gitignored example output (generated Go and wasm)')]
+[group('setup')]
+clean-examples:
+    @echo '{{ h }}clean: examples{{ n }}'
+    @git clean -f -X -- examples/