Files
hermenix/docs/DEVELOP.md
T
2026-10-09 14:35:12 -04:00

83 lines
2.2 KiB
Markdown

# Hacking on this repo
## Devshell
```bash
direnv allow
```
Provides nushell, nufmt, nixfmt, and pre-commit hooks (installed on first
entry):
- **treefmt** — nixfmt / deadnix / statix / nufmt
- **nu-check** — parse-check `*.nu`
- **gen-completions** — regenerates `nu/completions.nu` from usage blocks
- **nu-tests** — `bin/runtest` when anything under `nu/` changes
## Layout
See [GUIDELINES.md](../GUIDELINES.md#repository-layout). The CLI is several
nushell files concatenated by `flake.nix` in dependency order
(`lib/` → `host/` → `vm/` → `ctl/` → `hermenix.nu`).
## Testing
Three suites. **Agents may run them only through the wrappers below** — never
via bare `nix build` / `nix flake check`. See [GUIDELINES.md](../GUIDELINES.md).
### CLI tests (`nu/tests/`, nutest)
```bash
runtest # everything (bin/ on PATH in the devShell)
runtest vm_test
runtest-debug vm_test
```
Pure helpers + smoke that the subcommand tree parses — no ssh, no disk writes,
no `nix build`.
### Guest VM tests (`guest/vm-tests/`)
Boot `guest/common.nix` in ephemeral NixOS test VMs. Never touches
`/var/lib/hermes-vm/**`:
```bash
runvmtest # NAT / isolated-bridge (default)
runvmtest guest-vm-bridged # bridged mode with simulated LAN
runvmtest-debug # interactive driver REPL
```
Shared seeding/SSH/user assertions live in `guest/vm-tests/common.nix`.
Mode-specific checks:
- **unbridged** — static `10.77.0.2/24` only, one default route via host
- **bridged** — DHCP lease beside service net, dual default routes, LAN
reachability both ways
Does not cover real `hermes-install` (no internet in the test VM) or the host
`hermes-vm` QEMU unit.
### Module evaluation checks
Static — no VM boot. Evaluates `modules/host.nix` in both network modes plus
`guest/common.nix`, asserts on nftables / networkd / guest DHCP metrics.
Operator/CI (not the agent-safe wrapper path today):
```bash
nix build .#checks.x86_64-linux.network-modes
```
Agents: describe the check and let the operator run it, unless/until a
`bin/` wrapper exists for it.
## Parsing the CLI without running it
```bash
nu nu/hermenix.nu --help
nu nu/hermenix.nu setup --help
# etc.
```
Nix syntax only: `nix-instantiate --parse path/to/file.nix`.