From cb79dcc168663eb5db790cefe1e3fab6605e4af7 Mon Sep 17 00:00:00 2001 From: mrbobbytables Date: Fri, 18 Sep 2026 21:04:48 +0000 Subject: [PATCH 1/2] fix(flavors): single-source flavor to image name mapping in flavors.py Collapse duplicate flavor-to-image name mappings in Justfile into scripts/flavors.py via a new `image FLAVOR` query. `image_name` in Justfile now queries `flavors.py image "{{ flavor }}"`, and `build-ghcr` delegates to `just image_name` like `gen-sbom` and `secureboot` already do. Extend the `just check` guard to ensure neither workflows nor the Justfile contain hardcoded flavored image names. Update tests and the flavors skill documentation accordingly. Closes projectbluefin/utah#43 Assisted-by: Gemini 3.8 Flash via GitHub Copilot Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: mrbobbytables --- AGENTS.md | 5 +++-- Justfile | 33 ++++++++++++--------------------- docs/skills/flavors.md | 25 +++++++++++++++---------- docs/skills/index.json | 2 +- scripts/flavors.py | 8 ++++++++ tests/test_flavors.py | 32 ++++++++++++++++++++++++++++++-- 6 files changed, 69 insertions(+), 36 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 6655a3775..04b63aa7c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -47,8 +47,9 @@ checks (`scripts/check-skill-frontmatter.sh`, `scripts/check-skill-index.sh`, tracking issue. A missing contract package is a build failure, never a silent skip. - **`config/flavors.json` is the single source of the flavor set.** No - workflow may name `utah-nvidia` or `utah-gaming` literally — `just check` - fails on it. Retire a flavor by moving it under `retired` with the reason. + workflow or Justfile recipe may name `utah-nvidia` or `utah-gaming` + literally — `just check` fails on it. Retire a flavor by moving it under + `retired` with the reason. - **Containerfile ARG digests are Renovate-managed pins** (`BASE_IMAGE`, `PACKAGE_IMAGE_SHA`, `COMMON_IMAGE_SHA`, `BREW_IMAGE_SHA`). Do not bump them by hand unless the task is exactly that. `Containerfile` and diff --git a/Justfile b/Justfile index 95ba1a907..8c3acf834 100644 --- a/Justfile +++ b/Justfile @@ -110,13 +110,18 @@ check: bash scripts/check-skill-frontmatter.sh bash scripts/check-skill-index.sh python3 scripts/generate_skill_index.py --check - # No workflow may carry its own copy of the flavor list. That drift is what - # config/flavors.json exists to stop: narrowing the build matrix while + # Neither workflows nor the Justfile may carry their own copy of the flavor + # list or flavored image names. That drift is what config/flavors.json and + # scripts/flavors.py exist to stop: narrowing the build matrix while # promote and release still name images nothing produces fails late. - if grep -rn 'utah-nvidia\|utah-gaming' .github/workflows/; then + if grep -rnE 'utah-(nvidia|gaming)' .github/workflows/; then echo 'no workflow may name a flavored image; read it from config/flavors.json' >&2 exit 1 fi + if grep -nE '(utah|\{\{ image \}\})-(nvidia|gaming)' Justfile; then + echo 'no recipe may name a flavored image; use flavors.py image' >&2 + exit 1 + fi # Verify branding, desktop defaults, first-boot Flatpak policy, and service # enablement in an already-composed image. The same verifier runs in the @@ -154,15 +159,7 @@ check-parity: fi image_name base_name stream flavor: - #!/usr/bin/env bash - set -euo pipefail - case "{{ flavor }}" in - main) echo "{{ image }}" ;; - nvidia) echo "{{ image }}-nvidia" ;; - gaming) echo "{{ image }}-gaming" ;; - nvidia-gaming) echo "{{ image }}-nvidia-gaming" ;; - *) echo "unknown Utah image flavor: {{ flavor }}" >&2; exit 2 ;; - esac + @python3 scripts/flavors.py image "{{ flavor }}" generate-default-tag stream build_number: @echo "{{ stream }}" @@ -190,13 +187,7 @@ build-ghcr base_name stream flavor kernel_pin="": #!/usr/bin/env bash set -euo pipefail version="{{ stream }}-$(date -u +%Y%m%d)-$(git rev-parse --short HEAD)" - case "{{ flavor }}" in - main) image_name="{{ image }}" ;; - nvidia) image_name="{{ image }}-nvidia" ;; - gaming) image_name="{{ image }}-gaming" ;; - nvidia-gaming) image_name="{{ image }}-nvidia-gaming" ;; - *) echo "unknown Utah image flavor: {{ flavor }}" >&2; exit 2 ;; - esac + image_name="$(python3 scripts/flavors.py image '{{ flavor }}')" # The kernel cache image and the layer cache below are both published # private by default, and the reusable build workflow only logs in to GHCR # for non-PR events -- so pulling either would 401 on exactly the runs that @@ -302,7 +293,7 @@ tag-images image_name default_tag alias_tags: gen-sbom base_name stream flavor syft_cmd: #!/usr/bin/env bash set -euo pipefail - image_name="$(just image_name '{{ base_name }}' '{{ stream }}' '{{ flavor }}')" + image_name="$(python3 scripts/flavors.py image '{{ flavor }}')" mkdir -p "sbom_out/$image_name" "{{ syft_cmd }}" "localhost/$image_name:{{ stream }}" -o json >"sbom_out/$image_name/sbom.json" @@ -443,7 +434,7 @@ boot-vm: secureboot base_name default_tag flavor: #!/usr/bin/env bash set -euo pipefail - image_name="$(just image_name '{{ base_name }}' '{{ default_tag }}' '{{ flavor }}')" + image_name="$(python3 scripts/flavors.py image '{{ flavor }}')" podman run --rm --entrypoint /bin/sh "localhost/$image_name:{{ default_tag }}" -c 'test -e /usr/lib/modules || test -e /boot' # Regenerate the status page's package data from the manifests. Run this after diff --git a/docs/skills/flavors.md b/docs/skills/flavors.md index 18a08188b..df9c7ed5b 100644 --- a/docs/skills/flavors.md +++ b/docs/skills/flavors.md @@ -1,7 +1,7 @@ --- name: flavors version: "1.0" -last_updated: "2026-09-05" +last_updated: "2026-09-18" id: flavors one_line_purpose: Add, remove, or retire an image flavor safely. entry_point: docs/skills/flavors.md @@ -29,6 +29,7 @@ kernel cache image is built at all. ```bash python3 scripts/flavors.py list # ["main", "nvidia", "gaming", "nvidia-gaming"] +python3 scripts/flavors.py image nvidia # utah-nvidia python3 scripts/flavors.py needs-kernel # true ``` @@ -41,16 +42,17 @@ stages, and the cache image all stay put either way. `retired` is not commentary -- it is what a flavor moves to when it is switched off (docstring, `scripts/flavors.py`). -## No workflow literals +## No workflow or Justfile literals -`just check` fails if any workflow names `utah-nvidia` or `utah-gaming` -directly (`Justfile`, `check` recipe; the guard is -`! grep -rn 'utah-nvidia\|utah-gaming' .github/workflows/`). No workflow may -carry its own copy of the flavor list -- that drift is what -`config/flavors.json` exists to stop. The literals were previously duplicated -across three workflows, so narrowing the build matrix while promote and -release still named images nothing produces failed late (recipe comment, -`Justfile`, `check`). +`just check` fails if any workflow or Justfile recipe names `utah-nvidia` or +`utah-gaming` directly (`Justfile`, `check` recipe; the guards are +`! grep -rnE 'utah-(nvidia|gaming)' .github/workflows/` and +`! grep -nE '(utah|\{\{ image \}\})-(nvidia|gaming)' Justfile`). No workflow +or recipe may carry its own copy of the flavor list or image names -- that drift +is what `config/flavors.json` and `scripts/flavors.py` exist to stop. Image +names are resolved centrally by delegating to `just image_name`, which queries +`scripts/flavors.py image `, ensuring build, promote, and release always +agree on published image names. ## The matrix is split in two, by what each flavor builds on @@ -76,6 +78,9 @@ group on that name; Utah's Justfile ignores it when naming images. building the cache is 45 minutes spent on nothing. - `images` / `releases` -- the same set shaped for the promote and release matrices (docstring, `scripts/flavors.py`). +- `image FLAVOR` -- the published image name for a flavor (e.g. `utah` or + `utah-nvidia`), queried by `just image_name` and recipes that tag or publish + images. Unknown names in `flavors` are a hard error at read time, so a typo in the config fails before any matrix is built from it. diff --git a/docs/skills/index.json b/docs/skills/index.json index 6641f793a..88593cca6 100644 --- a/docs/skills/index.json +++ b/docs/skills/index.json @@ -69,7 +69,7 @@ ], "description": "config/flavors.json is the single source for build, promote, and release matrices. Use when changing the flavor set or debugging a matrix that names an image nothing builds.", "version": "1.0", - "last_updated": "2026-09-05", + "last_updated": "2026-09-18", "doc_type": "procedure" }, { diff --git a/scripts/flavors.py b/scripts/flavors.py index e6f03d0a3..9fd1e8646 100755 --- a/scripts/flavors.py +++ b/scripts/flavors.py @@ -16,6 +16,7 @@ flavors.py needs-kernel true / false flavors.py list-main ["main"] flavors that build on the pristine base flavors.py list-kernel ["nvidia", ...] flavors that build on the kernel cache + flavors.py image FLAVOR utah / utah-nvidia published image name for flavor """ import json import sys @@ -54,5 +55,12 @@ print(json.dumps([f for f in flavors if f == "main"])) elif what == "list-kernel": print(json.dumps([f for f in flavors if f != "main"])) +elif what == "image": + if len(sys.argv) < 3: + raise SystemExit("usage: flavors.py image FLAVOR") + flavor = sys.argv[2] + if flavor not in IMAGE: + raise SystemExit(f"unknown flavor: {flavor}") + print(IMAGE[flavor]) else: raise SystemExit(f"unknown query: {what}") diff --git a/tests/test_flavors.py b/tests/test_flavors.py index c7976ab0d..b70b58577 100644 --- a/tests/test_flavors.py +++ b/tests/test_flavors.py @@ -72,6 +72,30 @@ def test_images_maps_every_flavor_to_its_image_name(self): {"image": "utah-nvidia-gaming"}, ]) + def test_image_maps_every_flavor_to_its_image_name(self): + cli = build_tree({"flavors": ALL_FLAVORS, "retired": {}}) + for flavor, expected in ( + ("main", "utah"), + ("nvidia", "utah-nvidia"), + ("gaming", "utah-gaming"), + ("nvidia-gaming", "utah-nvidia-gaming"), + ): + result = run(cli, "image", flavor) + self.assertEqual(result.returncode, 0, result.stderr) + self.assertEqual(result.stdout.strip(), expected) + + def test_image_fails_without_flavor_argument(self): + cli = build_tree({"flavors": ALL_FLAVORS, "retired": {}}) + result = run(cli, "image") + self.assertNotEqual(result.returncode, 0) + self.assertIn("usage: flavors.py image FLAVOR", result.stderr) + + def test_image_fails_for_unknown_flavor(self): + cli = build_tree({"flavors": ALL_FLAVORS, "retired": {}}) + result = run(cli, "image", "unknown-flavor") + self.assertNotEqual(result.returncode, 0) + self.assertIn("unknown flavor: unknown-flavor", result.stderr) + def test_releases_promotes_testing_to_stable_for_every_flavor(self): cli = build_tree({"flavors": ["main", "gaming"], "retired": {}}) result = run(cli, "releases") @@ -107,7 +131,7 @@ def test_list_main_is_empty_when_main_is_retired(self): def test_unknown_flavor_in_config_fails_every_query(self): cli = build_tree({"flavors": ["main", "utah-nvidia"], "retired": {}}) - for query in ("list", "images", "releases", "needs-kernel", "list-kernel"): + for query in ("list", "images", "releases", "needs-kernel", "list-kernel", "image"): result = run(cli, query) self.assertNotEqual(result.returncode, 0, f"{query} accepted it") self.assertIn("unknown flavor", result.stderr) @@ -149,7 +173,11 @@ def test_shipped_config_agrees_across_all_queries(self): run(SCRIPT, "needs-kernel").stdout.strip(), "true" if kernel else "false", ) + self.assertEqual( + [run(SCRIPT, "image", f).stdout.strip() for f in flavors], + [i["image"] for i in images], + ) if __name__ == "__main__": - unittest.main() \ No newline at end of file + unittest.main() From 16a21fbd6fa4a3c668f188aee9c61ebf314778bd Mon Sep 17 00:00:00 2001 From: "sec-check[bot]" Date: Mon, 21 Sep 2026 00:02:34 -0400 Subject: [PATCH 2/2] docs(flavors): describe the image-name call path the recipes actually take The flavors skill said image names were resolved by delegating to `just image_name`, but build-ghcr, gen-sbom, and secureboot each call `python3 scripts/flavors.py image ` directly; `image_name` is now only the entry point for callers outside the Justfile. A reader tracing image-name resolution through the doc would land on a recipe nothing calls. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/skills/flavors.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/docs/skills/flavors.md b/docs/skills/flavors.md index df9c7ed5b..4779089ef 100644 --- a/docs/skills/flavors.md +++ b/docs/skills/flavors.md @@ -49,10 +49,12 @@ commentary -- it is what a flavor moves to when it is switched off `! grep -rnE 'utah-(nvidia|gaming)' .github/workflows/` and `! grep -nE '(utah|\{\{ image \}\})-(nvidia|gaming)' Justfile`). No workflow or recipe may carry its own copy of the flavor list or image names -- that drift -is what `config/flavors.json` and `scripts/flavors.py` exist to stop. Image -names are resolved centrally by delegating to `just image_name`, which queries -`scripts/flavors.py image `, ensuring build, promote, and release always -agree on published image names. +is what `config/flavors.json` and `scripts/flavors.py` exist to stop. Recipes +that need an image name ask for it at the source -- `build-ghcr`, `gen-sbom`, +and `secureboot` each run `python3 scripts/flavors.py image ` -- so +build, promote, and release always agree on published image names. `just +image_name` is the same query wrapped for callers outside the Justfile; no +recipe goes through it. ## The matrix is split in two, by what each flavor builds on @@ -79,8 +81,8 @@ group on that name; Utah's Justfile ignores it when naming images. - `images` / `releases` -- the same set shaped for the promote and release matrices (docstring, `scripts/flavors.py`). - `image FLAVOR` -- the published image name for a flavor (e.g. `utah` or - `utah-nvidia`), queried by `just image_name` and recipes that tag or publish - images. + `utah-nvidia`), called directly by the recipes that build, tag, or publish + images, and exposed to outside callers as `just image_name`. Unknown names in `flavors` are a hard error at read time, so a typo in the config fails before any matrix is built from it.