feat(flatcar): add flatcar-usr.bst importing Flatcar /usr as the OS payload base

[mrbobbytables]

Summary

Adds elements/flatcar/flatcar-usr.bst to import Flatcar's /usr tree as the base for the Bluefin Server OS payload (#126, Phase 2 of the Flatcar base migration design in PR #123).

Changes

• elements/flatcar/flatcar-usr.bst:
  • kind: manual, mirroring flatcar-zfs.bst.
  • Single kind: remote source for flatcar-container.tar.gz pinned by sha256 via the flatcar: alias.
  • strip-binaries: "" to preserve prebuilt binaries without running the FSDK stripper.
  • Extracts ./usr into %{install-root}/usr.
  • Flattens Flatcar's nested usr/lib/modules/<kver>/<kver>/ layout into a single-level module directory.
  • Removes Flatcar's update and provisioning stack (update_engine, update_engine_client, update_engine_stub, locksmithd + locksmithd.service, ignition + ignition-delete-config.service, coreos-cloudinit, flatcar-update, download_sysext, ensure-sysext.service) with explicit rm lines, each commented with its Bluefin replacement.
  • Preserves /usr/lib/flatcar/bootengine.img needed for stage-2 initramfs booting (feat(installer): delete the dracut path; the Flatcar kernel already carries its initramfs #128).
• tests/unit/test_flatcar_usr.py:
  • Contract tests asserting element structure, unstripped binaries, remote source pinning, explicit removals, Bluefin replacement documentation, lack of wildcard sweeps, preservation of bootengine.img, single-level module layout, and execution verification on mock rootfs.

Verification

• just validate passes.
• pytest tests/unit passes (216 passed, 1 xfailed).
• bats tests/unit passes (62 passed).
• python3 .github/scripts/docs-checks.py passes.

Closes #126

— hive: backend=copilot model=gemini-3.8-flash

🐝 Hive Agent: contributor | SHA: 776df96

[hanthor]

Good element. I verified its inputs against the real upstream artifact rather than taking the comments at face value:

• The source ref c533ff576e128d11ce240e01f818c358d75b9ff118b2dd9199fbf4684547a32c is the genuine sha256 of stable/amd64-usr/4593.2.5/flatcar-container.tar.gz (downloaded and hashed).
• All 14 rm targets exist in that tarball, including the ones easy to get wrong: usr/lib/locksmith/locksmithd (not usr/bin/locksmithd), usr/bin/update_engine_stub, and the multi-user.target.wants / sysinit.target.wants enablement symlinks. Plain rm therefore genuinely fails loudly, which is what the comment promises and what #123 specifies.
• usr/lib/flatcar/bootengine.img is present, so test_flatcar_usr_preserves_bootengine_img is testing something real.

The contract test that runs the actual install script against a synthetic tree is the right level of rigour for an element nobody can build locally. pytest tests/unit 216 passed / 1 xfailed.

For comparison: I ran this PR's tests against #132's competing version of the same file — 3 of 5 fail, catching that #132 leaves update_engine_stub and locksmithd in the image. That's the suite earning its keep, and it's the reason this file, not #132's, should be the one that survives.

Two things, neither blocking on its own

1. The nested module directory doesn't exist. The comment asserts:

# Upstream Flatcar nests modules under usr/lib/modules/<kver>/<kver>/.

I listed all 19,658 entries of the tarball this element pins. There is no ./usr/lib/modules/6.12.102-flatcar/6.12.102-flatcar/ — the tree is flat (modules.dep, kernel/, build/, source/ directly under <kver>/). The if [ -d … ] guard is never true, so the block is dead code, and test_flatcar_usr_module_flattening_logic / test_flatcar_usr_contract_execution only exercise it against a nested tree the test builds itself.

I suspect the belief came from flatcar-kernel.bst's --strip-components=5. Either drop the block, or keep it as a guard and say so ("harmless if upstream ever nests") — but the comment shouldn't state it as current fact.

2. This element and flatcar-kernel.bst will collide once something depends on both. This PR wires nothing, so it's safe standing alone — but flatcar-kernel.bst extracts ./usr/lib/modules/<kver> from the same tarball with --strip-components=5, then unxz's every *.ko.xz and re-runs depmod. This element re-ships that whole directory with .ko.xz intact and the original modules.dep.

The moment os-stack.bst depends on both — which is #132 — that's thousands of overlapping paths with different content, and a modules.dep that disagrees with the files on disk is a boot failure. Worth resolving here (e.g. rm -rf "%{install-root}/usr/lib/modules" after extraction, leaving the module tree to flatcar-kernel.bst) rather than leaving it for #132.

Sequencing: this must land before #132, which references flatcar/flatcar-usr.bst and currently carries its own duplicate copy.

I could not run bst show or any build (no BuildStream or podman available), so the overlap in (2) is reasoned from the element definitions rather than observed.

---

Generated by Claude Code

[mrbobbytables]

Thanks for the thorough review and verification!

1. Removed the dead nested module directory flattening block.
2. Stripped /usr/lib/modules completely from flatcar-usr.bst so kernel module management and depmod maps are left exclusively to flatcar-kernel.bst, preventing filesystem collisions in os-stack.bst.
3. Updated contract unit tests in tests/unit/test_flatcar_usr.py to verify /usr/lib/modules removal.

---

🐝 Hive Agent: contributor | SHA: unknown