desi_explorer/AGENTS.md

AGENTS.md

Odin + raylib interactive 3D universe map (DESI data), a Rust + axum API, with Go + Pulumi infra and Gitea Actions CI. A clean odin build + cargo test + go test is the verification step.

Commands (root Makefile)

• Run: make run (odin run src); Build: make build (odin build src -collection:lib=lib/local -out:bin/desi_explorer)
• Web: make build-web (Emscripten/WASM -> build/web); Debug: make build-debug
• Test: make test (runs odin test for src/, go test for infra/, and cargo test for api/); Clean: make clean
• API: make api-run (cargo run in api/), make api-test, make api-check (cargo fmt --check + clippy -D warnings)
• Setup: make setup (submodules + go mod tidy in infra/)
• Infra: make infra-preview, make infra-up, make infra-down, make infra-refresh (Pulumi, --cwd infra)
• Renovate: make renovate-validate (npx renovate-config-validator)
• Format Odin with odinfmt (config odinfmt.json: tabs, width 80); format Rust with cargo fmt

Layout

• src/main.odin — entrypoint; loop is update() → draw(); resizable window with an orbital Camera3D; point cloud generated procedurally in make_universe.
• lib/ — third-party Odin deps (submodules / vendored libs). raylib is not here: it ships vendored with Odin and is imported as vendor:raylib. lib/local/ is the default -collection:lib target and is currently empty.
• api/ — Rust + axum backend API that will serve DESI catalog data. src/lib.rs exposes routes/models/config; src/main.rs is the server entrypoint (binds API_BIND_ADDR, default 0.0.0.0:8080). Crate name is desi-explorer-api (lib desi_explorer_api); Rust version pinned in api/rust-toolchain.toml.
• infra/ — Go + Pulumi (runtime: go) targeting the on-prem k3s cluster via the default kubeconfig, mirroring the homelab repo's pattern. Module name is desi-explorer-infra.
• .gitea/workflows/ — ci.yml (PR: install Odin, Rust, odin test + build, cargo test + clippy, go test) and release.yml (tag v*: build native + WASM + publish a Gitea release).

Conventions

• Odin code lives in src/; external deps go in lib/ and are wired via -collection:lib=lib/local (or a git submodule imported by relative path).
• Everything is plain make — no Taskfile — so CI (Gitea Actions) can call make directly.
• Keep the renderer (src/), API (api/), and infra (infra/) logically separated; the root Makefile is the only place that ties them together.

Gotchas

• Odin version is pinned in .gitea/workflows/*.yml (ODIN_VERSION) and defaults in scripts/install_odin.sh; bump both together when tracking a new release.
• CI installs clang (Odin uses it as the linker backend) and, for the WASM build, Emscripten + MinGW (Windows cross-build).
• The WASM build uses -define:RAYLIB_WASM_LIB=env.o so emcc links raylib's prebuilt web lib instead of Odin.
• Gitea Actions reuse the GitHub Actions plugin ecosystem (actions/checkout, christopherHX/gitea-upload-artifact / gitea-download-artifact); contexts remain ${{ github.* }}.

Session History

Export session information to resources/ai/sessions at the end of every session — for both plans and builds. (Gitignored.)

Gitignored

bin/, build/, *.bin, *.o, *.log, resources/ai/sessions, infra/Pulumi.*.yaml.backup, api/target/.