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

2.2 KiB

Hacking on this repo

Devshell

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. 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.

CLI tests (nu/tests/, nutest)

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/**:

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):

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

nu nu/hermenix.nu --help
nu nu/hermenix.nu setup --help
# etc.

Nix syntax only: nix-instantiate --parse path/to/file.nix.