|
| 1 | +> NOTE: Before using this guide, read the repository root `AGENTS.md` for authoritative agent instructions. |
| 2 | +
|
| 3 | +# Rain Orderbook – Agent Guide (Concise) |
| 4 | + |
| 5 | +Always run commands via Nix: `nix develop -c <command>`. Never cancel long-running tasks (45–90 min builds, 30+ min tests). |
| 6 | + |
| 7 | +## 1. Dependency readiness (quick check) |
| 8 | +```bash |
| 9 | +nix develop -c cargo build |
| 10 | +nix develop -c cargo build --target wasm32-unknown-unknown --lib -r --workspace \ |
| 11 | + --exclude rain_orderbook_cli --exclude rain_orderbook_integration_tests |
| 12 | +nix develop -c npm install |
| 13 | +nix develop -c npm run build:orderbook |
| 14 | +nix develop -c npm run build:ui |
| 15 | +``` |
| 16 | + |
| 17 | +If any step fails due to earlier lint/test issues, use the fallback below. |
| 18 | + |
| 19 | +## 2. Development loop |
| 20 | +- Edit code |
| 21 | +- Rebuild dependencies you touched: |
| 22 | + - Rust used by `@rainlanguage/orderbook` → `nix develop -c npm run build:orderbook` |
| 23 | + - `@rainlanguage/ui-components` → `nix develop -c npm run build -w @rainlanguage/ui-components` |
| 24 | +- Run targeted tests and lints for changed areas |
| 25 | + |
| 26 | +## Reference: tests and lints by area |
| 27 | + |
| 28 | +| Area | Build (if needed) | Lint/Check | Tests | |
| 29 | +|------|--------------------|------------|-------| |
| 30 | +| Rust crates (`crates/*`) | `nix develop -c cargo build` | `nix develop -c cargo clippy --workspace --all-targets --all-features -D warnings` | `nix develop -c cargo test --workspace` or `--package <crate>` | |
| 31 | +| Orderbook TS (`packages/orderbook`) | `nix develop -c npm run build:orderbook` | `nix develop -c npm run check -w @rainlanguage/orderbook` | `nix develop -c npm run test -w @rainlanguage/orderbook` | |
| 32 | +| UI components (`packages/ui-components`) | `nix develop -c npm run build -w @rainlanguage/ui-components` | `nix develop -c npm run svelte-lint-format-check -w @rainlanguage/ui-components` | `nix develop -c npm run test -w @rainlanguage/ui-components` | |
| 33 | +| Webapp (`packages/webapp`) | `nix develop -c npm run build -w @rainlanguage/webapp` | `nix develop -c npm run svelte-lint-format-check -w @rainlanguage/webapp` | `nix develop -c npm run test -w @rainlanguage/webapp` | |
| 34 | +| Solidity contracts | `nix develop -c forge build` | — | `nix develop -c forge test` | |
| 35 | + |
| 36 | +## Frontend verification (required when frontend changes) |
| 37 | + |
| 38 | +- If you modify frontend code or functionality affecting the frontend, you MUST provide a screenshot of the built webapp reflecting your change. |
| 39 | +- Build and preview: |
| 40 | +```bash |
| 41 | +nix develop -c npm run build -w @rainlanguage/webapp |
| 42 | +nix develop -c npm run preview -w @rainlanguage/webapp |
| 43 | +``` |
| 44 | +- If you are unable to build the webapp, you MUST provide the concrete reasons and errors. Workarounds are not acceptable. |
| 45 | + |
| 46 | +## 3. End-of-session gate (comprehensive) |
| 47 | +Partial commits are OK during the session. Before your final commit of the session, fully mirror CI: |
| 48 | +```bash |
| 49 | +./prep-all.sh |
| 50 | +nix develop -c npm run lint-format-check:all |
| 51 | +nix develop -c npm run build:orderbook # if Rust/orderbook changed |
| 52 | +nix develop -c npm run build:ui |
| 53 | +nix develop -c cargo test --workspace |
| 54 | +nix develop -c npm run test |
| 55 | +nix develop -c forge test |
| 56 | +``` |
| 57 | + |
| 58 | +## 4. Push gate (quick recheck) |
| 59 | +Do a short verification right before pushing: |
| 60 | +```bash |
| 61 | +nix develop -c npm run lint-format-check:all |
| 62 | +nix develop -c npm run test |
| 63 | +nix develop -c cargo test --workspace |
| 64 | +``` |
| 65 | + |
| 66 | +## Fallback if end-of-session `./prep-all.sh` fails early |
| 67 | +If the end-of-session gate fails during `./prep-all.sh`, run these steps sequentially so dependencies still build: |
| 68 | +```bash |
| 69 | +nix develop -c forge install |
| 70 | +nix develop -c bash -c '(cd lib/rain.interpreter && rainix-sol-prelude && rainix-rs-prelude && i9r-prelude)' |
| 71 | +nix develop -c bash -c '(cd lib/rain.interpreter/lib/rain.interpreter.interface/lib/rain.math.float && rainix-sol-prelude && rainix-rs-prelude)' |
| 72 | +nix develop -c bash -c '(cd lib/rain.interpreter/lib/rain.metadata && rainix-sol-prelude && rainix-rs-prelude)' |
| 73 | +nix develop -c rainix-sol-prelude && nix develop -c rainix-rs-prelude && nix develop -c raindex-prelude |
| 74 | +nix develop .#tauri-shell -c ob-tauri-prelude && nix develop .#tauri-shell -c ob-ui-components-prelude |
| 75 | +nix develop -c npm run build -w @rainlanguage/orderbook |
| 76 | +nix develop -c npm run build -w @rainlanguage/ui-components |
| 77 | +nix develop -c npm run build -w @rainlanguage/webapp |
| 78 | +``` |
| 79 | + |
| 80 | +Goal: all CI checks in `.github/workflows` pass. Be patient with long builds/tests and never commit with failing lint/tests. |
| 81 | + |
| 82 | + |
0 commit comments