|
| 1 | +--- |
| 2 | +name: justfile-ci |
| 3 | +description: > |
| 4 | + Guide for editing Justfiles and GitHub Actions CI workflows in this repository. |
| 5 | + Use when the user asks to add, modify, or remove build/test/lint/format steps, |
| 6 | + add new CI jobs, update Justfile recipes, or wire new tasks into the build system. |
| 7 | + Trigger phrases: "add to CI", "add a just recipe", "update the Justfile", |
| 8 | + "add a test step", "wire into CI", "add to the build", "new CI job". |
| 9 | +--- |
| 10 | + |
| 11 | +# Justfile & CI Editing Guide |
| 12 | + |
| 13 | +## Architecture |
| 14 | + |
| 15 | +This repo uses a **hierarchical Justfile** structure with a matching **GitHub Actions CI** workflow. |
| 16 | + |
| 17 | +### Justfile Hierarchy |
| 18 | + |
| 19 | +``` |
| 20 | +Justfile (root) ← orchestrates everything |
| 21 | +├── mod wasm 'src/wasm_sandbox/Justfile' |
| 22 | +├── mod jssandbox 'src/javascript_sandbox/Justfile' |
| 23 | +├── mod nanvix 'src/nanvix_sandbox/Justfile' |
| 24 | +├── mod python 'src/sdk/python/Justfile' |
| 25 | +└── mod examples_mod 'examples/Justfile' |
| 26 | +``` |
| 27 | + |
| 28 | +- Root recipes (`test`, `build-all`, `lint`, `fmt`) delegate to subproject recipes via `mod::recipe` syntax |
| 29 | +- Subproject Justfiles own environment setup (e.g. `WIT_WORLD` for WASM) |
| 30 | +- Root Justfile uses `set unstable := true` to enable module imports |
| 31 | +- Justfiles are organized with `#### SECTION ####` headers (BUILD TARGETS, TESTS, DOCS, etc.) |
| 32 | +- Section headers must have a blank line after them to avoid becoming recipe doc comments in `just --list` |
| 33 | +- Example recipes are flat: one `examples` recipe listing all `cargo run`/`uv run` commands directly (no per-example helper recipes) |
| 34 | + |
| 35 | +### CI Structure |
| 36 | + |
| 37 | +`.github/workflows/ci.yml` has separate jobs per subproject. Each job calls `just` recipes — never raw `cargo`/`python` commands. |
| 38 | + |
| 39 | +See `references/architecture.md` for the full CI job layout and Justfile recipe map. |
| 40 | + |
| 41 | +## Workflow: Adding a New Step |
| 42 | + |
| 43 | +1. **Add the recipe to the subproject Justfile** — include any env setup, deps, and the actual command |
| 44 | +2. **Wire it into the root Justfile** if it should be part of `test`, `lint`, `fmt`, `build-all`, or `examples` |
| 45 | +3. **Add the CI step** — call the `just` recipe from the appropriate CI job |
| 46 | +4. **Verify alignment** — root `just test` should run the same test steps that CI runs |
| 47 | + |
| 48 | +## Rules |
| 49 | + |
| 50 | +### Justfile Rules |
| 51 | +- Always add recipes to the **subproject Justfile first**, then reference from root via `mod::recipe` |
| 52 | +- Don't create root-level wrapper recipes for things that can be called as `mod::recipe` directly |
| 53 | +- Subproject recipes handle their own env setup (e.g. `WIT_WORLD`, `CARGO_MANIFEST_DIR`) |
| 54 | +- Use recipe dependencies for ordering: `test: build lint` not separate commands |
| 55 | +- Use `#### SECTION ####` headers to group recipes; keep a blank line after the header |
| 56 | +- Keep comments minimal — don't restate the recipe name; only add comments for non-obvious behavior |
| 57 | +- Use `default-target` parameter pattern for build profile selection |
| 58 | +- Example recipes should be flat lists of commands in one `examples` recipe, not separate per-example recipes |
| 59 | + |
| 60 | +### CI Rules |
| 61 | +- CI steps must call `just` recipes — never bypass with raw commands |
| 62 | +- Each subproject has its own CI job (don't mix unrelated subprojects) |
| 63 | +- Exception: Python SDK runs in the `wasm-sandbox` job to avoid rebuilding |
| 64 | +- KVM setup is required for jobs that run Hyperlight sandboxes |
| 65 | +- `just` is installed via `cargo install --locked just` in each job |
| 66 | + |
| 67 | +### Alignment Rule |
| 68 | +- Root `just test` and CI must test the same things |
| 69 | +- When adding a test step to CI, verify it's also called from `just test` |
| 70 | +- When adding a `just test` dependency, verify CI runs it too |
| 71 | + |
| 72 | +## Common Patterns |
| 73 | + |
| 74 | +### Adding a test recipe to a subproject |
| 75 | +```just |
| 76 | +# In subproject Justfile: |
| 77 | +test target=default-target: |
| 78 | + {{ wit-world }} cargo test --manifest-path {{repo-root}}/path/Cargo.toml --profile={{ if target == "debug" {"dev"} else { target } }} --test my_test |
| 79 | +``` |
| 80 | + |
| 81 | +### Wiring it into root |
| 82 | +```just |
| 83 | +# In root Justfile — add to test deps: |
| 84 | +test: wasm::guest-build wasm::js-guest-build python::build python::python-test test-rust wasm::test |
| 85 | +``` |
| 86 | + |
| 87 | +### Adding to CI |
| 88 | +```yaml |
| 89 | +# In ci.yml — add step to appropriate job: |
| 90 | + - name: Integration tests |
| 91 | + run: just wasm test |
| 92 | +``` |
| 93 | +
|
| 94 | +### Recipe with feature flags |
| 95 | +```just |
| 96 | +test-rust: |
| 97 | + cargo test -p hyperlight-sandbox --features test-utils |
| 98 | + |
| 99 | +lint-rust: |
| 100 | + cargo clippy -p hyperlight-sandbox --all-targets --features test-utils -- -D warnings |
| 101 | +``` |
0 commit comments