Port and deploy flake-status as a Go binary #158

New issue

Open

opened 2026-08-26 03:03:21 +01:00 by vnprc-agent · 0 comments

vnprc-agent commented

2026-08-26 03:03:21 +01:00

Contributor

Replace flake-status with a standard-library-only Go binary while preserving its command and output contracts, then deploy it and retire the Bash implementation.

Primary goals:

One tool, one finish line — this issue is done only when the Go implementation is deployed and verified on its real consumers and the Bash source is removed; it owns the remaining flake-status work split from issue allod/tools#98.
Executable parity — run the same scenarios against Bash and Go, preserving arguments, environment variables, exit behavior, stdout/stderr, row ordering, health warnings, and upstream comparison behavior.
Keep the package minimal — use pkgs.buildGoModule with vendorHash = null; parse lock JSON in-process and retain only the external commands the contract actually needs.
Close on retirement — implementation and consumer cutover PRs use Refs allod/tools#158; the final allod/tools PR that removes the verified Bash implementation carries the closing keyword.

Current state and contracts

flake/flake-status is a 490-line Bash program. It sources lib/workspace.sh, parses flake.lock through jq, coordinates parallel collection through temporary files, optionally resolves upstream revisions with git ls-remote, and renders results back in workspace order. tests/flake/flake-status.sh is the executable contract; flake/README.md and flake/flake-status --help are the human-facing contract.

The deployed command is still assembled with writeShellApplication: allod/archetypes modules/dev-home-shared.nix:56-60 for development machines and allod/nexus nix/home.nix:49-53 for the host. Both wrappers prepend the shared workspace library to the Bash source. The Go implementation must preserve workspace_collect_repos discovery and ordering semantics even though it can no longer source that function.

Freeze current behavior at implementation start. In particular, preserve no-argument and named-input modes, --upstream, FLAKE_STATUS_JOBS, terminal color behavior, direct-pin versus follows handling, repository health warnings, majority/staleness reporting, URL de-duplication, and nonfatal upstream lookup failures. The closed won't-fix decision in issue allod/tools#102 remains unchanged; this migration does not expand discovery. A correctness bug still open when implementation starts may diverge only with a regression test and an explicit PR-body note.

Validation and deployment

Parameterize tests/flake/flake-status.sh with a binary-under-test override and run its scenarios unchanged against both implementations. Compare stdout, stderr, and exit status for deterministic fixtures; add Go unit tests around lock parsing, ordering, concurrency bounds, and upstream-result aggregation where the Bash suite cannot isolate them.

Before cutover, gofmt -l ., go vet ./..., go test ./..., the Bash oracle suite, the Go-target parity suite, nix build .#flake-status, and affected flake checks must pass. Consumer PRs switch only this command to buildGoModule and retain the Bash file for rollback. After the downstream lock updates and human rebuilds, verify that command -v flake-status resolves to the Go package and run read-only no-argument, named-input, and upstream smoke checks on a development machine and nexus. Remove the Bash source only after those witnesses pass.

Scope

In scope: the Go command and supporting internal packages in allod/tools; parity and Go tests; the allod/tools package output; the allod/archetypes and allod/nexus package switches; downstream lock updates and rebuild verification; documentation adjustments required by packaging; and final Bash retirement.

Out of scope: flake-update-cascade, new discovery behavior, output redesign, unrelated workspace-tool migrations, and the report-validator work in issue allod/tools#142.

Replace `flake-status` with a standard-library-only Go binary while preserving its command and output contracts, then deploy it and retire the Bash implementation. Primary goals: - **One tool, one finish line** — this issue is done only when the Go implementation is deployed and verified on its real consumers and the Bash source is removed; it owns the remaining `flake-status` work split from issue allod/tools#98. - **Executable parity** — run the same scenarios against Bash and Go, preserving arguments, environment variables, exit behavior, stdout/stderr, row ordering, health warnings, and upstream comparison behavior. - **Keep the package minimal** — use `pkgs.buildGoModule` with `vendorHash = null`; parse lock JSON in-process and retain only the external commands the contract actually needs. - **Close on retirement** — implementation and consumer cutover PRs use `Refs allod/tools#158`; the final `allod/tools` PR that removes the verified Bash implementation carries the closing keyword. ### Current state and contracts `flake/flake-status` is a 490-line Bash program. It sources `lib/workspace.sh`, parses `flake.lock` through `jq`, coordinates parallel collection through temporary files, optionally resolves upstream revisions with `git ls-remote`, and renders results back in workspace order. `tests/flake/flake-status.sh` is the executable contract; `flake/README.md` and `flake/flake-status --help` are the human-facing contract. The deployed command is still assembled with `writeShellApplication`: `allod/archetypes` `modules/dev-home-shared.nix:56-60` for development machines and `allod/nexus` `nix/home.nix:49-53` for the host. Both wrappers prepend the shared workspace library to the Bash source. The Go implementation must preserve `workspace_collect_repos` discovery and ordering semantics even though it can no longer source that function. Freeze current behavior at implementation start. In particular, preserve no-argument and named-input modes, `--upstream`, `FLAKE_STATUS_JOBS`, terminal color behavior, direct-pin versus `follows` handling, repository health warnings, majority/staleness reporting, URL de-duplication, and nonfatal upstream lookup failures. The closed won't-fix decision in issue allod/tools#102 remains unchanged; this migration does not expand discovery. A correctness bug still open when implementation starts may diverge only with a regression test and an explicit PR-body note. ### Validation and deployment Parameterize `tests/flake/flake-status.sh` with a binary-under-test override and run its scenarios unchanged against both implementations. Compare stdout, stderr, and exit status for deterministic fixtures; add Go unit tests around lock parsing, ordering, concurrency bounds, and upstream-result aggregation where the Bash suite cannot isolate them. Before cutover, `gofmt -l .`, `go vet ./...`, `go test ./...`, the Bash oracle suite, the Go-target parity suite, `nix build .#flake-status`, and affected flake checks must pass. Consumer PRs switch only this command to `buildGoModule` and retain the Bash file for rollback. After the downstream lock updates and human rebuilds, verify that `command -v flake-status` resolves to the Go package and run read-only no-argument, named-input, and upstream smoke checks on a development machine and nexus. Remove the Bash source only after those witnesses pass. ### Scope In scope: the Go command and supporting internal packages in `allod/tools`; parity and Go tests; the `allod/tools` package output; the `allod/archetypes` and `allod/nexus` package switches; downstream lock updates and rebuild verification; documentation adjustments required by packaging; and final Bash retirement. Out of scope: `flake-update-cascade`, new discovery behavior, output redesign, unrelated workspace-tool migrations, and the report-validator work in issue allod/tools#142.