chore: add Flox development environment

[nvidiajeff]

Summary

• Add a Flox (Nix-based) development environment as an alternative to make tools-setup
• The .flox/env/manifest.toml tracks tools from tools/setup-tools and .settings.yaml on a best-effort basis
• Provides an isolated, reproducible dev shell with a single flox activate command
• Update DEVELOPMENT.md with Flox usage instructions and guidance for keeping the manifest in sync with .settings.yaml

Test plan

• flox activate -- make tools-check verifies tools are available
• Review DEVELOPMENT.md rendering for clarity

[github-actions]

Coverage Report ✅

Metric	Value
Coverage	74.5%
Threshold	70%
Status	Pass

Coverage Badge

![Coverage](https://img.shields.io/badge/coverage-74.5%25-green)

No Go source files changed in this PR.

[mchmarny]

We had Flox before as an alternative and since it was really used by one contributor it often lagged behind the frequently evolving main settings approach that allows the entire project (dev and CI/CD side to sync on versions while enable different deployment mechanism).

Some of the constraints on the GH actions that can be used in NVIDIA org means that the CI side for Flox also had to do some non-idiomatic stuff installation/updates). Even in this PR you can already see the coverage gaps between manifest.toml and .settings.yaml. The manifest claims to mirror .settings.yaml, but they're out of sync:

Tool	In .settings.yaml	In manifest.toml	Notes
kwok	✅ v0.7.0	❌ missing	Used by make kwok-test-all
karpenter	✅ v1.8.0	❌ missing
hugo	✅ 0.155.3	❌ missing	Docs builds
node	✅ 22	❌ missing	Docs builds
awscli2	❌ not listed	✅ present	Where does this come from?

A developer running flox activate would be missing tools that make tools-setup provides, which undermines the "drop-in alternative" claim.

Also, the DEVELOPMENT.md currently says .settings.yaml changes "propagate everywhere automatically." That's no longer true with Flox — the manifest requires manual updates. The sync instructions ("use an AI assistant prompt") are creative but fragile. Maybe could either:

• Generating manifest.toml from .settings.yaml (a script in tools/ that templates it), or
• Being explicit in the docs that Flox is best-effort and may lag behind make tools-setup

Version pinning

Only Go has a version constraint (^1.26). Every other tool is unpinned in the manifest — the lock file pins them, but flox update would pull whatever's latest in nixpkgs, potentially mismatching .settings.yaml. Adding version constraints (even just major version) would reduce surprise drift.

Housekeeping

Per project policy, please remove the "Generated with Claude Code" line from the PR description (see CLAUDE.md).

Summary

Larger, meta point, given the early stage of this project and the velocity with which it evolves, we want to keep things as aligned to the default, idiomatic OSS Go project experience.

I’m looking at projects like Kubernetes, Helm, Terraform, Docker, or Prometheus and I am not seeing any of them using Flox. While Flox does have some nice properties, unless we have consensus from other maintainers in this project to use Flox themselves and ensure ongoing support, I'm incline to recommend we hold back on introducing yet another tool for now.

[dims]

I'm incline to recommend we hold back on introducing yet another tool for now.

I am in agreement with @mchmarny

[nvidiajeff]

Sounds good - it was useful to me and thus I wanted to share. We can close this and hopefully revisit it once Flox/Nix are in more widespread usage.

It is incredibly useful to have an isolated environment for installing all these tools without conflicting with the requirements of other projects developers work on.

[nvidiajeff]

Re-opening 🙏 - I have made a best effort to address the feedback @mchmarny / @dims - if this is sufficient, please consider merging, if not I am ok if we want to close the PR and address it at a later date.

Aside from that, if I may offer my opinion:

I understand introducing a new paradigm for environment management is not a trivial thing, but the industry is indeed moving this direction and it is in part our duty to innovate.

Ideally we would use Flox OSS for all environments across dev/CI rather than maintain shell scripts that do not provide an isolated environment.

For those unfamiliar - Flox provides Python Virtualenv-like environments for all dev/ci dependencies while guaranteeing that the exact build of each tool is used end-to-end in all environments.

[lockwobr]

I want to add my thoughts to this discussion. This week I found and fixed several issues in our current tools-setup, and it's making me wish it were easier to add and test new dependencies. Let me outline the problems I've been running into and how I think Flox could help address them.

Issues with the current approach:

• Linux support — Several deps didn't work on Linux at all. Since most core devs are on Mac, the Linux side doesn't get the same exercise. Flox uses Nix packages under the hood, which are built and tested for both Linux and macOS from the same definition — no platform-specific install logic to maintain.
• System-level dependencies — Some tools depend on system packages like Python (e.g., yamllint). Depending on your Linux distro, you may need to set up Python separately. I added apt support, but if you're on a Red Hat variant it just warns and skips. Flox resolves the full dependency tree, so yamllint would bring in its own Python without touching the system or caring about the distro's package manager.
• No version locking on macOS — Many installs use Homebrew, which (as far as I know) doesn't have a good way to pin versions. That means running setup-tools today gives you different versions than someone who ran it weeks ago. Flox has a lockfile (manifest.lock) that pins exact package builds, so every developer gets the same versions until someone explicitly runs flox update.
• Staleness — Twice recently I ran a command that failed because my system was missing something new. I had to manually track it down and add it. To @mchmarny point, Flox can also drift from .settings.yaml — but the current approach already has this problem, and debugging it is harder because you're dealing with platform-specific shell scripts rather than a single declarative manifest.

