mcpx: the nix derivation's generated man page, completions and version are unverified, and one of them is not reproducible #1895

Relocated from dezren39/darwin-nix#178 on 2026-10-28 (placement audit): mcpx's single source lives in developing-today/code (pkgs/mcpx); re-home tracked at #309. Original body below; issue references inside it are historical (dezren39/nix numbering).

Parent: #177

Summary

pkgs/mcpx/package.nix postInstall produces three artefacts from the binary it just built — a man page, three shell completion scripts, and a version string injected by ldflags. Nothing asserts any of them, one of them is not reproducible, and the version exists in three places that no test keeps in agreement. These are release prerequisites: #158 designs tags, release artefacts and install channels on top of a derivation whose generated half is currently unchecked, and a release that ships a man page dated by whichever day the builder ran is a release that cannot be rebuilt bit-for-bit.

This issue owns the three defects in postInstall and the version fan-out. It does not own the platform matrix (#136), the CI workflow shape and caching design (#135), the container image (#134), or the release pipeline (#158). (It previously named #161 and #168; both were closed as duplicates — the survivors are #134 and #135.)

What was verified

All checks at 8001f23, which is one commit ahead of the d0b7e01 the earlier issues were written against; nothing in this area changed between them. Every row was re-checked at 05c78b2 in the 2026-09-30 issues pass and every one still holds: internal/cli/manual.go:335 still stamps time.Now(); package.nix:19 and :61 and cmd/mcpx/main.go:18 still carry three separate 0.1.0 literals; internal/testsupport/build.go:63 still builds without ldflags; and rg over every *_test.go still finds no reference to ManPage, CmdMan or CmdCompletion. #171 and #182 changed nothing here.

Current state (with file refs)

1. The man page is not reproducible

// internal/cli/manual.go:333-337
func ManPage(version string) string {
	var b strings.Builder
	date := time.Now().UTC().Format("2006-01-02")

	fmt.Fprintf(&b, ".TH MCPX 1 %q %q \"mcpx manual\"\n", date, "mcpx "+version)

package.nix runs mcpx man inside postInstall, so $out/share/man/man1/mcpx.1 embeds the UTC date of the build. Everything else in the derivation is deterministic: Go builds reproducibly, ldflags = [ "-s" "-w" ... ] strips, and the vendor tree is a fixed-output derivation. time.Now() is the only wall-clock input.

Consequences, in increasing order of how much they will matter later:

• nix build .#mcpx --rebuild diffs across a UTC midnight boundary. Nothing runs that today, so nobody has seen it.
• A content-addressed or signed release artefact (amd host fails at evaluation: no outputHashes for p2panda-core-0.7.1 #158) is not byte-stable, so "the tarball I built matches the tarball CI published" cannot be asserted.
• man mcpx shows the build date where a reader expects the documentation date, which is the wrong fact: a binary substituted from a cache shows the cache's build day.

The convention for exactly this is SOURCE_DATE_EPOCH, which nixpkgs already exports in every build (it is set to 1 in the stdenv unless overridden) and which every reproducible-build toolchain honours.

2. Neither generated artefact is asserted

# package.nix postInstall
$out/bin/mcpx man > $out/share/man/man1/mcpx.1

installShellCompletion --cmd mcpx \
  --bash <($out/bin/mcpx completion bash) \
  --zsh <($out/bin/mcpx completion zsh) \
  --fish <($out/bin/mcpx completion fish)

mcpx man and mcpx completion <shell> are executed at build time and their output is never inspected, by the build or by any test. The build fails only if the process exits non-zero. A ManPage that returned the empty string, or a completion zsh that emitted a syntactically invalid #compdef block, would produce a green nix build and a broken installed package. rg over every _test.go in the tree returns no reference to ManPage, CmdMan or CmdCompletion.

This is worse than it looks because both generators read Commands(), which is itself incomplete — seven dispatched commands are missing from it (#159 item 1; re-measured in the sibling review issue). So the man page and the completions are known to be wrong, and there is no mechanism by which anyone would find out.

3. The version has three sources and no arbiter

They agree today only because nobody has changed one. The first bump breaks the property silently in two directions: the derivation name and the binary's self-report can diverge, and the e2e suite keeps exercising a binary that reports the pre-bump version while the packaged one reports the new one. internal/api/openapi.go and internal/cli/openapi.go both take version as a parameter, so a wrong value propagates into the published specification too.

Approaches

1. Reproducible man page — no real choice

Honour SOURCE_DATE_EPOCH: parse it when set, fall back to time.Now() when it is not, so an interactive mcpx man still shows today. Five lines in internal/cli/manual.go. The only sub-decision is what to show when the variable is absent from a release build, and the answer is that a release build always has it.

2. Asserting the generated artefacts

• A — least recommended: assert in postInstall. Add grep -q checks to the nix expression (grep -q '^\.TH MCPX' mcpx.1, non-empty completions). It works, and it puts test logic in the one place that only runs under nix build, is invisible to go test, cannot be run locally without a full derivation rebuild, and is written in bash inside a Nix string. Every future assertion accretes there.
• B — middle: a Go golden test. internal/cli/manual_test.go compares ManPage("test") against a checked-in golden file. Catches regressions in content, and catches nothing about the completions actually being valid shell, because a golden file of a zsh script only proves it did not change.
• C — recommended: a Go presence test plus a shell-parser smoke test, and keep nix build dumb. In Go: every entry in Commands() appears in ManPage, every entry appears in each of the three completion scripts, and the .TH line carries the version it was given. In CI (this belongs to Update Rust crate tokio to v1.38.2 [SECURITY] #135's job graph, not to postInstall): pipe each completion script through bash -n, zsh -n and fish --no-execute, which is the only check that distinguishes "non-empty" from "valid". Once Root flake check fails on nixosConfigurations due to missing clan-core.clanModules #159's Commands() gap is closed, the same presence test is what stops it reopening. Recommended because it moves the assertion to where it can be run in a second by anyone, and because the shell-parse check is the one that finds the failure mode that actually ships.

3. Single-sourcing the version

• A — least recommended: a //go:generate step or a version.txt read by both. A file both Nix and Go read is genuinely single-sourced, but it adds a build input that has to be kept in the cleanSourceWith filter, and it does not solve the test-binary problem: go build without ldflags still falls back.
• B — middle: drop the fallback and make an un-stamped binary say so. var version = "dev" in cmd/mcpx/main.go (which is already the convention used at internal/pool/pool.go:39, var Version = "dev"). Then a binary built without ldflags reports dev and can never be confused with a release. Cheap, honest, and leaves package.nix's two copies still hand-synchronised.
• C — recommended: B, plus derive the ldflag from the version attribute, plus a test. ldflags = [ "-s" "-w" "-X main.version=${version}" ] removes one of the two Nix copies outright (finalAttrs.version or a let-bound name). var version = "dev" removes the third. That leaves exactly one literal, which amd host fails at evaluation: no outputHashes for p2panda-core-0.7.1 #158 then replaces with the git tag. Add one e2e assertion that mcpx --version matches the derivation's version when run from result/bin/mcpx — which is the "handful of assertions against result/bin/mcpx" that Update Rust crate rand to v0.9.3 [SECURITY] #134 identifies as the cheapest win in its area (formerly Phase 2: removal: weak is stored but not built #161, closed as a duplicate), so the two should land together.

Open questions

• Should postInstall keep generating the man page from the binary at all, or should the release pipeline (amd host fails at evaluation: no outputHashes for p2panda-core-0.7.1 #158) generate and commit it so that the tarball, the nix package and the distro packages all ship the same bytes? Generating from the binary is the right call for correctness and the wrong call for a distro packager who does not want to execute a freshly built cross-compiled binary. This is a real fork and amd host fails at evaluation: no outputHashes for p2panda-core-0.7.1 #158 should decide it, not this issue.
• Does SOURCE_DATE_EPOCH belong in ManPage's signature (explicit, testable) or read from the environment inside it (fewer call sites to change)? Prefer the parameter, but it touches CmdMan.
• Is lib.platforms.unix plus an unasserted man page enough for a distro package's lintian/rpmlint pass, or does that need a .TH date in a specific format? Unknown; matters only once amd host fails at evaluation: no outputHashes for p2panda-core-0.7.1 #158 picks a distro channel.

Ease · Impact · Related

Ease: S (the man-page date and the version fan-out are a handful of lines each; the presence test is the bulk, and it is one file) · Impact: med (nothing is broken for a user today; everything here is a prerequisite that gets more expensive the longer #158 waits on it)

Related: #158 — this is largely a prerequisite for it: a release pipeline needs a reproducible derivation, one version source and generated artefacts it can trust. #134 owns the container image and the "run assertions against result/bin/mcpx" step that item 3C plugs into (formerly #161, closed as a duplicate). #182 added a Containerfile; nothing in CI builds or tests it yet, so that step is still owed. #159 item 5 records the man-page date as a documentation problem; this issue adds the nix-reproducibility consequence and the fix shape. #159 item 16 and #158 both record the three version sites; this issue adds the test-binary divergence via internal/testsupport/build.go:63. #136 owns the platform matrix and the static-binary question, which is why CGO_ENABLED is only recorded here and not decided. #135 owns the CI job graph the shell-parse check belongs in, and the rest of the caching design (its cache-dependency-path line landed in #182). #144/#145 own generating a reference from Commands(), which shares the presence test. #49 — the same "built but never exercised" gap for every other flake package.

Security/auth deferred; see tracker.