Story: Hotfix: NATS cert generation fails on macOS/Windows (missing `ip` command)
Table of Contents
This page documents a story in Sprint 25. It captures the goal, current status, acceptance criteria, and the tasks that compose it.
Goal
`compass env configure` fails on macOS and Windows runners during NATS certificate generation: `_local_ipv4_addresses` shells out to the Linux-only `ip` binary, and the missing executable raises `FileNotFoundError` before the gethostname fallback can run. The fix restores the documented fallback so `env configure` completes on all three platforms. Linux is unaffected (`ip` is always present).
Status
| Field | Value |
|---|---|
| State | DONE |
| Parent sprint | Sprint 25 |
| Now | Nothing. |
| Waiting on | Nothing. |
| Next | Nothing. |
| Last touched | 2026-08-11 |
Acceptance
- `compass env configure` completes on macOS, Windows, and Linux.
- The NATS server cert SAN still lists the host's IPv4 addresses when `ip` is available (Linux behaviour unchanged).
Tasks
| Task | State | Start | End | Description |
|---|---|---|---|---|
| Scaffold story: Hotfix: NATS cert generation fails on macOS/Windows (missing `ip` command) | DONE | 2026-08-11 | 2026-08-11 | Story scaffolding rides this task: documents, sprint wiring, and the scaffold PR. Close it before merging that PR. |
| Implement Hotfix: NATS cert generation fails on macOS/Windows (missing `ip` command) | DONE | 2026-08-11 | 2026-08-11 | Initial task for: Hotfix: NATS cert generation fails on macOS/Windows (missing `ip` command) |
Decisions
- Catch `OSError` (not just `FileNotFoundError`) around the `ip` subprocess call: sandboxed or non-executable `ip` is the same class of failure as a missing binary.
- Filter fallback addresses with `ipaddress` `is_loopback`/ `is_link_local` rather than a literal `127.0.0.1` discard: `/etc/hosts` may map the hostname to another loopback (127.0.1.1), and the cert SAN must stay non-routable-address-free.