Related PRs from this week:

• feat(release): add supply chain verification to Homebrew formula #342
• fix(tools): fix Linux setup-tools for yq, chainsaw, helm, yamllint, grype, crane, goreleaser #314

[yuanchen8911]

Inline comments from cross-review (Claude Code + Codex + CodeRabbit)

[yuanchen8911]

Cross-Review Summary (Iterative Consensus)

Reviewers: Claude Code, Codex, CodeRabbit
Rounds: 3 (independent reviews → cross-review → resolve contested)
Consensus reached: Yes

Confirmed Issues

#	File	Severity	Description
1	.flox/env/manifest.toml	Medium	Helm v3 installed but .settings.yaml specifies v4.1.1. Major version mismatch could produce incorrect bundle output. Needs prominent callout or on-activate warning.
2	.flox/env/manifest.toml L88	Minor	GOFLAGS="-mod=vendor" set globally affects all go commands including go install/go get. Document limitation or scope more narrowly.
3	.flox/env/manifest.toml ~L96-110	Minor	GOPATH/GOBIN exported identically in both [hook].on-activate and [profile].common. Add comment explaining why both are needed.
4	DEVELOPMENT.md ~L150	Minor	Sync instructions rely on AI assistant prompt. A make flox-check target or script would be more reliable.
5	.flox/env/manifest.toml	Minor	Version drift risk — loose constraints (^2, unpinned) can diverge from .settings.yaml. No automated drift detection.
6	.flox/env/manifest.toml	Minor	Several packages (crane, grype, syft, addlicense, go-licenses) have no version constraint. flox update could pull breaking bumps.
7	.flox/env/manifest.toml L65	Low	Tilt pinned to ^0.36 but .settings.yaml specifies 0.37. Documented deviation — update when nixpkgs catches up.

Dismissed Findings

• Large lockfile bloat (Codex, originally Major) — Dismissed after Round 3: committing the lockfile is standard Flox practice for reproducibility. linguist-generated=true already hides it from diffs. Codex accepted this reasoning.
• Empty TOML sections (Codex, Minor) — Standard Flox scaffolding, serves as documentation of available config sections.
• Missing copyright headers on .flox/ files (CodeRabbit, Low) — Tool-generated config files are typically excluded from addlicense checks. Dismissed by Claude Code + Codex.

Positive Observations

• Clean separation: Flox is opt-in, doesn't affect existing make tools-setup workflow
• linguist-generated=true on lockfile is good practice
• Documentation is thorough with prerequisites, quick start, and known limitations
• Inline comments in manifest.toml explain every version deviation

---

Iterative cross-review by Claude Code + Codex + CodeRabbit (3 rounds)

[yuanchen8911]

Inline comments from iterative cross-review (Claude Code + Codex + CodeRabbit, 3 rounds)

[yuanchen8911]

Cross-Review Summary for PR #251

Reviewers: Claude Code, Codex, CodeRabbit + Integration Impact Analysis
Rounds: 1 (strong consensus on round 1)
Consensus reached: Yes

Confirmed Issues

#	File	Severity	Description	Agreed By
1	manifest.lock (vars)	Critical	Lockfile is stale — contains GOFLAGS="-mod=vendor" and an older hook/profile, but manifest.toml intentionally has empty [vars] and a different hook. flox activate will export GOFLAGS globally, breaking go install/go get. Lock must be regenerated (flox lock).	Claude Code, CodeRabbit
2	manifest.toml L57	Major	Helm 3 vs 4: .settings.yaml requires v4.1.1 but nixpkgs only has v3.x. make tools-check will fail.	All reviewers
3	manifest.toml L63	Major	Tilt 0.36 vs 0.37: .settings.yaml requires 0.37.0 but nixpkgs only has 0.36.x.	Claude Code, Codex, CodeRabbit
4	DEVELOPMENT.md L136	Major	"All tools are now available — verify with: make tools-check" is misleading given Helm/tilt version gaps. Test plan claims tools-check passes but it cannot with these mismatches. Should note expected warnings.	Codex, CodeRabbit
5	.dockerignore	Minor	.flox/ not excluded from Docker build context (~500KB lockfile sent unnecessarily).	Codex, Integration
6	manifest.toml L28,40,43	Minor	Unpinned tools (crane, grype, syft) may drift from .settings.yaml. Documented but make tools-check may flag.	All reviewers

Integration Findings

• Makefile GOFLAGS usage (lines 102, 121, 123, 171, 188, 216): The stale lock accidentally sets GOFLAGS which is compatible with Makefile, but breaks standalone go install. Regenerating the lock to remove GOFLAGS from vars is the correct fix.
• CI/CD impact: None — no workflows reference .flox/. Purely opt-in local tooling.
• GoReleaser/Tiltfile: Unaffected — both use explicit directory paths.

Positive Observations

• Clean hook scripts with proper quoting and safe || true fallback
• .gitattributes correctly marks lockfile as linguist-generated
• Karpenter exclusion is well-documented
• Zero CI/CD risk — purely opt-in

---

Cross-review by Claude Code + Codex + CodeRabbit

[nvidiajeff]

Addressed all of the feedback, and updated the manifest again - great news is that several dependencies have been updated in Nixpkgs and the only remaining tool discrepancy is Helm v3 / v4 which should land in Nixpkgs in the near future.

[mchmarny]

@nvidiajeff I know you are looking to refresh this. For now, I'm going to close it given how long this has been out there but we can revisit when you are back.