NeilClack
b88caa291d
- nixos/vm.nix: enable PasswordAuthentication for kiosk user (SSH test access) - scripts/test-vm.sh: one-command build → start → diagnose workflow - macOS: builds and runs on remote Linux server, SSH through server - Linux: builds and runs locally - Commands: --build, --start, --stop, --diagnose, --shell - Diagnostics: NetworkManager, PipeWire, wpctl, ALSA, pactl, processes, logs - AGENTS.md: compact agent guide for the repo
59 lines
2.3 KiB
Markdown
59 lines
2.3 KiB
Markdown
# RadiantWave Agent Guide
|
|
|
|
## What This Is
|
|
|
|
Go kiosk application using SDL2, OpenGL 3.3, SQLite (via GORM), and D-Bus (NetworkManager). Nix flake is the primary build system. CI runs on Forgejo (not GitHub Actions).
|
|
|
|
## Build & Run
|
|
|
|
Dev shell via direnv (`use flake` in `.envrc`). Inside the nix dev shell:
|
|
|
|
```sh
|
|
# Build
|
|
go build -o bin/rhemawave rhemawave.go
|
|
|
|
# Run
|
|
./bin/rhemawave
|
|
|
|
# Nix build (CI uses this)
|
|
nix build -L
|
|
```
|
|
|
|
CGO is required (`CGO_ENABLED=1`). The nix dev shell and `flake.nix` `preBuild` set the necessary `CGO_CFLAGS` and `CGO_LDFLAGS` for SDL2. Do not attempt a plain `go build` outside the nix shell — it will fail on missing SDL2 headers.
|
|
|
|
## Tests
|
|
|
|
Only one test suite exists: `internal/mixer/mixer_test.go`. Run with:
|
|
|
|
```sh
|
|
go test ./internal/mixer/
|
|
```
|
|
|
|
No lint or typecheck commands are configured in the repo. CI only runs `nix build -L`.
|
|
|
|
## Branch Model
|
|
|
|
`dev` → `main` via pull requests. CI workflows are in `.forgejo/workflows/`:
|
|
- `build-dev.yml`: PRs to `dev`
|
|
- `build-prod.yml`: PRs to `main`
|
|
|
|
Both run `nix build -L` on a self-hosted runner (`neils-server-runner`).
|
|
|
|
## Key Architecture
|
|
|
|
- **Entry**: `rhemawave.go` → `internal/application.Run()`
|
|
- **State machine**: `internal/application/application.go` — FIRST_RUN → NEEDS_INTERNET → NEEDS_EMAIL_ADDRESS → NEEDS_LICENSE_KEY → DOWNLOADING_ASSETS → READY
|
|
- **Pages**: `internal/page/` — router pattern with page interface (`page.go`)
|
|
- **DB**: SQLite at `~/.local/share/rhemawave/database.sqlite`, managed by GORM in `internal/db/`
|
|
- **Assets**: `share/rhemawave/` (fonts, shaders, proclamations, tos) — copied into nix store at build time
|
|
- **Audio**: `.wav` files are gitignored, downloaded at runtime from `files.radiantwavetech.com`
|
|
- **Vendor**: Dependencies are vendored and committed. Use `go mod vendor` after adding deps.
|
|
|
|
## Common Pitfalls
|
|
|
|
- The `dev_scripts/reset.sh` referenced in the nix devShell hook does not exist in the repo.
|
|
- `share/rhemawave/audio/*.wav` is gitignored — do not commit audio assets.
|
|
- The `vendor/` directory is committed — always run `go mod vendor` after `go mod tidy`.
|
|
- CI runs on a self-hosted Forgejo runner, not GitHub-hosted runners. Workflows source nix via `/nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh`.
|
|
- The `packaging/` directory contains a kiosk-specific updater script and is not part of the main build.
|