Build is not hermetic: system toolchain, unpinned tools, and a hard-coded port 9000

[behinddwalls]

Build is not hermetic: relies on system toolchain and unpinned env

A fresh clone does not build or run without hunting down several host tools, and the failure modes are confusing. The repo should either pin/provide every tool (e.g. the Nix devshell as the single entry point) or enumerate them with exact versions and per-platform install steps.

What a fresh contributor hits (observed on macOS, 2026-08-25)

Step	Problem	Symptom
cargo build	cargo not on PATH in a new shell even after rustup	command not found: cargo
cargo build	rustup shims missing after toolchain install	could not execute process 'rustc -vV' (never executed)
just web-build	Node 24 + pnpm required; system node is older; corepack shim not enabled	node:internal/errors:490 crash, pnpm: command not found
protoc	not checked up front	build fails deep into walgit-proto compile
just dev-store	assumes port 9000 is bindable	container starts, host can never reach it if anything else (e.g. ZscalerTunnel on corporate Macs) holds 0.0.0.0:9000 — health check just hangs
just dev-store	Linux-only assumptions (rootless podman API socket path, setsid)	recipe fails on macOS before starting the store

Concrete gaps

1. No single version-pinned toolchain path. rust-toolchain.toml pins Rust, but git (≥2.46), just, protoc, node 24 and pnpm are unpinned and come from the host.
2. README vs reality. README says "needs rust per rust-toolchain.toml, protoc, node 24 + pnpm" but doesn't say how to get them per platform, and doesn't mention just or a container runtime at all.
3. Port 9000 is a hard-coded, unverifiable assumption. just dev-store fails opaquely when 9000 is taken; there is no preflight check with an actionable message.
4. just dev-local is documented as self-contained but isn't on macOS — dev-store is Linux-shaped.

Suggested direction

• Make the Nix devshell (flake.nix already exists) the canonical "it works" path: nix develop gives rust + git + just + protoc + node + pnpm + podman at pinned versions. Document it as the primary path, keep "bring your own tools" as the fallback with an exact version table (now in docs/DEV_SETUP.md).
• Add a preflight to just dev-store/just dev-local: verify each tool exists with its minimum version and verify port 9000 is free, and fail fast with the exact fix for the platform (brew install … / apt install … / "set WALGIT__STORE__S3__ENDPOINT to a free port").
• Make dev-store work on macOS (no setsid, no /run/user/$UID socket path) or auto-detect Docker Desktop and use docker compose there.

Environment where this was hit

macOS (Apple Silicon), rustup 1.29.0, git 2.55, just 1.58, node 18 system / 24 via nvm, podman 6.1.0 + Docker Desktop both present, Zscaler holding port 9000.

[0bserver07]

With #36 in, the recipe side of this is done: just dev-store runs on macOS (the Linux-only podman socket bootstrap is guarded; elsewhere it probes podman and says how to start it), just dev-local no longer trusts the placeholder index.html cargo writes, and tests/e2e.sh works under the bash 3.2 macOS ships. #29 fixed the container build (#21), and #43 makes just clippy pass on a Mac. From the list here, what's still open is the version table and the port 9000 preflight, both of which #17 carries along with a DEV_SETUP.md (#12 has another).