atomic_image_builder.py

#!/usr/bin/env python3
from __future__ import annotations

import base64
import http.client
import json
import os
import re
import secrets
import shlex
import shutil
import subprocess
import sys
import tempfile
import textwrap
import urllib.error
import urllib.parse
import urllib.request
from collections.abc import Callable, Iterable, Sequence
from contextlib import ExitStack
from dataclasses import asdict, dataclass, field
from dataclasses import fields as dataclass_fields
from datetime import datetime, timedelta, timezone, tzinfo
from pathlib import Path, PurePosixPath

if sys.version_info < (3, 10):  # noqa: UP036
    raise SystemExit("Python 3.10 or newer is required.")

# This file intentionally keeps the whole beginner-focused tool in one module.
# The runtime model is:
# 1. collect choices from the user into Config
# 2. validate and normalize that Config
# 3. write a canonical state file so future updates do not need fragile parsing
# 4. render a GitHub repo from a pinned template snapshot plus generated files
# 5. let GitHub Actions build and sign the image
#
# A future refactor could split UI, GitHub operations, and rendering into
# separate modules, but the comments below aim to make the current layout easier
# to understand for anyone reading it now.
VERSION = "0.12.0"
TOOL_NAME = "Atomic Image Builder"
TOOL_SLUG = "atomic-image-builder"
# The command users type. Deliberately separate from TOOL_SLUG: that one names
# the product and, through STATE_FILE, is written into every managed repo, so
# renaming it would orphan every repo this tool has ever created. This one only
# has to match whatever the installers put on PATH.
#
# Not plain "aib" -- contrib/aib already installs a host wrapper by that name to
# ~/.local/bin, which on a normal PATH sits ahead of Homebrew's bin. Sharing the
# name would mean whichever came first silently won, with no way for a user to
# tell which one they were running.
TOOL_COMMAND = "aib-tool"
STATE_FILE = f".{TOOL_SLUG}.json"
# `gh repo list --limit N` is a cap, not a page size: gh pages on its own
# until it has N repos. At 100 an account with more repos than that lost every
# managed repo past the 100 most recent, and the picker then said none
# existed. This means "every repo" for any real account while still bounding
# a pathological one.
REPO_LIST_LIMIT = 10000
# Repos checked per GraphQL query in batch_check_state_files. One alias per
# repo; a few thousand in a single query would run into GitHub's query limits.
STATE_FILE_QUERY_BATCH = 100
DEFAULT_REPO_NAME = "my-atomic-image"
# Said the same way wherever a name is refused, because the wizard's field
# error and validate_config()'s final gate are the same rule.
REPO_NAME_RULE = (
    "It must start and end with a letter or number, cannot end with .git, and can join "
    "parts only with a single dot, one or two underscores, or dashes."
)
DEFAULT_GITHUB_BUILD_CRON = "05 10 * * *"
FEDORA_ATOMIC_FALLBACK_TAG = "44"
# Pinned by digest rather than by the tag it is published under. Every other
# third-party input this tool writes into a stranger's repository is pinned --
# actions through ACTION_PINS, downloads by sha256 -- and the payload below is
# the one that was not, even though it is the only one whose whole file tree is
# copied into `/` of an image the generated workflow then signs. A tag that
# moves upstream changes what a signed image contains without changing a byte
# of the repository that built it, and nothing in a generated repo records
# which payload went in, so the change leaves no trace to find afterwards.
#
# Refreshing this is a deliberate step, not a rubber stamp: the digest names
# the exact payload tests/test_brew_login_fragments.py and
# tests/test_brew_setup_staging.py reproduce, and a new one can ship files
# neither of them knows about. maintenance_audit.py --check-action-updates
# reports weekly when the tag stops resolving here, so the pin going stale is
# visible rather than silent.
UNIVERSAL_BLUE_BREW_IMAGE_REPO = "ghcr.io/ublue-os/brew"
UNIVERSAL_BLUE_BREW_IMAGE_TAG = "latest"
UNIVERSAL_BLUE_BREW_IMAGE_DIGEST = "sha256:60ada2d65891d8797beef49d8b43f2108519cbbaf04c9c7363e1a008677fcd35"
UNIVERSAL_BLUE_BREW_IMAGE = f"{UNIVERSAL_BLUE_BREW_IMAGE_REPO}@{UNIVERSAL_BLUE_BREW_IMAGE_DIGEST}"
# The other third-party image the tool ships to strangers, pinned for the
# same reason. The bundled disk workflow names bootc-image-builder by its
# :latest tag in `BIB_IMAGE`, and image-template.env names it again for the
# Justfile's local `just build-qcow2`; the action that runs it is pinned by
# SHA through ACTION_REF_PINS, the image it runs to produce the user's qcow2
# and installer ISO was not. It is the one builder that touches every disk
# artifact a generated repository publishes.
#
# What this pin costs is compatibility rather than freshness: the builder has
# to keep up with the bootc in whichever base image the user chose, and a
# pin holds it still while the base images move. That is why the weekly
# advisory below exists -- a re-pin is a check that the new builder still
# handles the base images the wizard offers, not a digest to copy across.
BOOTC_IMAGE_BUILDER_IMAGE_REPO = "quay.io/centos-bootc/bootc-image-builder"
BOOTC_IMAGE_BUILDER_IMAGE_TAG = "latest"
BOOTC_IMAGE_BUILDER_IMAGE_DIGEST = "sha256:2b52843ea2bfda73b0a08d97e76b734393b1d3a804681b9fabb26723bd3a2f0b"
BOOTC_IMAGE_BUILDER_IMAGE = f"{BOOTC_IMAGE_BUILDER_IMAGE_REPO}@{BOOTC_IMAGE_BUILDER_IMAGE_DIGEST}"
# The brew payload's /system_files carries three login-shell fragments
# alongside the units and the tarball, and none of them is guarded:
#
#   /etc/profile.d/brew.sh                         evals `brew shellenv`
#   /etc/profile.d/brew-bash-completion.sh         runs `brew completions link`,
#                                                  then sources every file in the
#                                                  prefix's etc/bash_completion.d
#   /usr/share/fish/vendor_conf.d/ublue-brew.fish  the fish equivalent
#
# All three execute code out of /home/linuxbrew/.linuxbrew, and
# brew-setup.service -- which the block presets -- ends with
# `chown -R 1000:1000 /home/linuxbrew`. /etc/profile.d and the fish vendor
# directory are read by every login shell, the root account's included (`su -`,
# `sudo -i`, a console or SSH root login), so on a booted machine each fragment
# is UID 1000 choosing what root executes, with no password and no sudo record.
#
# This tool only offers Homebrew for a Fedora Atomic or CentOS base
# (offer_brew_if_applicable forces it off for Universal Blue, which ships its
# own), so the block is what puts the fragments in the image at all.
BREW_LOGIN_FRAGMENTS = (
    "/etc/profile.d/brew.sh",
    "/etc/profile.d/brew-bash-completion.sh",
    "/usr/share/fish/vendor_conf.d/ublue-brew.fish",
)
# The replacement. It puts the prefix on PATH for the account that owns it and
# executes nothing out of it, so `brew` still works for that user.
BREW_PATH_FRAGMENT = "/etc/profile.d/brew-path.sh"
# Everything a login shell reads on its way in. The sweep is the load-bearing
# half of the fix: the payload is an image this tool does not build, pulled by a
# mutable tag, so deleting three names fixes today's digest and says nothing
# about the next one. Only a check of what actually landed can see a fourth.
BREW_LOGIN_SHELL_DIRS = (
    "/etc/profile.d",
    "/etc/fish/conf.d",
    "/usr/share/fish/vendor_conf.d",
)
# The other half of what the payload does on a booted machine. brew-setup.service
# stages a 154 MB tarball through one fixed path, as root, with no `PrivateTmp=`:
#
#   ExecStart=/usr/bin/mkdir -p /tmp/homebrew
#   ExecStart=/usr/bin/tar --zstd -xf /usr/share/homebrew.tar.zst -C /tmp/homebrew
#   ExecStart=/usr/bin/cp -R -n /tmp/homebrew/home/linuxbrew/.linuxbrew /home/linuxbrew
#   ExecStart=/usr/bin/chown -R 1000:1000 /home/linuxbrew
#
# /tmp on a booted system is a world-writable tmpfs, and `mkdir -p` exits 0 on an
# existing symlink instead of replacing it -- so an account that claims
# /tmp/homebrew first has root extract through its symlink, has whatever it left
# there copied into /home/linuxbrew, and has it handed to UID 1000 by the chown.
# The `-n` protects nothing on the run that matters: the unit's own
# `ConditionPathExists=!/home/linuxbrew/.linuxbrew` guarantees the destination
# does not exist yet. The `--mount=type=tmpfs,dst=/tmp` on the preset RUN is a
# build-time mount and has no bearing on any of this.
BREW_SETUP_UNIT = "/usr/lib/systemd/system/brew-setup.service"
BREW_SETUP_DROPIN = "/usr/lib/systemd/system/brew-setup.service.d/10-private-tmp.conf"
MAX_UI_WIDTH = 120
# Every colour here is a 256-palette index chosen to stay legible on BOTH a
# light and a dark terminal. The originals were picked on a dark background and
# were near-invisible on a light one -- 252 is almost white, and 117 is a pale
# blue that gum was also given for `choose --selected.foreground`, so on a light
# terminal an all-selected list rendered as an empty screen.
#
# The rule for anything added here: mid-range indices only. Nothing above ~230
# (washes out on white) and nothing below ~20 (disappears on black).
ACCENT_COLOR = 33      # blue, for headers, cursors and selections
MUTED_COLOR = 244      # grey, for secondary text and placeholders
SUCCESS_COLOR = 28     # green, for the "created" panel
WARNING_COLOR = 178    # gold, for the attention panel
NOTICE_COLOR = 214     # orange, already legible on both
CONTROLS_COLOR = SUCCESS_COLOR
PACKAGE_SEARCH_LIMIT = 40
MANAGED_REPO_WARNING = "If you hand-edit a repo after this tool creates or manages it, stop using this tool for that repo."
MANAGED_REPO_HINT_CONTAINERFILE = (
    f"Future updates use {STATE_FILE} as the source of truth and rewrite managed files such as README.md and build_files/build.sh."
)
MANAGED_REPO_HINT_BLUEBUILD = (
    f"Future updates use {STATE_FILE} as the source of truth and rewrite managed files such as README.md and recipes/recipe.yml."
)
# Lead-in to the reset-then-switch instructions in the README, the creation
# panel and the build-status screen. It must hold whether the scan carried
# packages into the image or only found customizations the user agreed to
# leave behind: the build-status screen reads the single state-file flag and
# cannot tell the two apart, and an update regenerates the README from that
# same flag. So it says where the repo came from, not what the image carries.
SCAN_SWITCH_LEAD_IN = "This repo was created from a scan of your current system's rpm-ostree customizations."
CONTAINERFILE_TEMPLATE_REPO = "ublue-os/image-template"
BLUEBUILD_TEMPLATE_REPO = "blue-build/template"
TEMPLATE_SNAPSHOT_DIR = Path(__file__).resolve().parent / "template_snapshots"
CONTAINERFILE_TEMPLATE_DIR = TEMPLATE_SNAPSHOT_DIR / "containerfile"
BLUEBUILD_TEMPLATE_DIR = TEMPLATE_SNAPSHOT_DIR / "bluebuild"
ALLOWED_METHODS = {"containerfile", "bluebuild"}
METHOD_DISPLAY = {"containerfile": "Containerfile", "bluebuild": "BlueBuild"}
BLUEBUILD_RECIPE_SCHEMA = "https://schema.blue-build.org/recipe-v1.json"
# These regexes are our low-cost safety rails. They do not prove a package or
# service is real, but they do stop obviously unsafe values from becoming shell
# script content later.
#
# The first character must be alphanumeric: a token such as "--version" or
# "-y" is never a package name, and dnf5 reads it as an option wherever the
# list lands -- the repoquery lookup (which then prints its version and
# reports every real name in the batch as missing) and the generated
# `dnf5 install -y` line. The regex is the only guard, because dnf5 has no
# "--" end-of-options separator: 5.4.2.1 rejects it on repoquery, install and
# remove with 'Unknown argument "--"', so emitting one would break every
# lookup and every build.sh instead of hardening them.
PACKAGE_TOKEN_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._+:-]*$")
# What `dnf5 copr enable` takes: the owner is a username or a @groupname
# (@caddy/caddy), and the project may be a project directory with colons
# (owner/project:custom:123). The "@" is allowed only as the first character
# and the colons only after the slash, so this stays a repo spec and not a
# shell or YAML surprise -- shell_quote and yaml_scalar quote it downstream
# regardless. As with packages, the owner cannot start with "-": "-x/y" lands
# on `dnf5 copr enable` as an option ("-x" is --exclude), and dnf5 has no "--"
# to put in front of it.
COPR_REPO_RE = re.compile(r"^@?[A-Za-z0-9._][A-Za-z0-9._-]*/[A-Za-z0-9._:-]+$")
# A unit name cannot start with "-" either. "--now" otherwise passes as a
# service and becomes a bare `systemctl enable --now` line in build.sh, which
# fails under `set -e` on every build, and the BlueBuild systemd module passes
# the same token to its own systemctl call, where no "--" can be added.
SERVICE_TOKEN_RE = re.compile(r"^[A-Za-z0-9@._:+][A-Za-z0-9@._:+-]*$")
# The repo name becomes the image name in ghcr.io/<owner>/<repo>, so it has to
# satisfy the container-reference grammar as well as GitHub's naming rules.
# This is distribution/reference's path-component production: alphanumeric runs
# joined by a single dot, one or two underscores, or a run of hyphens. Names
# GitHub accepts but that grammar does not -- "a..b", "a.-b", "a___b" -- parse
# as an invalid reference, so the wizard would create a repo and signing key
# for an image that nothing can push or pull.
OCI_PATH_COMPONENT_RE = re.compile(r"[a-z0-9]+(?:(?:[._]|__|-+)[a-z0-9]+)*")
# A "./"-prefixed entry in a workflow path filter. The prefix is repeated in
# the pattern rather than matched once so "././x" normalises in a single pass.
RELATIVE_PATH_FILTER_RE = re.compile(r"^(\s*-\s+)(['\"]?)(?:\./)+(.*)$")
# Matched on the action name rather than a pinned SHA, so the step is still
# found after a pin refresh moves the SHA out from under this patcher.
UPLOAD_ARTIFACT_ACTION = "actions/upload-artifact@"
DISK_ARTIFACT_NAME = "${{ env.IMAGE_NAME }}-${{ matrix.disk-type }}"
# The disk workflow's runner ternary. The amd64 label is captured rather than
# written out, so a snapshot refresh that bumps the runner image is followed
# automatically instead of being pinned to whatever was current when this was
# written.
DISK_RUNNER_CHOICE_RE = re.compile(
    r"^(\s*runs-on:\s*)\$\{\{\s*inputs\.platform\s*==\s*'amd64'\s*&&\s*'([^']+)'\s*\|\|\s*'[^']+'\s*\}\}\s*$"
)
# The two conditions upstream ships on the platform input. The first gates a
# step that only ever ran on ARM, so it goes with ARM; the second is now
# always true, so only the condition goes.
DISK_ARM_ONLY_IF = "if: inputs.platform == 'arm64'"
DISK_NON_ARM_IF = "if: inputs.platform != 'arm64'"
# `BIB_IMAGE` as the bundled template spells it, in the workflow's env block
# (`key: "value"`) and in image-template.env (`key="value"`). The reference is
# matched on its repository and any tag or digest, so a repository written
# before the pin, or on an earlier one, is re-pinned on its next update. A
# different repository is the user's own choice of builder and passes through
# untouched, the way every patcher here no-ops on text it does not recognise.
DISK_BUILDER_IMAGE_RE = re.compile(
    r"^(?P<prefix>\s*BIB_IMAGE[=:]\s*)(?P<quote>['\"]?)"
    + re.escape(BOOTC_IMAGE_BUILDER_IMAGE_REPO)
    + r"(?:[:@][^'\"\s#]*)?(?P=quote)(?P<suffix>\s*(?:#.*)?)$"
)
# The bundled Justfile's spawn-vm rebuild dispatch, and what it should say.
# "the ISO" in upstream's message is wrong for every type but one, so it goes
# with the arguments.
SPAWN_VM_REBUILD_LINE = (
    '    [ "{{ rebuild }}" -eq 1 ] && echo "Rebuilding the ISO" && just build-vm {{ rebuild }} {{ type }}'
)
SPAWN_VM_REBUILD_FIXED = (
    '    [ "{{ rebuild }}" -eq 1 ] && echo "Rebuilding the {{ type }} image" && just rebuild-{{ type }}'
)
FROM_LINE_RE = re.compile(r"^(\s*FROM(?:\s+--platform=\S+)?\s+)(\S+)(.*)$", flags=re.IGNORECASE)
FROM_STAGE_NAME_RE = re.compile(r"^\s+AS\s+(\S+)", flags=re.IGNORECASE)
# BuildKit (frontend/dockerfile/parser) reads heredocs only from RUN, COPY and
# ADD, and only from a whole shell word -- split with quotes kept -- shaped
# <<[-]WORD. So "<<EOF" in quotes, cat<<EOF and a <<< here-string open none.
CONTAINERFILE_HEREDOC_INSTRUCTION_RE = re.compile(r"^\s*(?:ONBUILD\s+)?(?:RUN|COPY|ADD)\s", flags=re.IGNORECASE)
CONTAINERFILE_HEREDOC_WORD_RE = re.compile(r"^\d*<<(-?)\s*([^<]*)$")
# A parser directive (escape, syntax, check) is honoured only in the run of
# "# key=value" lines at the very top of the file; any other line -- a blank
# one, another comment or an instruction -- ends that run for good.
CONTAINERFILE_DIRECTIVE_RE = re.compile(r"^#\s*([a-zA-Z][a-zA-Z0-9]*)\s*=\s*(.+?)\s*$")
CONTAINERFILE_DIRECTIVE_NAMES = frozenset({"escape", "syntax", "check"})
# BuildKit's line-continuation test for each allowed escape character: the
# character, not itself escaped, then only spaces and tabs to the end.
CONTAINERFILE_CONTINUATION_RE = {
    escape: re.compile(rf"(?:(?<=[^{re.escape(escape)}])|^){re.escape(escape)}[ \t]*$") for escape in ("\\", "`")
}
INSTALLER_SWITCH_RE = re.compile(r"^(\s*bootc switch --mutate-in-place --transport registry )(\S+)(.*)$")
INSTALLER_UNVERIFIED_SWITCH_COMMENT = (
    "# Signature enforcement is deliberately omitted for this installer switch:",
    "# the standalone installer has no trusted copy of this repo's cosign.pub",
    "# before its first pull. After installation, follow README's Trusting The",
    "# Signing Key section and repeat the enforced switch so later upgrades verify it.",
)
# dnf5 prints this when -C (cache-only) is used and no repository metadata has
# been downloaded yet. Matched so package search and the exact-name check can
# offer to fix it in place instead of naming a command the user may have no
# shell to run. It and DNF5_MISSING_MARKERS are dnf5's English messages, which
# is why dnf5_command() pins the locale for every dnf5 run the tool makes.
DNF5_NO_CACHE_MARKER = "cache-only enabled but no cache"
PACKAGE_SEARCH_NEEDS_METADATA = (
    "Package search needs local DNF metadata. "
    "Exact-name entry still works without it, but names are then only checked by the GitHub build."
)
DNF5_MISSING_MARKERS = (
    "no matches found",
    "no package matched",
    "no packages to list",
    "matched no packages",
    "no matching packages",
)
# Every spelling of a package that `dnf5 install` and `rpm -q` accept as a
# NEVRA spec: libdnf5's NAME, NA, NEV, NEVR and NEVRA forms, each with and
# without the epoch (dnf5 prints %{epoch} as 0 when the package has none,
# and an explicit 0: still matches it). A positional repoquery matches a spec
# ignoring case where install and rpm -q do not, so the exact-name check asks
# dnf5 to print these for whatever it matched and requires the spec to be one
# of them verbatim -- see _resolve_package_spec.
DNF5_SPEC_SPELLINGS = (
    "%{name}",
    "%{name}.%{arch}",
    "%{name}-%{version}",
    "%{name}-%{version}-%{release}",
    "%{name}-%{version}-%{release}.%{arch}",
    "%{name}-%{epoch}:%{version}",
    "%{name}-%{epoch}:%{version}-%{release}",
    "%{name}-%{epoch}:%{version}-%{release}.%{arch}",
)
# What `rpm -q` prints, on stdout, for each spec it was asked about that is
# not installed. The spec comes back verbatim, so it is the key the removal
# lookup matches against -- see lookup_installed_host_packages for why the
# printed %{name} cannot be.
RPM_NOT_INSTALLED_RE = re.compile(r"^package (.+) is not installed$")
# GitHub Actions should be pinned to immutable SHAs instead of floating tags.
# The human-readable tag is kept as a comment so maintainers can still tell what
# upstream version the pin came from.
ACTION_PINS: dict[str, tuple[str, str]] = {
    "actions/checkout": ("3d3c42e5aac5ba805825da76410c181273ba90b1", "v7"),
    "actions/setup-python": ("5fda3b95a4ea91299a34e894583c3862153e4b97", "v7"),
    "ublue-os/remove-unwanted-software": ("695eb75bc387dbcd9685a8e72d23439d8686cba6", "master"),
    "docker/metadata-action": ("dc802804100637a589fabce1cb79ff13a1411302", "v6.2.0"),
    "redhat-actions/buildah-build": ("719e3c40d8af9790c23eca13f7daa339f2867034", "v3.1.0"),
    "docker/login-action": ("dbcb813823bdd20940b903addbd779551569679f", "v4.6.0"),
    "redhat-actions/push-to-registry": ("94ade333c38ecc0e60e94785125d9a52ca423b37", "v3.0.0"),
    "sigstore/cosign-installer": ("6f9f17788090df1f26f669e9d70d6ae9567deba6", "v4.1.2"),
    "actions/upload-artifact": ("043fb46d1a93c77aae656e7c1c64a875d1fc6a0a", "v7.0.1"),
    "blue-build/github-action": ("c295af864f2802fc6aea227507af43d35823db81", "v1.13"),
    "extractions/setup-just": ("53165ef7e734c5c07cb06b3c8e7b647c5aa16db3", "v4.0.0"),
}
ACTION_REF_PINS: dict[str, tuple[str, str]] = {
    "ublue-os/remove-unwanted-software@v8": ("695eb75bc387dbcd9685a8e72d23439d8686cba6", "v8"),
    "ublue-os/remove-unwanted-software@695eb75bc387dbcd9685a8e72d23439d8686cba6": ("695eb75bc387dbcd9685a8e72d23439d8686cba6", "v8"),
    "ublue-os/remove-unwanted-software@v9": ACTION_PINS["ublue-os/remove-unwanted-software"],
    "ublue-os/remove-unwanted-software@cc0becac701cf642c8f0a6613bbdaf5dc36b259e": ACTION_PINS["ublue-os/remove-unwanted-software"],
    "osbuild/bootc-image-builder-action@main": ("56d652d0afb02eb3e4b8fd35e7ca0391dbebab2a", "main"),
    "osbuild/bootc-image-builder-action@5fc2ef0c4689b43ba959a10e3dfed3a889810ba1": ("56d652d0afb02eb3e4b8fd35e7ca0391dbebab2a", "main"),
    "osbuild/bootc-image-builder-action@8661cd3832544ad68c12dcde8681b13ab0f56a8d": ("56d652d0afb02eb3e4b8fd35e7ca0391dbebab2a", "main"),
    "osbuild/bootc-image-builder-action@56d652d0afb02eb3e4b8fd35e7ca0391dbebab2a": ("56d652d0afb02eb3e4b8fd35e7ca0391dbebab2a", "main"),
    "actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f": ACTION_PINS["actions/upload-artifact"],
    "blue-build/github-action@836161eb076426a451e6a0054f722b1153b8b3ad": ACTION_PINS["blue-build/github-action"],
    "sigstore/cosign-installer@v4.0.0": ("faadad0cce49287aee09b3a48701e75088a2c6ad", "v4.0.0"),
    "sigstore/cosign-installer@faadad0cce49287aee09b3a48701e75088a2c6ad": ("faadad0cce49287aee09b3a48701e75088a2c6ad", "v4.0.0"),
}
# The BlueBuild CLI a local test build renders `recipes/recipe.yml` with. It
# is fetched the way both blue-build/github-action and BlueBuild's own
# install.sh fetch it: create a container from the installer image and copy
# `/out/bluebuild` out of it. The tag is the floating one the pinned action
# above installs by default (`CLI_VERSION_TAG` in its "Determine Vars" step);
# the digest is what podman is given. The binary runs on the host, as the
# user, with the user's files and credentials in reach, so like the other two
# third-party images above it is pinned to the bytes that were reviewed rather
# than to a tag anyone with push access to the repository can repoint.
#
# The cost is the one every pin has, and here it is parity: CI pulls the tag
# and moves when it moves, while this stays until re-pinned, so a local build
# can render with a CLI a step behind CI's. maintenance_audit.py's weekly run
# reports when the tag no longer resolves to this digest
# (audit_bluebuild_cli_image_pin); re-pin after a local build against the
# wizard's recipe still renders, and re-read the action's default tag whenever
# the action pin changes.
BLUEBUILD_CLI_INSTALLER_IMAGE_REPO = "ghcr.io/blue-build/cli"
BLUEBUILD_CLI_INSTALLER_IMAGE_TAG = "v0.9-installer"
BLUEBUILD_CLI_INSTALLER_IMAGE_DIGEST = "sha256:1a53a3a145068a38d1c20b00a6047dd2c5e8848f7cd6b6c89d49c793ebd76fd6"
BLUEBUILD_CLI_INSTALLER_IMAGE = f"{BLUEBUILD_CLI_INSTALLER_IMAGE_REPO}@{BLUEBUILD_CLI_INSTALLER_IMAGE_DIGEST}"
# Written into the local build context when no real key exists yet. The
# recipe's signing module only copies `cosign.pub` into /etc/pki/containers
# and names it in policy.json; nothing at build time parses it. A repo the
# tool created has a real key, and the update path uses that one.
LOCAL_BUILD_PLACEHOLDER_COSIGN_PUB = (
    "-----BEGIN PLACEHOLDER-----\n"
    f"Written by {TOOL_NAME} for a local test build only.\n"
    "The real cosign.pub is generated when the repository is created.\n"
    "-----END PLACEHOLDER-----\n"
)
# The rechunk step's Justfile invocation, matched so Chunkah can be swapped in
# for rpm-ostree. Upstream has shipped two spellings: the pre-rootless
# `sudo -E $(command -v just) ostree-rechunk` and, since ublue-os/image-template
# b9783f6, a bare `just ostree-rechunk`. Existing managed repositories still
# carry the older one, so both must keep matching -- a single-shape matcher
# would rename the step to Chunkah while leaving it running rpm-ostree.
# Step names whose body the rechunk recipe swap may rewrite. Upstream ships the
# first; the second is what we rename it to, kept in scope so a half-switched
# workflow is repaired rather than left alone.
RECHUNK_STEP_NAMES: frozenset[str] = frozenset(
    {"- name: Rechunk with rpm-ostree", "- name: Rechunk with Chunkah"}
)
RECHUNK_RECIPE_RE = re.compile(r"(?<![\w./-])(just\)?)(\s+)ostree-rechunk\b")
# Upstream's trailing "if you are feeling adventurous" comment block, in both
# spellings, stripped once the active step above it is running Chunkah. Matched
# on upstream's exact literal text, same no-op-on-drift convention as every
# other patcher in this file.
STALE_CHUNKAH_COMMENT_BLOCKS: tuple[str, ...] = tuple(
    (
        "      # If you are feeling adventurous, use the new distro agnostic rechunker\n"
        "      # https://github.com/coreos/chunkah\n"
        "      # You can delete the Rechunk with rpm-ostree portion then if you use this\n"
        "      #- name: Rechunk with Chunkah\n"
        "      #  id: rechunk\n"
        "      #  run: |\n"
        f"      #    {invocation} rechunk \\\n"
        "      #      ${IMAGE_NAME} \\\n"
        "      #      ${DEFAULT_TAG}\n"
        "\n"
    )
    for invocation in ("just", "sudo -E $(command -v just)")
)
# "Is the user logged in to GitHub" asks about the active github.com account
# only. Bare `gh auth status` checks every account on every configured host and
# exits 1 if any one fails, so a stale GHES login or an old inactive github.com
# account made a working login look missing and sent the user into the login
# guide on every launch (#513). contrib/aib and container/entrypoint.sh use the
# same probe. --active needs gh 2.40 or later.
GH_AUTH_PROBE = ("gh", "auth", "status", "--hostname", "github.com", "--active")
PRECHECK_REQUIRED_TOOLS: tuple[str, ...] = ("gum", "git", "gh", "cosign")
BREW_INSTALLABLE_TOOLS: tuple[str, ...] = ("gum", "git", "gh", "cosign")
HOST_REQUIRED_TOOLS: tuple[str, ...] = ("dnf5", "rpm-ostree")


@dataclass(frozen=True)
class BaseImage:
    # This is the small curated image list shown to beginners. Keeping it as a
    # dataclass instead of plain dicts gives the rest of the code typed fields
    # and avoids magic string lookups.
    key: str
    provider: str
    name: str
    description: str
    image_uri: str
    # Whether the base runs a first-boot account wizard (gnome-initial-setup,
    # or Fedora's desktop-neutral initial-setup) after Anaconda finishes.
    # installer_profile() reads this to pick the ISO config: upstream's
    # iso-gnome.toml disables Anaconda's Users module on the assumption that
    # the wizard creates the account, so a base without one installs a system
    # nobody can log in to (#361). No default on purpose -- a new entry has to
    # say which it is, because the wrong guess is invisible until first boot.
    first_boot_setup: bool
    # Other repositories the same desktop is published at, without a tag.
    # match_base_image() treats a host booted from one of these as this
    # curated image; image_uri stays the one the tool recommends and writes.
    aliases: tuple[str, ...] = ()


def read_os_release_fields(path: Path = Path("/etc/os-release")) -> dict[str, str]:
    try:
        text = path.read_text()
    except OSError:
        return {}
    fields: dict[str, str] = {}
    for raw_line in text.splitlines():
        line = raw_line.strip()
        if not line or line.startswith("#") or "=" not in line:
            continue
        key, value = line.split("=", 1)
        value = value.strip()
        if len(value) >= 2 and value[0] == value[-1] and value[0] in {'"', "'"}:
            value = value[1:-1]
        fields[key] = value
    return fields


def determine_fedora_atomic_default_tag(
    *,
    fallback: str = FEDORA_ATOMIC_FALLBACK_TAG,
    os_release_path: Path = Path("/etc/os-release"),
) -> str:
    data = read_os_release_fields(os_release_path)
    if data.get("ID") != "fedora":
        return fallback
    version_id = data.get("VERSION_ID", "")
    if not version_id.isdigit():
        return fallback
    # Track a host that is ahead of the pinned fallback, but only by one
    # release. quay.io/fedora-ostree-desktops publishes a tag per Fedora
    # release, and a pre-release host (Rawhide, or Branched well before GA)
    # reports a VERSION_ID whose tag does not exist yet. Taking an unbounded
    # max meant such a host produced curated URIs like
    # ".../silverblue:47", the repo was created and pushed successfully, and
    # the GitHub build then failed on FROM with a manifest-unknown error the
    # user has no way to diagnose. Nothing here can verify the tag resolves
    # without a network call, so bound it instead: one release ahead covers a
    # host that upgraded before this constant was bumped.
    return str(min(int(fallback) + 1, max(int(fallback), int(version_id))))


FEDORA_ATOMIC_DEFAULT_TAG = determine_fedora_atomic_default_tag()


def universal_blue_image(key: str, name: str, description: str, image_uri: str, *, first_boot_setup: bool) -> BaseImage:
    return BaseImage(key=key, provider="Universal Blue", name=name, description=description, image_uri=image_uri, first_boot_setup=first_boot_setup)


def fedora_atomic_image(key: str, name: str, description: str, variant: str, *, first_boot_setup: bool, official_alias: bool = True) -> BaseImage:
    # Fedora publishes each desktop twice: the long-standing
    # quay.io/fedora-ostree-desktops/<variant>, and the newer official bootc
    # location quay.io/fedora/fedora-<variant>. Both carry the same release
    # tags, and which one a host was rebased to is not the user's choice of
    # base -- it is the same Silverblue either way. Without the alias a host
    # on the official location was refused as a custom image (#354).
    aliases = (f"quay.io/fedora/fedora-{variant}",) if official_alias else ()
    return BaseImage(
        key=key,
        provider="Fedora Atomic",
        name=name,
        description=description,
        image_uri=f"quay.io/fedora-ostree-desktops/{variant}:{FEDORA_ATOMIC_DEFAULT_TAG}",
        first_boot_setup=first_boot_setup,
        aliases=aliases,
    )


# first_boot_setup follows the desktop, not the provider: GNOME bases ship
# gnome-initial-setup, and Fedora's Budgie and COSMIC variants ship the
# desktop-neutral initial-setup. KDE bases have no wizard, and neither does
# Sway Atomic -- it boots straight to sddm (checked against
# quay.io/fedora-ostree-desktops/sway-atomic:44 on 2026-09-20; #361).
BASE_IMAGES: tuple[BaseImage, ...] = (
    universal_blue_image("bazzite", "Bazzite (KDE)", "KDE desktop for gaming systems and handheld-style setups", "ghcr.io/ublue-os/bazzite:stable", first_boot_setup=False),
    universal_blue_image("bazzite-gnome", "Bazzite (GNOME)", "GNOME desktop for gaming systems and handheld-style setups", "ghcr.io/ublue-os/bazzite-gnome:stable", first_boot_setup=True),
    universal_blue_image("bazzite-dx", "Bazzite DX (KDE)", "Bazzite plus extra developer tools on KDE", "ghcr.io/ublue-os/bazzite-dx:stable", first_boot_setup=False),
    universal_blue_image("bazzite-dx-gnome", "Bazzite DX (GNOME)", "Bazzite plus extra developer tools on GNOME", "ghcr.io/ublue-os/bazzite-dx-gnome:stable", first_boot_setup=True),
    universal_blue_image("aurora", "Aurora (KDE)", "KDE desktop for everyday use", "ghcr.io/ublue-os/aurora:stable", first_boot_setup=False),
    universal_blue_image("aurora-dx", "Aurora DX", "Aurora plus extra developer tools", "ghcr.io/ublue-os/aurora-dx:stable", first_boot_setup=False),
    universal_blue_image("bluefin", "Bluefin (GNOME)", "GNOME desktop for everyday use", "ghcr.io/ublue-os/bluefin:stable", first_boot_setup=True),
    universal_blue_image("bluefin-dx", "Bluefin DX", "Bluefin plus extra developer tools", "ghcr.io/ublue-os/bluefin-dx:stable", first_boot_setup=True),
    fedora_atomic_image("silverblue", "Fedora Silverblue", "GNOME desktop built from the official Fedora Atomic desktop image", "silverblue", first_boot_setup=True),
    fedora_atomic_image("kinoite", "Fedora Kinoite", "KDE Plasma desktop built from the official Fedora Atomic desktop image", "kinoite", first_boot_setup=False),
    fedora_atomic_image("sway-atomic", "Fedora Sway Atomic", "Sway desktop built from the official Fedora Atomic desktop image", "sway-atomic", first_boot_setup=False),
    fedora_atomic_image("budgie-atomic", "Fedora Budgie Atomic", "Budgie desktop built from the official Fedora Atomic desktop image", "budgie-atomic", first_boot_setup=True),
    # quay.io/fedora/fedora-cosmic-atomic does not exist (checked against the
    # registry API on 2026-09-20; the other four variants do), so claiming
    # the alias here would match a reference no host can be booted from.
    fedora_atomic_image("cosmic-atomic", "Fedora COSMIC Atomic", "COSMIC desktop built from the official Fedora Atomic desktop image", "cosmic-atomic", first_boot_setup=True, official_alias=False),
)


def supported_base_image_names() -> str:
    return ", ".join(image.name for image in BASE_IMAGES)


def supported_base_image_lines() -> list[str]:
    # Grouped by provider so the main menu can say what this tool supports
    # without printing thirteen names on one line.
    grouped: dict[str, list[str]] = {}
    for image in BASE_IMAGES:
        grouped.setdefault(image.provider, []).append(image.name)
    return [f"{provider}: {', '.join(names)}" for provider, names in grouped.items()]


# scan_os() has three outcomes, and the caller has to tell them apart: a scan
# that could not run at all falls back to picking a base by hand, while a user
# who backed out should simply return to the menu.
SCAN_OK = "ok"
SCAN_UNAVAILABLE = "unavailable"
SCAN_CANCELLED = "cancelled"
# The running image is not one of the curated bases. Distinct from
# SCAN_UNAVAILABLE: the scan worked perfectly, and what it found is the problem.
SCAN_UNSUPPORTED_BASE = "unsupported-base"
# The host runs on an architecture the generated workflow publishes no image
# for. Also a scan that worked: no base chosen by hand would change the
# answer, so the caller stops rather than offering one.
SCAN_UNPUBLISHED_ARCHITECTURE = "unpublished-architecture"

# rpm-ostree records customizations in more fields than this tool reads.
# `requested-packages` and `requested-base-removals` are the two it can carry,
# because both are names an image build can install or remove from a
# repository -- except a `requested-packages` entry typed as a capability or
# file path, which scan_os reports alongside these. The rest are real
# customizations pinned to files on this host --
# an RPM built somewhere else, a package replaced by a local build -- and no
# generated image reproduces them. They were read as absent rather than as
# unsupported, so a scan reported success and recommended `rpm-ostree reset`
# while the new image silently omitted them. See the rpm-ostree administrator
# handbook's "rpm-ostree status --json" section for the field list. The first
# three are string arrays; the remote one is a list of (from, packages) pairs
# and needs remote_replacement_list() rather than string_list().
UNSUPPORTED_SCAN_FIELDS: tuple[tuple[str, str], ...] = (
    ("requested-local-packages", "Locally installed RPMs"),
    ("requested-local-fileoverride-packages", "Local file overrides"),
    ("requested-base-local-replacements", "Base packages replaced by a local RPM"),
    ("requested-base-remote-replacements", "Base packages replaced from a repository"),
)
# Not a package list, so it is reported separately -- but it belongs with them,
# because a bare `rpm-ostree reset` removes initramfs customization too.
INITRAMFS_SCAN_FIELDS: tuple[tuple[str, str], ...] = (
    ("initramfs-etc", "Files kept in the initramfs from /etc"),
    ("initramfs-args", "Custom initramfs arguments"),
)

COMMON_SERVICES: tuple[tuple[str, str], ...] = (
    ("SSH remote access", "sshd.service"),
    ("Tailscale VPN", "tailscaled.service"),
    ("Cockpit web admin", "cockpit.socket"),
)


@dataclass
class Config:
    # Config is the single source of truth for what the user wants to build.
    # Most of the app mutates this object in memory, then state_payload()
    # serializes it to STATE_FILE before repo files are written.
    method: str = ""
    base_image_uri: str = ""
    base_image_name: str = ""
    repo_name: str = ""
    image_desc: str = "My custom bootc image"
    packages: list[str] = field(default_factory=list)
    copr_repos: list[str] = field(default_factory=list)
    services: list[str] = field(default_factory=list)
    removed_packages: list[str] = field(default_factory=list)
    brew_enabled: bool = False
    signing_enabled: bool = False
    github_user: str = ""
    # The scan lists hold the running host's complete layered-package and
    # base-removal inventory. They stay in memory to drive the selection screens
    # and are deliberately NOT written to the state file - see state_payload().
    # scan_omitted_customizations is in-memory too: the scan found something the
    # user agreed to leave behind, which reset still has to clear on switch.
    # scan_customizations_carried is the one bit anything downstream needs.
    scanned_packages: list[str] = field(default_factory=list)
    scanned_removed: list[str] = field(default_factory=list)
    scan_omitted_customizations: bool = False
    scan_customizations_carried: bool = False

    def normalize(self) -> None:
        # Every menu appends to lists over time. Normalizing here keeps ordering
        # stable for humans while still removing duplicates and empty values.
        self.packages = unique(self.packages)
        self.copr_repos = unique(self.copr_repos)
        self.services = unique(self.services)
        self.removed_packages = unique(self.removed_packages)


# The state file's schema is Config itself: state_payload() writes every field
# with asdict(), so the loader reads back the same names rather than keeping a
# second list that a new field could be left out of. With postponed
# annotations each type is its source spelling. A field of any other type would
# be written and never read back, which the round-trip test catches.
CONFIG_LIST_FIELDS = tuple(f.name for f in dataclass_fields(Config) if f.type == "list[str]")
CONFIG_STRING_FIELDS = tuple(f.name for f in dataclass_fields(Config) if f.type == "str")
CONFIG_BOOL_FIELDS = tuple(f.name for f in dataclass_fields(Config) if f.type == "bool")


def unique(values: Iterable[str]) -> list[str]:
    # This preserves first-seen order, which makes generated files and review
    # screens stable and easier for users to reason about.
    seen: set[str] = set()
    output: list[str] = []
    for value in values:
        stripped = value.strip()
        if stripped and stripped not in seen:
            output.append(stripped)
            seen.add(stripped)
    return output


def string_list(value: object) -> list[str]:
    # rpm-ostree status is untrusted input: it can be a stale override file or a
    # future schema change. Any field we expect to be a list of package names may
    # arrive as null, a bare string, or a list with non-string entries, so coerce
    # to a clean list of strings instead of letting unique() hit .strip() on an
    # int. A bare string is NOT iterated into characters - it is rejected.
    if not isinstance(value, list):
        return []
    return [item for item in value if isinstance(item, str)]


def next_boot_deployment(deployments: Sequence[dict[str, object]]) -> tuple[dict[str, object], bool]:
    # The deployment a scan has to read, and whether it is pending rather than
    # running. rpm-ostree lists deployments in boot order. A deployment of the
    # booted OS listed ahead of the booted one is pending: an `rpm-ostree
    # install`, `uninstall`, `rebase` or `rollback` since the last boot put it
    # there, and it is what the next boot runs. It is also what `rpm-ostree
    # reset` and `bootc switch` start from -- rpm-ostree takes the pending
    # deployment's origin, not the booted one's, as the base of a new one
    # (ostree_sysroot_query_deployments_for). Reading the booted deployment
    # instead dropped every package layered since the last boot, and carried
    # over one uninstalled since, right before the reset the generated README
    # recommends made those changes permanent (#519).
    booted = next((item for item in deployments if item.get("booted")), None)
    if booted is None:
        # No deployment claims to be booted: the first is the default boot.
        return (deployments[0] if deployments else {}), False
    osname = booted.get("osname")
    # Always found: booted itself matches its own osname.
    first = next(item for item in deployments if item.get("osname") == osname)
    return first, first is not booted


def remote_replacement_list(value: object) -> list[str]:
    # requested-base-remote-replacements is the one scan field that is not a
    # flat list of names. rpm-ostree records each `override replace --from
    # repo=...` as a (from, packages) pair -- Vec<(String, Vec<String>)> in
    # rust/src/daemon.rs -- so the JSON is [["repo=<id>", ["pkg", ...]], ...].
    # string_list() kept only str items, which dropped every pair and read the
    # override as absent: no "Cannot Be Carried Over" row, no confirm, and a
    # README recommending the reset that removes it (#353). Flatten to one
    # entry per package with its source attached, package name first so a long
    # COPR id is what the preview truncates. Same coercion contract as
    # string_list() otherwise: null, a bare string, or an entry of another
    # shape is dropped rather than raised on.
    if not isinstance(value, list):
        return []
    found: list[str] = []
    for entry in value:
        if isinstance(entry, str):
            found.append(entry)
            continue
        if not isinstance(entry, list) or len(entry) != 2:
            continue
        source, packages = entry
        source = source.strip() if isinstance(source, str) else ""
        names = string_list(packages)
        if names:
            found.extend(f"{name} (from {source})" if source else name for name in names)
        elif source:
            # A source with no readable package list is still an override the
            # image will not reproduce; naming the repository beats silence.
            found.append(source)
    return found


def sanitize_slug(value: str, default: str = DEFAULT_REPO_NAME) -> str:
    # GitHub repo names cannot contain spaces, so we translate user-friendly
    # input into a slug before running stricter validation.
    cleaned = re.sub(r"[^a-z0-9._-]", "-", value.lower()).strip("-")
    return cleaned or default


def is_valid_repo_name(value: str) -> bool:
    # Two rules, and the name has to satisfy both: the subset of GitHub naming
    # rules we support in the beginner UI, and the reference grammar that
    # decides whether ghcr.io/<owner>/<name> can be parsed at all. The first
    # alone let "test..image" through as far as repository creation and signing
    # setup, and every later push and pull of it failed to parse.
    if not value or len(value) > 100:
        return False
    if value.endswith(".git"):
        return False
    if not re.fullmatch(r"[a-z0-9](?:[a-z0-9._-]{0,98}[a-z0-9])?", value):
        return False
    if not OCI_PATH_COMPONENT_RE.fullmatch(value):
        return False
    return True


def file_lines(text: str) -> list[str]:
    """Split file text on line endings only, as YAML, sh and Dockerfile do.

    Every patcher that edits a file in place splits it with this and joins it
    back with "\\n". str.splitlines() would also break on \\v, \\f,
    \\x1c-\\x1e, U+0085, U+2028 and U+2029, so re-joining its output turned
    those characters into real line breaks in text the tool did not write --
    an owner's comment, or a description from before #527 -- and could leave
    the workflow unparseable (#689). For text whose only boundaries are \\n,
    \\r\\n and \\r the result is the same as str.splitlines(), so CRLF files
    still come back as LF.
    """
    lines = re.split(r"\r\n|\r|\n", text)
    if lines and lines[-1] == "":
        lines.pop()
    return lines


# What json.dumps(ensure_ascii=False) leaves raw but YAML forbids in a
# document: DEL and the C1 controls (U+007F-U+009F) and the two noncharacters
# U+FFFE/U+FFFF. YAML 1.2's c-printable production stops there -- C0 controls
# are already escaped by json.dumps, and everything else up to U+10FFFF is
# printable. U+0085 (NEL) is technically printable but a 1.1 line break, which
# PyYAML folds to a space, so it is escaped along with its neighbours. U+2028
# and U+2029 are the other two 1.1 line breaks, so a YAML 1.1 reader would fold
# a raw one too; escaping them keeps the value the same to every reader. (They
# once also orphaned the rest of the value on the next update, when the
# patchers split files with str.splitlines() -- #527; file_lines() removed that.)
_YAML_UNPRINTABLE_RE = re.compile("[\x7f-\x9f\u2028\u2029￾￿]")


def yaml_scalar(value: str) -> str:
    # JSON string quoting is valid YAML 1.2 and saves us from bringing in a
    # YAML library just to safely escape a single scalar value. Only with
    # ensure_ascii=False, though: json.dumps otherwise writes anything outside
    # the BMP -- every modern emoji -- as a UTF-16 surrogate pair, and a YAML
    # \u escape must name a single scalar value. libyaml, go-yaml, serde-yaml
    # and YamlDotNet all refuse the pair (see #360), so a description like
    # "My 🚀 image" would produce a recipe BlueBuild cannot read and a
    # workflow Actions cannot load. The characters that need escaping (quotes,
    # backslashes, C0 controls) are still escaped; the rest is written as the
    # UTF-8 the file is saved in anyway -- except the few code points YAML
    # refuses to see raw anywhere in a document, which ensure_ascii=False
    # would now pass through and libyaml would reject the whole file over.
    # Those go back to the \u escape, which every parser reads as itself.
    return _YAML_UNPRINTABLE_RE.sub(lambda m: f"\\u{ord(m.group()):04x}", json.dumps(value, ensure_ascii=False))


# A plain scalar that every YAML reader Actions and BlueBuild use resolves to
# the string it spells: letters, digits and the separators a branch name
# usually carries, not starting with a digit or an indicator character.
_YAML_SAFE_PLAIN_RE = re.compile(r"[A-Za-z_][A-Za-z0-9_./-]*")
# ...minus the words YAML 1.1 resolves to a boolean or null when unquoted.
_YAML_RESERVED_PLAIN_WORDS = frozenset({"y", "n", "yes", "no", "on", "off", "true", "false", "null"})


def yaml_plain_or_scalar(value: str) -> str:
    """``value`` bare when YAML reads it back as that string, else yaml_scalar().

    For hand-shaped lines such as a branch filter entry, where the ordinary
    value -- ``main`` -- is expected to stay bare, but a legal branch name
    such as ``#main`` (a comment), ``@dev`` (a reserved indicator) or
    ``null`` (not a string at all) must not be written unquoted.
    """
    if _YAML_SAFE_PLAIN_RE.fullmatch(value) and value.lower() not in _YAML_RESERVED_PLAIN_WORDS:
        return value
    return yaml_scalar(value)


def ensure_trailing_newline(text: str) -> str:
    return text.rstrip("\n") + "\n"


def containerfile_shell_words(text: str) -> list[str]:
    """Split ``text`` into shell words with their quotes and escapes kept."""
    words: list[str] = []
    word: list[str] = []
    quote = ""
    escaped = False
    for char in text:
        if escaped:
            escaped = False
        elif char == "\\" and quote != "'":
            escaped = True
        elif quote:
            if char == quote:
                quote = ""
        elif char in "'\"":
            quote = char
        elif char.isspace():
            if word:
                words.append("".join(word))
                word = []
            continue
        word.append(char)
    if word:
        words.append("".join(word))
    return words


def containerfile_heredocs(instruction: str) -> list[tuple[str, bool]]:
    """(terminator, strips-leading-tabs) for each heredoc ``instruction`` opens."""
    if "<<" not in instruction or not CONTAINERFILE_HEREDOC_INSTRUCTION_RE.match(instruction):
        return []
    heredocs: list[tuple[str, bool]] = []
    for word in containerfile_shell_words(instruction):
        match = CONTAINERFILE_HEREDOC_WORD_RE.match(word)
        if not match:
            continue
        try:
            # The terminator is the word with its quoting removed: <<"EOF"
            # ends at a line reading EOF.
            name = shlex.split(match.group(2))
        except ValueError:
            continue
        if len(name) == 1:
            heredocs.append((name[0], match.group(1) == "-"))
    return heredocs


def containerfile_escape(lines: list[str]) -> str:
    """The escape character BuildKit reads ``lines`` with.

    It is a backslash unless an ``# escape=`` parser directive in the
    leading run of directives sets it to a backtick. The escape character is
    also the line-continuation character, so a scanner that assumed the
    backslash would miss every continuation in a backtick-escaped file.
    """
    for index, line in enumerate(lines):
        # BuildKit drops a byte-order mark and leading whitespace first.
        match = CONTAINERFILE_DIRECTIVE_RE.match((line.removeprefix("\ufeff") if index == 0 else line).lstrip())
        if not match or match.group(1).lower() not in CONTAINERFILE_DIRECTIVE_NAMES:
            break
        if match.group(1).lower() == "escape":
            # BuildKit rejects any other value, so that build fails anyway.
            return match.group(2) if match.group(2) in CONTAINERFILE_CONTINUATION_RE else "\\"
    return "\\"


def containerfile_from_indices(lines: list[str]) -> list[int]:
    """Indices of the lines that are FROM instructions, in order.

    A line that merely looks like one is skipped when it is the continuation
    of the instruction above it or part of a heredoc body -- a Python
    "from x import y" written by a RUN heredoc matches FROM_LINE_RE, and the
    last FROM decides which stage is published, so it must not count. The
    walk follows BuildKit's parser: the continuation character is the file's
    escape character (see containerfile_escape), a comment line neither
    starts nor ends a continued instruction, a blank line never ends one,
    and heredoc bodies start after the whole instruction has been read.
    """
    continuation = CONTAINERFILE_CONTINUATION_RE[containerfile_escape(lines)]
    indices: list[int] = []
    heredocs: list[tuple[str, bool]] = []
    instruction: str | None = None
    for index, line in enumerate(lines):
        if heredocs:
            name, strip_tabs = heredocs[0]
            if (line.lstrip("\t") if strip_tabs else line) == name:
                heredocs.pop(0)
            continue
        stripped = line.strip()
        if not stripped or stripped.startswith("#"):
            continue
        if instruction is None:
            if FROM_LINE_RE.match(line):
                indices.append(index)
            instruction = ""
        if continuation.search(line):
            instruction += continuation.sub("", line)
            continue
        heredocs = containerfile_heredocs(instruction + line)
        instruction = None
    return indices


def normalize_container_image_reference(container_ref: str) -> str:
    # rpm-ostree reports image origins with different prefixes depending on how
    # the deployment was created. Normalize those into a plain image reference
    # so scan results can be matched against our curated base-image list.
    base = container_ref.strip()
    # "ostree-image-signed:" and "ostree-unverified-image:" are the signed and
    # signature-disabled spellings of the same thing: an origin prefix followed
    # by a transport-qualified reference. Both must be stripped, then the
    # transport below. Handling only the signed spelling meant a host rebased
    # with verification off fell through unchanged and never matched the curated
    # list, so choose_base_image discarded a base image that is on it.
    for origin_prefix in ("ostree-image-signed:", "ostree-unverified-image:"):
        if base.startswith(origin_prefix):
            base = base[len(origin_prefix) :]
            break
    else:
        if base.startswith("ostree-unverified-registry:"):
            base = base[len("ostree-unverified-registry:") :]
        elif base.startswith(("ostree-remote-image:", "ostree-remote-registry:")):
            # These carry the ostree remote name as a second field:
            # ostree-remote-image:<remote>:docker://<ref>
            parts = base.split(":", 2)
            if len(parts) == 3:
                base = parts[2]
    for transport in ("docker://", "registry:"):
        if base.startswith(transport):
            return base[len(transport) :]
    return base


# Every way rpm-ostree spells a container origin starts with one of these:
# the ostree-* prefixes normalize_container_image_reference() strips, and the
# bare transports a status override file may carry. What is left after ruling
# them out is a classic ostree origin -- `<remote>:<ref>` -- which is what
# every stock Fedora Silverblue or Kinoite install has until its first rebase.
CONTAINER_ORIGIN_PREFIXES: tuple[str, ...] = ("ostree-", "docker://", "registry:")

# The classic ref keeps a variant's original codename: Fedora renamed Sericea
# to Sway Atomic and Onyx to Budgie Atomic, and the container images on
# quay.io took the new names, but the ostree refs Fedora signs are
# still fedora/<release>/<arch>/sericea and .../onyx (see the ostree_refs
# table in fedora-infra/ansible's robosignatory role). The other three refs
# already spell the curated key.
CLASSIC_FEDORA_REF_ALIASES: dict[str, str] = {"sericea": "sway-atomic", "onyx": "budgie-atomic"}

# The remote Fedora's installer configures for its own ostree repo. Remote
# names are local configuration, so the ref alone says nothing about where a
# deployment came from: `corp:fedora/44/x86_64/silverblue` is whatever the
# corp remote serves under that name. Only this remote is Fedora's.
FEDORA_OSTREE_REMOTE = "fedora"

# The image workflow this tool generates builds and publishes one native
# x86_64 image and nothing else (see patch_disk_workflow_platform and #236).
# A host on another architecture can be scanned, but the image it would be
# guided into building could never be switched onto it.
PUBLISHED_ARCHITECTURE = "x86_64"
# The same architecture as an OCI image config spells it.
PUBLISHED_OCI_ARCHITECTURE = "amd64"


def deployment_image_architecture(deployment: dict) -> str:
    # The OCI architecture ("amd64", "arm64", ...) of the image a
    # container-image deployment booted, or "" when the status does not
    # carry one. rpm-ostree keeps the image's config in the commit metadata,
    # as JSON text; a decoded object is taken as-is.
    meta = deployment.get("base-commit-meta")
    config = meta.get("ostree.container.image-config") if isinstance(meta, dict) else None
    if isinstance(config, str):
        try:
            config = json.loads(config)
        except json.JSONDecodeError:
            return ""
    architecture = config.get("architecture") if isinstance(config, dict) else None
    return architecture.strip() if isinstance(architecture, str) else ""


def classic_ostree_origin(origin: str) -> tuple[str, str] | None:
    # A deployment that was installed from an ostree repo and never rebased
    # has no container-image-reference; its `origin` is a plain
    # `<remote>:<ref>` such as "fedora:fedora/44/x86_64/silverblue". Return
    # (remote, ref) -- the remote is "" for a bare ref deployed without one --
    # or None when the value names a container image so the caller can send
    # it through normalize_container_image_reference() instead. The shape
    # check matters: an unprefixed image reference has a colon too, but what
    # precedes it is a registry path -- slashes, and a host with a dot in it
    # -- where a classic origin has a bare remote name or a ref segment.
    value = origin.strip()
    if not value or value.startswith(CONTAINER_ORIGIN_PREFIXES):
        return None
    remote, sep, ref = value.partition(":")
    if not sep:
        remote, ref = "", value
    if "/" in remote or "." in (remote or ref.split("/", 1)[0]):
        return None
    if not re.fullmatch(r"[A-Za-z0-9._-]+(/[A-Za-z0-9._-]+)*", ref):
        return None
    return remote, ref


def parse_classic_fedora_ref(ref: str) -> tuple[str, str, str] | None:
    # fedora/<release>/<arch>/<variant> -> (release, arch, variant), or None
    # for any ref that is not spelled the way Fedora's desktop refs are.
    parts = ref.split("/")
    if len(parts) != 4 or parts[0] != "fedora" or not all(parts):
        return None
    _fedora, release, arch, variant = parts
    return release, arch, variant


def fedora_atomic_image_for_classic_origin(remote: str, ref: str) -> str | None:
    # fedora:fedora/<release>/<arch>/<variant> -> the quay.io image of the
    # same variant and release, which is the curated Fedora Atomic entry's
    # repository with the host's own release as the tag. Handing back a
    # tagged URI rather than the BaseImage lets scan_os treat it exactly like
    # a scanned image: match_base_image() finds the curated entry, and the
    # existing tag check offers the recommended tag when the host is on an
    # older release.
    #
    # None for everything else, and that is deliberately strict. The remote
    # has to be Fedora's own: the ref is only evidence of provenance when it
    # was pulled from Fedora's repo, and substituting the official image for
    # a same-named ref served by some other remote would quietly build on a
    # different base than the one running. And the architecture has to be
    # the one the generated workflow publishes: an aarch64 host offered the
    # x86_64 image would be walked through creating an image it cannot use.
    if remote != FEDORA_OSTREE_REMOTE:
        return None
    parsed = parse_classic_fedora_ref(ref)
    if parsed is None:
        return None
    release, arch, variant = parsed
    if arch != PUBLISHED_ARCHITECTURE:
        return None
    key = CLASSIC_FEDORA_REF_ALIASES.get(variant, variant)
    for image in BASE_IMAGES:
        if image.provider == "Fedora Atomic" and image.key == key:
            return f"{image.image_uri.rsplit(':', 1)[0]}:{release}"
    return None


def image_reference_tag_and_digest(image_ref: str) -> tuple[str, str]:
    # "<repo>[:<tag>][@<digest>]" -> (tag, digest), each "" when absent. The
    # digest comes off first: it carries a colon of its own ("@sha256:<hex>"),
    # so splitting a digest-pinned ref on its last colon hands back the 64 hex
    # characters as if they were a tag. The tag is then read from the last
    # path component only, so a registry port ("localhost:5000/repo") is not
    # mistaken for one either.
    ref, _, digest = image_ref.partition("@")
    _, _, tag = ref.rsplit("/", 1)[-1].partition(":")
    return tag, digest


def format_daily_rebuild_note(
    cron: str,
    *,
    now_utc: datetime | None = None,
    local_tz: tzinfo | None = None,
) -> str:
    parts = cron.split()
    if len(parts) != 5:
        return "Scheduled rebuilds also run automatically on GitHub."
    minute_text, hour_text, day_of_month, month, day_of_week = parts
    if day_of_month != "*" or month != "*" or day_of_week != "*" or not minute_text.isdigit() or not hour_text.isdigit():
        return f"Scheduled rebuilds also run automatically on GitHub using the configured schedule ({cron} UTC)."
    hour = int(hour_text)
    minute = int(minute_text)
    if not (0 <= hour <= 23 and 0 <= minute <= 59):
        return f"Scheduled rebuilds also run automatically on GitHub using the configured schedule ({cron} UTC)."

    base_utc = now_utc.astimezone(timezone.utc) if now_utc else datetime.now(timezone.utc)
    scheduled_utc = base_utc.replace(hour=hour, minute=minute, second=0, microsecond=0)
    tz = local_tz or datetime.now().astimezone().tzinfo or timezone.utc
    scheduled_local = scheduled_utc.astimezone(tz)
    local_time = scheduled_local.strftime("%I:%M %p").lstrip("0")
    local_zone = scheduled_local.tzname() or "local time"
    utc_time = scheduled_utc.strftime("%H:%M")
    if local_zone == "UTC":
        return f"Scheduled rebuilds also run daily at about {local_time} UTC."
    return f"Scheduled rebuilds also run daily at about {local_time} {local_zone} on this system ({utc_time} UTC)."


GHCR_TOKEN_URL = "https://ghcr.io/token?service=ghcr.io&scope=repository:{path}:pull"
GHCR_TAGS_URL = "https://ghcr.io/v2/{path}/tags/list"
# A newly published GHCR package is private, whatever the repository that
# published it is set to: package visibility is a separate setting that does
# not inherit from repository access. `gh repo create --public` therefore does
# not make the first build's image anonymously pullable, and `bootc switch` on
# a host with no GHCR credentials cannot read it. There is no REST endpoint for
# changing package visibility, so this can only be pointed at, which is also
# what keeps it an explicit decision by the person who owns the package.
BOOTC_REGISTRY_DOCS_URL = "https://bootc.dev/bootc/registries-and-offline.html"
# ghcr_package_exists() makes two sequential requests, so its default timeout
# is really twice that in the worst case. That is fine before creating a repo,
# where the answer gates an irreversible step. The build-status screen is
# somewhere people come back to repeatedly and the answer there is advisory --
# an unreachable network reports the same thing a private package does -- so
# it waits a good deal less.
GHCR_ADVISORY_TIMEOUT = 2.5


def ghcr_package_exists(owner: str, name: str, *, timeout: float = 6.0) -> bool:
    # Deleting a GitHub repo does not delete its GHCR packages. The orphan keeps
    # the Actions-access list of the repo that made it, so a new repo of the same
    # name -- a different repo as far as GitHub is concerned -- cannot push to it.
    # The generated workflow only discovers this at its final push step, after
    # the image has already built, rechunked, and tagged.
    #
    # An anonymous pull is enough to answer this and needs no extra `gh` scope.
    # It returns True only for a package it actually read: a private package is
    # indistinguishable from a missing one this way, and every error collapses to
    # False, because warning someone about a conflict in their own namespace that
    # does not exist is worse than staying quiet.
    path = f"{owner.lower()}/{name.lower()}"
    try:
        token_request = urllib.request.Request(
            GHCR_TOKEN_URL.format(path=urllib.parse.quote(path)),
            headers={"User-Agent": TOOL_SLUG},
        )
        with urllib.request.urlopen(token_request, timeout=timeout) as response:
            payload = json.load(response)
        token = payload.get("token") if isinstance(payload, dict) else None
        if not isinstance(token, str) or not token:
            return False
        tags_request = urllib.request.Request(
            GHCR_TAGS_URL.format(path=urllib.parse.quote(path)),
            headers={"Authorization": f"Bearer {token}", "User-Agent": TOOL_SLUG},
        )
        with urllib.request.urlopen(tags_request, timeout=timeout) as response:
            return response.status == 200
    except (OSError, ValueError, http.client.HTTPException):
        # http.client's exceptions -- IncompleteRead, BadStatusLine, LineTooLong,
        # InvalidURL -- descend from HTTPException, not OSError or ValueError. A
        # response truncated by GHCR or a proxy would otherwise escape an
        # advisory check and stop the user creating a repo at all.
        return False


def ghcr_package_page_url(owner: str, repo: str) -> str:
    # The repository-scoped package page, because "Package settings" is
    # reachable from it for a user account and an organization alike. The
    # /users/<owner>/packages/... settings path is not: it 404s for an org,
    # and the repo picker can reach repositories in one.
    return f"https://github.com/{owner}/{repo}/pkgs/container/{repo.lower()}"


def open_url_in_browser(url: str) -> bool:
    # Fire and forget, with the browser's output thrown away. A GUI browser is
    # chatty on stderr -- Mesa, EGL and sandbox warnings -- and inheriting this
    # terminal writes all of it over the running TUI. It is also detached and
    # not waited on, so a browser that takes its time starting cannot stall the
    # prompt that follows.
    for opener in ("xdg-open", "open"):
        if not command_exists(opener):
            continue
        try:
            subprocess.Popen(
                [opener, url],
                stdout=subprocess.DEVNULL,
                stderr=subprocess.DEVNULL,
                stdin=subprocess.DEVNULL,
                start_new_session=True,
            )
        except OSError:
            return False
        return True
    return False


def command_exists(name: str) -> bool:
    return shutil.which(name) is not None


def shell_quote(value: str) -> str:
    return shlex.quote(value)


def brew_login_fragment_run_lines(indent: str = "") -> list[str]:
    """Return the RUN step that keeps the brew payload out of root's login shell.

    Emitted immediately after the ``COPY --from=<brew image> /system_files /``
    and its preset RUN, by every path that writes that COPY: the Containerfile
    generator, the Containerfile patcher, and the BlueBuild recipe's
    containerfile module. See BREW_LOGIN_FRAGMENTS for what it removes and why.

    The step does three things, in order: remove the three fragments the pinned
    payload ships, write a replacement that only extends PATH, and fail the
    build if anything else in a login-shell directory still mentions brew.

    ``indent`` prefixes every line, for the BlueBuild recipe, where the same
    text lives inside a YAML literal block scalar.
    """
    first, *rest = BREW_LOGIN_FRAGMENTS
    removals = [f"{indent}RUN rm -f {first} \\"]
    removals += [f"{indent}          {path} \\" for path in rest]
    # Written with printf rather than a heredoc: a heredoc inside a RUN needs
    # BuildKit's heredoc support, and these repos are also built with
    # buildah-build and plain `podman build` from the Justfile.
    #
    # Nothing below is expanded when the Containerfile is parsed -- RUN is not
    # one of the instructions Docker does environment replacement on -- and
    # every line the file receives is single-quoted here, so ${PATH} reaches
    # the fragment as text for the login shell to expand.
    fragment = [
        "# Put the Homebrew prefix on PATH for the account that owns it, and run",
        "# nothing out of it. brew-setup.service ends with",
        '# "chown -R 1000:1000 /home/linuxbrew", so every file under the prefix,',
        "# the brew executable included, is writable by the desktop user, and",
        "# /etc/profile.d is read by every login shell, including the root",
        "# account. A fragment that evals or sources anything from the prefix",
        "# therefore hands its owner code execution as root.",
        "#",
        '# -O is "owned by the effective user", so this is inert for root and for',
        "# every account that does not own the prefix. The prefix is appended,",
        "# not prepended, so system binaries keep priority -- the ordering the",
        "# payload fragment aimed for.",
        "if [ -O /home/linuxbrew/.linuxbrew ] && [ -d /home/linuxbrew/.linuxbrew/bin ]; then",
        '  case ":${PATH}:" in',
        '    *":/home/linuxbrew/.linuxbrew/bin:"*) ;;',
        '    *) PATH="${PATH}:/home/linuxbrew/.linuxbrew/bin:/home/linuxbrew/.linuxbrew/sbin"; export PATH ;;',
        "  esac",
        "fi",
    ]
    # Every fragment line is emitted inside a single-quoted printf argument, so
    # one apostrophe would close the quote and hand the rest of the line to the
    # build shell. Nothing here needs one; refuse rather than write a broken --
    # or worse, a differently-behaving -- Containerfile if that ever changes.
    for line in fragment:
        if "'" in line:
            raise CommandError(f"brew PATH fragment line cannot contain an apostrophe: {line!r}")
    lines = [*removals]
    lines[-1] = lines[-1].removesuffix(" \\") + " && \\"
    lines.append(f"{indent}    printf '%s\\n' \\")
    lines.extend(f"{indent}      '{line}' \\" for line in fragment)
    lines.append(f"{indent}      > {BREW_PATH_FRAGMENT} && \\")
    lines.append(f"{indent}    chmod 0644 {BREW_PATH_FRAGMENT} && \\")
    lines.append(
        f'{indent}    unguarded="$(grep -rlI -- brew {" ".join(BREW_LOGIN_SHELL_DIRS)} 2>/dev/null \\'
    )
    lines.append(f"{indent}      | grep -vxF -e {BREW_PATH_FRAGMENT} || true)\" && \\")
    lines.append(f'{indent}    if [ -n "${{unguarded}}" ]; then \\')
    lines.append(
        f'{indent}        echo "error: unguarded Homebrew shell integration from the brew payload:" >&2; \\'
    )
    lines.append(f"{indent}        printf '%s\\n' \"${{unguarded}}\" >&2; \\")
    lines.append(
        f'{indent}        echo "Remove it in this step, or guard it the way {BREW_PATH_FRAGMENT} is." >&2; \\'
    )
    lines.append(f"{indent}        exit 1; \\")
    lines.append(f"{indent}    fi")
    return lines


# `ExecStart=` lines only, and only a /tmp or /var/tmp path inside one. Scoping
# it to ExecStart= is what keeps a `ConditionPathExists=` or a comment that
# happens to name /tmp from standing in as evidence of where the payload stages.
BREW_SETUP_STAGING_RE = "^ExecStart="
BREW_SETUP_TMP_PATH_RE = "(^|[^[:alnum:]_.-])/(var/)?tmp(/|[[:space:]]|$)"


def brew_setup_staging_run_lines(indent: str = "") -> list[str]:
    """Return the RUN step that confines brew-setup.service to a private /tmp.

    Emitted immediately after ``brew_login_fragment_run_lines()`` by every path
    that writes the ``COPY --from=<brew image> /system_files /`` block: the
    Containerfile generator, the Containerfile patcher, and the BlueBuild
    recipe's containerfile module. See BREW_SETUP_UNIT for what the payload's
    unit does without this and why it matters on a booted machine.

    The step does two things, in this order: refuse to write the drop-in if the
    payload no longer has a unit for it to apply to, or no longer stages
    anywhere ``PrivateTmp=`` confines; and then write it. The check comes first
    because the point of failing is to stop a vestigial drop-in shipping beside
    a payload that has moved -- the image is named by a mutable tag, so what
    landed in it is the only thing worth asserting against.

    ``indent`` prefixes every line, for the BlueBuild recipe, where the same
    text lives inside a YAML literal block scalar.
    """
    dropin = [
        "# brew-setup.service stages the Homebrew payload through /tmp as root and",
        "# ships no PrivateTmp=, so on a booted system its staging path is a name in",
        "# a world-writable tmpfs that any local account can claim first. With this",
        "# drop-in the unit gets its own /tmp and /var/tmp for the whole invocation,",
        "# shared by every ExecStart= of that invocation and by nothing else on the",
        "# system. /home/linuxbrew is outside both, so the payload still lands there.",
        "#",
        "# A drop-in rather than a unit that overrides ExecStart=: a copy of the",
        "# payload command chain would drift silently the next time the payload moves.",
        "[Service]",
        "PrivateTmp=yes",
    ]
    # Same rule, and the same reason, as the login-shell fragment above: every
    # line is emitted inside a single-quoted printf argument, so one apostrophe
    # would close the quote and hand the rest of the line to the build shell.
    for line in dropin:
        if "'" in line:
            raise CommandError(f"brew-setup drop-in line cannot contain an apostrophe: {line!r}")
    lines = [f"{indent}RUN if [ ! -f {BREW_SETUP_UNIT} ]; then \\"]
    lines.append(
        f'{indent}        echo "error: the brew payload no longer ships {BREW_SETUP_UNIT}, so there is nothing to confine." >&2; \\'
    )
    lines.append(f"{indent}        exit 1; \\")
    lines.append(f"{indent}    fi && \\")
    lines.append(
        f"{indent}    staging=\"$(grep -E '{BREW_SETUP_STAGING_RE}' {BREW_SETUP_UNIT} \\"
    )
    lines.append(f"{indent}      | grep -E '{BREW_SETUP_TMP_PATH_RE}' || true)\" && \\")
    lines.append(f'{indent}    if [ -z "${{staging}}" ]; then \\')
    lines.append(
        f'{indent}        echo "error: brew-setup.service no longer stages under /tmp or /var/tmp, which is all PrivateTmp= confines:" >&2; \\'
    )
    lines.append(f"{indent}        grep -E '{BREW_SETUP_STAGING_RE}' {BREW_SETUP_UNIT} >&2; \\")
    lines.append(
        f'{indent}        echo "Find where the payload stages now before trusting {BREW_SETUP_DROPIN}." >&2; \\'
    )
    lines.append(f"{indent}        exit 1; \\")
    lines.append(f"{indent}    fi && \\")
    lines.append(f"{indent}    mkdir -p {PurePosixPath(BREW_SETUP_DROPIN).parent} && \\")
    lines.append(f"{indent}    printf '%s\\n' \\")
    lines.extend(f"{indent}      '{line}' \\" for line in dropin)
    lines.append(f"{indent}      > {BREW_SETUP_DROPIN} && \\")
    lines.append(f"{indent}    chmod 0644 {BREW_SETUP_DROPIN}")
    return lines


ANSI_RE = re.compile(r"\x1b\[[0-9;]*m")


def validate_string_list(value: object, field_name: str) -> list[str]:
    # State files are user-editable JSON. Strict type checks here keep a broken
    # or hand-edited state file from turning into confusing runtime errors.
    if not isinstance(value, list):
        raise ValueError(f"{field_name} must be a list of strings")
    invalid = [item for item in value if not isinstance(item, str)]
    if invalid:
        raise ValueError(f"{field_name} must contain only strings")
    return list(value)


def require_encodable_state_string(value: str, field_name: str) -> None:
    # json.loads accepts a lone-surrogate escape such as "\\udc80" and returns a
    # str Python cannot encode, so it would load, validate, and then crash with
    # UnicodeEncodeError at the first file write (#700). Refuse it here, where
    # the "state file is damaged" message is produced.
    try:
        value.encode("utf-8")
    except UnicodeEncodeError:
        raise ValueError(f"{field_name} contains a character that is not valid text") from None


def config_from_state_payload(data: object) -> Config:
    # Older repo updates depend on this loader being defensive. If the state
    # file is wrong, we would rather fail loudly with a helpful message than
    # quietly write a damaged repo back to GitHub.
    if not isinstance(data, dict):
        raise ValueError("state file must contain a JSON object")
    state_version = data.get("state_version")
    if state_version is not None:
        if not isinstance(state_version, int):
            raise ValueError("state_version must be an integer")
        if state_version > 1:
            raise ValueError(f"unsupported state_version: {state_version}")

    cfg = Config()
    for name in CONFIG_LIST_FIELDS:
        if name in data:
            items = validate_string_list(data[name], name)
            for item in items:
                require_encodable_state_string(item, name)
            setattr(cfg, name, items)
    for name in CONFIG_STRING_FIELDS:
        if name in data:
            value = data[name]
            if not isinstance(value, str):
                raise ValueError(f"{name} must be a string")
            require_encodable_state_string(value, name)
            setattr(cfg, name, value)
    for bool_field in CONFIG_BOOL_FIELDS:
        if bool_field in data:
            value = data[bool_field]
            if not isinstance(value, bool):
                raise ValueError(f"{bool_field} must be a boolean")
            setattr(cfg, bool_field, value)
    if cfg.method and cfg.method not in ALLOWED_METHODS:
        raise ValueError(f"unsupported build method: {cfg.method}")
    cfg.normalize()
    return cfg


def pin_disk_builder_image_line(line: str) -> str | None:
    """The line with BIB_IMAGE re-pinned, or None if it does not name the builder.

    Shared by the disk workflow and image-template.env patchers, which spell
    the assignment differently and scope it differently but pin the same
    image. The quoting and any trailing comment are the line's own.
    """
    match = DISK_BUILDER_IMAGE_RE.match(line)
    if match is None:
        return None
    prefix, quote, suffix = match.group("prefix", "quote", "suffix")
    return f"{prefix}{quote}{BOOTC_IMAGE_BUILDER_IMAGE}{quote}{suffix}"


def yaml_key_pattern(name: str) -> str:
    """A regex fragment for the YAML key `name` and its colon, in any spelling.

    `uses:`, `"uses":`, `'uses':` and `uses :` are one key to YAML and to
    Actions. A patcher that recognizes only the first leaves the others
    unpatched -- an action on its floating tag, a Cosign release below the
    floor -- and reports nothing (#525).
    """
    escaped = re.escape(name)
    return rf"""(?:{escaped}|"{escaped}"|'{escaped}')\s*:"""


# A `uses:` line: an optional list dash (the compact `- uses:` step form),
# the key in any spelling, and an `action@ref` value, bare or quoted. The
# quote is its own group so the rewrite writes it back, and the ref stops
# short of it so `'actions/checkout@v4'` looks up `actions/checkout`, not
# `'actions/checkout`. Anything after the value must be whitespace-led, so
# an unbalanced quote does not match.
WORKFLOW_USES_LINE_RE = re.compile(
    rf"""(\s*(?:-\s+)?{yaml_key_pattern("uses")}\s+)(['"]?)([^@\s'"]+)@([^\s#'"]+)\2((?:\s.*)?)"""
)


def step_uses_action(step_lines: Sequence[str], action: str) -> bool:
    """Whether a step block runs `action`, at any ref and in any `uses:` spelling."""
    return any(
        match is not None and match.group(3) == action
        for match in map(WORKFLOW_USES_LINE_RE.fullmatch, step_lines)
    )


def pin_action_uses_line(line: str) -> str:
    # When patching upstream workflow text, we rewrite "uses:" lines to pinned
    # SHAs. This avoids supply-chain drift if an upstream tag ever changes.
    #
    # Every YAML spelling of a step has to be read, because this runs over
    # workflow text written elsewhere -- upstream's snapshot, or whatever the
    # repository's owner has edited it into since. maintenance_audit's USES_RE
    # already allows for the compact `- uses:` form; a rewriter that only knew
    # the `- name:` / `uses:` form would leave a compact step on its floating
    # tag and report nothing, in a managed repository nothing audits later.
    # A quoted value is the same miss (#525). The list dash and the quote are
    # captured so the line keeps its own shape.
    match = WORKFLOW_USES_LINE_RE.fullmatch(line)
    if not match:
        return line
    prefix, quote, action, _ref, _suffix = match.groups()
    pin = ACTION_REF_PINS.get(f"{action}@{_ref}") or ACTION_PINS.get(action)
    if not pin:
        return line
    sha, label = pin
    # ACTION_REF_PINS may name the SHA ACTION_PINS already holds under an
    # older label -- remove-unwanted-software's "v8" entries do, and stay as
    # they are so the freshness audit keeps watching that tag (see
    # maintenance_notes.txt). The label written into a workflow is ACTION_PINS',
    # though: workflows the tool once generated from scratch carry that label
    # for this SHA, and if the ref table's won here, such a repository would
    # have its comment rewritten on its next update with no upstream change
    # behind it. Same SHA, one label.
    current = ACTION_PINS.get(action)
    if current is not None and current[0] == sha:
        label = current[1]
    return f"{prefix}{quote}{action}@{sha}{quote} # {label}"


# Job-level env is set for every step in the job, `uses:` steps included, so a
# secret placed there is handed to every third-party action the job runs. The
# signing condition only needs to know *whether* a key exists, and the secrets
# context is available in job-level env even though it is not available in a
# step-level `if:` -- so the job carries this boolean and never the key itself.
SIGNING_ENABLED_ENV = ("SIGNING_ENABLED", "${{ secrets.SIGNING_SECRET != '' }}")
# What repositories generated before that carry. Their conditions test a
# job-level variable this no longer defines, so the clause has to be removed
# rather than left to evaluate false forever -- signing that silently stops is
# worse than signing that fails.
LEGACY_SIGNING_ENV_KEYS = ("COSIGN_PRIVATE_KEY", "COSIGN_PASSWORD")
LEGACY_SIGN_CONDITION = " && env.COSIGN_PRIVATE_KEY != ''"


def strip_job_env_entries(workflow_text: str, names: Sequence[str]) -> str:
    """Drop job-level env entries by name, leaving step-level ones alone.

    Only the entries directly under a job's own `env:` count, at whatever
    indent that block's first entry uses, which is the same block
    ensure_workflow_job_env_entries() reads and extends. Matching six spaces
    anywhere kept the signing step's own `COSIGN_PRIVATE_KEY:`, at eight,
    from being removed with it, but it also missed a job env an editor had
    put at eight. That update then succeeded and left the signing key
    exposed to every step in the job (#524). A value continued on deeper
    lines goes with its key.

    Removing the last entry would leave a bare `env:`, which YAML reads as
    null, so the block collapses to `env: {}` instead, the way
    strip_permission_entries() collapses `permissions:`. A comment is not an
    entry.
    """
    lines = file_lines(workflow_text)
    drop: set[int] = set()
    emptied: set[int] = set()
    for _, start, end in workflow_job_ranges(lines):
        job = lines[start:end]
        env_at = workflow_job_level_key_index(job, "env")
        if env_at is None:
            continue
        entry_indent = len(block_mapping_entry_indent(job, env_at))
        dropping = False
        dropped_any = False
        kept_any = False
        for offset in range(env_at + 1, len(job)):
            stripped = job[offset].strip()
            if not stripped:
                continue
            indent = len(job[offset]) - len(job[offset].lstrip())
            if indent <= 4 and not stripped.startswith("#"):
                break
            if indent > entry_indent:
                if dropping:
                    drop.add(start + offset)
                continue
            dropping = indent == entry_indent and workflow_key(stripped) in names
            if dropping:
                drop.add(start + offset)
                dropped_any = True
            elif not stripped.startswith("#"):
                kept_any = True
        if dropped_any and not kept_any:
            emptied.add(start + env_at)
    kept = [
        f"{line[: len(line) - len(line.lstrip())]}env: {{}}" if index in emptied else line
        for index, line in enumerate(lines)
        if index not in drop
    ]
    return ensure_trailing_newline("\n".join(kept))


def workflow_level_env_keys(lines: Sequence[str]) -> set[str]:
    """Return the names defined in the top-level `env:` block, if there is one."""
    defined: set[str] = set()
    inside = False
    for line in lines:
        stripped = line.strip()
        if not stripped or stripped.startswith("#"):
            continue
        if not line[0].isspace():
            inside = workflow_block_key(stripped) == "env"
            continue
        if inside and line.startswith("  ") and not line.startswith("   "):
            key = workflow_key(stripped)
            if key is not None:
                defined.add(key)
    return defined


def strip_legacy_signing_job_env(workflow_text: str) -> str:
    """Remove the legacy job-level signing key and password, or refuse to.

    Run after patch_workflow_signing_steps(). Removing a job's COSIGN_PRIVATE_KEY
    is only safe once nothing in that job reads `env.COSIGN_PRIVATE_KEY` any
    more: a step's own `env:` is not visible to its `if:`, so a condition the
    step rewrite did not reach would test a variable that no longer exists, be
    false forever, and publish every image unsigned on a green run (#526).
    Keeping the keys instead would leave the signing key exposed to every
    action in the job, which is what the migration exists to end (#255). So a
    surviving reference fails closed, naming the line to fix by hand.

    Only a read the removal actually breaks counts: one inside a job whose
    job-level entry for that name is removed, and not also defined in the
    workflow-level `env:`, which this leaves alone and which would still
    answer it. What was removed is read from the same block, at the same
    indent and by the same parsed key name, as strip_job_env_entries()
    removes it: matching one literal six-space spelling missed an env at
    eight or a quoted key, skipped the check, and the migration published
    unsigned (#695). The strip only ever reaches jobs the parser recognizes,
    so nothing outside them is removed. A workflow with no legacy job-level
    entry is returned as it is: this update cannot be what breaks it.
    """
    stripped = strip_job_env_entries(workflow_text, LEGACY_SIGNING_ENV_KEYS)
    if stripped == ensure_trailing_newline(workflow_text):
        return stripped
    lines = file_lines(workflow_text)
    still_defined = workflow_level_env_keys(lines)

    def removed_names(job: Sequence[str]) -> set[str]:
        env_at = workflow_job_level_key_index(job, "env")
        if env_at is None:
            return set()
        return (set(LEGACY_SIGNING_ENV_KEYS) & workflow_job_env_keys(job, env_at)) - still_defined

    scopes = [(lines[start:end], removed_names(lines[start:end])) for _, start, end in workflow_job_ranges(lines)]
    for scope, names in scopes:
        if not names:
            continue
        reads = re.compile(rf"\benv\.(?:{'|'.join(sorted(names))})\b")
        for line in scope:
            if line.lstrip().startswith("#") or not reads.search(line):
                continue
            raise CommandError(
                f"This workflow still reads a legacy job-level signing variable after its signing "
                f"steps were migrated ({line.strip()!r}), and this update removes that variable from "
                f"the job's 'env:'. Left as it is, that condition would be false forever and the "
                f"image would be published unsigned. Make it test env.{SIGNING_ENABLED_ENV[0]} == "
                f"'true' instead -- in a signing step's 'if:', delete "
                f"\"{LEGACY_SIGN_CONDITION.strip()}\" -- then run this update again."
            )
    return stripped


# Nothing in the Containerfile path asks GitHub for an OIDC token. Signing
# there is key-based -- `cosign sign --key env://COSIGN_PRIVATE_KEY`, with
# COSIGN_EXPERIMENTAL explicitly false -- and none of the actions those
# workflows run requests one: checked at the pinned SHAs of actions/checkout,
# ublue-os/remove-unwanted-software, extractions/setup-just,
# docker/login-action, sigstore/cosign-installer, actions/upload-artifact and
# osbuild/bootc-image-builder-action. Several of them bundle @actions/core,
# which *exports* getIDToken, but none of them calls it.
#
# So the scope is granted and never used, and a pull_request run carries it in
# a workflow file that comes from the pull request's own head. Removing it is
# the whole of the mitigation; see maintenance_notes.txt, "OIDC Token Scope on
# Generated Builds", for when it has to come back.
UNUSED_WORKFLOW_PERMISSIONS = ("id-token",)


def strip_permission_entries(workflow_text: str, names: Sequence[str]) -> str:
    """Drop named entries from every `permissions:` block in a workflow.

    Scoped to the block rather than matched on indentation alone, the way the
    path-filter patcher is: `id-token` is a perfectly good `with:` input name,
    and an action input spelled that way is not a token scope. Only a line
    that opens a block counts, so `permissions: read-all` and
    `permissions: {}` are left as they are -- they are values, not mappings
    with entries to remove.

    Removing the last entry would leave a bare `permissions:` key, which YAML
    reads as null and Actions rejects. The block collapses to
    `permissions: {}` instead, which is the same thing the caller asked for --
    a job granted nothing -- and is valid. A comment is not an entry: a block
    holding only `# OIDC for signing` and `id-token: write` collapses too
    (#524). Comments and blank lines end nothing either, whatever their
    indent, the way workflow_job_ranges() reads a job.

    Lines of a block scalar are the owner's script, not keys, so a `run: |`
    that happens to print `permissions:` is left as written.
    """
    lines = file_lines(workflow_text)
    scalar_body = block_scalar_body_indexes(lines)
    output: list[str] = []
    block_indent: int | None = None
    header_index = 0
    kept_any = False
    # The indent of the entry being dropped, so a value it continues on
    # deeper lines goes with it.
    dropping_at: int | None = None

    def close_block() -> None:
        if not kept_any:
            output[header_index] = f"{' ' * block_indent}permissions: {{}}"

    for index, line in enumerate(lines):
        stripped = line.strip()
        indent = len(line) - len(line.lstrip())
        if index in scalar_body:
            output.append(line)
            continue
        if block_indent is not None:
            # A blank or comment line inside the block neither ends it nor
            # is an entry; the next line with content decides.
            if not stripped or stripped.startswith("#"):
                output.append(line)
                continue
            if indent > block_indent:
                if dropping_at is not None and indent > dropping_at:
                    continue
                # By parsed name, so `"id-token": write` and `id-token : write`
                # go too (#525, #698).
                if workflow_key(stripped) in names:
                    dropping_at = indent
                    continue
                dropping_at = None
                kept_any = True
                output.append(line)
                continue
            close_block()
            block_indent = None
        if workflow_block_key(stripped) == "permissions":
            block_indent = indent
            header_index = len(output)
            kept_any = False
            dropping_at = None
        output.append(line)
    if block_indent is not None:
        close_block()
    return ensure_trailing_newline("\n".join(output))


def patch_signing_step_block(step_lines: Sequence[str], *, branch_if: str, sign_if: str) -> list[str]:
    # Signing-related steps are identified by behavior rather than display
    # names so template renames do not silently bypass our signing guard.
    is_cosign_install = step_uses_action(step_lines, "sigstore/cosign-installer")
    is_cosign_sign = any(re.search(r"\bcosign\s+sign\b", line) for line in step_lines)
    if not (is_cosign_install or is_cosign_sign):
        return list(step_lines)
    if is_cosign_sign:
        step_lines = add_signing_step_password(step_lines)

    # The step's own keys sit at one column: just past the `- ` of its first
    # line. Anything deeper is a value -- above all a `run: |` body, where a
    # shell line such as `if : ; then` parses as an `if` key when read on its
    # own. Counting that as the step's condition meant no guard was inserted,
    # and the step signed on pull requests or with no key configured.
    #
    # A bare `-` item, or one whose first line holds only a comment, carries
    # its keys on the lines below, and they set the column. Reading it from
    # the dash line found no key there, so the step's own `if:` was missed
    # and a second one inserted, which Actions rejects (#697).
    first_stripped = step_lines[0].lstrip()
    dash = re.match(r"-\s+", first_stripped)
    first_key_text = first_stripped[dash.end() :] if dash else first_stripped
    if first_key_text.rstrip() in ("", "-") or first_key_text.startswith("#"):
        first_key_text = ""
        dash_indent = len(step_lines[0]) - len(first_stripped)
        key_column = next(
            (
                len(line) - len(line.lstrip())
                for line in step_lines[1:]
                if line.strip() and not line.strip().startswith("#")
            ),
            dash_indent + 2,
        )
    else:
        key_column = len(step_lines[0]) - len(first_key_text)
    patched: list[str] = []
    has_if = False
    for index, line in enumerate(step_lines):
        stripped = line.lstrip()
        # The key is read by name, so `if :` and `"if":` count, and so does
        # the first key of the step's own `- ` item: key-sorted YAML writes
        # `- if: ...` first, and missing it meant a second `if:` was inserted
        # into the same mapping, which Actions rejects (#525).
        if index == 0:
            key_text = first_key_text
        elif len(line) - len(stripped) == key_column:
            key_text = stripped
        else:
            key_text = ""
        if key_text and workflow_key(key_text) == "if":
            has_if = True
            # A block scalar `if: >-` holds its condition on the lines below,
            # which this does not rewrite. Taking it as handled left the step
            # on the branch guard alone, with no SIGNING_ENABLED written
            # anywhere (#699). Already guarded, it is left as it is;
            # otherwise the owner folds it back onto one line.
            if BLOCK_SCALAR_HEADER_RE.match(key_text):
                folded: list[str] = []
                for later in step_lines[index + 1 :]:
                    if later.strip() and len(later) - len(later.lstrip()) <= key_column:
                        break
                    folded.append(later.strip())
                body = " ".join(part for part in folded if part)
                if sign_if in body and LEGACY_SIGN_CONDITION.strip() not in body:
                    patched.append(line)
                    continue
                raise CommandError(
                    f"The signing step {signing_step_label(step_lines)!r} writes its 'if:' as a block "
                    f"scalar ({stripped.strip()!r}), which this tool cannot rewrite, so it cannot add "
                    f"the guard that keeps signing off pull requests and repositories without a key. "
                    f"Put that condition on one line after 'if:', then run this update again."
                )
            # Drop the legacy clause first. Rewriting around it would leave
            # "... && env.SIGNING_ENABLED == 'true' && env.COSIGN_PRIVATE_KEY != ''",
            # whose second half tests a job-level variable that no longer
            # exists -- so every existing repository would quietly stop
            # signing while its workflow still looked correct.
            condition = stripped.replace(LEGACY_SIGN_CONDITION, "", 1)
            if branch_if in condition and sign_if not in condition:
                condition = condition.replace(branch_if, sign_if, 1)
            if condition != stripped:
                indent = line[: len(line) - len(stripped)]
                patched.append(f"{indent}{condition}")
                continue
        patched.append(line)
    if has_if or not patched:
        return patched

    # At the step's own key column: `indent + "  "` put it two columns
    # short of `-   name:`'s keys, and the step no longer parsed (#697).
    return [patched[0], f"{' ' * key_column}if: {sign_if}", *patched[1:]]


def signing_step_label(step_lines: Sequence[str]) -> str:
    """The step's `name:`, or its first line when it has none, for an error."""
    for line in step_lines:
        stripped = line.strip().removeprefix("-").strip()
        if workflow_key(stripped) == "name":
            return stripped.split(":", 1)[1].strip()
    return step_lines[0].strip()


def patch_workflow_steps(workflow_text: str, patch_step: Callable[[list[str]], list[str]]) -> list[str]:
    """Split a workflow into step blocks and run patch_step over each one.

    A step block is a "- " item directly under a `steps:` key, plus every line
    indented beneath it. Lines outside any step pass through untouched.

    The key may carry a comment (`steps: # build`), and the items sit
    wherever the first one puts them: YAML asks only that a sequence's
    entries agree with each other, so +4 and the indentless +0 are as valid
    as +2. Anchoring on a bare `steps:` with items at +2 walked past every
    step in those shapes, and the signing migration then stripped the job
    key its unrewritten conditions still read (#526).

    Both workflow patchers walked their own byte-identical copy of this state
    machine, so a correction to the step-boundary rules reached only one of
    them. Returns the output lines; the caller decides how to join them.

    A block scalar's body is the owner's script, not keys. A `run: |` that
    writes a manifest with its own `steps:` restarted the walk inside the
    script, and every real step after it went unpatched (#696). Those lines
    go with whatever step holds them and decide nothing.
    """
    output: list[str] = []
    current_step: list[str] = []
    in_steps = False
    steps_indent = 0
    item_indent: int | None = None

    def flush_step() -> None:
        nonlocal current_step
        if not current_step:
            return
        output.extend(patch_step(current_step))
        current_step = []

    lines = file_lines(workflow_text)
    scalar_body = block_scalar_body_indexes(lines)
    for index, line in enumerate(lines):
        stripped = line.strip()
        indent = len(line) - len(line.lstrip())
        is_item = stripped == "-" or stripped.startswith("- ")

        if index in scalar_body:
            (current_step if current_step else output).append(line)
            continue

        if in_steps and stripped and not stripped.startswith("#"):
            if item_indent is None:
                # The first line with content decides where the items sit.
                # Anything but a sequence item at or beyond the key means the
                # key holds no block sequence to walk.
                if is_item and indent >= steps_indent:
                    item_indent = indent
                else:
                    in_steps = False
            elif indent < item_indent or (indent == item_indent and not is_item):
                flush_step()
                in_steps = False

        if workflow_block_key(stripped) == "steps":
            flush_step()
            in_steps = True
            steps_indent = indent
            item_indent = None
            output.append(line)
            continue

        if in_steps and indent == item_indent and is_item:
            flush_step()
            current_step = [line]
            continue

        if current_step:
            current_step.append(line)
        else:
            output.append(line)

    flush_step()
    return output


def add_signing_step_password(step_lines: Sequence[str]) -> list[str]:
    """Give the signing step its own COSIGN_PASSWORD.

    The key this tool generates is password-protected, and the step used to
    read that password from the job environment. Once the job stops carrying
    it, the step has to carry it, or `cosign sign` cannot decrypt the key --
    a failure that would only appear on someone else's first push.
    """
    lines = list(step_lines)
    # By parsed key name, so a quoted or spaced `"COSIGN_PRIVATE_KEY":` is
    # the same key (#525, #698).
    if any(workflow_key(line.strip()) == "COSIGN_PASSWORD" for line in lines):
        return lines
    for index, line in enumerate(lines):
        stripped = line.strip()
        if workflow_key(stripped) == "COSIGN_PRIVATE_KEY":
            indent = line[: len(line) - len(line.lstrip())]
            return lines[: index + 1] + [f"{indent}COSIGN_PASSWORD: ${{{{ secrets.COSIGN_PASSWORD }}}}"] + lines[index + 1 :]
    # No key in this step's own env means the shape is not the one this
    # understands. Leaving it alone is the same no-op convention every patcher
    # here follows; the generated-workflow test is what makes that loud.
    return lines


def patch_workflow_signing_steps(workflow_text: str, *, branch_if: str, sign_if: str) -> str:
    return "\n".join(
        patch_workflow_steps(
            workflow_text,
            lambda step: patch_signing_step_block(step, branch_if=branch_if, sign_if=sign_if),
        )
    )


# A YAML mapping key, bare or quoted in either style, with optional
# whitespace before the colon. Each spelling is its own group; the key name
# is whichever one matched.
#   push:
#   workflow_dispatch: # allow manually triggering builds
#   "SIGNING_ENABLED": ...
#   'build_push':
#   env :
WORKFLOW_KEY_PATTERN = r"""(?:"([^"]+)"|'([^']+)'|([A-Za-z_][A-Za-z0-9_.-]*))\s*:"""
WORKFLOW_KEY_RE = re.compile(rf"^{WORKFLOW_KEY_PATTERN}(?=\s|$)")


def workflow_key_name(match: re.Match[str] | None) -> str | None:
    """The key a WORKFLOW_KEY_PATTERN match names, without its quotes."""
    if match is None:
        return None
    return next(group for group in match.groups()[:3] if group is not None)


def workflow_key(stripped_line: str) -> str | None:
    """Return the mapping key a stripped YAML line declares, if any.

    Comparing against a literal "push:" misses the equally valid
    "push: # only the default branch", and the bundled snapshots do carry
    inline comments on trigger keys. It misses `"SIGNING_ENABLED":`,
    `'env':` and `env :` too, all of which YAML reads as the same key, and a
    patcher that decides a key is absent writes a second one beside it --
    which Actions rejects outright (#525). So the key is compared by the
    name it parses to, never by its spelling.

    This deliberately also matches keys carrying an inline value, such as
    "push: { branches: [main] }" - a sibling key with a value still ends the
    previous trigger's block. Use workflow_block_key() when deciding whether a
    key opens a block that nested lines may be appended under.
    """
    return workflow_key_name(WORKFLOW_KEY_RE.match(stripped_line))


# Like WORKFLOW_KEY_RE, but only when nothing follows the colon except an
# optional inline comment - i.e. the key opens a block mapping.
WORKFLOW_BLOCK_KEY_RE = re.compile(rf"^{WORKFLOW_KEY_PATTERN}\s*(?:#.*)?$")


def workflow_block_key(stripped_line: str) -> str | None:
    """Return the key only when the line opens a block (no inline value).

    workflow_key() answers "which key does this line declare" and is right for
    sibling detection, but appending nested lines under a key is only valid
    when the key has no value of its own: "push: { branches: [main] }" already
    carries an inline flow mapping, and writing "branches:" beneath it produces
    a YAML parse error, not a patched workflow.

    Quoted keys count here as they do there. A quoted job ID such as
    `"build_push":` is legal and some owners' editors emit it; a walk that
    did not see it dropped the whole job from workflow_job_ranges(), its
    guards still got rewritten to test env.SIGNING_ENABLED, no job was found
    to define the variable in, and the image shipped unsigned on a green run.
    """
    return workflow_key_name(WORKFLOW_BLOCK_KEY_RE.match(stripped_line))


# The top-level `on:` key opening the trigger block, in every spelling YAML
# and Actions read as that one key: `on:`, `"on":`, `'on':` and `on :`.
WORKFLOW_ON_BLOCK_RE = re.compile(r"""^(?:on|"on"|'on')\s*:\s*(?:#.*)?$""")


def is_workflow_on_block(stripped_line: str) -> bool:
    """Whether a top-level line opens the workflow's trigger block.

    workflow_block_key() knows only the bare spelling, and a patcher scoped to
    the `on:` block through it silently skips every trigger under `"on":`,
    which an owner's editor or YAML dumper may well write.
    """
    return WORKFLOW_ON_BLOCK_RE.match(stripped_line) is not None


def block_sequence_entry_indent(lines: list[str], key_index: int) -> str:
    """Indent for a new entry in the block sequence under ``lines[key_index]``.

    YAML asks only that a sequence's entries agree with each other, not that
    they sit two spaces in from their key, and an editor's reformat is enough
    to put them at four. An entry written at key indent plus two beside
    entries at plus four mixes indentation inside one sequence, which Actions
    rejects outright -- the repo stops building instead of merely missing an
    ignore. So copy the indent of the first entry that follows the key, and
    fall back to key indent plus two only when the list is empty.
    """
    key_line = lines[key_index]
    key_indent = key_line[: len(key_line) - len(key_line.lstrip())]
    for line in lines[key_index + 1 :]:
        stripped = line.strip()
        if not stripped or stripped.startswith("#"):
            continue
        indent = line[: len(line) - len(line.lstrip())]
        # A sequence may also sit at its key's own indent; YAML allows both.
        if len(indent) >= len(key_indent) and stripped.startswith("- "):
            return indent
        break
    return key_indent + "  "


# A key whose value is an inline flow sequence, "paths-ignore: ['**.md']",
# with an optional trailing comment. The items group is non-greedy so the
# comment's own brackets, if any, stay in the suffix.
WORKFLOW_FLOW_SEQUENCE_LINE_RE = re.compile(r"^(\s*[^\s#][^:]*:\s*)\[(.*?)\](\s*(?:#.*)?)$")


def extend_flow_sequence_line(line: str, item: str) -> str | None:
    """Return ``line`` with ``item`` appended to its inline flow sequence.

    "paths-ignore: ['**.md']" is the same trigger filter as the block form
    the bundled snapshots use, and a repository owner may well collapse it to
    one line. Writing a block "- item" beneath it is not a list entry, it is
    a parse error, and GitHub then runs nothing from the file at all - a
    worse outcome than the no-op the other patchers fall back to. So the
    sequence is extended in place instead. Returns None when the line is not
    a flow sequence, so the caller can go on to the block-form insert. An
    empty list becomes "[item]" rather than "[, item]", and a list that
    already ends in a comma - "['**.md',]" is valid YAML - is not given a
    second one. ``item`` is written verbatim, so pass it already quoted. A
    trailing comment is kept: the bundled BlueBuild snapshot carries one on
    this very key.
    """
    match = WORKFLOW_FLOW_SEQUENCE_LINE_RE.match(line)
    if not match:
        return None
    prefix, items, suffix = match.groups()
    # Drop surrounding whitespace and any trailing comma so the separator
    # written below is the only one before the new item: "['**.md',, 'x']"
    # is a parse error, and a quoted item ending in a comma keeps its
    # closing quote, so only a bare separator is removed here.
    items = items.strip().rstrip(",").rstrip()
    return f"{prefix}[{items}, {item}]{suffix}" if items else f"{prefix}[{item}]{suffix}"


def block_mapping_entry_indent(lines: Sequence[str], key_index: int) -> str:
    """Indent for a new entry in the block mapping under ``lines[key_index]``.

    The mapping twin of block_sequence_entry_indent(), and the same trap
    (#524). YAML asks only that a mapping's keys agree with each other, so a
    `with:` or `env:` whose entries an editor put four in from the key is
    valid. A key written at plus two above them closes the mapping there,
    and the owner's first entry after it is a parse error. So copy the
    indent of the first entry below the key, and fall back to key indent
    plus two only when the mapping is empty.
    """
    key_line = lines[key_index]
    key_indent = len(key_line) - len(key_line.lstrip())
    for line in lines[key_index + 1 :]:
        stripped = line.strip()
        if not stripped or stripped.startswith("#"):
            continue
        indent = len(line) - len(line.lstrip())
        if indent > key_indent:
            return line[:indent]
        break
    return key_line[:key_indent] + "  "


# The line a block scalar opens on: a `key:` or a `- ` item, or both, whose
# value is `|` or `>` with optional indentation and chomping indicators and
# an optional comment. `node` ends where the scalar's parent starts: at the
# key when there is one, after the last dash otherwise.
BLOCK_SCALAR_HEADER_RE = re.compile(
    r"^(?P<node>\s*(?:-\s+)*)(?P<key>[^\s#-][^#]*?:\s+|-\S[^#]*?:\s+)?[|>][1-9]?[-+]?[1-9]?\s*(?:#.*)?$"
)


def block_scalar_body_indexes(lines: Sequence[str]) -> set[int]:
    """Return the indexes of every line that is the body of a block scalar.

    A `run: |` script is text to YAML, whatever it looks like. A line in one
    that reads `permissions:` or `IMAGE_DESC: x` is a line of the owner's
    shell, and a patcher that takes it for a key rewrites their script
    (#524). The body is every line deeper than the scalar's parent node,
    blank lines included, up to the first line that is not.
    """
    body: set[int] = set()
    parent: int | None = None
    for index, line in enumerate(lines):
        stripped = line.strip()
        indent = len(line) - len(line.lstrip())
        if parent is not None:
            if not stripped or indent > parent:
                body.add(index)
                continue
            parent = None
        match = BLOCK_SCALAR_HEADER_RE.match(line)
        if match is None:
            continue
        node = match.group("node")
        if match.group("key") is not None:
            parent = len(node)
        elif "-" in node:
            # A bare `- |` item: its parent is the sequence, at the dash.
            parent = len(node.rstrip()) - 1
    return body


def add_paths_ignore_entry(lines: list[str], item: str, anchors: Iterable[str]) -> list[str]:
    """Return ``lines`` with ``item`` added to the first `paths-ignore:` list.

    The list may be written three ways, and a block "- item" is right for
    only one of them. Under any flow list it is a parse error, and GitHub
    then runs nothing from the file.

    - A block sequence takes a new entry at the indent of its existing
      entries (block_sequence_entry_indent, #359).
    - A one-line flow list is extended in place (extend_flow_sequence_line,
      #358).
    - A flow list spread over lines, the way prettier writes a long one --
      `paths-ignore: [` or a `[` on the next line, items, then `]` -- takes
      the item straight after its `[` (#524). That is the one place in the
      list whose syntax is known without finding the matching bracket: an
      item and a comma, before whatever followed, and a trailing comma
      before `]` is valid YAML.

    Any other value -- a scalar, an alias, a tag -- is not a list this can
    extend, so the lines come back unchanged, like any patcher's no-op.

    The key is matched by its parsed name, so `"paths-ignore":` and
    `paths-ignore :` are the same key (#525, #698). A workflow with no key
    this reads gets the entry after the first ``anchors`` line instead, the
    snapshot's own list item -- but only one that no other key holds. Tested
    line by line ahead of the key, an anchor in `pull_request.paths:` won,
    and the state file landed in a positive filter instead (#698).
    """
    for index, line in enumerate(lines):
        stripped = line.strip()
        key = WORKFLOW_KEY_RE.match(stripped)
        if key is None or workflow_key_name(key) != "paths-ignore":
            continue
        extended = extend_flow_sequence_line(line, item)
        if extended is not None:
            return [*lines[:index], extended, *lines[index + 1 :]]
        value = stripped[key.end() :].lstrip()
        opener = index
        if not value or value.startswith("#"):
            key_indent = len(line) - len(line.lstrip())
            opener = next(
                (
                    at
                    for at in range(index + 1, len(lines))
                    if lines[at].strip() and not lines[at].strip().startswith("#")
                ),
                len(lines),
            )
            opened = lines[opener] if opener < len(lines) else ""
            if not (opened.lstrip().startswith("[") and len(opened) - len(opened.lstrip()) > key_indent):
                return [*lines[: index + 1], f"{block_sequence_entry_indent(lines, index)}- {item}", *lines[index + 1 :]]
        elif not value.startswith("["):
            return lines
        opened = lines[opener]
        bracket = opened.index("[")
        rest = opened[bracket + 1 :].lstrip()
        patched = f"{opened[: bracket + 1]}{item}," + (f" {rest}" if rest else "")
        return [*lines[:opener], patched, *lines[opener + 1 :]]
    anchor_set = set(anchors)
    for index, line in enumerate(lines):
        if line.strip() not in anchor_set or enclosing_workflow_key(lines, index) not in (None, "paths-ignore"):
            continue
        indent = line[: len(line) - len(line.lstrip())]
        return [*lines[: index + 1], f"{indent}- {item}", *lines[index + 1 :]]
    return lines


def enclosing_workflow_key(lines: Sequence[str], item_index: int) -> str | None:
    """The key whose block sequence holds the `- ` item at ``lines[item_index]``.

    That is the nearest line above with content that is shallower than the
    item, or at its indent and not itself an item: YAML lets a sequence sit
    at its key's own indent. None when that line is not a key this reads.
    """
    item = lines[item_index]
    item_indent = len(item) - len(item.lstrip())
    for line in reversed(lines[:item_index]):
        stripped = line.strip()
        if not stripped or stripped.startswith("#"):
            continue
        indent = len(line) - len(line.lstrip())
        if indent < item_indent or (indent == item_indent and not stripped.startswith("-")):
            return workflow_key(stripped)
    return None


# The oldest Cosign release the generated signing step works with. Workflows
# pinned below it are raised to it; anything at or above it is the owner's
# choice and stays. The bundled snapshot pins this same version.
COSIGN_COMPATIBILITY_FLOOR = "v3.1.2"
# A whole line that is the `cosign-release:` input: the key at the start of
# the line, in any spelling, a value, and nothing after it but an optional
# comment. Anchoring both ends is what keeps a shell line that merely
# mentions the input -- `run: echo "cosign-release: '2.6.3'"` -- from being
# rewritten. The value may be quoted or plain: `cosign-release: v2.2.4` is
# the same string, and missing it left the release below the floor while
# the signing step still gained flags that release rejects (#525).
COSIGN_RELEASE_LINE_RE = re.compile(
    rf"""^(?P<prefix>\s*{yaml_key_pattern("cosign-release")}\s*)"""
    r"""(?:(?P<quote>['"])(?P<quoted>[^'"]*)(?P=quote)|(?P<plain>[^\s'"#]\S*))"""
    r"""(?P<suffix>\s*(?:#.*)?)$"""
)


def cosign_release_tuple(release: str) -> tuple[int, int, int] | None:
    """Parse a `cosign-release:` value like `v3.1.2` into (3, 1, 2).

    Returns None for anything that is not a plain version, so the caller can
    leave it alone rather than guess.
    """
    match = re.fullmatch(r"v?(\d+)\.(\d+)\.(\d+)", release.strip())
    if match is None:
        return None
    major, minor, patch = (int(part) for part in match.groups())
    return major, minor, patch


def raise_cosign_release_floor(step_lines: Sequence[str]) -> list[str]:
    """Raise a below-floor `cosign-release:` input of a cosign-installer step.

    Only the installer step's own `with:` block is looked at. The workflow is
    patched in place, so the same text anywhere else -- in an owner's `run:`
    script, a comment, another action that happens to take an input of that
    name -- is theirs and stays as written.
    """
    if not step_uses_action(step_lines, "sigstore/cosign-installer"):
        return list(step_lines)
    floor = cosign_release_tuple(COSIGN_COMPATIBILITY_FLOOR)
    patched: list[str] = []
    with_indent: int | None = None
    for line in step_lines:
        stripped = line.strip()
        indent = len(line) - len(line.lstrip())
        if with_indent is not None and stripped and not stripped.startswith("#") and indent <= with_indent:
            with_indent = None
        if with_indent is None:
            if workflow_block_key(stripped.removeprefix("- ").lstrip()) == "with":
                with_indent = indent
            patched.append(line)
            continue
        match = COSIGN_RELEASE_LINE_RE.match(line)
        if match is not None:
            quote = match.group("quote") or ""
            current = cosign_release_tuple(match.group("quoted") if quote else match.group("plain"))
            if current is not None and current < floor:
                line = f"{match.group('prefix')}{quote}{COSIGN_COMPATIBILITY_FLOOR}{quote}{match.group('suffix')}"
        patched.append(line)
    return patched


def patch_cosign_compatibility(workflow_text: str) -> str:
    """Keep existing managed workflows compatible with Cosign 3.x.

    Only versions below COSIGN_COMPATIBILITY_FLOOR are raised, and only on the
    cosign-installer step's own `cosign-release:` input. An unconditional
    rewrite meant every update reverted an owner's deliberate bump to a newer
    3.x or a 4.x release, so a security patch they applied was undone the next
    time they ran the tool.
    """
    lines = patch_workflow_steps(workflow_text, raise_cosign_release_floor)

    # `cosign sign` is routinely written across shell line continuations, so the
    # guard has to consider the whole logical command. Testing each physical
    # line in isolation meant a split invocation matched nothing - the verb line
    # has no `--key env://` and the key line has no `cosign sign` - and the
    # workflow was published still carrying the exact Cosign 3.x incompatibility
    # this function exists to remove.
    #
    # The verb has to be followed by whitespace or the end of the line, not a
    # mere word boundary: a hyphen is one, so `\bcosign\s+sign\b` also matched
    # the `sign` inside `cosign sign-blob`, and the flags were spliced into the
    # middle of that subcommand's name. `cosign sign --new-bundle-format=false
    # --use-signing-config=false-blob` is not a command, and an owner who signs
    # an SBOM or ISO checksum with the same key found out on their next push.
    verb_re = r"\bcosign(\s+)sign(?=\s|$)"
    index = 0
    while index < len(lines):
        start = index
        while lines[index].rstrip().endswith("\\") and index + 1 < len(lines):
            index += 1
        logical = " ".join(part.rstrip().rstrip("\\") for part in lines[start:index + 1])
        index += 1
        if not re.search(verb_re, logical):
            continue
        if "--key env://" not in logical or "--new-bundle-format=" in logical:
            continue
        # Insert directly after the `cosign sign` verb instead of matching a
        # literal "cosign sign -y " prefix. The confirmation flag may be spelled
        # --yes, may be absent, or may sit on a later continuation line, and in
        # each of those cases the old prefix replace silently did nothing while
        # the guard above reported the line as needing a fix.
        for offset in range(start, index):
            patched, count = re.subn(
                verb_re,
                r"cosign\1sign --new-bundle-format=false --use-signing-config=false",
                lines[offset],
                count=1,
            )
            if count:
                lines[offset] = patched
                break
        else:
            # The verb itself is split across a continuation. Rather than
            # publishing a workflow we know signs incompatibly, fail closed.
            raise CommandError(
                "This workflow has a 'cosign sign --key env://' command that needs the Cosign 3.x "
                "compatibility flags, but the 'cosign sign' command is split across line "
                "continuations in a way this tool cannot rewrite safely. Add "
                "'--new-bundle-format=false --use-signing-config=false' to that command by hand, "
                "then run this update again."
            )
    return "\n".join(lines)


# A job-level `env: {}` -- an empty flow mapping, optionally commented, the
# key in any spelling. It holds nothing, so it can be unwrapped into a block
# and entries written beneath it; `env: { FOO: bar }` cannot, and is handled
# separately.
WORKFLOW_EMPTY_ENV_RE = re.compile(rf"^({yaml_key_pattern('env')})\s*\{{\s*\}}\s*(#.*)?$")


def workflow_job_ranges(lines: Sequence[str]) -> list[tuple[str, int, int]]:
    """Return (name, start, end) for every job in a workflow, as line indexes.

    A job is a key, bare or quoted, at two-space indentation inside the
    top-level `jobs:` block. Its range runs from that key up to the next job
    key, or to the first line that leaves the block. Blank lines and
    comments end nothing, so a job keeps the trailing blank line that
    separates it from the next.
    """
    ranges: list[tuple[str, int, int]] = []
    in_jobs = False
    name: str | None = None
    start = 0
    for index, line in enumerate(lines):
        stripped = line.strip()
        if not stripped or stripped.startswith("#"):
            continue
        indent = len(line) - len(line.lstrip())
        if indent == 0:
            if name is not None:
                ranges.append((name, start, index))
                name = None
            in_jobs = workflow_block_key(stripped) == "jobs"
            continue
        if in_jobs and indent == 2:
            key = workflow_block_key(stripped)
            if key is None:
                continue
            if name is not None:
                ranges.append((name, start, index))
            name, start = key, index
    if name is not None:
        ranges.append((name, start, len(lines)))
    return ranges


def workflow_job_level_key_index(job: Sequence[str], key: str) -> int | None:
    """Return the index within `job` of the first job-level line declaring `key`.

    Job-level keys sit at exactly four spaces. The match goes through
    workflow_key() rather than a literal `    env:` so a key carrying a
    comment or trailing whitespace (`env: # build settings`, `env: `) is
    found and extended instead of missed and duplicated (#345).
    """
    for index, line in enumerate(job):
        if line.startswith("    ") and not line.startswith("     ") and workflow_key(line.strip()) == key:
            return index
    return None


def workflow_job_env_keys(job: Sequence[str], env_at: int) -> set[str]:
    """Return the names of the keys directly under the job-level `env:` at `env_at`.

    The block runs until the first non-blank, non-comment line at the job's
    own indentation or shallower; only its direct children count. Those sit
    at whatever indent the block's first entry uses -- six in every workflow
    this tool writes, eight after an editor's reformat, and counting only
    six there found nothing and wrote a duplicate key (#524). Other keys sit
    at that depth too -- the job's `outputs:` entries, a step-level `env:`
    -- and taking one of those for the job env entry leaves the real block
    without it while every guard that tests the variable goes on reading it
    undefined.
    """
    entry_indent = len(block_mapping_entry_indent(job, env_at))
    defined: set[str] = set()
    for line in job[env_at + 1 :]:
        stripped = line.strip()
        if not stripped or stripped.startswith("#"):
            continue
        indent = len(line) - len(line.lstrip())
        if indent <= 4:
            break
        if indent == entry_indent:
            key = workflow_key(stripped)
            if key is not None:
                defined.add(key)
    return defined


def ensure_workflow_job_env_entries(workflow_text: str, entries: Sequence[tuple[str, str]]) -> str:
    """Define each variable, at job level, in every job that reads it.

    A job reads a variable when one of its lines refers to `env.<NAME>` --
    the shape of the signing guard's step condition. Defining the variable
    anywhere else does nothing: job env does not reach across jobs, so a
    guard in `build_push` testing a variable defined in a `lint` job the
    owner added ahead of it is false forever, both cosign steps are skipped,
    and the image is published unsigned while the run stays green. That is
    what searching the whole file for the first `env:` did (#344).

    Within a job, presence is decided by key name, not by comparing the
    whole line to the value this tool would write. An owner who renamed the
    secret the value reads (`secrets.COSIGN_KEY`), or hung a comment on the
    line, has still defined the key -- and GitHub rejects a workflow with a
    duplicate mapping key (`'SIGNING_ENABLED' is already defined`), so
    writing our line next to theirs stops the repository building until
    they hand-edit it (#345). The differing value is theirs and is left as
    it is; the update preview then shows nothing to change for that key,
    which is the truth. Only a key nested under the job-level `env:` block
    this tool extends counts as defined -- see workflow_job_env_keys().

    An existing job-level `env:` is extended whatever follows the colon -- a
    comment, trailing whitespace, or an empty `{}` that is unwrapped into a
    block. The one shape that cannot take nested entries is an `env:` with
    an inline value, and the alternative to stopping there is a second
    `env:` key in the same job, which the parser rejects, so that shape
    fails closed. Without any `env:` the block is opened above `steps:`.

    A job that reads the variable but has neither an `env:` nor a `steps:`
    key at the expected indentation cannot be patched, and the only outcome
    of leaving it is the silent-unsigned one above. So that case fails
    closed with a message saying what to add by hand. So does a reference
    that sits outside every job this parser recognizes -- a job nested at
    an indentation it does not expect, say -- because a reader the walk
    cannot see is a reader that never gets its definition. A workflow in
    which no job reads the variable needs nothing and is returned untouched.
    """
    lines = file_lines(workflow_text)
    changed = False
    for name, value in entries:
        entry = f"{name}: {value}"
        reads = re.compile(rf"\benv\.{re.escape(name)}\b")
        ranges = workflow_job_ranges(lines)
        covered = {index for _, start, end in ranges for index in range(start, end)}
        for index, line in enumerate(lines):
            if index in covered or line.lstrip().startswith("#") or not reads.search(line):
                continue
            raise CommandError(
                f"This workflow refers to env.{name} on line {index + 1}, outside every job this "
                f"tool recognizes under 'jobs:', so it cannot tell which job to define the variable "
                f"in. Left undefined, every condition that tests it is false and the steps it guards "
                f"are skipped. Add '{name}: {value}' under that job's 'env:' by hand, then run this "
                f"update again."
            )
        # Walk the jobs back to front so an insertion never shifts a range
        # that is still to be visited.
        for job_name, start, end in reversed(ranges):
            job = lines[start:end]
            if not any(reads.search(line) for line in job if not line.lstrip().startswith("#")):
                continue
            env_at = workflow_job_level_key_index(job, "env")
            if env_at is not None:
                if name in workflow_job_env_keys(job, env_at):
                    continue
                stripped = job[env_at].strip()
                empty = WORKFLOW_EMPTY_ENV_RE.match(stripped)
                if empty:
                    key_text, comment = empty.groups()
                    lines[start + env_at] = f"    {key_text}" + (f" {comment}" if comment else "")
                elif workflow_block_key(stripped) != "env":
                    raise CommandError(
                        f"This workflow's '{job_name}' job-level 'env:' carries an inline value "
                        f"({stripped!r}), so this tool cannot add '{name}' beneath it, and writing a "
                        f"second 'env:' key would stop the workflow parsing. Rewrite that 'env:' as a "
                        f"block mapping with one entry per line, then run this update again."
                    )
                lines.insert(start + env_at + 1, f"{block_mapping_entry_indent(job, env_at)}{entry}")
            else:
                steps_at = workflow_job_level_key_index(job, "steps")
                if steps_at is None:
                    raise CommandError(
                        f"This workflow's '{job_name}' job reads env.{name}, but the job has no 'env:' "
                        f"or 'steps:' key where this tool expects one, so it cannot define the variable "
                        f"there. Left undefined, every condition that tests it is false and the steps "
                        f"it guards are skipped. Add '{name}: {value}' under that job's 'env:' by hand, "
                        f"then run this update again."
                    )
                # Job-level keys are at four, so a new env block's entries go at six.
                lines[start + steps_at:start + steps_at] = ["    env:", f"      {entry}"]
            changed = True
    if not changed:
        return workflow_text
    return "\n".join(lines) + ("\n" if workflow_text.endswith("\n") else "")


class CommandError(RuntimeError):
    pass


class ScreenBack(RuntimeError):
    pass


def managed_path(base_dir: Path, relative: str) -> Path:
    # Every read and write the tool performs inside a managed repo goes through
    # here. The repo is a clone of whatever is on GitHub, and git checks out
    # symlinks as symlinks, so a file the tool believes it owns can be a
    # pointer at something outside the clone that it does not:
    #
    #     README.md -> /home/dan/.bashrc
    #
    # Python's open() follows that. `readme_path.write_text(...)` would then
    # rewrite the user's shell profile, on a host where the tool's own promise
    # is that it writes to GitHub and never to the running system. A directory
    # link is worse, because one of them redirects every generated file beneath
    # it, and worse again because it is silent: the symlink in the worktree is
    # unchanged by a write through it, so `git status` reports nothing and the
    # diff the update flow shows the user before pushing is empty.
    #
    # Getting there needs only a merged pull request to a user's own image
    # repo, which is a repo whose contents this tool otherwise treats as its
    # own output. Refuse rather than sanitize: there is no legitimate reason
    # for a managed file to be a link, and a repo that has one is telling us
    # something has gone wrong with it.
    #
    # Each component is checked, not just the last. `.github` being a link is
    # what redirects `.github/workflows/build.yml`, and `mkdir(parents=True,
    # exist_ok=True)` on a path under it succeeds quietly.
    current = base_dir
    for part in PurePosixPath(relative).parts:
        if part in ("", ".", "..") or "/" in part or "\\" in part:
            raise CommandError(f"Refusing to use `{relative}` as a path inside a managed repo.")
        current = current / part
        if current.is_symlink():
            raise CommandError(
                f"`{current.relative_to(base_dir)}` in this repo is a symbolic link, and this tool "
                "will not read or write through one. Replace it with a regular file or directory "
                "and run the update again."
            )
    return current


def run(
    args: Sequence[str],
    *,
    cwd: Path | None = None,
    env: dict[str, str] | None = None,
    check: bool = True,
    capture: bool = True,
    stdin: str | None = None,
) -> subprocess.CompletedProcess[str]:
    # This is the single subprocess helper used by most of the file. Keeping
    # command execution here centralizes our "raise CommandError with useful
    # text" behavior instead of repeating it around the app.
    #
    # Output is decoded leniently. The commands run here echo back content the
    # tool does not control -- `git diff` over a managed repo prints whatever
    # bytes a user's editor left in README.md, and a cp1252 curly quote is not
    # UTF-8. With strict decoding that one byte raised UnicodeDecodeError out
    # of the update flow's "View full diff?" step, which nothing in main()
    # catches, so the session died and the pending update with it (#372).
    # Showing U+FFFD in its place is the right outcome: the diff is still
    # readable, and the byte is the user's to fix in their own repo.
    proc = subprocess.run(
        list(args),
        cwd=str(cwd) if cwd else None,
        env=env,
        input=stdin,
        text=True,
        errors="replace",
        capture_output=capture,
        check=False,
    )
    if check and proc.returncode != 0:
        raise CommandError(command_failure_detail(args, proc))
    return proc


def command_failure_detail(args: Sequence[str], proc: subprocess.CompletedProcess[str]) -> str:
    # The one place that decides what a failed command looks like to the user:
    # the command's own stderr (or stdout when it wrote nothing there), then
    # the command line for context. Both run() and the spinner helpers raise
    # through here so a `gh` 404 reads the same whichever one ran it.
    stderr = proc.stderr.strip() if proc.stderr else ""
    stdout = proc.stdout.strip() if proc.stdout else ""
    body = stderr or stdout
    return f"{body} (command: {' '.join(args)})" if body else f"command failed: {' '.join(args)}"


class Gum:
    # Gum is used as a lightweight TUI toolkit. This wrapper smooths out a few
    # rough edges for the rest of the app:
    # - it normalizes Ctrl+C vs Esc/back behavior
    # - it computes widths consistently
    # - it hides the exact gum command lines from the workflow code
    def terminal_width(self) -> int:
        return shutil.get_terminal_size((MAX_UI_WIDTH, 24)).columns

    def content_width(self, *, max_width: int = MAX_UI_WIDTH, min_width: int = 40, reserve: int = 4) -> int:
        return max(min_width, min(max_width, self.terminal_width() - reserve))

    def form_width(self, *, max_width: int = 96, min_width: int = 40, reserve: int = 6) -> int:
        return max(min_width, min(max_width, self.terminal_width() - reserve))

    def terminal_available(self, *, stdin_inherited: bool = True) -> bool:
        # Mirrors how gum (bubbletea) finds its keyboard: the widget's own
        # stdin when that is a terminal, otherwise /dev/tty. Which of the two
        # a widget gets to try depends on how it was started. input, write and
        # the Enter prompt inherit this process's stdin; choose and filter get
        # their options through a pipe, so for them only /dev/tty counts.
        #
        # The two answers can differ. Under `setsid tool` with no redirect,
        # stdin is still the terminal the shell handed over, but the process
        # has no controlling terminal and /dev/tty fails with ENXIO: gum input
        # reads keys fine while gum choose exits 1 with "could not open a new
        # TTY". Asking about the parent's stdin for every widget read that
        # exit as Esc. A cron job or CI step has neither, and every widget
        # then fails before it draws anything.
        if stdin_inherited and sys.stdin.isatty():
            return True
        try:
            fd = os.open("/dev/tty", os.O_RDWR)
        except OSError:
            return False
        os.close(fd)
        return True

    def require_interactive_success(
        self, proc: subprocess.CompletedProcess[str], *, stdin_inherited: bool = True
    ) -> subprocess.CompletedProcess[str]:
        # gum v0.17.0 exits 130 for Ctrl+C and 1 for Esc ("nothing selected",
        # "not submitted"). Converting those to Python exceptions lets the rest
        # of the app reason about navigation instead of raw exit codes.
        #
        # Not every non-zero status is navigation, though, and reading one as
        # Esc hides it: main() turns ScreenBack into a quiet exit 0, so gum
        # failing outright looked like success to whatever ran the tool (#367).
        # gum exits 80 for a usage error (a flag value it could not parse,
        # #362) and 1 -- the same code as Esc -- when it has no terminal to
        # read from ("could not open a new TTY"). The exit code alone cannot
        # tell the second case from Esc, so ask the question gum asked: is
        # there a terminal? If not, nobody pressed anything. stdin_inherited
        # says whether the widget was given this process's stdin or a pipe
        # (see terminal_available()); the caller knows because it passed the
        # pipe's contents to interactive_stdout().
        if proc.returncode == 130:
            raise KeyboardInterrupt()
        if proc.returncode == 0:
            return proc
        command = [str(part) for part in proc.args]
        if proc.returncode == 1:
            if self.terminal_available(stdin_inherited=stdin_inherited):
                raise ScreenBack()
            raise CommandError(f"{' '.join(command[:2])} needs a terminal to read from, and this session has none")
        raise CommandError(f"command failed with exit status {proc.returncode}: {' '.join(command)}")

    def clear(self) -> None:
        if sys.stdout.isatty() and os.environ.get("TERM"):
            run(["clear"], capture=False, check=False)

    def interactive_stdout(self, args: Sequence[str], *, stdin: str | None = None) -> subprocess.CompletedProcess[str]:
        # We capture stdout for chooser/input widgets because that is how gum
        # returns the selected value. stderr is left attached to the terminal so
        # interactive drawing still appears on screen.
        return subprocess.run(
            list(args),
            input=stdin,
            text=True,
            stdout=subprocess.PIPE,
            stderr=None,
            check=False,
        )

    def ensure_available(self) -> None:
        if not command_exists("gum"):
            raise SystemExit("gum is required. Install it with: brew install gum")

    def style(self, *lines: str, **opts: str | int | bool) -> str:
        args = ["gum", "style"]
        for key, value in opts.items():
            flag = "--" + key.replace("_", "-")
            if isinstance(value, bool):
                if value:
                    args.append(flag)
            else:
                args.extend([flag, str(value)])
        # Everything after this point is content, not flags. Without the
        # separator, text that happens to start with a dash (buildah's "--> id"
        # step markers in a captured build log, a git error, a diff line) is
        # parsed as an unknown flag and gum exits 80, which run(check=True)
        # turns into a CommandError thrown from a *display* call.
        args.append("--")
        args.extend(lines)
        output = run(args).stdout.rstrip("\n")
        if output and not ANSI_RE.search(output):
            output = self.apply_ansi_fallback(output, **opts)
        return output

    def apply_ansi_fallback(self, text: str, **opts: str | int | bool) -> str:
        # gum style disables ANSI when we capture stdout through a pipe. Reapply
        # the basic text styling ourselves so headings and helper text remain
        # visible in normal terminals.
        #
        # Only where gum itself would have coloured, though. gum honours the
        # no-color.org convention (NO_COLOR set to any non-empty value means no
        # colour) and treats TERM=dumb -- Emacs M-x shell, serial consoles --
        # as a terminal that cannot render SGR codes, where they show up as
        # literal "[1;38;5;33m" around every header. Because we always read gum
        # through a pipe we never see its own decision, so mirror it here.
        term = os.environ.get("TERM")
        if not sys.stdout.isatty() or not term or term == "dumb":
            return text
        if os.environ.get("NO_COLOR"):
            return text
        codes: list[str] = []
        if opts.get("bold"):
            codes.append("1")
        if opts.get("faint"):
            codes.append("2")
        if opts.get("italic"):
            codes.append("3")
        if opts.get("underline"):
            codes.append("4")
        if opts.get("strikethrough"):
            codes.append("9")
        foreground = self.ansi_color_code(opts.get("foreground"), background=False)
        if foreground:
            codes.append(foreground)
        background = self.ansi_color_code(opts.get("background"), background=True)
        if background:
            codes.append(background)
        if not codes:
            return text
        return f"\x1b[{';'.join(codes)}m{text}\x1b[0m"

    def ansi_color_code(self, value: str | int | bool | None, *, background: bool) -> str | None:
        if value is None or isinstance(value, bool):
            return None
        if isinstance(value, int):
            return f"{48 if background else 38};5;{value}"
        text = str(value).strip()
        if not text:
            return None
        if text.isdigit():
            return f"{48 if background else 38};5;{text}"
        return None

    def log(self, level: str, message: str) -> None:
        run(["gum", "log", "--level", level, "--", message], capture=False)

    def success(self, message: str) -> None:
        self.log("info", message)

    def warn(self, message: str) -> None:
        self.log("warn", message)

    def error(self, message: str) -> None:
        self.log("error", message)

    def header(self, title: str, *, clear_screen: bool = True) -> None:
        if clear_screen:
            self.clear()
        print()
        print(self.style(f"━━━  {title}  ━━━", foreground=ACCENT_COLOR, bold=True))
        print()

    def hint(self, message: str) -> None:
        print(self.style(message, width=self.content_width()))

    def instruction(self, message: str) -> None:
        print(self.style(message, foreground=ACCENT_COLOR, bold=True, width=self.content_width()))

    def controls(self, *parts: str) -> None:
        label = self.style("Keys:", foreground=CONTROLS_COLOR, bold=True)
        print(f"{label} {' | '.join(parts)}")
        print()

    def write_controls(self) -> None:
        # Every widget runs with --no-show-help, so this is the only place a
        # user learns that `gum write` submits on Enter and needs Ctrl+J for a
        # newline. Without it, "one per line" on screen plus Enter after the
        # first name submitted a single entry with no explanation (#368).
        self.controls("Ctrl+J new line", "Enter submit", "Esc back", "Ctrl+C quit")

    def confirm(self, prompt: str, *, default: bool = True) -> bool:
        args = ["gum", "confirm", "--no-show-help"]
        args.append("--default=true" if default else "--default=false")
        # Separator last, so --default is still parsed as a flag and only the
        # prompt is positional. See the note in style().
        args.extend(["--", prompt])
        proc = run(args, check=False, capture=False)
        if proc.returncode == 130:
            raise KeyboardInterrupt()
        return proc.returncode == 0

    def input(
        self,
        *,
        prompt: str,
        value: str | None = None,
        placeholder: str | None = None,
        width: int | None = None,
    ) -> str:
        # Text the caller supplies goes in as one --flag=value token. Split
        # into two, a value that starts with a dash is read as the next flag
        # and gum exits 80 without ever drawing the prompt. The description
        # prompt shows the current description as its placeholder, so a
        # description like "- Doug's daily driver" could be typed in once and
        # never edited again: require_interactive_success() read the usage
        # error as Esc and the menu came straight back. See #362.
        args = ["gum", "input", "--no-show-help", f"--prompt={prompt}"]
        args.extend(["--prompt.foreground", str(ACCENT_COLOR), "--cursor.foreground", str(ACCENT_COLOR)])
        if value is not None:
            args.append(f"--value={value}")
        if placeholder is not None:
            args.append(f"--placeholder={placeholder}")
            args.extend(["--placeholder.foreground", str(MUTED_COLOR)])
        if width is not None:
            args.extend(["--width", str(width)])
        return self.require_interactive_success(self.interactive_stdout(args)).stdout.rstrip("\n")

    def write(self, *, placeholder: str, height: int, width: int) -> str:
        return self.require_interactive_success(
            self.interactive_stdout(
                [
                    "gum",
                    "write",
                    "--no-show-help",
                    f"--placeholder={placeholder}",
                    "--placeholder.foreground",
                    str(MUTED_COLOR),
                    "--cursor.foreground",
                    str(ACCENT_COLOR),
                    "--height",
                    str(height),
                    "--width",
                    str(width),
                ]
            )
        ).stdout.rstrip("\n")

    def choose(
        self,
        options: Sequence[str],
        *,
        height: int = 10,
        no_limit: bool = False,
        selected: Sequence[str] | None = None,
        header: str | None = None,
        label_delimiter: str | None = None,
        cursor_prefix: str | None = None,
        selected_prefix: str | None = None,
        unselected_prefix: str | None = None,
    ) -> list[str]:
        args = ["gum", "choose", "--no-show-help", "--height", str(height)]
        args.extend(
            [
                "--cursor.foreground",
                str(ACCENT_COLOR),
                "--header.foreground",
                str(ACCENT_COLOR),
                "--selected.foreground",
                str(ACCENT_COLOR),
            ]
        )
        if no_limit:
            args.append("--no-limit")
        # The text flags are single --flag=value tokens for the reason given in
        # input(): a pre-selected entry or a header that starts with a dash
        # would otherwise be parsed as a flag and abort the chooser with exit
        # 80, which reads as Esc.
        if selected:
            # gum splits --selected on commas, so an entry that contains one
            # arrives as two fragments and pre-selects nothing. Its parser
            # honours a backslash before the separator; a plain backslash is
            # kept as-is, so nothing else needs escaping.
            args.append("--selected=" + ",".join(item.replace(",", "\\,") for item in selected))
        if header:
            args.append(f"--header={header}")
        if label_delimiter is not None:
            args.append(f"--label-delimiter={label_delimiter}")
        if cursor_prefix is not None:
            args.append(f"--cursor-prefix={cursor_prefix}")
        if selected_prefix is not None:
            args.append(f"--selected-prefix={selected_prefix}")
        if unselected_prefix is not None:
            args.append(f"--unselected-prefix={unselected_prefix}")
        proc = self.require_interactive_success(
            self.interactive_stdout(args, stdin="\n".join(options) + "\n"), stdin_inherited=False
        )
        output = proc.stdout.strip("\n")
        return [line for line in output.splitlines() if line]

    def filter(self, options: Sequence[str], *, height: int = 20, placeholder: str = "Search...") -> str:
        proc = self.require_interactive_success(
            self.interactive_stdout(
                [
                    "gum",
                    "filter",
                    "--no-show-help",
                    "--height",
                    str(height),
                    f"--placeholder={placeholder}",
                    "--prompt.foreground",
                    str(ACCENT_COLOR),
                    "--header.foreground",
                    str(ACCENT_COLOR),
                    "--selected-indicator.foreground",
                    str(ACCENT_COLOR),
                    "--match.foreground",
                    str(ACCENT_COLOR),
                    "--placeholder.foreground",
                    str(MUTED_COLOR),
                ],
                stdin="\n".join(options) + "\n",
            ),
            stdin_inherited=False,
        )
        return proc.stdout.strip()

    def pager(self, text: str) -> None:
        # gum pager exits 0 for q and Esc and 130 for Ctrl+C, like every other
        # widget. Left on run()'s default check=True, the 130 surfaced as
        # "command failed: gum pager" -- the one screen where the Ctrl+C the
        # hints promise would quit produced an error instead, and in the update
        # flow that error aborted the update.
        #
        # Not through require_interactive_success(), though. For the chooser
        # and input widgets a non-zero exit other than 130 is Esc, so that
        # helper turns it into ScreenBack. The pager exits 0 for Esc, so any
        # other status is gum itself failing -- v0.17.0 exits 1 with "unable
        # to read stdin" when it has no terminal -- and reading that as "the
        # user went back" would hide it: main() turns ScreenBack into a quiet
        # exit 0, and push_update() would drop the update without a word.
        # That case stays the CommandError it always was.
        proc = run(["gum", "pager"], capture=False, check=False, stdin=text)
        if proc.returncode == 130:
            raise KeyboardInterrupt()
        if proc.returncode != 0:
            raise CommandError("command failed: gum pager")

    def table(self, rows: Sequence[Sequence[str]], *, columns: str) -> None:
        # --print is what makes this a display widget. Without it `gum table` is
        # an interactive row picker: it draws the rows, highlights one, shows a
        # "1/4 navigate / enter select" footer and blocks. Every screen that
        # showed a table therefore stopped there, and everything meant to follow
        # it -- hints, controls, the package chooser -- never ran, so the screen
        # looked like a table floating above an empty page.
        #
        # --print also means gum sizes every column to its widest cell and
        # ignores --widths (v0.17.0), so fitting the terminal is done here. One
        # long value -- a digest-pinned image reference is over 110 characters
        # -- otherwise pushed the box past the edge, and the terminal wrapped
        # its border into a broken mess (#515).
        fitted = self.fit_table_rows(rows, headers=columns.split(","))
        text = "\n".join("\t".join(row) for row in fitted) + "\n"
        run(
            ["gum", "table", "--print", "--separator", "\t", "--columns", columns],
            capture=False,
            stdin=text,
        )

    def fit_table_rows(self, rows: Sequence[Sequence[str]], *, headers: Sequence[str]) -> list[list[str]]:
        # Wraps the last column so the rendered table is no wider than
        # content_width(). gum draws each column as its widest cell (header
        # included) plus a space either side, with a border before, between and
        # after the columns: 3 per column plus 1. The other columns keep their
        # width; they hold labels, and the long values sit in the last one.
        #
        # Each wrapped line past the first becomes a row of its own with the
        # other cells blank. --print draws no rule between rows, so it reads as
        # one cell over several lines, and it keeps the input free of CSV
        # quoting, which a newline inside a cell would need.
        leading = [max(len(cell) for cell in column) for column in zip(headers, *rows)][:-1]
        # Never narrower than the header: gum would draw the column that wide
        # anyway, and it keeps the width positive on the narrowest terminal.
        budget = max(len(headers[-1]), self.content_width() - sum(leading) - 3 * len(headers) - 1)
        fitted: list[list[str]] = []
        for row in rows:
            *first, last = row
            lines = [last] if len(last) <= budget else textwrap.wrap(last, budget, break_on_hyphens=False) or [""]
            fitted.append([*first, lines[0]])
            fitted.extend([*([""] * len(first)), line] for line in lines[1:])
        return fitted

    def require_spinner_success(
        self, proc: subprocess.CompletedProcess[str], args: Sequence[str]
    ) -> subprocess.CompletedProcess[str]:
        # gum spin uses exit code 130 for Ctrl+C, same convention as the other
        # interactive widgets. Any other nonzero exit means the spinner itself
        # failed to run. That holds only because every spinner goes through
        # spinner_result(), whose `bash -c` wrapper ends in a `printf` of the
        # wrapped command's status, so bash -- and therefore gum, which exits
        # with its child's code -- returns 0 however that command fared. The
        # wrapped command's own status comes back in the status file and is
        # judged by the caller, not here.
        if proc.returncode == 130:
            raise KeyboardInterrupt()
        if proc.returncode != 0:
            raise CommandError(f"command failed: {' '.join(args)}")
        return proc

    def spinner(self, title: str, command: Sequence[str], *, cwd: Path | None = None) -> None:
        self.spinner_capture(title, command, cwd=cwd)

    def spinner_capture(self, title: str, command: Sequence[str], *, cwd: Path | None = None) -> str:
        # Runs the command under a spinner and returns its stdout, raising
        # CommandError if it failed. This used to hand the command straight to
        # `gum spin`, which exits with the child's code and, on a TTY, shows
        # none of its output. A `gh` 404 or an auth failure therefore surfaced
        # as "command failed: gum spin --spinner dot --title ... -- bash -c
        # ..." with the real reason discarded (#363). Capturing through
        # spinner_result() keeps the child's stderr, so the error the user
        # sees is the one `gh` wrote.
        proc = self.spinner_result(title, command, cwd=cwd)
        if proc.returncode == 130:
            # The wrapped command took the Ctrl+C: `gh` exits 130 on SIGINT,
            # as the shell convention has it. Handing the command straight to
            # gum spin used to surface that as gum's own 130, which
            # require_spinner_success() turns into KeyboardInterrupt and
            # main() into exit 130. The bash wrapper now keeps that status in
            # the file instead, so map it back here rather than report an
            # interrupted clone as a failed one.
            raise KeyboardInterrupt()
        if proc.returncode != 0:
            raise CommandError(command_failure_detail(command, proc))
        return proc.stdout

    def spinner_result(self, title: str, command: Sequence[str], *, cwd: Path | None = None) -> subprocess.CompletedProcess[str]:
        # gum spin does not give us structured output directly, so the command
        # runs inside `bash -c` with stdout, stderr and exit status each
        # redirected to a temporary file, and those are read back after the
        # spinner closes. Callers inspect the result themselves; nothing is
        # raised for a nonzero status.
        with ExitStack() as stack:
            with tempfile.NamedTemporaryFile(delete=False) as stdout_tmp:
                stdout_path = stdout_tmp.name
            stack.callback(Path(stdout_path).unlink, missing_ok=True)
            with tempfile.NamedTemporaryFile(delete=False) as stderr_tmp:
                stderr_path = stderr_tmp.name
            stack.callback(Path(stderr_path).unlink, missing_ok=True)
            with tempfile.NamedTemporaryFile(delete=False) as status_tmp:
                status_path = status_tmp.name
            stack.callback(Path(status_path).unlink, missing_ok=True)
            shell_command = (
                f"{shlex.join(command)} > {shlex.quote(stdout_path)} 2> {shlex.quote(stderr_path)}; "
                f"printf '%s' $? > {shlex.quote(status_path)}"
            )
            args = ["gum", "spin", "--spinner", "dot", "--title", title, "--", "bash", "-c", shell_command]
            self.require_spinner_success(run(args, cwd=cwd, capture=False, check=False), args)
            # Decoded the way run() decodes (#372): podman, dnf5 and gh print
            # whatever bytes they like, and a strict read of one that is not
            # UTF-8 raised UnicodeDecodeError, which nothing up to main()
            # catches, so the session died instead of reporting the failure.
            stdout = Path(stdout_path).read_text(encoding="utf-8", errors="replace")
            stderr = Path(stderr_path).read_text(encoding="utf-8", errors="replace")
            status_text = Path(status_path).read_text().strip()
            try:
                returncode = int(status_text)
            except ValueError:
                returncode = 1
            return subprocess.CompletedProcess(list(command), returncode, stdout, stderr)

    def enter_to_continue(self, placeholder: str = "Press Enter to continue...") -> None:
        self.instruction(placeholder)
        # A pause is an acknowledgement, not a screen: there is nothing to go
        # back to, and every placeholder names where Enter goes next. So Esc
        # means the same as Enter here. Left as ScreenBack it unwound past the
        # screen the prompt promised -- through main_menu() to main(), which
        # exits 0, discarding a filled-in wizard (#507). Only Esc is absorbed:
        # gum exiting 1 with no terminal is still a CommandError (#367), and
        # Ctrl+C still quits.
        try:
            self.require_interactive_success(
                self.interactive_stdout(
                    [
                        "gum",
                        "input",
                        "--no-show-help",
                        "--prompt",
                        "> ",
                        "--prompt.foreground",
                        str(ACCENT_COLOR),
                        "--cursor.foreground",
                        str(ACCENT_COLOR),
                        "--width",
                        "3",
                    ]
                )
            )
        except ScreenBack:
            pass


def parse_release_version(text: object) -> tuple[int, int, int] | None:
    """Parse a plain `X.Y.Z` release string; anything else is None."""
    if not isinstance(text, str):
        return None
    match = re.fullmatch(r"v?(\d+)\.(\d+)\.(\d+)", text.strip())
    if match is None:
        return None
    return int(match[1]), int(match[2]), int(match[3])


def refuse_newer_tool_version(state: object) -> None:
    """Stop when the repo was last written by a newer copy of this tool.

    Older tools would silently overwrite files that a newer release generated.
    A missing or unparsable `tool_version` keeps the old behaviour.
    """
    if not isinstance(state, dict):
        return
    recorded_text = state.get("tool_version")
    recorded = parse_release_version(recorded_text)
    running = parse_release_version(VERSION)
    if recorded is None or running is None or recorded <= running:
        return
    raise CommandError(
        f"This repo was last updated by {TOOL_NAME} {str(recorded_text).strip().lstrip('v')}, "
        f"which is newer than the {VERSION} you are running. "
        "Updating it with this older version could overwrite newer generated files. "
        "Upgrade first: `brew upgrade` (Homebrew install) or `podman pull` "
        "(container image), then run this again."
    )


class App:
    def __init__(self) -> None:
        # The app keeps a small amount of session state beyond Config:
        # - GitHub login information discovered during preflight
        # - temporary signing/public-key data while creating or updating a repo
        # - memoized host package lookups so repeated manual checks are faster
        self.gum = Gum()
        self.config = Config()
        self.github_available = False
        self.github_user = ""
        self.generated_cosign_pub: str | None = None
        # Keyed by (spec, resolve_provides): "vim" is installable, through
        # Provides, and not removable, so the two screens' answers differ.
        self.package_lookup_cache: dict[tuple[str, bool], bool | None] = {}
        # The rpm -q answers live apart from the repo answers: the two
        # lookups ask different questions of different databases.
        self.installed_package_lookup_cache: dict[str, bool | None] = {}
        self.package_search_cache: dict[str, list[tuple[str, str]]] = {}
        self.package_lookup_warning_shown = False
        self.last_manual_package_check_had_missing = False
        self.removed_package_lookup_warning_shown = False
        self.last_manual_removed_package_check_had_missing = False

    def fresh_config(self) -> Config:
        # Starting a new create/scan flow should not inherit stale repo names or
        # package picks from the previous action the user ran in this session.
        return Config(github_user=self.github_user)

    def landing_panel_width(self) -> int:
        return self.gum.content_width(max_width=92, reserve=10)

    def landing_card(
        self,
        title: str,
        lines: Sequence[str],
        *,
        width: int,
        border_foreground: int,
        foreground: int = 252,
        background: int = 236,
    ) -> None:
        # Keep the landing screen visually consistent without repeating the
        # same gum style options for each intro card.
        print(
            self.gum.style(
                title,
                "",
                *lines,
                align="left",
                width=width,
                margin="0 2",
                padding="1 2",
                foreground=foreground,
                background=background,
                border_foreground=border_foreground,
                border="rounded",
            )
        )

    def banner(self) -> None:
        panel_width = self.landing_panel_width()
        print()
        print(self.gum.style(f"{TOOL_NAME}  v{VERSION}", align="center", width=panel_width, foreground=ACCENT_COLOR, bold=True))
        print(self.gum.style("GitHub-backed bootc image repo builder", align="center", width=panel_width, foreground=MUTED_COLOR))
        print(self.gum.style("for Universal Blue and Fedora Atomic desktops", align="center", width=panel_width, foreground=MUTED_COLOR))
        print()

    def startup_requirements(self) -> None:
        # This screen exists because GitHub is not optional for the beginner
        # tool. Telling users that up front is better than failing halfway
        # through the wizard after they already entered data.
        info_width = self.landing_panel_width()
        self.landing_card(
            "Before You Start",
            [
                "GitHub account required",
                "Log in first: gh auth login",
                "",
                "Official template repos",
                "Containerfile: ublue-os/image-template",
                "BlueBuild: blue-build/template",
                "Generated repos start from bundled snapshots",
                "of these official template repositories.",
                "Those templates work across this tool's",
                "supported images and change infrequently.",
            ],
            width=info_width,
            border_foreground=ACCENT_COLOR,
        )
        print()
        self.landing_card(
            "Important",
            [
                "Third-party tool",
                "Not an official Universal Blue utility",
                "Not an official Fedora Project utility",
                "",
                "Provided as-is",
                "Review changes before you push",
                "Keep backups where appropriate",
                "Repository damage, data loss, failed builds,",
                "and system changes are your risk.",
            ],
            width=info_width,
            border_foreground=NOTICE_COLOR,
        )
        print()
        self.gum.enter_to_continue("Press Enter to start the preflight checks...")

    def clear(self) -> None:
        self.gum.clear()

    def gh_json(self, args: Sequence[str]) -> object:
        # Small helper around "gh ... --json" style commands.
        proc = run(["gh", *args])
        return json.loads(proc.stdout or "null")

    def gh_json_with_spinner(self, title: str, args: Sequence[str]) -> object:
        # Networked GitHub queries can feel frozen without a spinner.
        output = self.gum.spinner_capture(title, ["gh", *args])
        return json.loads(output or "null")

    def github_login_name(self) -> str:
        try:
            data = self.gh_json(["api", "user"])
        except (CommandError, json.JSONDecodeError) as exc:
            raise CommandError(f"Unable to determine GitHub username: {exc}") from exc
        if not isinstance(data, dict):
            raise CommandError("Unable to determine GitHub username: unexpected API response.")
        login = data.get("login")
        if not isinstance(login, str) or not login.strip():
            raise CommandError("Unable to determine GitHub username: login field missing from API response.")
        return login.strip()

    def show_step_header(self, title: str, *, step: int, total_steps: int, next_hint: str | None = None) -> None:
        self.gum.header(title)
        if next_hint:
            self.gum.hint(next_hint)
        self.gum.hint(f"Step {step} of {total_steps}.")
        print()

    def format_task_choice(self, title: str, status: str) -> str:
        return f"{title:<24} {self.truncate_label(status, limit=56)}"

    def truncate_label(self, value: str, limit: int = 36) -> str:
        clean = " ".join(value.split())
        if len(clean) <= limit:
            return clean
        return clean[: limit - 3] + "..."

    def preview_values(self, values: Sequence[str], *, limit: int = 2, item_limit: int = 24) -> str:
        if not values:
            return ""
        shown = [self.truncate_label(value, limit=item_limit) for value in values[:limit]]
        remaining = len(values) - len(shown)
        if remaining > 0:
            shown.append(f"{remaining} more")
        return ", ".join(shown)

    def summarize_selection(self, values: Sequence[str], *, empty: str, verb: str, limit: int = 2) -> str:
        if not values:
            return empty
        preview = self.preview_values(values, limit=limit)
        if len(values) <= limit:
            return preview
        return f"{len(values)} {verb}: {preview}"

    def software_status(self) -> str:
        parts: list[str] = []
        if self.config.packages:
            parts.append(f"{len(self.config.packages)} pkg")
        if self.config.copr_repos:
            parts.append(f"{len(self.config.copr_repos)} COPR")
        if self.config.services:
            parts.append(f"{len(self.config.services)} svc")
        if self.config.removed_packages:
            parts.append(f"{len(self.config.removed_packages)} removed")
        if self.config.brew_enabled:
            parts.append("brew")
        return ", ".join(parts) or "No software changes yet"

    def repository_status(self) -> str:
        repo = f"{self.github_user}/{self.config.repo_name}" if self.github_user else self.config.repo_name or "(not set)"
        if not self.config.image_desc:
            return repo
        return f"{repo} | {self.truncate_label(self.config.image_desc, limit=28)}"

    def requested_packages_note(self) -> str:
        return "Selected packages are what this repo will attempt to add, even if some are already present in the chosen base image."

    def published_image_ref(self, owner: str | None = None) -> str:
        image_owner = (owner or self.config.github_user or self.github_user or "your-user").lower()
        return f"ghcr.io/{image_owner}/{self.config.repo_name}:latest"

    @staticmethod
    def bootc_switch_command(image_ref: str, *, signing_enabled: bool) -> str:
        enforce = "--enforce-container-sigpolicy " if signing_enabled else ""
        return f"sudo bootc switch {enforce}{image_ref}"

    def render_preflight_failure(
        self,
        *,
        missing_tools: Sequence[str],
        missing_host_tools: Sequence[str] = (),
        github_login_missing: bool = False,
        github_account_error: bool = False,
    ) -> None:
        brew_tools = [name for name in PRECHECK_REQUIRED_TOOLS if name in missing_tools and name in BREW_INSTALLABLE_TOOLS]
        host_tools = list(missing_host_tools)

        if command_exists("gum"):
            self.gum.ensure_available()
            self.gum.header("Preflight Failed", clear_screen=False)
            self.gum.warn("This tool requires all startup checks to pass before it can continue.")
            print()
            if missing_tools:
                self.menu_section("Missing Tools", ", ".join(missing_tools))
                print()
            if brew_tools:
                self.menu_section("Install With Homebrew", f"brew install {' '.join(brew_tools)}")
                print()
            if github_login_missing:
                self.menu_section("GitHub Login", "Run: gh auth login")
                print()
            if github_account_error:
                self.menu_section("GitHub Account Check", "Run: gh auth status && gh auth login")
                print()
            if host_tools:
                self.menu_section(
                    "Host Requirements",
                    f"Missing host tools: {', '.join(host_tools)}",
                    "This tool expects a supported rpm-ostree / bootc desktop image with dnf5 and rpm-ostree available.",
                )
                print()
            # Esc here leaves just as Enter does: enter_to_continue() reads
            # Esc as acknowledgement, so preflight() still raises its
            # SystemExit(1) and the wrapper sees the failure (#367).
            self.gum.enter_to_continue("Press Enter to exit to the terminal...")
            return

        print()
        print("Preflight Failed")
        print()
        print("This tool requires all startup checks to pass before it can continue.")
        if missing_tools:
            print()
            print(f"Missing tools: {', '.join(missing_tools)}")
        if brew_tools:
            print()
            print(f"Install with Homebrew: brew install {' '.join(brew_tools)}")
        if github_login_missing:
            print()
            print("Run: gh auth login")
        if github_account_error:
            print()
            print("Run: gh auth status && gh auth login")
        if host_tools:
            print()
            print(f"Missing host tools: {', '.join(host_tools)}")
            print()
            print("This tool expects a supported rpm-ostree / bootc desktop image with dnf5 and rpm-ostree available.")
        print()

    def menu_section(self, title: str, *lines: str) -> None:
        label = title if title.endswith((":", "?", "!")) else f"{title}:"
        self.gum.instruction(label)
        for line in lines:
            self.gum.hint(line)

    def render_package_menu_intro(
        self,
        *,
        packages_empty: str,
        packages_label: str = "Packages",
        include_copr: bool = False,
        include_services: bool = False,
        include_removed: bool = False,
        next_step_hint: str,
    ) -> None:
        self.menu_section(
            "Package Entry",
            "Search package names when you only know part of the RPM name. Use exact-name entry when you already know it.",
            self.requested_packages_note(),
        )
        print()
        current_lines = [
            f"{packages_label}: {self.summarize_selection(self.config.packages, empty=packages_empty, verb='selected')}"
        ]
        if include_copr:
            current_lines.append(f"COPR repositories: {self.summarize_selection(self.config.copr_repos, empty='None', verb='added')}")
        if include_services:
            current_lines.append(f"Services: {self.summarize_selection(self.config.services, empty='None', verb='enabled')}")
        if include_removed:
            current_lines.append(f"Removed base packages: {self.summarize_selection(self.config.removed_packages, empty='None', verb='selected')}")
        self.menu_section("Current Selections", *current_lines)
        print()
        self.menu_section("Next Step", next_step_hint)

    def update_task_choices(self) -> list[tuple[str, str]]:
        choices = [
            ("Packages", self.summarize_selection(self.config.packages, empty="No packages", verb="selected")),
            ("Base image", self.config.base_image_name or "(not set)"),
            ("Description", self.truncate_label(self.config.image_desc or "(empty)")),
            ("COPR repositories", self.summarize_selection(self.config.copr_repos, empty="No COPRs", verb="added")),
            ("Services", self.summarize_selection(self.config.services, empty="No services", verb="enabled")),
            ("Removed base packages", self.summarize_selection(self.config.removed_packages, empty="None", verb="selected")),
        ]
        if not self.is_universal_blue_base():
            choices.append(("Homebrew", "Enabled" if self.config.brew_enabled else "Not included"))
        return choices

    def show_managed_repo_warning(self) -> None:
        self.gum.warn(MANAGED_REPO_WARNING)
        if self.config.method == "bluebuild":
            self.gum.hint(MANAGED_REPO_HINT_BLUEBUILD)
        else:
            self.gum.hint(MANAGED_REPO_HINT_CONTAINERFILE)

    def preflight(self) -> None:
        # Preflight is intentionally blunt: it checks the tools this app depends
        # on before we let the user invest time in the wizard.
        missing_tools = [name for name in PRECHECK_REQUIRED_TOOLS if not command_exists(name)]
        missing_host_tools = [name for name in HOST_REQUIRED_TOOLS if not command_exists(name)]
        github_login_missing = False
        github_account_error = False

        if "gh" not in missing_tools:
            if run(GH_AUTH_PROBE, check=False).returncode != 0:
                github_login_missing = True
            else:
                try:
                    self.github_user = self.github_login_name()
                    self.github_available = True
                    self.config.github_user = self.github_user
                except CommandError:
                    self.github_available = False
                    github_account_error = True
        else:
            self.github_available = False

        # If a GitHub login is the *only* thing missing (every required tool is
        # present, including gum for the guided prompts), walk the user through
        # `gh auth login` here instead of exiting. The container distribution
        # runs the app as the container's entrypoint, so bailing out would leave
        # a Podman-only user with no shell in which to log in. github_setup_guide()
        # runs `gh auth login` (device-code flow when headless) and raises
        # SystemExit itself if the user declines or the login fails.
        only_login_missing = (
            github_login_missing
            and not github_account_error
            and not missing_tools
            and not missing_host_tools
        )
        if only_login_missing:
            self.gum.ensure_available()
            self.github_setup_guide()
            try:
                self.github_user = self.github_login_name()
                self.config.github_user = self.github_user
                self.github_available = True
                github_login_missing = False
            except CommandError:
                # The login flow returned but the account still can't be read.
                self.github_available = False
                github_account_error = True

        if missing_tools or missing_host_tools or github_login_missing or github_account_error:
            self.render_preflight_failure(
                missing_tools=missing_tools,
                missing_host_tools=missing_host_tools,
                github_login_missing=github_login_missing,
                github_account_error=github_account_error,
            )
            raise SystemExit(1)

        self.gum.ensure_available()
        self.gum.header("Preflight Checks", clear_screen=False)
        self.gum.hint("Checking required tools and the runtime environment...")
        print()

        self.gum.success("git found")
        self.gum.success(f"GitHub CLI authenticated as: {self.github_user}")
        self.gum.success("cosign found (new repos can configure signing automatically)")

        print()
        self.gum.enter_to_continue("Press Enter to continue...")

    def require_github(self) -> bool:
        try:
            return self._require_github()
        except ScreenBack:
            return False

    def _require_github(self) -> bool:
        # Many flows call this right before making networked changes. It either
        # confirms GitHub is ready or walks the user through login first.
        if self.github_available and self.github_user:
            return True
        if not command_exists("gh"):
            self.gum.error("GitHub CLI is required for this action.")
            print()
            self.gum.hint("Install it with: brew install gh")
            return False
        if run(GH_AUTH_PROBE, check=False).returncode != 0:
            self.github_setup_guide()
        try:
            self.github_user = self.github_login_name()
        except CommandError:
            self.gum.error("Unable to determine GitHub username after login.")
            return False
        self.config.github_user = self.github_user
        self.github_available = True
        self.gum.success(f"GitHub ready: {self.github_user}")
        return True

    def github_setup_guide(self) -> None:
        print(
            self.gum.style(
                "GitHub Account Required",
                "",
                "This tool stores your image configuration on GitHub",
                "and uses GitHub Actions to build it automatically.",
                align="left",
                width=self.gum.content_width(max_width=100, reserve=8),
                margin="0 2",
                padding="1 2",
                foreground=ACCENT_COLOR,
                border_foreground=ACCENT_COLOR,
                border="rounded",
            )
        )
        print()
        self.gum.hint("Choose one option below, then press Enter.")
        print()
        choice = self.gum.choose(
            [
                "I already have a GitHub account - log me in",
                "I need to create a GitHub account first",
                "Quit",
            ],
            height=5,
        )
        selected = choice[0] if choice else "Quit"
        if selected.startswith("Quit"):
            raise SystemExit(0)
        if selected.startswith("I need to create"):
            print(
                self.gum.style(
                    "Create a GitHub Account",
                    "",
                    "Go to https://github.com/signup in a browser,",
                    "create an account, then return here for login.",
                    align="left",
                    width=self.gum.content_width(max_width=100, reserve=8),
                    margin="0 2",
                    padding="1 2",
                    foreground=WARNING_COLOR,
                    border_foreground=WARNING_COLOR,
                    border="rounded",
                )
            )
            print()
            if self.gum.confirm("Open github.com/signup now?", default=True):
                if not open_url_in_browser("https://github.com/signup"):
                    self.gum.hint("Could not open a browser here. Go to https://github.com/signup manually.")
            self.gum.enter_to_continue("Press Enter after you've created the account...")

        print(
            self.gum.style(
                "Log In to GitHub",
                "",
                "The GitHub CLI will now guide you through login.",
                "Use GitHub.com, HTTPS, and browser login.",
                align="left",
                width=self.gum.content_width(max_width=100, reserve=8),
                margin="0 2",
                padding="1 2",
                foreground=ACCENT_COLOR,
                border_foreground=ACCENT_COLOR,
                border="rounded",
            )
        )
        print()
        if not self.gum.confirm("Ready to log in?", default=True):
            raise SystemExit(0)
        if run(["gh", "auth", "login"], check=False, capture=False).returncode != 0:
            raise SystemExit("GitHub login failed. Try: gh auth login")
        # The build and update flows push over HTTPS with raw `git push`, which
        # needs gh configured as git's credential helper. `gh auth login` only
        # does that if the user answered yes to its "Authenticate Git" prompt,
        # so configure it explicitly here (best-effort, mirroring
        # container/entrypoint.sh) — otherwise the first push fails even though
        # login and preflight succeeded.
        run(["gh", "auth", "setup-git"], check=False, capture=False)

    def main_menu(self) -> None:
        # The main menu loops forever so the app drops the user back here after
        # create/update flows instead of exiting after one action.
        while True:
            self.gum.header("Main Menu")
            self.gum.controls("Up/Down move", "Enter choose", "Esc quit", "Ctrl+C quit")
            self.menu_section("Supported Base Images", *supported_base_image_lines())
            print()
            try:
                action = self.gum.choose(
                    [
                        "Create Image",
                        "Update Existing Image",
                        "View Build Status",
                        "Quit",
                    ],
                    height=8,
                )
            except ScreenBack:
                raise SystemExit(0)
            selected = action[0] if action else "Quit"
            if selected == "Quit":
                raise SystemExit(0)
            try:
                if selected == "Create Image":
                    self.create_image()
                elif selected == "Update Existing Image":
                    self.update_existing_image()
                elif selected == "View Build Status":
                    self.view_build_status()
            except ScreenBack:
                # Esc that a flow did not handle itself pops back one screen,
                # and from inside any of these flows that screen is this menu.
                # Left to propagate, main() read it as quitting and exited 0,
                # dropping whatever the flow held (#507).
                continue
            except CommandError as exc:
                # A failure here means something in the flow broke, not that
                # the user chose to leave (that is SystemExit). Report it and
                # return to the main menu instead of taking the whole app down.
                self.gum.error(str(exc))
                self.gum.enter_to_continue("Press Enter to return to the main menu...")

    def create_image(self) -> None:
        # One door. The scan decides which flow you get: it reads the base off
        # the running system, so nobody is asked to pick one unless there is no
        # system to read -- a bare `podman run` has no host state, and that is
        # the only case where the base is genuinely a choice.
        outcome = self.scan_os()
        if outcome == SCAN_OK:
            self.create_new_image(scanned=True)
            return
        if outcome in (SCAN_CANCELLED, SCAN_UNPUBLISHED_ARCHITECTURE):
            # For the architecture, scan_os has already said why: any base
            # chosen by hand is an image this machine cannot switch to.
            return
        if outcome == SCAN_UNSUPPORTED_BASE:
            # scan_os has already explained what it found. Defaulting to no:
            # if this is their own managed image, starting fresh from a curated
            # base discards the settings that repo already holds.
            if self.gum.confirm("Start fresh from a supported base image instead?", default=False):
                self.create_new_image()
            return
        print()
        self.gum.hint("Without your system's details, the base image has to be chosen by hand.")
        self.gum.hint("Running through the aib wrapper or distrobox lets the tool read it for you.")
        print()
        if self.gum.confirm("Choose a base image and continue?", default=True):
            self.create_new_image()

    def create_new_image(self, *, scanned: bool = False) -> None:
        # This is a simple step-by-step wizard. The steps are held in a list
        # rather than as fixed numbers because a scanned run has one fewer of
        # them, and the screens display "Step N of M".
        if scanned:
            self.config.github_user = self.github_user
        else:
            self.config = self.fresh_config()

        # A scan reads the base image out of the running system's
        # container-image-reference, so after one the base is a fact about this
        # machine rather than a choice. Offering it anyway would let someone
        # build, say, a Bluefin image on a Bazzite install -- and Universal Blue
        # images are not rebase-compatible with each other, so the result is an
        # image they cannot switch to. The base list stays for the
        # nothing-installed-yet path, where there is no system to read.
        steps = ["method"] if scanned else ["method", "base"]
        # Homebrew is a decision about the base, not about the base *screen*,
        # and dropping that screen after a scan dropped the question with it:
        # a Fedora Atomic host reached the first build with Homebrew off and
        # nothing having asked. It can be a step of its own here precisely
        # because the scan already settled the base, so whether it applies is
        # known before the wizard starts. On the other path the base is not
        # known until step 2, which is why choose_base_image() still asks it
        # there, immediately after the choice it depends on.
        if scanned and not self.is_universal_blue_base():
            steps.append("brew")
        steps += ["repo", "software"]
        review_step = len(steps) + 1
        total_steps = review_step
        index = 0
        # Set while the user is on a step they opened from the review screen
        # (and the steps the wizard walks through after it). Esc there returns
        # to review, which is where they came from: stepping back one index
        # instead meant Esc on "Build method" -- index 0 -- hit the "leave the
        # wizard" case meant for the first pass and discarded everything
        # entered so far (#507). Review has its own explicit Cancel for that.
        editing_from_review = False
        while True:
            try:
                if index < len(steps):
                    name = steps[index]
                    number = index + 1
                    if name == "method":
                        self.choose_method(step=number, total_steps=total_steps)
                    elif name == "base":
                        self.choose_base_image(step=number, total_steps=total_steps)
                    elif name == "brew":
                        self.offer_brew_if_applicable(step=number, total_steps=total_steps)
                    elif name == "repo":
                        self.configure_repo(step=number, total_steps=total_steps)
                    else:
                        self.select_packages(step=number, total_steps=total_steps)
                    index += 1
                    continue
                editing_from_review = False
                action = self.review_new_image(
                    step=review_step, total_steps=total_steps, allow_base_edit="base" in steps
                )
            except ScreenBack:
                if editing_from_review:
                    index = len(steps)
                    continue
                if index == 0:
                    return
                index -= 1
                continue
            if action == "brew":
                # Not a step on every path, so it is edited in place rather
                # than jumped to, the way the local test build already is.
                self.run_screen_action(
                    self.offer_brew_if_applicable,
                    return_hint="Press Enter to return to the review screen...",
                )
                continue
            if action == "build":
                try:
                    if self.do_build():
                        return
                except ScreenBack:
                    # Esc on a screen inside the build returns to review with
                    # the config intact, the same as declining does.
                    pass
                except CommandError as exc:
                    # Keep the wizard's in-memory state intact and return to
                    # the review screen instead of taking the whole app down.
                    self.gum.error(str(exc))
                    self.gum.enter_to_continue("Press Enter to return to the review screen...")
                continue
            if action in steps:
                index = steps.index(action)
                editing_from_review = True
            else:
                return

    def choose_method(self, *, step: int | None = None, total_steps: int | None = None) -> None:
        if step is not None and total_steps is not None:
            self.show_step_header("Build Method", step=step, total_steps=total_steps)
        else:
            self.gum.header("Build Method")
        self.gum.controls("Up/Down move", "Enter choose", "Esc back", "Ctrl+C quit")
        self.menu_section(
            "Tip",
            "Containerfile uses a standard Containerfile and shell script.",
            "BlueBuild uses a YAML recipe and the BlueBuild GitHub Action.",
        )
        print()
        options = [
            "Containerfile    Standard Containerfile with build script (recommended for beginners)",
            "BlueBuild        YAML recipe with the BlueBuild GitHub Action",
        ]
        choice = self.gum.choose(options, height=5)
        selected = choice[0] if choice else options[0]
        if selected.startswith("BlueBuild"):
            self.config.method = "bluebuild"
        else:
            self.config.method = "containerfile"
        if self.config.method == "bluebuild" and "@" in self.config.base_image_uri:
            # A scan keeps the digest the host booted on, and BlueBuild cannot
            # express one. The scanned wizard has no base-image step to change
            # it, so settle it here rather than at "Start GitHub build".
            matched = self.match_base_image(self.config.base_image_uri)
            self.gum.warn("BlueBuild cannot use a digest-pinned base image, and your system is pinned to one.")
            if matched and self.gum.confirm(f"Use the tagged {matched.image_uri} instead?", default=True):
                self.config.base_image_uri = matched.image_uri
            else:
                self.config.method = "containerfile"
                self.gum.hint("Using the Containerfile method instead, which supports digest pins.")
        self.gum.success(f"Build method: {METHOD_DISPLAY[self.config.method]}")

    def choose_base_image(self, *, step: int | None = None, total_steps: int | None = None) -> None:
        # Supported base images are intentionally limited. The point of this tool
        # is a predictable beginner path across curated Universal Blue and
        # Fedora Atomic desktop images, not every possible bootc image variant.
        if step is not None and total_steps is not None:
            self.show_step_header("Base Image", step=step, total_steps=total_steps)
        else:
            self.gum.header("Base Image")
        self.gum.controls("Up/Down move", "Enter choose", "Esc back", "Ctrl+C quit")
        self.menu_section(
            "Tip",
            f"Universal Blue DX images start with extra developer tools. Fedora Atomic options use the official Fedora {FEDORA_ATOMIC_DEFAULT_TAG} desktop images.",
        )
        print()
        if self.config.base_image_uri:
            matched = self.match_base_image(self.config.base_image_uri)
            if matched:
                print(f"  Detected base image: {self.gum.style(self.config.base_image_name or self.config.base_image_uri, bold=True)}")
                print(f"  Image: {self.gum.style(self.config.base_image_uri, foreground=ACCENT_COLOR)}")
                print()
                if self.gum.confirm("Use this base image?", default=True):
                    self.offer_brew_if_applicable()
                    return
            else:
                self.gum.warn(f"This tool supports only the curated images listed below: {supported_base_image_names()}.")
                self.gum.hint("Choose one of those supported starting images below.")
                print()
                self.config.base_image_uri = ""
                self.config.base_image_name = ""

        options = [
            f"[{image.provider}] {image.name:<24} {image.description}  [{image.image_uri}]"
            for image in BASE_IMAGES
        ]
        choice = self.gum.choose(options, height=18)
        selected = choice[0] if choice else options[0]
        for image in BASE_IMAGES:
            if image.name in selected:
                self.config.base_image_uri = image.image_uri
                self.config.base_image_name = image.name
                break
        self.gum.success(f"Base image: {self.config.base_image_name} ({self.config.base_image_uri})")
        self.offer_brew_if_applicable()

    def is_universal_blue_base(self) -> bool:
        matched = self.match_base_image(self.config.base_image_uri)
        return matched is not None and matched.provider == "Universal Blue"

    def offer_brew_if_applicable(self, *, step: int | None = None, total_steps: int | None = None) -> None:
        if self.is_universal_blue_base():
            self.config.brew_enabled = False
            return
        if step is not None and total_steps is not None:
            self.show_step_header("Homebrew", step=step, total_steps=total_steps)
        print()
        self.menu_section(
            "Homebrew",
            "Universal Blue images include Homebrew (brew) for installing extra command-line tools.",
            "Since you chose a Fedora Atomic base image, Homebrew is not included by default.",
            "You can add it now using the Universal Blue Homebrew OCI layer.",
        )
        print()
        self.config.brew_enabled = self.gum.confirm(
            "Include Homebrew (brew) in this image?", default=self.config.brew_enabled
        )
        if self.config.brew_enabled:
            self.gum.success("Homebrew will be included in your image.")
        else:
            self.gum.hint("You can add Homebrew later from the update menu.")

    def configure_repo(self, *, step: int | None = None, total_steps: int | None = None) -> None:
        # We collect repo name and description together because those two values
        # become both GitHub metadata and generated file content later.
        while True:
            if step is not None and total_steps is not None:
                self.show_step_header("Repository Configuration", step=step, total_steps=total_steps)
            else:
                self.gum.header("Repository Configuration")
            self.menu_section(
                "Repository Rules",
                "Repository names use letters, numbers, dashes, and dots. Spaces are turned into dashes.",
                "The name also becomes the image name, so parts are joined by a single dot, one or two underscores, or dashes.",
            )
            print()
            default_name = self.config.repo_name or DEFAULT_REPO_NAME
            raw_name = self.gum.input(
                prompt="Repository name: ",
                placeholder=default_name,
                width=self.gum.form_width(max_width=72),
            )
            candidate_name = sanitize_slug(raw_name or default_name, default_name)
            if not is_valid_repo_name(candidate_name):
                self.gum.error(REPO_NAME_RULE)
                self.gum.enter_to_continue("Press Enter to try another repository name...")
                continue
            self.config.repo_name = candidate_name
            self.config.image_desc = self.gum.input(
                prompt="Description: ",
                placeholder=self.config.image_desc,
                width=self.gum.form_width(max_width=110),
            ) or self.config.image_desc
            print()
            self.menu_section("Visibility", "Repositories created by this tool are public.")
            print()
            if self.github_user:
                self.gum.success(f"Repo: {self.github_user}/{self.config.repo_name}")
            else:
                self.gum.success(f"Repo name: {self.config.repo_name}")
            return

    def select_packages(self, *, step: int | None = None, total_steps: int | None = None) -> None:
        # "Software" is a menu of smaller editing tasks. Each option mutates the
        # same Config object, so the review screen can always show current state.
        while True:
            if step is not None and total_steps is not None:
                self.show_step_header("Software Selection", step=step, total_steps=total_steps)
            else:
                self.gum.header("Software Selection")
            self.gum.controls("Up/Down move", "Enter choose", "Esc back", "Ctrl+C quit")
            self.render_package_menu_intro(
                packages_empty="No packages yet",
                include_copr=True,
                include_services=True,
                include_removed=True,
                next_step_hint="Choose Continue to review when you are finished, or use the remove options to undo package, COPR, or service choices.",
            )
            print()
            selection = self.gum.choose(
                [
                    "Search package names",
                    "Type exact package names",
                    "Remove selected packages",
                    "Add a COPR repository",
                    "Remove COPR repositories",
                    "Add systemd services to enable",
                    "Remove enabled services",
                    "Removed base packages",
                    "Review current selections",
                    "Continue to review",
                ],
                height=13,
            )
            selected = selection[0] if selection else "Continue to review"
            if selected == "Continue to review":
                self.config.normalize()
                return
            try:
                if selected == "Search package names":
                    self.search_packages()
                elif selected == "Type exact package names":
                    self.manual_packages()
                elif selected == "Remove selected packages":
                    self.config.packages = self.choose_to_remove(self.config.packages, "Remove Packages")
                elif selected == "Add a COPR repository":
                    self.add_copr()
                elif selected == "Remove COPR repositories":
                    self.config.copr_repos = self.choose_to_remove(self.config.copr_repos, "Remove COPR Repositories")
                elif selected == "Add systemd services to enable":
                    self.add_services()
                elif selected == "Remove enabled services":
                    self.config.services = self.choose_to_remove(self.config.services, "Remove Services")
                elif selected == "Removed base packages":
                    self.manage_removed_packages(return_to="package menu")
                elif selected == "Review current selections":
                    self.view_selections()
            except ScreenBack:
                continue

    def manual_packages(self) -> None:
        # Package entry is intentionally simple now: the user types the RPM
        # package names they want, and the tool does a lightweight local check
        # for obvious mistakes before the GitHub build does the final check.
        self.gum.header("Add Packages")
        self.gum.write_controls()
        self.menu_section(
            "What To Enter",
            "Enter exact RPM package names separated by spaces or newlines.",
            "Use package search instead if you only know part of the name.",
        )
        print()
        self.menu_section(
            "Validation",
            "This tool will try to catch obvious package-name mistakes here first.",
            "That check uses local DNF metadata. If it is missing, this tool offers to download it.",
            "The GitHub build is still the final check.",
            "Leave this empty if you want to go back without adding anything.",
        )
        print()
        raw = self.gum.write(
            placeholder="Enter package names separated by spaces...",
            height=6,
            width=self.gum.form_width(max_width=110),
        )
        packages = raw.replace(",", " ").split()
        if not packages:
            return
        before_count = len(self.config.packages)
        added = self.add_packages_to_config(packages, source_label="manual entry")
        added_count = len(self.config.packages) - before_count
        if added and not self.last_manual_package_check_had_missing:
            self.gum.enter_to_continue(f"Added {added_count} package(s). Press Enter to return to the package menu...")
            return
        if added and self.last_manual_package_check_had_missing:
            self.gum.enter_to_continue("Finished checking package names. Press Enter to return to the package menu...")
            return
        self.gum.enter_to_continue("No packages were added. Press Enter to return to the package menu...")

    def search_packages(self) -> None:
        while True:
            self.gum.header("Search Packages")
            self.menu_section(
                "Search Tips",
                "Search package names when you only know part of the RPM name.",
                "Search uses local DNF metadata. If it is missing, this tool offers to download it.",
            )
            print()
            term = self.gum.input(
                prompt="Search term: ",
                placeholder="tmux, podman, tailscale",
                width=self.gum.form_width(max_width=72),
            ).strip()
            if not term:
                return

            results, truncated, unavailable_message = self.search_host_packages(term)
            if unavailable_message:
                self.gum.warn(unavailable_message)
                self.gum.enter_to_continue("Press Enter to return to the package menu...")
                return
            if not results:
                self.gum.warn(f"No package names matched '{term}'.")
                self.gum.hint("Try a shorter or more specific term, or use exact-name entry if you already know the package name.")
                self.gum.enter_to_continue("Press Enter to search again...")
                continue

            self.gum.header("Package Search Results")
            self.gum.controls("Up/Down move", "x select", "Enter add", "Esc back", "Ctrl+C quit")
            if truncated:
                self.gum.hint(f"Showing the first {PACKAGE_SEARCH_LIMIT} matches. Narrow the search term if you need something else.")
            print()

            # With --label-delimiter, gum matches --selected against the label
            # half of each line, not the value it prints. Passing the package
            # names pre-ticks nothing, and everything below then reads the
            # untouched matches as deliberate removals (#351).
            options: list[str] = []
            selected_labels: list[str] = []
            for name, summary in results:
                label = f"{name:<30} {self.truncate_label(summary or '(no summary available)', limit=60)}"
                options.append(f"{label}\t{name}")
                if name in self.config.packages:
                    selected_labels.append(label)

            try:
                picked = self.gum.choose(
                    options,
                    height=20,
                    no_limit=True,
                    selected=selected_labels,
                    label_delimiter="\t",
                    selected_prefix="[x] ",
                    unselected_prefix="[ ] ",
                )
            except ScreenBack:
                return

            picked_names = picked
            matching_current = [name for name, _summary in results if name in self.config.packages]
            removed_names = {name for name in matching_current if name not in picked_names}
            if removed_names:
                self.config.packages = [pkg for pkg in self.config.packages if pkg not in removed_names]
                self.config.normalize()

            new_packages = [name for name in picked_names if name not in self.config.packages]
            added_count = 0
            if new_packages:
                before_count = len(self.config.packages)
                added = self.add_packages_to_config(new_packages, source_label=f"search '{term}'")
                if added:
                    added_count = len(self.config.packages) - before_count

            removed_count = len(removed_names)
            if added_count and removed_count:
                self.gum.enter_to_continue(
                    f"Added {added_count} and removed {removed_count} package(s). Press Enter to return to the package menu..."
                )
            elif added_count:
                self.gum.enter_to_continue(f"Added {added_count} package(s). Press Enter to return to the package menu...")
            elif removed_count:
                self.gum.enter_to_continue(f"Removed {removed_count} package(s). Press Enter to return to the package menu...")
            else:
                self.gum.enter_to_continue("No package changes were made. Press Enter to return to the package menu...")
            return

    def add_copr(self) -> None:
        # COPR is powerful but advanced. The UI copy here tries to frame it as
        # optional so new users do not feel forced to understand it immediately.
        self.gum.header("Add COPR Repository")
        self.menu_section(
            "When To Use COPR",
            "COPR is an extra community package source outside the normal Fedora and image-provider repos.",
            "Most users can skip this. Only use it if you know a package you need comes from that COPR.",
            "Example: kwizart/fedy. A group-owned COPR starts with @, like @caddy/caddy.",
            "Leave the repo field empty if you want to go back.",
        )
        print()
        repo = self.gum.input(
            prompt="COPR repo: ",
            placeholder="owner/project",
            width=self.gum.form_width(max_width=60),
        )
        repo = repo.strip()
        if not repo:
            return
        if not COPR_REPO_RE.fullmatch(repo):
            self.gum.error("Enter the COPR repo as owner/project or @group/project.")
            return
        proposed_copr_repos = unique([*self.config.copr_repos, repo])
        print()
        self.menu_section(
            "Optional Package Entry",
            "Enter the package names you want from this COPR. Leave it empty if you only want to add the repo.",
        )
        pkgs = self.gum.input(
            prompt="Packages: ",
            placeholder="package1 package2",
            width=self.gum.form_width(max_width=80),
        )
        # Names already selected are skipped rather than handed on: with
        # nothing new, add_packages_to_config returns False, which here would
        # otherwise read as a rejected name and drop the repo as well.
        packages = [package for package in pkgs.replace(",", " ").split() if package not in self.config.packages]
        if packages and not self.add_packages_to_config(packages, source_label=f"COPR {repo}"):
            return
        self.config.copr_repos = proposed_copr_repos
        self.config.normalize()
        self.gum.success(f"Added COPR: {repo}")
        self.gum.hint("The GitHub build will confirm that the COPR repo and package names are valid.")

    def add_services(self) -> None:
        # Service enabling is another advanced-ish option, so this menu starts
        # with common examples before dropping to raw systemd unit names.
        while True:
            self.gum.header("Enable Services")
            self.menu_section(
                "What This Does",
                "Services are background features that start automatically when the image boots.",
                "Most users can skip this unless they know they want something like SSH or Tailscale always on.",
                "Choose a common service, type another one manually, or go back.",
            )
            print()
            try:
                choice = self.gum.choose(
                    [
                        "Choose from common services",
                        "Type service names manually (advanced)",
                        "Back",
                    ],
                    height=6,
                )
            except ScreenBack:
                return
            selected = choice[0] if choice else "Back"
            if selected == "Back":
                return
            if selected.startswith("Choose from common services"):
                self.select_common_services()
            elif selected.startswith("Type service names manually"):
                self.add_services_manually()

    def select_common_services(self) -> None:
        self.gum.header("Common Services")
        self.gum.controls("Up/Down move", "x select", "Enter save", "Esc back", "Ctrl+C quit")
        label_to_service = {f"{label} ({service})": service for label, service in COMMON_SERVICES}
        options = list(label_to_service)
        selected = [label for label, service in label_to_service.items() if service in self.config.services]
        try:
            picked = self.gum.choose(
                options,
                height=10,
                no_limit=True,
                selected=selected,
                selected_prefix="[x] ",
                unselected_prefix="[ ] ",
            )
        except ScreenBack:
            return
        remaining = [service for service in self.config.services if service not in label_to_service.values()]
        chosen_services = [label_to_service[label] for label in picked]
        self.config.services = unique([*remaining, *chosen_services])
        self.gum.success(f"Total services configured: {len(self.config.services)}")

    def add_services_manually(self) -> None:
        self.gum.header("Add Services Manually")
        self.gum.write_controls()
        self.menu_section(
            "What To Enter",
            "Type systemd service names like sshd.service or tailscaled.service, separated by spaces or newlines.",
            "Leave this empty if you want to go back without adding anything.",
        )
        raw = self.gum.write(
            placeholder="Enter service names separated by spaces...",
            height=5,
            width=self.gum.form_width(max_width=80),
        )
        # Same tokenising as package entry. Splitting on newlines alone meant a
        # user who typed two names with a space -- the natural thing once Enter
        # submits -- got one invalid "a b" token rejected instead of two services.
        services = unique(raw.replace(",", " ").split())
        if not services:
            return
        try:
            self.validate_token_list(services, SERVICE_TOKEN_RE, "systemd service")
        except CommandError as exc:
            self.gum.error(str(exc))
            return
        self.config.services.extend(services)
        self.config.normalize()
        self.gum.success(f"Total services configured: {len(self.config.services)}")

    def view_selections(self) -> None:
        sections = [
            ("Packages", self.config.packages),
            ("COPR Repositories", self.config.copr_repos),
            ("Services", self.config.services),
            ("Removed Base Packages", self.config.removed_packages),
        ]
        lines = ["This is a read-only summary.", ""]
        for index, (title, values) in enumerate(sections):
            if index:
                lines.append("")
            lines.append(title)
            if values:
                lines.extend(f"- {value}" for value in values)
            else:
                lines.append("- (none)")
        if not self.is_universal_blue_base():
            lines.append("")
            lines.append("Homebrew")
            lines.append(f"- {'Enabled' if self.config.brew_enabled else 'Not included'}")
        self.gum.pager(self.read_only_pager_text("Current Selections", lines))

    def show_summary(
        self,
        *,
        step: int | None = None,
        total_steps: int | None = None,
        next_hint: str | None = None,
    ) -> None:
        # Use a pager instead of rendering a table directly so long summaries
        # stay readable on shorter terminals and close cleanly with q.
        intro_lines: list[str] = []
        if next_hint:
            intro_lines.append(next_hint)
        if step is not None and total_steps is not None:
            intro_lines.append(f"Step {step} of {total_steps}.")
        intro_lines.append("This is a read-only summary of the current settings.")
        rows = [
            ("Build Method", METHOD_DISPLAY.get(self.config.method, "(not set)")),
            ("Repository", f"{self.github_user}/{self.config.repo_name}" if self.github_user else self.config.repo_name),
            ("Description", self.config.image_desc),
            ("Base Image", self.config.base_image_name or self.config.base_image_uri),
            ("Image URI", self.config.base_image_uri),
            ("Packages", self.summarize_selection(self.config.packages, empty="None selected", verb="selected", limit=3)),
            ("COPR Repos", self.summarize_selection(self.config.copr_repos, empty="None", verb="added", limit=3)),
            ("Services", self.summarize_selection(self.config.services, empty="None", verb="enabled", limit=3)),
            ("Removed Base Packages", self.summarize_selection(self.config.removed_packages, empty="None", verb="selected", limit=3)),
        ]
        if not self.is_universal_blue_base():
            rows.append(("Homebrew", "Enabled" if self.config.brew_enabled else "Not included"))
        body = self.format_key_value_rows(rows)
        lines = [*intro_lines, "", *body]
        self.gum.pager(self.read_only_pager_text("Review Build Configuration", lines))

    def run_screen_action(self, action: Callable[[], object], *, return_hint: str) -> None:
        # An action launched from a menu screen must not unwind past that
        # screen. main_menu catches CommandError, so an error escaping from
        # here drops the user at the main menu having lost the whole
        # in-progress wizard or update session - method, base image, repo name,
        # description and every package selection. Report it and stay put, the
        # way the "Start GitHub build" branch already does for do_build.
        try:
            action()
        except CommandError as exc:
            self.gum.error(str(exc))
            self.gum.enter_to_continue(return_hint)

    def review_new_image(self, *, step: int, total_steps: int, allow_base_edit: bool = True) -> str:
        while True:
            self.show_step_header("Review and Create Image", step=step, total_steps=total_steps)
            self.gum.hint("Choose a section to review or change, or start the GitHub build.")
            if not allow_base_edit:
                self.menu_section(
                    "Base Image",
                    f"{self.config.base_image_name or self.config.base_image_uri} (detected from your running system)",
                )
            print()
            method_label = self.format_task_choice("Build method", METHOD_DISPLAY.get(self.config.method, "(not set)"))
            software_label = self.format_task_choice("Software", self.software_status())
            repo_label = self.format_task_choice("Repository settings", self.repository_status())
            base_label = self.format_task_choice("Base image", self.config.base_image_name or "(not set)")
            brew_label = self.format_task_choice(
                "Homebrew", "Enabled" if self.config.brew_enabled else "Not included"
            )
            full_label = "View full configuration"
            local_build_label = "Test build locally (podman)"
            build_label = "Start GitHub build"
            cancel_label = "Cancel and return to the main menu"
            options = [method_label, software_label, repo_label]
            # After a scan the base came from the running system and cannot be
            # changed, so it is shown as a fact rather than offered as an edit.
            if allow_base_edit:
                options.append(base_label)
            # Same rule as the update menu's task list: the choice exists
            # exactly when the base does not already provide it. Reviewing a
            # setting that cannot be reached from the screen showing it is how
            # a scanned Fedora run reported "Not included" with nothing to do
            # about it.
            if not self.is_universal_blue_base():
                options.append(brew_label)
            options.extend([full_label, local_build_label, build_label, cancel_label])
            choice = self.gum.choose(options, height=10)
            selected = choice[0] if choice else cancel_label
            if selected == build_label:
                return "build"
            if selected == local_build_label:
                self.run_screen_action(
                    self.test_build_locally,
                    return_hint="Press Enter to return to the review screen...",
                )
                continue
            if selected == method_label:
                return "method"
            if selected == software_label:
                return "software"
            if selected == repo_label:
                return "repo"
            if allow_base_edit and selected == base_label:
                return "base"
            if selected == brew_label:
                return "brew"
            if selected == full_label:
                self.show_summary(step=step, total_steps=total_steps, next_hint="This is the full build summary.")
                continue
            return "cancel"

    def scan_os(self) -> str:
        # This is the one place where the beginner tool looks at the running
        # host. It only reads rpm-ostree state so it can carry layered packages
        # and base-package removals into a new GitHub-backed image repo.
        self.config = self.fresh_config()
        self.gum.header("Scanning Running OS")
        status_override_path = os.environ.get("AIB_RPM_OSTREE_STATUS_FILE")
        if status_override_path:
            # Lets a container wrapper capture `rpm-ostree status --json` on the
            # host (where rpm-ostreed's D-Bus socket actually is) and hand it to
            # the tool running inside the container. See maintenance_notes.txt.
            try:
                status_text = Path(status_override_path).read_text()
            except (OSError, UnicodeDecodeError):
                # OSError: missing/unreadable/permission/is-a-directory.
                # UnicodeDecodeError: a non-text (e.g. binary) file. Both are
                # "unreadable" and must hit the friendly error, not a traceback.
                self.gum.error("Failed to read rpm-ostree status.")
                return SCAN_UNAVAILABLE
        else:
            if not command_exists("rpm-ostree"):
                self.gum.error("rpm-ostree not found. OS scanning is unavailable.")
                return SCAN_UNAVAILABLE

            # Not `--booted`: that leaves out a deployment waiting for a
            # reboot, which is the one this scan has to read. See
            # next_boot_deployment().
            proc = run(["rpm-ostree", "status", "--json"], check=False)
            if proc.returncode != 0 or not proc.stdout.strip():
                self.gum.error("Failed to read rpm-ostree status.")
                return SCAN_UNAVAILABLE
            status_text = proc.stdout

        try:
            status = json.loads(status_text)
        except json.JSONDecodeError:
            self.gum.error("Failed to read rpm-ostree status.")
            return SCAN_UNAVAILABLE
        # Valid JSON is not necessarily the object shape we expect: an override
        # file may hold `[]`, and a future rpm-ostree could change the schema.
        # Everything below must reach the friendly error, not an AttributeError.
        if not isinstance(status, dict):
            self.gum.error("Failed to read rpm-ostree status.")
            return SCAN_UNAVAILABLE
        raw_deployments = status.get("deployments")
        deployments = [item for item in raw_deployments if isinstance(item, dict)] if isinstance(raw_deployments, list) else []
        deployment, pending = next_boot_deployment(deployments)
        if not deployment:
            self.gum.error("No deployment information found.")
            return SCAN_UNAVAILABLE
        # Every message below that names what the host runs has to say which
        # of the two it read, or a pending rebase reads as the running image.
        host_state = "set to boot" if pending else "running"

        container_ref = (
            deployment.get("container-image-reference")
            or deployment.get("origin")
            or ""
        )
        if not isinstance(container_ref, str) or not container_ref.strip():
            # A deployment without a container-image-reference or origin
            # (e.g. a legacy ostree-commit deployment) cannot be carried into an
            # image repo. Bail instead of proceeding with an empty base image.
            self.gum.error(
                "This deployment has no container image reference; scanning only supports bootc / image-based deployments."
            )
            return SCAN_UNAVAILABLE
        # A classic origin names its architecture in the ref, checked below.
        # A container image does not: a multi-arch one such as
        # quay.io/fedora/fedora-kinoite:44 is the same reference on every
        # architecture, so read what the scanned deployment's image actually is.
        image_architecture = deployment_image_architecture(deployment)
        if image_architecture and image_architecture != PUBLISHED_OCI_ARCHITECTURE:
            self.gum.error(f"This system runs a {image_architecture} image.")
            self.gum.hint(
                f"This tool only publishes {PUBLISHED_ARCHITECTURE} images, so a {image_architecture} system cannot switch to an image it builds."
            )
            return SCAN_UNPUBLISHED_ARCHITECTURE
        classic = classic_ostree_origin(container_ref)
        if classic is None:
            base = normalize_container_image_reference(container_ref)
        else:
            # A stock Fedora Atomic install has no container-image-reference,
            # only a classic `remote:ref` origin. Treating that string as an
            # image sent the primary Fedora install down the custom-image
            # refusal below, which told the user their Silverblue was "not one
            # of the images this tool supports" and defaulted to stopping.
            # The ref names the same variant and release the quay.io image
            # does, so map it there and carry the layered packages as usual.
            # A classic origin this tool has no image for is the case the
            # error above describes -- there is no image to build on -- and
            # takes the same path, where create_image offers to choose a base.
            remote, classic_ref = classic
            mapped = fedora_atomic_image_for_classic_origin(remote, classic_ref)
            if mapped is None:
                self.gum.error(
                    f"This system was installed from the ostree origin {container_ref.strip()}, which is not one of the images this tool supports."
                )
                parsed = parse_classic_fedora_ref(classic_ref)
                if remote == FEDORA_OSTREE_REMOTE and parsed is not None and parsed[1] != PUBLISHED_ARCHITECTURE:
                    # The variant may well be supported; the architecture is
                    # not. Say so, or the "Supported" list below reads as a
                    # contradiction to someone running Kinoite on aarch64.
                    # And stop: SCAN_UNAVAILABLE would have create_image offer
                    # a base by hand, which is an x86_64 image all the same.
                    self.gum.hint(
                        f"This tool only publishes {PUBLISHED_ARCHITECTURE} images, so a {parsed[1]} system cannot switch to an image it builds."
                    )
                    return SCAN_UNPUBLISHED_ARCHITECTURE
                self.gum.hint(f"Supported: {supported_base_image_names()}")
                return SCAN_UNAVAILABLE
            base = mapped
        # rpm-ostree records what was typed, and `rpm-ostree install` resolves
        # capabilities and file paths as well as names: 'pkgconfig(gtk4)' and
        # /usr/bin/zsh both land in requested-packages verbatim. Neither is a
        # value validate_config lets into a generated repo, so pre-selecting
        # them sent the user through every step to an "Invalid package
        # value(s)" refusal at the very end, with nothing pointing back here.
        # Split them off now and name them with everything else this image
        # cannot carry, where the user decides with them in view.
        requested_packages = unique(string_list(deployment.get("requested-packages")))
        self.config.scanned_packages = [spec for spec in requested_packages if PACKAGE_TOKEN_RE.fullmatch(spec)]
        unwritable_packages = [spec for spec in requested_packages if not PACKAGE_TOKEN_RE.fullmatch(spec)]
        self.config.scanned_removed = unique(string_list(deployment.get("requested-base-removals")))
        self.config.removed_packages = list(self.config.scanned_removed)
        # Read alongside the two supported fields, not instead of them: a host
        # can have both, and the counts below have to be able to say so.
        omitted = self.unsupported_scan_customizations(deployment)
        if unwritable_packages:
            omitted.insert(0, ("Packages layered by capability or file path, not by name", unwritable_packages))

        self.config.base_image_uri = base
        self.config.base_image_name = base
        matched = self.match_base_image(base)
        if matched is None:
            # choose_base_image already refuses an image that is not curated.
            # This path stopped honouring that when the base step was removed
            # from the scanned flow, so an unsupported image was rejected when
            # typed in and accepted silently when detected. Building on top of
            # a custom image is not supported, so refuse here too. Clear the
            # detected ref the same way choose_base_image does, so a refused
            # image cannot leak into a later step through the config.
            self.config.base_image_uri = ""
            self.config.base_image_name = ""
            self.gum.warn(f"This system is {host_state} {base}, which is not one of the images this tool supports.")
            self.gum.hint(f"Supported: {supported_base_image_names()}")
            print()
            managed = self.scanned_image_is_managed(base)
            if managed is not None:
                owner, repo = managed
                self.menu_section(
                    "This Is One Of Yours",
                    f"{owner}/{repo} is a repo this tool manages.",
                    "Use 'Update Existing Image' to change it -- its saved settings are the source of truth.",
                    "Building a new image on top of it would lose them.",
                )
            else:
                self.menu_section(
                    "Why This Stops Here",
                    "Building a new image on top of a custom image is not supported.",
                    "You can start from one of the supported base images instead.",
                )
            print()
            return SCAN_UNSUPPORTED_BASE
        # Past the refusal above, matched is always a curated image.
        self.config.base_image_name = matched.name
        # Warn when the host is running a non-standard tag (e.g. :testing,
        # :44) that differs from the curated image_uri.  Offer to use the
        # curated tag so the generated repo tracks a known-good stream.
        # A host pinned to a digest with no tag at all gets the same offer,
        # worded for what it is: the digest is not a tag, and presenting its
        # hex as one ("running :911d8f...") reads as a bug in the tool.
        # Pinned to the curated tag ("...:stable@sha256:...") is not warned
        # about: the tag matches, and the digest is what the host asked for.
        scanned_tag, scanned_digest = image_reference_tag_and_digest(base)
        curated_tag, _ = image_reference_tag_and_digest(matched.image_uri)
        if curated_tag and scanned_tag != curated_tag and (scanned_tag or scanned_digest):
            if scanned_tag:
                self.gum.warn(
                    f"Your system is {host_state} :{scanned_tag}, but this tool recommends :{curated_tag} for {matched.name}."
                )
            else:
                self.gum.warn(
                    f"Your system is pinned to a digest rather than a tag, but this tool recommends :{curated_tag} for {matched.name}."
                )
            if self.gum.confirm(f"Use the recommended :{curated_tag} tag instead?", default=True):
                self.config.base_image_uri = matched.image_uri

        self.gum.header("Scan Results")
        rows = [
            ("Base Image", self.config.base_image_name),
            ("Image URI", self.config.base_image_uri),
            ("Layered Packages", str(len(self.config.scanned_packages))),
            ("Removed Base Packages", str(len(self.config.scanned_removed))),
        ]
        if omitted:
            # A category with no values -- a regenerated initramfs is a
            # boolean, not a list -- still counts for one, or the row reads
            # "Cannot Be Carried Over: 0" directly above the warning naming it.
            rows.append(("Cannot Be Carried Over", str(sum(len(values) or 1 for _label, values in omitted))))
        self.gum.table(rows, columns="Setting,Value")
        print()
        if pending:
            # The table reads as a description of the running system. On a
            # host with a pending deployment it is not one, so say which
            # deployment it came from and why that is the right one to read.
            self.gum.warn(
                "This system has changes waiting for a reboot. The scan read those, not the deployment running now: "
                "they are what your next boot, `rpm-ostree reset` and `bootc switch` all start from."
            )
            print()
        if omitted:
            if not self.confirm_omitted_scan_customizations(omitted):
                return SCAN_CANCELLED
            # That screen promised the switch instructions end with a reset.
            # A host whose only layering is omitted leaves both scan lists
            # empty, so without this nothing downstream would know to say it.
            self.config.scan_omitted_customizations = True
        # The table states facts and nothing else. Without this a user is left
        # looking at their own system's details with no idea what the tool is
        # about to do with them, or that the base is settled and will not be
        # asked about again.
        self.menu_section(
            "What Happens Next",
            f"Your image will be built on {self.config.base_image_name} - the base this system {'boots next' if pending else 'already runs'}.",
            "Next you choose which of these packages to carry over, then name the repo and review.",
            "Nothing is created on GitHub until you confirm at the end.",
        )
        print()

        if self.config.scanned_packages:
            # The scan results are a page of their own: read them, then move on.
            # gum choose draws inline rather than taking over the screen, so
            # without the pause and the clear that header() does, the results,
            # the explanation and a twenty-item list all pile onto one screen.
            self.gum.enter_to_continue("Press Enter to choose which packages to carry over...")
            self.gum.header("Packages To Carry Over")
            self.gum.controls("Up/Down move", "x select", "Enter continue", "Esc back", "Ctrl+C quit")
            self.menu_section("Selection", "Leave everything unselected if you want to skip carrying these packages over.")
            print()
            try:
                selected = self.gum.choose(
                    self.config.scanned_packages,
                    height=20,
                    no_limit=True,
                    selected=self.config.scanned_packages,
                    selected_prefix="[x] ",
                    unselected_prefix="[ ] ",
                )
            except ScreenBack:
                return SCAN_CANCELLED
            self.config.packages = selected
        else:
            # "No layered packages found" is false on a host whose only
            # layering is local RPMs, and it was the whole message such a host
            # got. Say what was actually found instead.
            self.gum.warn(
                "No layered packages this tool can carry over were found."
                if omitted
                else "No layered packages found."
            )
            if not self.gum.confirm("Continue to create a custom image anyway?", default=True):
                return SCAN_CANCELLED

        if self.config.scanned_removed:
            # Same again: its own page rather than stacked under the last one.
            self.gum.header("Base Packages To Remove")
            self.gum.controls("Up/Down move", "x select", "Enter continue", "Esc back", "Ctrl+C quit")
            self.menu_section("Selection", "Leave everything unselected if you do not want to remove any base packages.")
            print()
            try:
                selected_removed = self.gum.choose(
                    self.config.scanned_removed,
                    height=20,
                    no_limit=True,
                    selected=self.config.scanned_removed,
                    selected_prefix="[x] ",
                    unselected_prefix="[ ] ",
                )
            except ScreenBack:
                return SCAN_CANCELLED
            self.config.removed_packages = selected_removed

        self.config.normalize()
        return SCAN_OK

    def unsupported_scan_customizations(self, deployment: dict[str, object]) -> list[tuple[str, list[str]]]:
        # Every customization on this deployment that a generated image will
        # not reproduce, labelled for display. Values come back with it so the
        # user can see which packages are at stake rather than only a count --
        # "one local RPM" is not enough to decide with.
        found: list[tuple[str, list[str]]] = []
        for status_key, label in UNSUPPORTED_SCAN_FIELDS + INITRAMFS_SCAN_FIELDS:
            # Every field but one is a list of names; see remote_replacement_list.
            reader = remote_replacement_list if status_key == "requested-base-remote-replacements" else string_list
            values = unique(reader(deployment.get(status_key)))
            if values:
                found.append((label, values))
        if deployment.get("regenerate-initramfs"):
            # A boolean rather than a list, and still something reset undoes.
            found.append(("A locally regenerated initramfs", []))
        return found

    def confirm_omitted_scan_customizations(self, omitted: Sequence[tuple[str, list[str]]]) -> bool:
        # An explicit decision, defaulting to no. Reproducing an arbitrary
        # local RPM is not something this tool can do, but continuing without
        # one has to be a choice the user made rather than one made for them
        # by a field nothing read.
        self.gum.warn("Some of this system's customizations cannot be carried into an image.")
        self.menu_section(
            "Not Carried Over",
            *[
                # A truncated RPM name is not something anyone can act on,
                # so these get the room a package name actually needs.
                f"{label}: {self.preview_values(values, limit=3, item_limit=64)}" if values else label
                for label, values in omitted
            ],
        )
        self.menu_section(
            "What This Means",
            "The image builds without them, and they stay on this system until you remove them.",
            "The switch instructions end with `sudo rpm-ostree reset`, which removes all of the above as well as the packages this image does reproduce.",
            "Set up equivalents in the image later, or stop here and deal with these first.",
        )
        print()
        return self.gum.confirm("Continue without these customizations?", default=False)

    def scanned_image_owner_repo(self, image_ref: str) -> tuple[str, str] | None:
        # ghcr.io/<owner>/<repo>[:tag|@digest] -> (owner, repo). Anything else,
        # including a registry with a longer path, is not something this tool
        # could have produced, so it is not worth a lookup.
        ref = image_ref.split("@", 1)[0]
        parts = ref.split("/")
        if parts and ":" in parts[-1]:
            parts[-1] = parts[-1].rsplit(":", 1)[0]
        if len(parts) != 3 or parts[0] != "ghcr.io" or not parts[1] or not parts[2]:
            return None
        return parts[1], parts[2]

    def scanned_image_is_managed(self, image_ref: str) -> tuple[str, str] | None:
        # Worth one API call: telling someone their own image apart from a
        # stranger's changes the advice completely. A managed repo's saved
        # settings are the source of truth, so the answer is "update it", not
        # "start again and lose them". Any failure means "cannot tell", and the
        # caller falls back to the generic message.
        parsed = self.scanned_image_owner_repo(image_ref)
        if parsed is None or not command_exists("gh"):
            return None
        owner, repo = parsed
        try:
            return parsed if self.repo_has_state_file(owner, repo) else None
        except (CommandError, OSError):
            return None

    def match_base_image(self, value: str) -> BaseImage | None:
        for image in BASE_IMAGES:
            if value == image.image_uri:
                return image
            for image_repo in (image.image_uri.rsplit(":", 1)[0], *image.aliases):
                if value == image_repo or value.startswith(f"{image_repo}:") or value.startswith(f"{image_repo}@"):
                    return image
        return None

    def carried_scan_customizations(self) -> bool:
        # True when the switch has to start with `rpm-ostree reset`: something
        # scanned was carried into the image, or something scanned was left out
        # on the user's say-so and the omission screen promised the reset.
        if self.config.scan_omitted_customizations:
            return True
        scanned_packages = set(self.config.scanned_packages)
        scanned_removed = set(self.config.scanned_removed)
        if scanned_packages or scanned_removed:
            return any(pkg in scanned_packages for pkg in self.config.packages) or any(pkg in scanned_removed for pkg in self.config.removed_packages)
        # Loaded from a state file rather than a live scan: the inventory is not
        # persisted, so fall back to the flag recorded when it was written.
        return self.config.scan_customizations_carried

    def scheduled_rebuild_note(self) -> str:
        return format_daily_rebuild_note(DEFAULT_GITHUB_BUILD_CRON)

    def repo_secret_exists(self, owner: str, repo: str, secret_name: str) -> bool:
        # We probe for the secret before trying to generate or upload a new key.
        # That keeps updates idempotent and avoids silently rotating keys.
        if not command_exists("gh"):
            raise CommandError(
                "Signing-secret status could not be verified because gh is not installed; no signing keys were changed."
            )
        proc = run(["gh", "secret", "list", "-R", f"{owner}/{repo}", "--json", "name"], check=False)
        if proc.returncode != 0:
            raise CommandError(
                "Signing-secret status could not be verified; no signing keys were changed."
            )
        try:
            payload = json.loads(proc.stdout)
        except (json.JSONDecodeError, TypeError):
            raise CommandError(
                "Signing-secret status could not be verified because gh returned invalid data; no signing keys were changed."
            ) from None
        if not isinstance(payload, list) or any(
            not isinstance(item, dict) or set(item) != {"name"} or not isinstance(item["name"], str)
            for item in payload
        ):
            raise CommandError(
                "Signing-secret status could not be verified because gh returned an unexpected response; no signing keys were changed."
            )
        return any(item["name"] == secret_name for item in payload)

    def repo_file_exists(self, owner: str, repo: str, path: str) -> bool:
        proc = run(["gh", "api", f"/repos/{owner}/{repo}/contents/{path}"], check=False)
        return proc.returncode == 0

    def remote_state_payload(self, owner: str, repo: str) -> dict[str, object] | None:
        # Reads a managed repo's state file without cloning it. Any failure
        # means "do not know" (None), and callers treat every flag as unset.
        try:
            proc = run(
                ["gh", "api", f"repos/{owner}/{repo}/contents/{STATE_FILE}", "--jq", ".content"],
                check=False,
            )
            if proc.returncode != 0 or not proc.stdout.strip():
                return None
            payload = json.loads(base64.b64decode(proc.stdout.strip()).decode("utf-8"))
        except (OSError, ValueError, json.JSONDecodeError):
            return None
        return payload if isinstance(payload, dict) else None

    def repo_carried_scan_customizations(self, owner: str, repo: str) -> bool:
        # Any failure means "do not know", and the caller stays quiet rather
        # than guessing -- a wrong migration reminder is worse than none.
        payload = self.remote_state_payload(owner, repo)
        return payload is not None and payload.get("scan_customizations_carried") is True

    def repo_signing_enabled(self, owner: str, repo: str) -> bool:
        # Like the scan flag above, this screen is reached through the picker
        # without loading the selected repo into self.config. Read the persisted
        # flag rather than assuming every historical managed repo has signing.
        payload = self.remote_state_payload(owner, repo)
        return payload is not None and payload.get("signing_enabled") is True

    def repo_has_state_file(self, owner: str, repo: str) -> bool:
        return self.repo_file_exists(owner, repo, STATE_FILE)

    def batch_check_state_files(self, owner: str, repos: list[dict[str, str]]) -> set[str]:
        """Check which repos contain STATE_FILE using a single GraphQL query.

        Falls back to serial REST calls if GraphQL fails (e.g. token scopes).
        Returns a set of repo names that have the state file.
        """
        found: set[str] = set()
        for start in range(0, len(repos), STATE_FILE_QUERY_BATCH):
            found |= self._check_state_file_batch(owner, repos[start : start + STATE_FILE_QUERY_BATCH])
        return found

    def _check_state_file_batch(self, owner: str, repos: list[dict[str, str]]) -> set[str]:
        """One GraphQL query for batch_check_state_files, REST if it fails."""
        # GraphQL aliases must start with a letter and contain only [A-Za-z0-9_]
        alias_map: dict[str, str] = {}
        for i, item in enumerate(repos):
            alias_map[f"r{i}"] = item["name"]
        fragments: list[str] = []
        safe_owner = json.dumps(owner)
        for alias, name in alias_map.items():
            safe_name = json.dumps(name)
            fragments.append(
                f'{alias}: repository(owner: {safe_owner}, name: {safe_name}) '
                f'{{ object(expression: "HEAD:{STATE_FILE}") {{ id }} }}'
            )
        query = "query { " + " ".join(fragments) + " }"

        def rest_fallback() -> set[str]:
            # Serial REST checks: slower, but the only way to answer once the
            # batched GraphQL call has not given us a usable payload.
            return {
                item["name"] for item in repos
                if self.repo_has_state_file(owner, item["name"])
            }

        proc = run(["gh", "api", "graphql", "-f", f"query={query}"], check=False)
        if proc.returncode != 0 or not proc.stdout.strip():
            return rest_fallback()
        try:
            payload = json.loads(proc.stdout)
        except json.JSONDecodeError:
            return rest_fallback()
        # gh exits 0 for a GraphQL-level failure, which comes back as an
        # explicit {"data": null, "errors": [...]}. .get("data", {}) would hand
        # back that null - the default only applies to a *missing* key - and the
        # alias loop below would then raise AttributeError outside any handler.
        data = payload.get("data") if isinstance(payload, dict) else None
        if not isinstance(data, dict):
            return rest_fallback()
        found: set[str] = set()
        for alias, name in alias_map.items():
            repo_data = data.get(alias)
            if isinstance(repo_data, dict) and repo_data.get("object"):
                found.add(name)
        return found

    def generate_and_upload_signing_key(
        self,
        owner: str,
        repo: str,
        *,
        upload_failed_note: str,
        half_complete_note: str,
    ) -> str | None:
        """Generate a cosign keypair and upload the signing secrets to GitHub.

        Returns the new public key text, or None if the user declined to retry a
        failed SIGNING_SECRET upload. Raises CommandError if the keypair cannot
        be generated or a secret cannot be uploaded.

        Both signing entry points - first-time setup in ensure_signing_ready and
        rotation in rotate_signing_key - previously carried their own copy of
        this sequence, so any change to the retry semantics applied to only one
        of them. The two notes are the only wording that legitimately differs:
        one is setting signing up, the other is replacing a working key.
        """
        bluebuild_signing = self.config.method == "bluebuild"
        # BlueBuild generates its key with an empty password and never uploads
        # COSIGN_PASSWORD; the Containerfile workflow needs both.
        cosign_password = "" if bluebuild_signing else secrets.token_urlsafe(32)
        with tempfile.TemporaryDirectory(prefix=f"{TOOL_SLUG}-signing.") as tmp:
            tmpdir = Path(tmp)
            env = os.environ.copy()
            env["COSIGN_PASSWORD"] = cosign_password
            proc = run(["cosign", "generate-key-pair"], cwd=tmpdir, env=env, check=False)
            key_path = tmpdir / "cosign.key"
            pub_path = tmpdir / "cosign.pub"
            if proc.returncode != 0 or not key_path.exists() or not pub_path.exists():
                raise CommandError("Unable to generate a cosign keypair. Fix cosign first, then try again.")
            if not bluebuild_signing:
                password_proc = run(
                    ["gh", "secret", "set", "COSIGN_PASSWORD", "-R", f"{owner}/{repo}"],
                    cwd=tmpdir,
                    stdin=cosign_password,
                    check=False,
                )
                if password_proc.returncode != 0:
                    raise CommandError("Unable to upload COSIGN_PASSWORD to GitHub. Check your gh login and repo access, then try again.")
            while True:
                secret_proc = run(
                    ["gh", "secret", "set", "SIGNING_SECRET", "-R", f"{owner}/{repo}"],
                    cwd=tmpdir,
                    stdin=key_path.read_text(),
                    check=False,
                )
                if secret_proc.returncode == 0:
                    return pub_path.read_text()
                if bluebuild_signing:
                    self.gum.error(upload_failed_note)
                    if not self.gum.confirm("Retry uploading SIGNING_SECRET now?", default=True):
                        return None
                    continue
                # COSIGN_PASSWORD is already uploaded, so GitHub is now
                # half-configured: stopping here leaves signing broken.
                self.gum.error(half_complete_note)
                if not self.gum.confirm("Retry uploading SIGNING_SECRET now?", default=True):
                    return None

    def ensure_signing_ready(self, owner: str, repo: str, *, repo_dir: Path | None = None) -> bool:
        # Signed images are required for this tool, so "ready" means:
        # - the repo already has a compatible SIGNING_SECRET, or
        # - we can create a cosign keypair and upload the needed secrets now
        self.generated_cosign_pub = None
        bluebuild_signing = self.config.method == "bluebuild"
        if self.repo_secret_exists(owner, repo, "SIGNING_SECRET"):
            if repo_dir is not None and not managed_path(repo_dir, "cosign.pub").exists():
                # GitHub secrets are write-only, so the public half of the key
                # cannot be recovered from SIGNING_SECRET. Rotation is the only
                # way to restore signing when cosign.pub has gone missing.
                raise CommandError(
                    "SIGNING_SECRET is configured on GitHub but cosign.pub is missing from this repo. "
                    "The public key cannot be recovered; use 'Rotate signing key (cosign)' from the update menu to restore signing."
                )
            if not bluebuild_signing and not self.repo_secret_exists(owner, repo, "COSIGN_PASSWORD"):
                # The Containerfile workflow signs with
                #   cosign sign --key env://COSIGN_PRIVATE_KEY
                # under COSIGN_PASSWORD: ${{ secrets.COSIGN_PASSWORD }}, and the
                # key we generate is encrypted with a random password. With the
                # secret missing that expands to an empty string, cosign cannot
                # decrypt the key, and signing fails on every build. Fail closed
                # here the same way the missing-cosign.pub case above does,
                # rather than reporting signing ready. BlueBuild is exempt: it
                # generates its key with an empty password and never uploads the
                # secret. rotate_signing_key() is the repair path.
                raise CommandError(
                    "SIGNING_SECRET is configured on GitHub but COSIGN_PASSWORD is missing. "
                    "The signing key cannot be decrypted without it, so image builds would fail signing. "
                    "Use 'Rotate signing key (cosign)' from the update menu to regenerate both secrets."
                )
            return True
        if not command_exists("cosign"):
            raise CommandError("cosign is required for signed images. Install it with: brew install cosign")
        pub_text = self.generate_and_upload_signing_key(
            owner,
            repo,
            upload_failed_note="Could not upload SIGNING_SECRET to GitHub. Check your gh login and repo access, then try again.",
            half_complete_note=(
                "Could not upload SIGNING_SECRET to GitHub. Signing setup is half-complete — "
                "COSIGN_PASSWORD is set but SIGNING_SECRET is not, and image builds will fail signing until this finishes."
            ),
        )
        if pub_text is None:
            if bluebuild_signing:
                raise CommandError("SIGNING_SECRET upload was not completed.")
            raise CommandError(
                "Aborting with signing setup half-complete. Re-run this tool to finish "
                "uploading SIGNING_SECRET before pushing new commits."
            )
        self.generated_cosign_pub = pub_text
        # The public key is kept in memory for the current run so it can be
        # written into the repo files that we are about to generate.
        if bluebuild_signing:
            self.gum.success("Configured SIGNING_SECRET for BlueBuild image signing.")
        else:
            self.gum.success("Configured SIGNING_SECRET and COSIGN_PASSWORD for image signing.")
        return True

    def rotate_signing_key(self, repo_dir: Path | None = None) -> None:
        repo_dir = Path.cwd() if repo_dir is None else repo_dir
        owner = self.config.github_user or self.github_user
        repo = self.config.repo_name
        # Every exit below that reports something pauses before returning: the
        # update menu redraws with a clearing header straight away, and
        # run_screen_action only pauses for a CommandError that escapes. The
        # half-complete warnings are the ones that must not be wiped unread.
        return_hint = "Press Enter to return to the update menu..."
        if not owner or not repo:
            self.gum.warn("Run this from a configured image repo so the GitHub repository can be identified.")
            self.gum.enter_to_continue(return_hint)
            return
        if not self.gum.confirm(
            "Rotate the cosign signing key? Old signatures remain valid in the registry; re-pull or re-verify after rotation.",
            default=False,
        ):
            return
        missing = [name for name in ("cosign", "gh") if not command_exists(name)]
        if missing:
            verb = "is" if len(missing) == 1 else "are"
            self.gum.warn(f"{', '.join(missing)} {verb} required to rotate the signing key.")
            self.gum.hint("Install the missing tool, then try this again.")
            self.gum.enter_to_continue(return_hint)
            return

        bluebuild_signing = self.config.method == "bluebuild"
        try:
            pub_text = self.generate_and_upload_signing_key(
                owner,
                repo,
                upload_failed_note="Could not upload SIGNING_SECRET to GitHub. Rotation was not applied.",
                half_complete_note=(
                    "Could not upload SIGNING_SECRET to GitHub. Rotation is half-complete — "
                    "your next image build will fail signing until this finishes."
                ),
            )
        except CommandError as exc:
            self.gum.error(str(exc))
            self.gum.enter_to_continue(return_hint)
            return
        if pub_text is None:
            if not bluebuild_signing:
                # COSIGN_PASSWORD was already replaced, so the repo's key and
                # GitHub's secrets no longer agree.
                self.gum.warn(
                    "Aborting with rotation half-complete. Re-run 'Rotate signing key (cosign)' "
                    "before pushing new commits, or your GitHub Actions signing step will fail."
                )
            self.gum.enter_to_continue(return_hint)
            return
        try:
            managed_path(repo_dir, "cosign.pub").write_text(pub_text)
            self.configure_temp_repo_git_identity(repo_dir)
            run(["git", "add", "cosign.pub"], cwd=repo_dir)
            run(["git", "commit", "-m", "Rotate cosign signing key"], cwd=repo_dir)
            commit_sha = run(["git", "rev-parse", "--short", "HEAD"], cwd=repo_dir).stdout.strip()
            run(["git", "push", "origin", "HEAD"], cwd=repo_dir, capture=False)
        except (CommandError, OSError) as exc:
            # GitHub already has the new secrets. Surface the split state so the
            # user knows to re-run rotation instead of trusting a silent failure.
            self.gum.error(
                f"Uploaded new signing secrets to GitHub but could not write, commit, or push cosign.pub: {exc}"
            )
            self.gum.warn(
                "Rotation is half-complete — GitHub secrets and the repo's cosign.pub are out of sync. "
                "Re-run 'Rotate signing key (cosign)' before pushing new commits."
            )
            self.gum.enter_to_continue(return_hint)
            return
        self.gum.success(f"Rotated cosign signing key in commit {commit_sha}. GitHub secrets were updated.")
        self.gum.warn("Pre-rotation signatures remain valid in the registry; re-pull or re-verify after rotation.")
        self.gum.enter_to_continue(return_hint)

    def clone_repo(self, owner: str, repo: str, target: Path) -> None:
        self.gum.spinner(f"Cloning {owner}/{repo}...", ["gh", "repo", "clone", f"{owner}/{repo}", str(target)])

    def configure_temp_repo_git_identity(self, repo_dir: Path) -> None:
        # Temp repos are created in scratch directories, so they cannot rely on
        # the user's global git config already being set. We always configure a
        # local author identity before committing so first-time users do not hit
        # "please tell me who you are" commit failures.
        login = self.github_user or self.config.github_user or TOOL_SLUG
        name = self.github_user or self.config.github_user or TOOL_NAME
        email = f"{login}@users.noreply.github.com"
        run(["git", "config", "user.name", name], cwd=repo_dir)
        run(["git", "config", "user.email", email], cwd=repo_dir)

    def copy_template_snapshot(self, target: Path, *, repo: str, source_dir: Path) -> None:
        # We copy from a bundled snapshot instead of pulling a live template from
        # GitHub at runtime. That makes the tool deterministic and avoids breakage
        # if upstream template repos change unexpectedly.
        target = target.expanduser()
        target.parent.mkdir(parents=True, exist_ok=True)
        if not source_dir.is_dir():
            raise CommandError(f"Bundled template snapshot not found for {repo}.")
        if target.exists():
            if any(target.iterdir()):
                raise CommandError(f"{target} already exists and is not empty.")
            target.rmdir()
        try:
            shutil.copytree(source_dir, target, ignore=shutil.ignore_patterns(
                ".template-source", "renovate.json5",
            ))
        except (OSError, shutil.Error) as exc:
            raise CommandError(f"Unable to copy bundled template snapshot for {repo}: {exc}") from exc

    def clone_container_template(self, target: Path) -> None:
        self.copy_template_snapshot(target, repo=CONTAINERFILE_TEMPLATE_REPO, source_dir=CONTAINERFILE_TEMPLATE_DIR)

    def clone_bluebuild_template(self, target: Path) -> None:
        self.copy_template_snapshot(target, repo=BLUEBUILD_TEMPLATE_REPO, source_dir=BLUEBUILD_TEMPLATE_DIR)

    def repo_default_branch(self, owner: str, repo: str) -> str:
        try:
            data = self.gh_json(["repo", "view", f"{owner}/{repo}", "--json", "defaultBranchRef"])
        except (CommandError, json.JSONDecodeError):
            data = None
        # A brand-new empty repo (no commits yet) reports defaultBranchRef as
        # null, so the key is present but the value is None. Coerce that to {}
        # before .get() or this crashes instead of falling through to the REST
        # default_branch lookup below.
        branch = (data.get("defaultBranchRef") or {}).get("name") if isinstance(data, dict) else None
        if branch:
            return branch
        proc = run(["gh", "api", f"/repos/{owner}/{repo}"], check=False)
        if proc.returncode == 0 and proc.stdout.strip():
            try:
                rest_data = json.loads(proc.stdout)
            except json.JSONDecodeError:
                rest_data = None
            if isinstance(rest_data, dict):
                rest_branch = rest_data.get("default_branch")
                if isinstance(rest_branch, str) and rest_branch:
                    return rest_branch
        # Both detection paths failed. Warn the user instead of silently picking
        # "main", because a non-main default would otherwise leave the workflow's
        # branch filter pointing at a branch that does not exist on the repo.
        self.gum.warn("Could not detect the GitHub default branch; using 'main'.")
        self.gum.hint(
            "If your repo's default branch is not 'main', edit .github/workflows/build.yml after the first push."
        )
        return "main"

    def seed_project_template(self, target: Path) -> None:
        if self.config.method == "bluebuild":
            self.clone_bluebuild_template(target)
        else:
            self.clone_container_template(target)

    def add_packages_to_config(
        self,
        candidates: Iterable[str],
        *,
        source_label: str,
    ) -> bool:
        # A name already in the list adds nothing: drop it before validation,
        # the dnf5 lookup (and any metadata-refresh offer) and every message,
        # so "Added N" counts only names the config actually gains.
        packages = [package for package in unique(candidates) if package not in self.config.packages]
        if not packages:
            return False
        try:
            self.validate_token_list(packages, PACKAGE_TOKEN_RE, "package")
        except CommandError as exc:
            self.gum.error(str(exc))
            return False
        if source_label == "manual entry":
            packages = self.filter_available_manual_packages(packages)
            if not packages:
                return False
        self.config.packages.extend(packages)
        self.config.normalize()
        self.gum.success(f"Added {len(packages)} package(s) from {source_label}")
        return True

    def add_removed_packages_to_config(
        self,
        candidates: Iterable[str],
        *,
        source_label: str,
    ) -> bool:
        # Same as add_packages_to_config (#521): a name already listed adds
        # nothing, so drop it before the lookup and the "Added N" count.
        packages = [package for package in unique(candidates) if package not in self.config.removed_packages]
        if not packages:
            return False
        try:
            self.validate_token_list(packages, PACKAGE_TOKEN_RE, "removed package")
        except CommandError as exc:
            self.gum.error(str(exc))
            return False
        if source_label == "manual entry":
            packages = self.filter_available_manual_removed_packages(packages)
            if not packages:
                return False
        self.config.removed_packages.extend(packages)
        self.config.normalize()
        self.gum.success(f"Added {len(packages)} package removal(s) from {source_label}")
        return True

    def _filter_manual_packages(self, packages: Sequence[str], *, mode: str) -> list[str]:
        if mode == "available":
            missing_attr = "last_manual_package_check_had_missing"
            warning_attr = "package_lookup_warning_shown"
            missing_hint = "They were skipped because no RPM package with that name was found."
            unchecked_warn = "Could not fully check some package names on this system."
            unchecked_hint = "The GitHub build will do the final package check."
        else:
            missing_attr = "last_manual_removed_package_check_had_missing"
            warning_attr = "removed_package_lookup_warning_shown"
            missing_hint = "They were skipped because no RPM package with that name is installed here or found in your current host repos."
            unchecked_warn = "Could not fully check some package removals on this system."
            unchecked_hint = "The build will skip removals that are not installed in the base image."

        setattr(self, missing_attr, False)
        accepted: list[str] = []
        missing: list[str] = []
        missing_but_copr_may_provide: list[str] = []
        unchecked: list[str] = []
        if mode == "available":
            lookup_results = self.lookup_host_packages(packages, resolve_provides=True)
        else:
            # The removal screen asks the host's rpmdb first, then the repo
            # query without Provides: a removal is gated by
            # `rpm -q --quiet "$pkg"` in the generated build.sh, and rpm -q
            # does not resolve Provides, so a virtual name that install
            # would accept is a typo here. See lookup_removable_host_packages.
            lookup_results = self.lookup_removable_host_packages(packages)
        for package in packages:
            available = lookup_results[package]
            if available is True:
                accepted.append(package)
            elif available is False:
                if mode == "available" and self.config.copr_repos:
                    accepted.append(package)
                    missing_but_copr_may_provide.append(package)
                else:
                    missing.append(package)
            else:
                accepted.append(package)
                unchecked.append(package)
        if missing:
            setattr(self, missing_attr, True)
            joined = ", ".join(missing)
            self.gum.error(f"These package names were not found: {joined}")
            self.gum.hint(missing_hint)
        if missing_but_copr_may_provide:
            joined = ", ".join(missing_but_copr_may_provide)
            self.gum.warn("Some package names were not found in your current host repos.")
            self.gum.hint(f"Keeping for now because configured COPRs may provide them: {joined}")
            self.gum.hint("The GitHub build will do the final package check.")
        if unchecked and not getattr(self, warning_attr):
            joined = ", ".join(unchecked)
            self.gum.warn(unchecked_warn)
            self.gum.hint(f"Keeping for now: {joined}")
            self.gum.hint(unchecked_hint)
            setattr(self, warning_attr, True)
        return accepted

    def filter_available_manual_packages(self, packages: Sequence[str]) -> list[str]:
        # Manual package entry is intentionally forgiving:
        # - known good packages are accepted
        # - clearly missing packages are skipped
        # - packages that might come from configured COPRs are kept
        # - unknown/uncheckable cases are kept, but the user is warned that the
        #   GitHub build is the final authority
        return self._filter_manual_packages(packages, mode="available")

    def filter_available_manual_removed_packages(self, packages: Sequence[str]) -> list[str]:
        # Removed packages are checked locally for obvious typos before we save
        # them into the repo state file. The generated build script still skips
        # removals that are not installed in the chosen base image.
        return self._filter_manual_packages(packages, mode="removed")

    def dnf5_state_dir(self) -> Path:
        # dnf5 keeps its own state under XDG_STATE_HOME. Point that at a
        # scratch directory so queries made on the user's behalf never disturb
        # their real dnf5 state. The metadata *cache* is deliberately left
        # alone: refreshing it should benefit the rest of the system, and be
        # satisfied by it, rather than building a private copy.
        #
        # Scoped by uid and validated on every use: tempfile.gettempdir() is
        # shared and world-writable, so a fixed, unscoped name here would let
        # another local user pre-create it -- as a symlink, say -- before we
        # do, and dnf5 would then read/write through that path as us.
        state_dir = Path(tempfile.gettempdir()) / f"{TOOL_SLUG}-dnf5-{os.getuid()}"
        if state_dir.is_symlink() or (state_dir.exists() and not state_dir.is_dir()):
            raise CommandError(f"refusing to use {state_dir}: not a plain directory (possible symlink attack)")
        state_dir.mkdir(mode=0o700, parents=True, exist_ok=True)
        state_dir.chmod(0o700)
        st = state_dir.stat()
        if st.st_uid != os.getuid():
            raise CommandError(f"refusing to use {state_dir}: owned by uid {st.st_uid}, not us")
        return state_dir

    def dnf5_command(self, state_dir: Path, *args: str) -> list[str]:
        # Every dnf5 run the tool makes goes through here, so that each one
        # uses the scoped state directory and speaks English. The no-cache
        # and "nothing matched" markers are matched as English text, and dnf5
        # translates both: under a German or French locale neither matches,
        # so a missing cache never gets the refresh offer and every name is
        # left unchecked (#504). LC_ALL=C overrides LANG and every LC_*.
        # LANGUAGE is removed too: it outranks the locale in gettext, so
        # LANGUAGE=de alone gives German output. glibc happens to ignore it
        # under the C locale, but dropping it does not lean on that. Same
        # reasoning as the rpm -q pin in lookup_installed_host_packages().
        return ["env", "-u", "LANGUAGE", "LC_ALL=C", f"XDG_STATE_HOME={state_dir}", "dnf5", *args]

    def refresh_package_metadata(self) -> bool:
        # Offered rather than run automatically: this is a real download over
        # whatever connection the user happens to be on.
        #
        # Offered *here*, rather than printed as advice, because the container
        # image runs this app as its entrypoint -- a `podman run` user has no
        # shell in which to go run dnf5. That is the same reason preflight()
        # walks people through `gh auth login` instead of telling them to.
        self.gum.warn("Checking package names needs local DNF metadata, which is not available yet.")
        self.gum.hint("Refreshing downloads the repository metadata dnf5 uses to match package names.")
        self.gum.hint("This is a large download: well over 100 MB for the standard Fedora repositories.")
        print()
        if not self.gum.confirm("Refresh package metadata now?"):
            return False
        proc = self.gum.spinner_result(
            "Refreshing package metadata...",
            self.dnf5_command(self.dnf5_state_dir(), "makecache"),
        )
        if proc.returncode != 0:
            self.gum.error("Could not refresh package metadata.")
            detail = (proc.stderr or proc.stdout).strip()
            if detail:
                self.gum.hint(detail.splitlines()[-1])
            return False
        self.gum.success("Package metadata refreshed.")
        return True

    def lookup_host_packages(
        self, packages: Sequence[str], *, resolve_provides: bool = True, allow_metadata_refresh: bool = True
    ) -> dict[str, bool | None]:
        # Host-side dnf5 checks are a lightweight "spellcheck" for manual RPM
        # names. They are not a perfect model of the final image build, but they
        # catch obvious mistakes like typos before we create a repo.
        #
        # resolve_provides says which build step the answer has to match.
        # `dnf5 install` resolves a Provides such as vim to vim-enhanced; the
        # removal loop's `rpm -q --quiet` gate does not, so for a removal a
        # virtual name is "not found". NEVRA forms (vim-enhanced.x86_64,
        # htop-3.4.1) are accepted by both and checked either way.
        #
        # This checks every requested package in a single dnf5 invocation
        # rather than one invocation per package. dnf5's first repoquery call
        # pays a real, human-perceptible cost to load its metadata cache;
        # every call after that is fast. One call per package meant only the
        # first package's "Checking package name" spinner was ever visible
        # for more than a flash, even though every package genuinely was
        # being checked -- discovered by watching a real demo recording.
        #
        # The query is cache-only (-C), the same as search_host_packages().
        # Without it, dnf5 fetches missing or expired repository metadata on
        # its own -- about 160 MB on Fedora -- behind a spinner that says only
        # "Checking package name" (#369). A missing cache is instead met with
        # the same refresh offer the search path makes, and a declined offer
        # leaves the names unchecked rather than blocking entry: the GitHub
        # build checks them anyway.
        results: dict[str, bool | None] = {}
        to_check: list[str] = []
        for package in packages:
            if (package, resolve_provides) in self.package_lookup_cache:
                results[package] = self.package_lookup_cache[package, resolve_provides]
            elif package not in to_check:
                to_check.append(package)
        if not to_check:
            return results
        if not command_exists("dnf5"):
            for package in to_check:
                self.package_lookup_cache[package, resolve_provides] = None
                results[package] = None
            return results
        state_dir = self.dnf5_state_dir()
        title = (
            f"Checking package name: {to_check[0]}"
            if len(to_check) == 1
            else f"Checking package names: {', '.join(to_check)}"
        )
        names, uncheckable, no_cache = self._dnf5_repoquery_names(title, state_dir, to_check)
        if no_cache:
            # Offer the fix, then check again. The retry has the offer
            # disabled so a refresh that reports success without producing
            # usable metadata cannot loop. Nothing is cached on this path:
            # a declined download is not a verdict on the names, and a later
            # accepted refresh (here or from search) must be able to check
            # them for real.
            if allow_metadata_refresh and self.refresh_package_metadata():
                results.update(
                    self.lookup_host_packages(to_check, resolve_provides=resolve_provides, allow_metadata_refresh=False)
                )
                return results
            for package in to_check:
                results[package] = None
            return results
        unresolved: list[str] = []
        for package in to_check:
            if package in names:
                outcome: bool | None = True
            elif uncheckable:
                outcome = None
            else:
                # Not a package name -- which is not the same as not
                # installable. Decided per spec below, once the batch has
                # settled everything it can.
                unresolved.append(package)
                continue
            self.package_lookup_cache[package, resolve_provides] = outcome
            results[package] = outcome
        for package in unresolved:
            outcome = self._resolve_package_spec(package, state_dir, resolve_provides=resolve_provides)
            self.package_lookup_cache[package, resolve_provides] = outcome
            results[package] = outcome
        return results

    def _dnf5_repoquery_names(
        self, title: str, state_dir: Path, args: Sequence[str], *, query_format: str = "%{name}\n"
    ) -> tuple[set[str], bool, bool]:
        # One `dnf5 repoquery` run, reduced to the package names it printed,
        # whether that answer can be trusted, and whether the reason it
        # cannot is dnf5 having no metadata cache to answer from. A nonzero
        # exit that is not one of dnf5's own "nothing matched" messages means
        # dnf5 itself failed (no metadata, broken config), so an empty result
        # then says nothing about the names; callers report None rather than
        # a typo. The no-cache case is singled out because the batch caller
        # can offer to fix it (#369); the per-spec follow-ups run on the cache
        # the batch just used, so for them it is just another failed query.
        # query_format defaults to the bare name; the NEVRA follow-up swaps
        # in every spelling of the matched package, one per line.
        proc = self.gum.spinner_result(
            title,
            self.dnf5_command(
                state_dir,
                "-C",
                "repoquery",
                "--available",
                "--qf",
                query_format,
                "--latest-limit",
                "1",
                *args,
            ),
        )
        # %{name}\n means one result per line even when multiple packages are
        # queried at once; without the trailing newline in the format string,
        # multiple results print back to back with no separator at all.
        names = {line.strip() for line in proc.stdout.splitlines() if line.strip()}
        detail = "\n".join(part for part in [proc.stdout, proc.stderr] if part).lower()
        no_cache = proc.returncode != 0 and DNF5_NO_CACHE_MARKER in detail
        has_missing_marker = any(marker in detail for marker in DNF5_MISSING_MARKERS)
        uncheckable = proc.returncode != 0 and not has_missing_marker
        return names, uncheckable, no_cache

    def _resolve_package_spec(self, spec: str, state_dir: Path, *, resolve_provides: bool) -> bool | None:
        # The batch answers "is this exactly a package name?", and the
        # generated build.sh's `dnf5 install -y` accepts more than that: a
        # NEVRA form such as vim-enhanced.x86_64, or a Provides such as vim,
        # which dnf5 resolves to vim-enhanced. Rejecting those as typos
        # contradicted what `dnf install` does on the user's own machine
        # (#370). The batch cannot say which of its arguments printed which
        # line, so the leftovers are resolved one spec at a time, on the
        # metadata cache the batch just warmed -- these calls are the fast
        # kind.
        title = f"Checking package name: {spec}"
        if resolve_provides:
            # --whatprovides first. It is case-sensitive, like install's own
            # resolution, and every package provides its own name, so this
            # covers a plain name and a virtual one alike.
            names, uncheckable, _no_cache = self._dnf5_repoquery_names(title, state_dir, ["--whatprovides", spec])
            if names:
                return True
            if uncheckable:
                return None
        # A spec with no NEVRA separator can only be a name. For install the
        # Provides query already gave the case-exact answer; for a removal
        # the batch did, since rpm -q wants the name itself. (The batch is
        # positional and so matched ignoring case, but it printed the real
        # name, which is what the spec was compared against.) Swapping a
        # Provides for its provider instead would guess: `webserver` has
        # three (caddy, httpd, lighttpd), and the state file would then hold
        # a name the user never typed.
        if not any(separator in spec for separator in ".-:"):
            return False
        # NEVRA forms. dnf5 matches positional specs ignoring case where
        # install and rpm -q do not: on 5.4.2.1 repoquery matches
        # Vim-Enhanced and htop.X86_64, and install says "No match for
        # argument" to both; `rpm -q bash.X86_64` is "not installed".
        # Comparing only the printed %{name} against the start of the spec
        # let a wrong-case arch or version through (#505), so dnf5 prints
        # every spelling of what it matched and the spec must be one of them
        # verbatim.
        query_format = "".join(f"{spelling}\n" for spelling in DNF5_SPEC_SPELLINGS)
        spellings, uncheckable, _no_cache = self._dnf5_repoquery_names(
            title, state_dir, [spec], query_format=query_format
        )
        if spec in spellings:
            return True
        return None if uncheckable else False

    def lookup_host_package(self, package: str) -> bool | None:
        return self.lookup_host_packages([package])[package]

    def lookup_removable_host_packages(self, packages: Sequence[str]) -> dict[str, bool | None]:
        # The question a removal asks is "is this in the base image?", and
        # the repo query alone answers a different one. Bluefin, Bazzite and
        # Aurora carry packages from Universal Blue's own repos (uupd, the
        # ublue-os-* and bluefin-* sets) that `dnf5 repoquery --available`
        # never lists on the host, because they are in neither fedora nor
        # updates -- so the old check called a real base-image package a
        # typo. The closest unprivileged model of the base image is the
        # host's own rpmdb, so that is asked first.
        #
        # Only an installed answer is final. A name rpm does not know, or
        # could not check, still goes to the repo query: the base image can
        # carry a package the host has already overridden away, and a
        # different base than the host's can carry one it never had. The
        # repo answer for those is exactly the answer this screen gave
        # before, so nothing that used to be accepted stops being accepted.
        #
        # The repo query runs without Provides resolution: the build's
        # `rpm -q --quiet` gate does not resolve them either, so with
        # vim-enhanced in the base image `rpm -q vim` fails and the removal
        # is skipped. A virtual name is a typo on this screen.
        results = self.lookup_installed_host_packages(packages)
        remaining = [package for package in unique(packages) if results[package] is not True]
        if remaining:
            results.update(self.lookup_host_packages(remaining, resolve_provides=False))
        return results

    def lookup_installed_host_packages(self, packages: Sequence[str]) -> dict[str, bool | None]:
        # `rpm -q`, not `dnf5 repoquery --installed`: the dnf5 form opens
        # /var/lib/dnf/system-repo.lock and fails without root, while rpm
        # reads the database as any user. Inside the tool container this is
        # the container's own rpmdb rather than the host's, which is the same
        # limitation the repo query already has there; a name it accepts by
        # mistake is still gated by the build's own `rpm -q` before removal.
        #
        # Batched for the same reason as lookup_host_packages. Every spec
        # rpm does not find is named back on stdout as "package <spec> is not
        # installed", and those lines are what the misses are read
        # from -- deliberately not the %{name} of the hits. rpm accepts
        # name.arch and name-version specs and prints the bare name for
        # them, so a hit for vim-enhanced.x86_64 would print vim-enhanced
        # and never match what was asked. The "not installed" line echoes
        # the spec verbatim.
        results: dict[str, bool | None] = {}
        to_check: list[str] = []
        for package in packages:
            if package in self.installed_package_lookup_cache:
                results[package] = self.installed_package_lookup_cache[package]
            elif package not in to_check:
                to_check.append(package)
        if not to_check:
            return results
        if not command_exists("rpm"):
            for package in to_check:
                self.installed_package_lookup_cache[package] = None
                results[package] = None
            return results
        # Both the "not installed" line and the "error:" prefix are
        # translated strings, so a host locale other than English would hide
        # every miss and every failure from the checks below, and the batch
        # would read as "everything is installed". Pin the
        # locale so rpm speaks the English the parser expects.
        env = os.environ.copy()
        env["LC_ALL"] = "C"
        proc = run(["rpm", "-q", "--qf", "%{name}\n", *to_check], env=env, check=False)
        not_installed: set[str] = set()
        for line in (proc.stdout or "").splitlines():
            match = RPM_NOT_INSTALLED_RE.match(line.strip())
            if match:
                not_installed.add(match.group(1))
        # rpm exits with the number of specs it did not find, not 1: three
        # misses exit 3. Any exit status is therefore an ordinary answer,
        # and the misses are the "not installed" lines above. On a database
        # it cannot open, rpm also reports every spec as not installed; only
        # the "error:" line on stderr tells that apart, so it is checked
        # before the stdout is believed. A negative status is a signal, not
        # an exit, and rpm's output is incomplete.
        uncheckable = proc.returncode < 0 or "error:" in (proc.stderr or "").lower()
        for package in to_check:
            if uncheckable:
                outcome: bool | None = None
            else:
                outcome = package not in not_installed
            self.installed_package_lookup_cache[package] = outcome
            results[package] = outcome
        return results

    def search_host_packages(self, term: str, *, allow_metadata_refresh: bool = True) -> tuple[list[tuple[str, str]], bool, str | None]:
        normalized = " ".join(term.split())
        if not normalized:
            return [], False, None
        if not command_exists("dnf5"):
            return [], False, "dnf5 is not installed, so package search is unavailable on this system."

        cache_key = normalized.lower()
        cached = self.package_search_cache.get(cache_key)
        if cached is None:
            state_dir = self.dnf5_state_dir()
            pattern = f"*{normalized.replace(' ', '*')}*"
            proc = self.gum.spinner_result(
                f"Searching package names for: {normalized}",
                self.dnf5_command(
                    state_dir,
                    "-C",
                    "repoquery",
                    "--available",
                    "--latest-limit",
                    "1",
                    "--qf",
                    "%{name}\t%{summary}\n",
                    pattern,
                ),
            )
            detail = "\n".join(part for part in [proc.stdout, proc.stderr] if part).lower()
            if proc.returncode != 0:
                if DNF5_NO_CACHE_MARKER in detail:
                    # Offer the fix, then run the search again. The retry has
                    # the offer disabled so a refresh that reports success
                    # without producing usable metadata cannot loop.
                    if allow_metadata_refresh and self.refresh_package_metadata():
                        return self.search_host_packages(term, allow_metadata_refresh=False)
                    return [], False, PACKAGE_SEARCH_NEEDS_METADATA
                if any(marker in detail for marker in DNF5_MISSING_MARKERS):
                    return [], False, None
                return [], False, "Package search is unavailable right now. Use exact-name entry instead."

            by_name: dict[str, str] = {}
            for raw_line in proc.stdout.splitlines():
                line = raw_line.strip()
                if not line:
                    continue
                if "\t" in line:
                    name, summary = line.split("\t", 1)
                else:
                    name, summary = line, ""
                if name not in by_name:
                    by_name[name] = summary.strip()

            # dnf5 was asked for the words in order with anything between
            # them, but no RPM name contains a space, so ranking on the raw
            # term would leave every multi-word search in alphabetical order
            # and could push the obvious package past the limit. Words in a
            # package name are hyphen-joined, so rank on that spelling:
            # "kernel devel" puts kernel-devel first.
            needle = normalized.lower().replace(" ", "-")
            cached = sorted(
                by_name.items(),
                key=lambda item: (
                    item[0].lower() != needle,
                    not item[0].lower().startswith(needle),
                    needle not in item[0].lower(),
                    item[0].lower(),
                ),
            )
            self.package_search_cache[cache_key] = cached

        return cached[:PACKAGE_SEARCH_LIMIT], len(cached) > PACKAGE_SEARCH_LIMIT, None

    def confirm_ghcr_package_conflict(self, owner: str, repo: str) -> bool:
        # True means "go ahead and create the repo".
        if not ghcr_package_exists(owner, repo):
            return True
        package = repo.lower()
        self.gum.warn(f"A container package already exists at ghcr.io/{owner.lower()}/{package}.")
        self.gum.hint("Deleting a GitHub repo does not delete its packages, so this is usually left over from an earlier repo with the same name.")
        self.gum.hint("A brand-new repo cannot push to that package until the package grants it write access.")
        self.gum.hint("The build would run all the way through and then fail on its final push step.")
        print()
        self.menu_section(
            "How to Fix It",
            f"Package settings: https://github.com/users/{owner}/packages/container/{package}/settings",
            "Delete the package there, then answer yes -- the first build recreates it.",
            "Or answer yes now, then add this repo under 'Manage Actions access' with",
            "the Write role before the build reaches its push step. That selector only",
            "lists repos that already exist, so it cannot be done from here.",
        )
        print()
        return self.gum.confirm(f"Create {owner}/{repo} anyway?", default=False)

    def do_build(self) -> bool:
        # "Build" in this app really means "create or update the GitHub repo that
        # will trigger the real build on GitHub Actions."
        if not self.require_github():
            return False
        owner = self.github_user
        repo = self.config.repo_name
        self.config.github_user = owner
        self.validate_config()
        self.gum.header("Building Image")
        exists = run(["gh", "repo", "view", f"{owner}/{repo}", "--json", "name"], check=False).returncode == 0
        if exists:
            self.gum.error(f"{owner}/{repo} already exists on GitHub.")
            if self.repo_has_state_file(owner, repo):
                self.gum.hint("That repo was already created by this tool. Use 'Update Existing Image' to change it, or pick a new repo name.")
            else:
                self.gum.hint("That repo was not created by this tool.")
                self.gum.hint("This tool only updates repos it created itself. Pick a new repo name or manage that repo manually.")
            self.gum.enter_to_continue("Press Enter to go back to the review screen...")
            return False
        if not command_exists("cosign"):
            raise CommandError(
                "cosign is required to create a new repo because this tool must generate SIGNING_SECRET. Install it with: brew install cosign"
            )
        if not self.confirm_ghcr_package_conflict(owner, repo):
            self.gum.enter_to_continue("Press Enter to go back to the review screen...")
            return False
        self.gum.spinner(
            f"Creating {owner}/{repo}...",
            ["gh", "repo", "create", repo, "--description", self.config.image_desc, "--public"],
        )
        pushed = False
        try:
            self.config.signing_enabled = self.ensure_signing_ready(owner, repo)

            with tempfile.TemporaryDirectory(prefix=f"{TOOL_SLUG}.") as tmp:
                tmpdir = Path(tmp)
                # We build the initial commit locally from our bundled template
                # snapshot and only then push it to the brand-new remote repo.
                self.seed_project_template(tmpdir)
                branch = self.repo_default_branch(owner, repo)
                run(["git", "init", "-b", branch], cwd=tmpdir)
                run(["git", "remote", "add", "origin", f"https://github.com/{owner}/{repo}.git"], cwd=tmpdir)
                self.configure_temp_repo_git_identity(tmpdir)
                self.write_project_files(tmpdir, include_workflow=True, default_branch=branch)
                run(["git", "add", "-A"], cwd=tmpdir)
                run(["git", "commit", "-m", f"Initial image configuration via {TOOL_SLUG}"], cwd=tmpdir)
                run(["git", "push", "origin", "HEAD"], cwd=tmpdir, capture=False)
                pushed = True
        except BaseException:
            if not pushed:
                # Repo creation is the only irreversible network step before the
                # first push. If anything later fails, we delete that empty repo
                # so the user can retry cleanly instead of dealing with leftovers.
                self.gum.warn("Setup failed after the GitHub repo was created. Removing the empty repo so you can try again cleanly.")
                delete_proc = run(["gh", "repo", "delete", f"{owner}/{repo}", "--yes"], check=False)
                if delete_proc.returncode != 0:
                    self.gum.warn("I could not remove the new GitHub repo automatically.")
                    detail = "\n".join(part for part in [delete_proc.stdout, delete_proc.stderr] if part).strip()
                    if "delete_repo" in detail:
                        self.gum.hint("Your GitHub token needs the delete_repo scope to remove repos automatically.")
                        self.gum.hint("Delete the repo manually, or run: gh auth refresh -h github.com -s delete_repo")
                    else:
                        self.gum.hint("Delete the repo manually on GitHub before trying again.")
            raise

        image_uri = self.published_image_ref(owner)
        summary_lines = [
            "Repository Created",
            "",
            f"Repository: https://github.com/{owner}/{repo}",
            f"Image:      {image_uri}",
            "",
            "GitHub Actions is building your image now.",
            self.scheduled_rebuild_note(),
            "",
            "The first build publishes a private package. Make it public before switching:",
            ghcr_package_page_url(owner, repo),
            "",
        ]
        if self.config.signing_enabled:
            summary_lines.append("Before switching, follow 'Trusting The Signing Key' in the repo README.")
        summary_lines.extend(
            [
                "Then switch with:",
                self.bootc_switch_command(image_uri, signing_enabled=self.config.signing_enabled),
            ]
        )
        if self.config.signing_enabled:
            summary_lines.extend(
                [
                    "The enforcement flag verifies this switch and every later bootc upgrade.",
                    "Dropping it disables signature verification for both.",
                ]
            )
        summary_lines.append(f"Track the build: https://github.com/{owner}/{repo}/actions")
        if self.carried_scan_customizations():
            summary_lines.extend(
                [
                    "",
                    SCAN_SWITCH_LEAD_IN,
                    "Before rebooting, run this first in the same session:",
                    "sudo rpm-ostree reset",
                    "Then run the bootc switch command above.",
                    "",
                    "reset removes every layered package, override and initramfs change",
                    "on this system, not only the ones this image reproduces.",
                ]
            )
        print(
            self.gum.style(
                *summary_lines,
                align="center",
                width=self.gum.content_width(reserve=8),
                margin="1",
                padding="1 2",
                foreground=SUCCESS_COLOR,
                border_foreground=SUCCESS_COLOR,
                border="double",
            )
        )
        print()
        self.show_managed_repo_warning()
        self.gum.enter_to_continue("Press Enter to return to the main menu...")
        return True

    def test_build_locally(self, repo_dir: Path | None = None) -> None:
        if os.environ.get("AIB_DISABLE_LOCAL_BUILD"):
            # Set by the container image: podman is present there only as a
            # transitive dependency of rpm-ostree, so an in-container build
            # would be a nested build that is not supported and fails. Degrade
            # cleanly here instead. See maintenance_notes.txt.
            self.gum.warn("Local test builds are not available in this environment.")
            self.gum.hint("Run the tool from a local clone to test-build images with Podman.")
            # Pause so the message is read before the caller's menu redraws
            # over it (the caller clears the screen on its next iteration).
            self.gum.enter_to_continue("Press Enter to return to the menu...")
            return
        # The early exit below pauses for the same reason the branch above
        # does: run_screen_action pauses only on CommandError, so a plain
        # return goes straight back into the menu loop and its header() clears
        # the screen before the message can be read. podman is not a preflight
        # requirement, so this exit is reachable on any Homebrew install.
        if not command_exists("podman"):
            self.gum.warn("podman is required to run a local test build.")
            self.gum.hint("Install podman, then try this again.")
            self.gum.enter_to_continue("Press Enter to return to the menu...")
            return

        tag = f"{TOOL_SLUG}-local-test:dryrun"
        with tempfile.TemporaryDirectory(prefix=f"{TOOL_SLUG}-local-build.") as tmp:
            tmpdir = Path(tmp)
            self.seed_project_template(tmpdir)
            self.write_project_files(tmpdir, include_workflow=False)
            if self.config.method == "bluebuild" and not self.render_bluebuild_containerfile(tmpdir, repo_dir):
                self.gum.enter_to_continue("Press Enter to return to the menu...")
                return
            proc = self.gum.spinner_result(
                "Testing local podman build...",
                ["podman", "build", "-t", tag, str(tmpdir)],
            )
            if proc.returncode == 0:
                self.gum.success(f"Local test build succeeded: {tag}")
                self.gum.hint(f"Try inspecting it with: podman image inspect {tag}")
            else:
                self.report_local_build_failure("Local podman build", proc)
        self.gum.enter_to_continue("Press Enter to return to the menu...")

    def report_local_build_failure(self, what: str, proc: subprocess.CompletedProcess[str]) -> None:
        # Only the last eight stderr lines are shown: the useful part of a
        # failed podman build or bluebuild run is at the end, and the whole
        # log would push the menu off the screen.
        self.gum.error(f"{what} failed with exit status {proc.returncode}.")
        stderr = (proc.stderr or "").strip()
        if stderr:
            self.gum.hint("\n".join(stderr.splitlines()[-8:]))

    def render_bluebuild_containerfile(self, context: Path, repo_dir: Path | None) -> bool:
        """Turn the recipe in `context` into a Containerfile podman can build.

        CI never builds a recipe directly: blue-build/github-action installs
        the BlueBuild CLI and `bluebuild build` renders the recipe into a
        Containerfile before it hands that to the build driver. The local test
        build does the same two steps with the same CLI, fetched the way the
        action (and BlueBuild's own install.sh) fetches it -- a container
        created from the installer image, with the binary copied out. That
        avoids both a new host prerequisite and running the CLI inside the
        tool container, which is the nested build the AIB_DISABLE_LOCAL_BUILD
        exit refuses. `bluebuild generate` only reads the registry (the base
        image's digest and OS version) and the recipe schema; nothing is
        built until podman is, and podman is the same host podman the
        Containerfile path already uses.

        Returns False after reporting the failed step; the caller pauses.
        """
        cosign_pub = managed_path(context, "cosign.pub")
        if not cosign_pub.exists():
            # The recipe's signing module fails the build when the CLI has not
            # copied a public key in, and the CLI copies it from the context
            # root. The update path has the repo's real key; before the repo
            # exists there is none, so a marked placeholder stands in.
            repo_key = managed_path(repo_dir, "cosign.pub") if repo_dir is not None else None
            if repo_key is not None and repo_key.exists():
                shutil.copy2(repo_key, cosign_pub)
            else:
                cosign_pub.write_text(LOCAL_BUILD_PLACEHOLDER_COSIGN_PUB)
        with tempfile.TemporaryDirectory(prefix=f"{TOOL_SLUG}-bluebuild-cli.") as tmp:
            cli = Path(tmp) / "bluebuild"
            # By digest, so no --pull policy is needed: a digest either is in
            # local storage or is fetched, and it names the same bytes either
            # way. See BLUEBUILD_CLI_INSTALLER_IMAGE.
            #
            # The container is named up front and removed by name in a
            # finally that also covers the create: podman can have created
            # the container even when the spinner raises (Ctrl+C), and an ID
            # read from stdout would not exist yet to be cleaned up then.
            container_name = f"{TOOL_SLUG}-bluebuild-installer-{secrets.token_hex(8)}"
            try:
                created = self.gum.spinner_result(
                    "Fetching the BlueBuild CLI...",
                    ["podman", "create", "--name", container_name, BLUEBUILD_CLI_INSTALLER_IMAGE],
                )
                if created.returncode != 0:
                    self.report_local_build_failure(f"Fetching {BLUEBUILD_CLI_INSTALLER_IMAGE}", created)
                    return False
                copied = self.gum.spinner_result(
                    "Copying the BlueBuild CLI out of its installer image...",
                    ["podman", "cp", f"{container_name}:/out/bluebuild", str(cli)],
                )
            finally:
                run(["podman", "rm", "-f", container_name], check=False)
            if copied.returncode != 0:
                self.report_local_build_failure("Copying the BlueBuild CLI out of its installer image", copied)
                return False
            # CI's action runs the CLI inside its own image, where the CLI
            # detects itself as the podman driver. On the host the CLI
            # prefers docker when a docker with buildx is on PATH (the -dx
            # images ship one), and the template depends on the choice: under
            # docker the scripts bind mount loses its ,Z relabel and COPY
            # gains --link. The next step builds with host podman either
            # way, so the driver is pinned to match it.
            command = [str(cli), "generate", "--build-driver", "podman", "--output", "Containerfile"]
            # The signing module writes the image's registry path into
            # policy.json, so the rendered Containerfile matches CI's only
            # when it is told the same registry the action tells it.
            owner = (self.config.github_user or self.github_user).lower()
            if owner:
                command.extend(["--registry", "ghcr.io", "--registry-namespace", owner])
            command.append("recipes/recipe.yml")
            rendered = self.gum.spinner_result("Rendering the recipe with bluebuild generate...", command, cwd=context)
        if rendered.returncode != 0:
            self.report_local_build_failure("bluebuild generate", rendered)
            return False
        return True

    def select_repo(self, *, require_state_file: bool = False) -> tuple[str, str]:
        # This helper centralizes repo picking for update flows. The
        # require_state_file flag is what prevents the normal update path from
        # accidentally operating on unrelated repos.
        if not self.require_github():
            raise ScreenBack()
        while True:
            try:
                repo_data = self.gh_json_with_spinner(
                    "Fetching repositories from GitHub...",
                    ["repo", "list", self.github_user, "--json", "name,description", "--limit", str(REPO_LIST_LIMIT)],
                )
            except (CommandError, json.JSONDecodeError):
                self.gum.warn("I couldn't load your repository list from GitHub right now.")
                self.gum.hint("Type a repository name manually if you know one, or press Esc to go back.")
                repo_data = []
            repos = [
                item
                for item in (repo_data if isinstance(repo_data, list) else [])
                if isinstance(item, dict) and isinstance(item.get("name"), str)
            ]
            visible_repos = repos
            if require_state_file:
                self.gum.hint("Checking which repos were created by this tool...")
                managed = self.batch_check_state_files(self.github_user, repos)
                visible_repos = [item for item in repos if item["name"] in managed]
            if len(repos) >= REPO_LIST_LIMIT:
                # gh stopped at the cap, so a repo may be missing from the
                # list below; say so rather than let "none found" stand as fact.
                self.gum.warn(f"Only the {REPO_LIST_LIMIT} most recent repositories on your account were checked.")
                self.gum.hint("If yours is not listed, type its name manually.")
            elif not visible_repos:
                if require_state_file:
                    self.gum.warn("I couldn't find any GitHub repos on your account that were created by this tool yet.")
                    self.gum.hint("Type a repository name manually if you know one, or press Esc to go back.")
                else:
                    self.gum.warn("No repositories found on your GitHub account.")
                    self.gum.hint("Type a repository name manually if you want to check one by name, or press Esc to go back.")
            labels: list[str] = []
            mapping: dict[str, tuple[str, str]] = {}
            for item in visible_repos:
                # gum filter hands the chosen line back with its surrounding
                # whitespace stripped, so a label ending in a space never
                # matched its mapping key and Enter on that repo went back to
                # the menu. GitHub keeps whatever the owner typed, trailing
                # space and line breaks included; one line of single-spaced
                # words is also what a picker row can show.
                description = " ".join(str(item.get("description") or "").split()) or "(no description)"
                if len(description) > 40:
                    description = description[:37] + "..."
                label = f"{item['name']:<30} {description}"
                labels.append(label)
                mapping[label] = (self.github_user, item["name"].lower())
            manual_label = "Type a repository name manually"
            labels.append(manual_label)
            self.gum.controls("Type to search", "Up/Down move", "Enter choose", "Esc back", "Ctrl+C quit")
            self.menu_section(
                "Next Step",
                "Choose the last option if you want to type a repository name yourself.",
            )
            print()
            choice = self.gum.filter(labels, height=20, placeholder="Search repos...")
            if choice == manual_label:
                repo_input = self.gum.input(
                    prompt="Repository name: ",
                    placeholder=DEFAULT_REPO_NAME,
                    width=self.gum.form_width(max_width=72),
                ).strip()
                if not repo_input:
                    continue
                repo = sanitize_slug(repo_input)
                try:
                    repo_data = self.gh_json(["repo", "view", f"{self.github_user}/{repo}", "--json", "name"])
                except CommandError:
                    self.gum.error(f"{self.github_user}/{repo} was not found on GitHub.")
                    self.gum.enter_to_continue("Press Enter to choose a different repository...")
                    continue
                except json.JSONDecodeError:
                    self.gum.error(f"Unable to confirm {self.github_user}/{repo} on GitHub right now.")
                    self.gum.enter_to_continue("Press Enter to choose a different repository...")
                    continue
                if not isinstance(repo_data, dict) or not isinstance(repo_data.get("name"), str):
                    self.gum.error(f"Unable to confirm {self.github_user}/{repo} on GitHub right now.")
                    self.gum.enter_to_continue("Press Enter to choose a different repository...")
                    continue
                if require_state_file and not self.repo_has_state_file(self.github_user, repo):
                    self.gum.error(f"{self.github_user}/{repo} was not created by this tool.")
                    self.gum.hint(f"This tool can only update repos with `{STATE_FILE}`.")
                    self.gum.hint("Create a new repo with this tool instead, or manage that repo manually.")
                    self.gum.enter_to_continue("Press Enter to choose a different repository...")
                    continue
                return self.github_user, repo
            if choice in mapping:
                return mapping[choice]
            raise ScreenBack()

    def update_existing_image(self) -> None:
        # Update is deliberately limited to repos that already have the tool's
        # canonical state file.
        if not self.require_github():
            return
        try:
            owner, repo = self.select_repo(require_state_file=True)
        except ScreenBack:
            return
        self.config.repo_name = repo
        self.config.github_user = owner
        with tempfile.TemporaryDirectory(prefix=f"{TOOL_SLUG}-update.") as tmp:
            tmpdir = Path(tmp)
            self.clone_repo(owner, repo, tmpdir)
            self.load_repo_config(tmpdir)
            self.config.repo_name = repo
            self.config.github_user = owner
            if self.update_menu(repo_dir=tmpdir):
                self.show_summary()
                print()
                self.push_update(owner, repo, tmpdir)

    def view_build_status(self) -> None:
        # Most sessions never have a local clone of a managed repo (the app
        # works from temp clones), so falling back to the same managed-repo
        # picker used by "Update Existing Image" is what makes this reachable
        # in practice, instead of only working when run from inside a clone.
        repo_dir = Path.cwd()
        owner: str | None = None
        repo: str | None = None
        try:
            self.load_repo_config(repo_dir)
            owner = self.config.github_user or self.github_user
            repo = self.config.repo_name
        except CommandError:
            owner = None
            repo = None
        if not owner or not repo:
            # select_repo() already calls require_github() internally and
            # raises ScreenBack if the user backs out of GitHub login.
            try:
                owner, repo = self.select_repo(require_state_file=True)
            except ScreenBack:
                return
        self.render_build_status(owner, repo)

    def render_build_status(self, owner: str, repo: str) -> None:
        fields = "databaseId,displayTitle,status,conclusion,createdAt,updatedAt,url,workflowName"
        # Use check=False so a transient gh/network failure returns the user to
        # the main menu instead of raising CommandError out of the whole app.
        proc = run(["gh", "run", "list", "-R", f"{owner}/{repo}", "--limit", "5", "--json", fields], check=False)
        if proc.returncode != 0:
            self.gum.error("Unable to load GitHub Actions run data right now.")
            self.gum.hint("Check your network and gh login, then try again.")
            self.gum.enter_to_continue("Press Enter to return to the main menu...")
            return
        try:
            runs = json.loads(proc.stdout or "[]")
        except json.JSONDecodeError:
            # Pause like the branches either side of this one. view_build_status
            # has nothing after this call, so returning goes straight back into
            # main_menu's loop, which redraws immediately -- without a pause the
            # error is wiped off the screen before it can be read.
            self.gum.error("Unable to read GitHub Actions run data.")
            self.gum.enter_to_continue("Press Enter to return to the main menu...")
            return
        if not isinstance(runs, list) or not runs:
            self.gum.warn(f"No recent GitHub Actions runs found for {owner}/{repo}.")
            self.gum.enter_to_continue("Press Enter to return to the main menu...")
            return
        self.gum.header("Build Status")
        self.gum.hint(f"Recent GitHub Actions runs for {owner}/{repo}:")
        self.gum.hint("Status  Workflow                Title                                   When         URL")
        now = datetime.now(timezone.utc)
        for item in runs:
            if not isinstance(item, dict):
                continue
            conclusion = item.get("conclusion")
            icon = "✓" if conclusion == "success" else "✗" if conclusion else "●"
            workflow = self.truncate_label(str(item.get("workflowName") or "(workflow)"), limit=22)
            title = self.truncate_label(str(item.get("displayTitle") or f"Run {item.get('databaseId') or ''}").strip(), limit=38)
            created_at = item.get("createdAt")
            when = "unknown"
            if isinstance(created_at, str):
                try:
                    created = datetime.fromisoformat(created_at.replace("Z", "+00:00"))
                    if created.tzinfo is None:
                        # A timestamp with no Z and no offset (a GHES instance, or
                        # a future change in gh's output) parses fine but yields a
                        # naive datetime, and subtracting it from an aware `now`
                        # raises TypeError. GitHub reports UTC, so read it as UTC
                        # rather than dropping the column to "unknown".
                        created = created.replace(tzinfo=timezone.utc)
                    # A run created moments ago can carry a createdAt a few
                    # seconds ahead of this machine's clock. A negative delta
                    # has days == -1, which read as "-1d ago" on the screen
                    # people open right after pushing, so treat it as now.
                    delta = max(now - created, timedelta(0))
                    if delta.days:
                        when = f"{delta.days}d ago"
                    else:
                        hours = delta.seconds // 3600
                        minutes = (delta.seconds % 3600) // 60
                        when = f"{hours}h ago" if hours else f"{minutes}m ago"
                except (ValueError, TypeError, OverflowError):
                    when = "unknown"
            self.gum.hint(f"{icon:<7} {workflow:<22} {title:<38} {when:<12} {item.get('url') or ''}")

        # The riskiest step in the whole workflow is unassisted: after a build
        # that carried scanned packages, the user has to remember to reset and
        # switch in one session, without rebooting in between -- and by now the
        # build has taken the better part of an hour. This is the moment they
        # are standing there ready to do it, so say it again here.
        latest_succeeded = any(
            isinstance(item, dict) and item.get("conclusion") == "success" for item in runs
        )
        # A green build is not a switchable image. The package it published is
        # private by default, and this probe is the same anonymous pull a host
        # with no credentials would make -- so it answers the question that
        # actually decides whether the command below works. It clears itself:
        # once the package is public the check passes and this stops appearing.
        if latest_succeeded and not ghcr_package_exists(owner, repo, timeout=GHCR_ADVISORY_TIMEOUT):
            print()
            self.menu_section(
                "This Image Is Not Readable Yet",
                f"I could not pull ghcr.io/{owner.lower()}/{repo.lower()} anonymously.",
                "A newly published package is private, whatever the repository is set to, so a switch from a machine without registry credentials will fail.",
                f"Make it public: {ghcr_package_page_url(owner, repo)} -> Package settings -> Change visibility",
                f"Or give the machine GHCR pull credentials for root instead: {BOOTC_REGISTRY_DOCS_URL}",
            )
        if latest_succeeded and self.repo_carried_scan_customizations(owner, repo):
            signing_enabled = self.repo_signing_enabled(owner, repo)
            image_ref = f"ghcr.io/{owner.lower()}/{repo.lower()}:latest"
            print()
            self.menu_section(
                "Switching This Machine",
                SCAN_SWITCH_LEAD_IN,
                *(
                    (
                        "First follow 'Trusting The Signing Key' in the repo README.",
                        "The enforcement flag verifies this switch and every later bootc upgrade; dropping it disables both checks.",
                    )
                    if signing_enabled
                    else ()
                ),
                "Run both in the same session, and do not reboot in between:",
                "  sudo rpm-ostree reset",
                # Built from the arguments, not from self.config: this screen is
                # reachable via the repo picker, which does not load the config.
                f"  {self.bootc_switch_command(image_ref, signing_enabled=signing_enabled)}",
                "  systemctl reboot",
            )
        self.gum.enter_to_continue("Press Enter to return to the main menu...")

    def load_repo_config(self, repo_dir: Path) -> None:
        # Prefer the canonical JSON state file whenever possible. That is what
        # lets update flows be stable instead of reparsing generated shell.
        state_path = managed_path(repo_dir, STATE_FILE)
        if not state_path.exists():
            raise CommandError(
                f"This repo does not contain `{STATE_FILE}`, so it was not created by this tool. "
                "Only repos created by this tool are supported for updates."
            )
        try:
            data = json.loads(state_path.read_text())
        except (json.JSONDecodeError, UnicodeDecodeError, TypeError, OSError) as exc:
            raise CommandError(
                f"This repo's saved settings file `{STATE_FILE}` is missing or broken. "
                "Restore it from Git, or stop using this tool for this repo."
            ) from exc
        refuse_newer_tool_version(data)
        try:
            cfg = config_from_state_payload(data)
        except ValueError as exc:
            raise CommandError(
                f"This repo's saved settings file `{STATE_FILE}` is missing or broken. "
                "Restore it from Git, or stop using this tool for this repo."
            ) from exc
        except (json.JSONDecodeError, TypeError, OSError) as exc:
            raise CommandError(
                f"This repo's saved settings file `{STATE_FILE}` is missing or broken. "
                "Restore it from Git, or stop using this tool for this repo."
            ) from exc
        self.config = cfg
        if not self.github_user:
            self.github_user = cfg.github_user

    def update_menu(self, repo_dir: Path | None = None) -> bool:
        # Update uses a task-list style menu instead of the linear create wizard,
        # because returning users usually want to jump straight to one section.
        while True:
            self.gum.header("Update Image")
            self.menu_section(
                "Next Step",
                "Choose a section to review or change.",
                "Save and push changes when you are finished, or cancel to go back.",
            )
            print()
            mapping: dict[str, str] = {}
            options: list[str] = []
            for title, status in self.update_task_choices():
                label = self.format_task_choice(title, status)
                mapping[label] = title
                options.append(label)
            review_label = "Review current configuration"
            local_build_label = "Test build locally (podman)"
            rotate_label = "Rotate signing key (cosign)"
            save_label = "Save and push changes"
            cancel_label = "Cancel and go back"
            options.extend([review_label, local_build_label, rotate_label, save_label, cancel_label])
            try:
                choice = self.gum.choose(options, height=14)
            except ScreenBack:
                return False
            selected = choice[0] if choice else cancel_label
            if selected == save_label:
                self.config.normalize()
                return True
            if selected == cancel_label:
                return False
            if selected == review_label:
                self.show_summary(next_hint="This is the full configuration summary.")
                continue
            if selected == local_build_label:
                self.run_screen_action(
                    lambda: self.test_build_locally(repo_dir),
                    return_hint="Press Enter to return to the update menu...",
                )
                continue
            if selected == rotate_label:
                self.run_screen_action(
                    lambda: self.rotate_signing_key(repo_dir),
                    return_hint="Press Enter to return to the update menu...",
                )
                continue
            task = mapping[selected]
            try:
                if task == "Packages":
                    self.manage_packages()
                elif task == "Base image":
                    previous_base_uri = self.config.base_image_uri
                    previous_base_name = self.config.base_image_name
                    self.config.base_image_uri = ""
                    self.config.base_image_name = ""
                    try:
                        self.choose_base_image()
                    except ScreenBack:
                        self.config.base_image_uri = previous_base_uri
                        self.config.base_image_name = previous_base_name
                        raise
                elif task == "Description":
                    self.edit_description()
                elif task == "COPR repositories":
                    self.manage_copr_repos()
                elif task == "Services":
                    self.manage_services()
                elif task == "Removed base packages":
                    self.manage_removed_packages()
                elif task == "Homebrew":
                    self.offer_brew_if_applicable()
            except ScreenBack:
                continue

    def manage_packages(self) -> None:
        while True:
            self.gum.header("Edit Packages")
            self.gum.hint("Choose how you want to change packages.")
            self.render_package_menu_intro(
                packages_empty="None selected",
                next_step_hint="Choose Back to return to the update menu and keep the changes you already made here.",
            )
            print()
            try:
                choice = self.gum.choose(
                    ["Search package names", "Type exact package names", "Remove packages", "Back"],
                    height=8,
                )
            except ScreenBack:
                return
            selected = choice[0] if choice else "Back"
            if selected == "Back":
                return
            try:
                if selected == "Search package names":
                    self.search_packages()
                elif selected == "Type exact package names":
                    self.manual_packages()
                elif selected == "Remove packages":
                    self.config.packages = self.choose_to_remove(self.config.packages, "Remove Packages")
            except ScreenBack:
                continue

    def manage_copr_repos(self) -> None:
        while True:
            self.gum.header("Edit COPR Repositories")
            self.menu_section(
                "Next Step",
                "Choose how you want to change COPR repositories.",
                "Choose Back to return to the update menu and keep the changes you already made here.",
            )
            print()
            try:
                choice = self.gum.choose(
                    ["Add a COPR repository", "Remove a COPR repository", "Back"],
                    height=6,
                )
            except ScreenBack:
                return
            selected = choice[0] if choice else "Back"
            if selected == "Back":
                return
            try:
                if selected == "Add a COPR repository":
                    self.add_copr()
                elif selected == "Remove a COPR repository":
                    self.config.copr_repos = self.choose_to_remove(self.config.copr_repos, "Remove COPR Repos")
            except ScreenBack:
                continue

    def edit_description(self) -> None:
        self.gum.header("Edit Description")
        self.menu_section(
            "Description",
            "Enter a short description for this image.",
            "Leave it empty if you want to keep the current description.",
        )
        print()
        value = self.gum.input(
            prompt="New description: ",
            placeholder=self.config.image_desc,
            width=self.gum.form_width(max_width=110),
        )
        if value:
            self.config.image_desc = value

    def choose_to_remove(self, values: list[str], header: str) -> list[str]:
        if not values:
            self.gum.warn("Nothing to remove.")
            # The calling screen redraws with a clearing header next.
            self.gum.enter_to_continue("Press Enter to go back...")
            return values
        self.gum.header(header)
        self.gum.controls("Up/Down move", "x select", "Enter save", "Esc back", "Ctrl+C quit")
        self.menu_section("Selection", "Leave everything unselected if you want to keep everything.")
        print()
        selected = set(
            self.gum.choose(
                values,
                no_limit=True,
                height=20,
                selected_prefix="[x] ",
                unselected_prefix="[ ] ",
            )
        )
        return [value for value in values if value not in selected]

    def manage_services(self) -> None:
        self.gum.header("Edit Services")
        self.gum.controls("Up/Down move", "Enter choose", "Esc back", "Ctrl+C quit")
        self.menu_section(
            "Next Step",
            "Choose Back to return to the previous menu and keep the changes you already made here.",
        )
        print()
        try:
            choice = self.gum.choose(["Add services", "Remove services", "Back"], height=5)
        except ScreenBack:
            return
        selected = choice[0] if choice else "Back"
        if selected == "Add services":
            self.add_services()
        elif selected == "Remove services":
            self.config.services = self.choose_to_remove(self.config.services, "Remove Services")

    def manage_removed_packages(self, *, return_to: str = "update menu") -> None:
        self.gum.header("Edit Removed Base Packages")
        self.menu_section(
            "What This Does",
            "These are packages you want removed from the base image.",
            "Choose Add to type package names to remove, or Remove to stop removing packages you already listed.",
            f"Choose Back to return to the {return_to}. Changes are kept automatically.",
        )
        print()
        try:
            choice = self.gum.choose(["Add package names to remove", "Stop removing listed packages", "Back"], height=5)
        except ScreenBack:
            return
        selected = choice[0] if choice else "Back"
        if selected == "Add package names to remove":
            self.gum.write_controls()
            self.menu_section(
                "What To Enter",
                "Enter exact RPM package names separated by spaces or newlines.",
                "Leave this empty if you want to go back.",
            )
            raw = self.gum.write(
                placeholder="Enter package names separated by spaces...",
                height=6,
                width=self.gum.form_width(max_width=90),
            )
            packages = raw.replace(",", " ").split()
            if not packages:
                return
            before_count = len(self.config.removed_packages)
            added = self.add_removed_packages_to_config(packages, source_label="manual entry")
            added_count = len(self.config.removed_packages) - before_count
            if added and not self.last_manual_removed_package_check_had_missing:
                self.gum.enter_to_continue(f"Added {added_count} package removal(s). Press Enter to return to the {return_to}...")
                return
            if added and self.last_manual_removed_package_check_had_missing:
                self.gum.enter_to_continue(f"Finished checking package removals. Press Enter to return to the {return_to}...")
                return
            self.gum.enter_to_continue(f"No package removals were added. Press Enter to return to the {return_to}...")
        elif selected == "Stop removing listed packages":
            self.config.removed_packages = self.choose_to_remove(self.config.removed_packages, "Remove Base Package Removals")

    def push_update(self, owner: str, repo: str, repo_dir: Path) -> None:
        # The update path rewrites files in a temporary clone, shows the diff,
        # and only then asks for confirmation before pushing.
        #
        # write_project_files is called twice intentionally:
        #   1) First write: previews the diff before any secrets are created or
        #      rotated, so no new key material exists yet.
        #   2) Second write: after ensure_signing_ready() uploads the cosign
        #      keypair, adds the freshly generated cosign.pub.  If that
        #      changes the diff, the user is asked to re-confirm before
        #      pushing.
        self.generated_cosign_pub = None
        self.config.signing_enabled = True
        default_branch = self.repo_default_branch(owner, repo)
        self.write_project_files(repo_dir, include_workflow=True, default_branch=default_branch)
        diff = self.repo_diff_summary(repo_dir)
        if not diff:
            self.gum.warn("No changes detected.")
            # main_menu redraws with a clearing header next.
            self.gum.enter_to_continue("Press Enter to return to the main menu...")
            return
        print(diff)
        print()
        self.show_managed_repo_warning()
        print()
        if self.gum.confirm("View full diff?", default=False):
            full_diff = self.repo_full_diff(repo_dir)
            self.gum.pager(self.pager_text_with_hint(full_diff))
        if not self.gum.confirm(f"Push changes to {owner}/{repo}?", default=True):
            return
        self.config.signing_enabled = self.ensure_signing_ready(owner, repo, repo_dir=repo_dir)
        # Set when ensure_signing_ready() just generated a keypair and uploaded
        # its secrets. From here until the push lands, GitHub holds a private
        # key whose public half is not in the repo. The workflow signs whenever
        # SIGNING_SECRET is set, and a later session cannot tell the two apart
        # (secrets are write-only), so every way out below says so.
        new_signing_secrets = self.generated_cosign_pub is not None
        split_note = (
            "New signing secrets were already uploaded to GitHub, but the matching cosign.pub was not pushed, "
            "so images will be signed with a key the repo's cosign.pub cannot verify. "
            "Use 'Rotate signing key (cosign)' from the update menu before the next build."
        )
        self.write_project_files(repo_dir, include_workflow=True, default_branch=default_branch)
        final_diff = self.repo_diff_summary(repo_dir)
        if not final_diff:
            self.gum.warn("No changes detected.")
            if new_signing_secrets:
                self.gum.warn(split_note)
            self.gum.enter_to_continue("Press Enter to return to the main menu...")
            return
        if final_diff != diff:
            self.gum.warn("The final update changed after signing was prepared.")
            print(final_diff)
            print()
            if self.gum.confirm("View final full diff?", default=False):
                final_full_diff = self.repo_full_diff(repo_dir)
                self.gum.pager(self.pager_text_with_hint(final_full_diff))
            if not self.gum.confirm(f"Push final changes to {owner}/{repo}?", default=True):
                if new_signing_secrets:
                    self.gum.warn(split_note)
                    self.gum.enter_to_continue("Press Enter to return to the main menu...")
                return
        self.configure_temp_repo_git_identity(repo_dir)
        try:
            run(["git", "add", "-A"], cwd=repo_dir)
            run(["git", "commit", "-m", f"Update image configuration via {TOOL_SLUG} v{VERSION}"], cwd=repo_dir)
            run(["git", "push", "origin", "HEAD"], cwd=repo_dir, capture=False)
        except CommandError as exc:
            if not new_signing_secrets:
                raise
            # main_menu reports a CommandError and pauses, so the split state
            # rides along with the push failure itself.
            raise CommandError(f"{exc}\n{split_note}") from exc
        self.gum.success(f"Pushed changes to {owner}/{repo}.")
        self.gum.enter_to_continue("Press Enter to return to the main menu...")

    def repo_diff_summary(self, repo_dir: Path) -> str:
        parts: list[str] = []
        tracked_diff = run(["git", "diff", "--stat"], cwd=repo_dir).stdout.strip()
        if tracked_diff:
            parts.append(tracked_diff)
        untracked = self.repo_untracked_files(repo_dir)
        if untracked:
            parts.append("\n".join(f"?? {path}" for path in untracked))
        return "\n".join(parts)

    def repo_untracked_files(self, repo_dir: Path) -> list[str]:
        proc = run(
            ["git", "ls-files", "--others", "--exclude-standard", "-z"],
            cwd=repo_dir,
            check=False,
        )
        if proc.returncode != 0:
            raise CommandError(f"Could not enumerate untracked files in {repo_dir}.")
        return [path for path in proc.stdout.split("\0") if path]

    def repo_full_diff(self, repo_dir: Path) -> str:
        parts: list[str] = []
        tracked_diff = run(["git", "diff"], cwd=repo_dir).stdout.strip()
        if tracked_diff:
            parts.append(tracked_diff)
        for path in self.repo_untracked_files(repo_dir):
            proc = run(["git", "diff", "--no-index", "--", "/dev/null", path], cwd=repo_dir, check=False)
            if proc.returncode not in (0, 1):
                raise CommandError(f"Could not generate a full diff for untracked file {path}.")
            untracked_diff = proc.stdout.strip()
            if untracked_diff:
                parts.append(untracked_diff)
        if not parts:
            return ""
        return "\n\n".join(parts).rstrip("\n") + "\n"

    def pager_text_with_hint(self, text: str) -> str:
        hint = "Press q to close this diff and return to the previous screen."
        body = text.rstrip("\n")
        if not body:
            return hint + "\n"
        return f"{hint}\n\n{body}\n"

    def read_only_pager_text(self, title: str, lines: Sequence[str]) -> str:
        hint = "Press q to close this screen and return to the previous menu."
        body = "\n".join(lines).rstrip()
        if not body:
            return f"{title}\n\n{hint}\n"
        return f"{title}\n\n{hint}\n\n{body}\n"

    def format_key_value_rows(self, rows: Sequence[tuple[str, str]]) -> list[str]:
        if not rows:
            return []
        label_width = max(len(label) for label, _value in rows)
        return [f"{label:<{label_width}}  {value}" for label, value in rows]

    def validate_token_list(self, values: list[str], pattern: re.Pattern[str], label: str) -> None:
        # Validation happens before generating shell/YAML so bad values fail here
        # instead of turning into broken repo files or command injection risks.
        invalid = [value for value in values if not pattern.fullmatch(value)]
        if invalid:
            sample = ", ".join(invalid[:3])
            raise CommandError(f"Invalid {label} value(s): {sample}")

    def validate_config(self) -> None:
        # This is the final safety gate before any files are rendered or pushed.
        # It combines structural checks (repo name, base image) with token-level
        # checks for anything that will land in scripts or workflows.
        self.config.normalize()
        if self.config.method not in ALLOWED_METHODS:
            raise CommandError("Choose a supported build method before writing project files.")
        if not self.config.base_image_uri or re.search(r"\s", self.config.base_image_uri):
            raise CommandError("Base image URI is missing or invalid.")
        if not self.match_base_image(self.config.base_image_uri):
            raise CommandError(f"Choose one of the supported base images: {supported_base_image_names()}.")
        if self.config.method == "bluebuild" and "@" in self.config.base_image_uri:
            # match_base_image deliberately accepts a digest-pinned ref (a scanned
            # host is often booted on one), and the Containerfile path writes it
            # into FROM verbatim. BlueBuild splits the reference into base-image
            # and image-version and rejoins them with a colon, so a digest becomes
            # "...@sha256:abc...:latest" - unparseable, and every build fails.
            # Stop here with something actionable rather than pushing a dead repo.
            raise CommandError(
                "BlueBuild cannot use a digest-pinned base image "
                f"({self.config.base_image_uri}). Choose a tagged base image, or use the "
                "Containerfile method, which supports digest pins. If the base was detected "
                "from your system, switch the build method to Containerfile or re-run the scan "
                "and accept the recommended tag."
            )
        self.validate_token_list(self.config.packages, PACKAGE_TOKEN_RE, "package")
        self.validate_token_list(self.config.removed_packages, PACKAGE_TOKEN_RE, "removed package")
        self.validate_token_list(self.config.copr_repos, COPR_REPO_RE, "COPR repository")
        self.validate_token_list(self.config.services, SERVICE_TOKEN_RE, "systemd service")
        if not is_valid_repo_name(self.config.repo_name):
            raise CommandError(f"Repository name is invalid. {REPO_NAME_RULE}")

    def state_payload(self) -> dict[str, object]:
        # The JSON state file is the canonical source of truth for future
        # updates. Generated files are considered outputs, not the primary state.
        self.validate_config()
        payload = asdict(self.config)
        # scanned_packages/scanned_removed are the user's complete host software
        # inventory, including packages they looked at and deliberately did not
        # carry over. This file is committed and pushed to a repo created with
        # `gh repo create --public`, so writing them publishes that inventory to
        # anyone who looks. Nothing downstream reads the lists - the only
        # consumer, carried_scan_customizations(), needs a single boolean - so
        # record that instead. Popping also strips the lists from repos written
        # by an earlier version on their next update.
        payload["scan_customizations_carried"] = self.carried_scan_customizations()
        payload.pop("scanned_packages", None)
        payload.pop("scanned_removed", None)
        # Already folded into scan_customizations_carried above; the state
        # file keeps the one flag it has always had.
        payload.pop("scan_omitted_customizations", None)
        payload["tool_version"] = VERSION
        payload["state_version"] = 1
        return payload

    def render_containerfile(self, existing_text: str | None = None) -> str:
        # If the template already has a Containerfile, replace the FROM line and
        # inject or remove the brew block so we preserve upstream formatting and
        # comments where possible.
        if not existing_text:
            return self.generate_containerfile()
        lines = file_lines(existing_text)
        from_indices = containerfile_from_indices(lines)
        if not from_indices:
            return ensure_trailing_newline(existing_text)
        # The last stage is the image that gets built and published. Patching
        # the first non-scratch FROM instead rebased a builder stage added
        # ahead of it and gave it Homebrew, while the published stage kept its
        # old base -- a change that looks like a normal edit in the diff (#522).
        stage_names: set[str] = set()
        for index in from_indices[:-1]:
            stage = FROM_STAGE_NAME_RE.match(FROM_LINE_RE.match(lines[index]).group(3))
            if stage:
                stage_names.add(stage.group(1).lower())
        index = from_indices[-1]
        prefix, image, suffix = FROM_LINE_RE.match(lines[index]).groups()
        if image.lower() == "scratch" or image.lower() in stage_names:
            # Rewriting this FROM would discard the stage it builds on, and
            # rewriting any other would not change the published image. Stop
            # before anything is diffed or pushed.
            raise CommandError(
                f"The Containerfile's final stage (line {index + 1}: {lines[index].strip()}) does not "
                "start from a registry image, so the chosen base image and Homebrew setting cannot be "
                "applied to the image that gets published. Make the last FROM name the base image directly."
            )
        escape = containerfile_escape(lines)
        if self.config.brew_enabled and escape != "\\":
            # The brew block continues its RUNs with backslashes; under a
            # backtick escape each of those lines would parse as its own
            # instruction and the build would break after the push.
            raise CommandError(
                f"The Containerfile sets its escape character to {escape} with an '# escape=' parser "
                "directive, and the Homebrew block this tool adds is written for the default backslash. "
                "Remove the directive or turn Homebrew off for this image."
            )
        lines[index] = f"{prefix}{self.config.base_image_uri}{suffix}"
        lines = self._patch_brew_block(lines, from_index=index, continuation=CONTAINERFILE_CONTINUATION_RE[escape])
        return ensure_trailing_newline("\n".join(lines))

    def _patch_brew_block(self, lines: list[str], *, from_index: int, continuation: re.Pattern[str]) -> list[str]:
        # Find existing brew COPY line if present.
        brew_start: int | None = None
        brew_end: int | None = None
        # Only the stage that FROM opens is searched: a block in an earlier
        # stage is not in the published image, so it is not the one to update.
        for i in range(from_index + 1, len(lines)):
            line = lines[i]
            if line.strip().startswith("COPY --from=") and "brew" in line.lower() and "/system_files" in line:
                brew_start = i
                # The block is the COPY plus the RUNs that depend on what it
                # installs: the systemctl preset, and the step that strips the
                # payload's own login-shell fragments. Blank lines between them
                # are legal and a hand-edited Containerfile may well have them;
                # the old scan stopped at the first blank line, so disabling
                # Homebrew deleted only the COPY and left the RUN behind,
                # presetting units nothing provides any more and breaking the
                # build. It also stopped after one RUN, which was right when
                # the block had one; with two, an update that kept Homebrew on
                # would replace the preset and leave a stale second copy of the
                # fragment step stranded below it.
                brew_end = i + 1
                while True:
                    probe = brew_end
                    while probe < len(lines) and not lines[probe].strip():
                        probe += 1
                    if probe >= len(lines) or not lines[probe].strip().startswith("RUN"):
                        break
                    run_end = probe
                    while run_end < len(lines) and continuation.search(lines[run_end]):
                        run_end += 1
                    # Only absorb a RUN that belongs to the block - for the
                    # preset, "brew" appears on the continuation lines rather
                    # than the RUN line itself - so an unrelated neighbouring
                    # RUN is never eaten.
                    if "brew" not in " ".join(lines[probe : run_end + 1]).lower():
                        break
                    brew_end = run_end + 1
                # Consume a trailing blank line so removal/replacement
                # does not leave a double blank.
                if brew_end < len(lines) and not lines[brew_end].strip():
                    brew_end += 1
                break

        if not self.config.brew_enabled:
            # Remove the brew block if it exists.
            if brew_start is not None:
                return lines[:brew_start] + lines[brew_end:]
            return lines

        # brew_enabled: inject or replace the block.
        brew_lines = [
            f"COPY --from={UNIVERSAL_BLUE_BREW_IMAGE} /system_files /",
            "RUN --mount=type=cache,dst=/var/cache \\",
            "    --mount=type=cache,dst=/var/log \\",
            "    --mount=type=tmpfs,dst=/tmp \\",
            "    /usr/bin/systemctl preset brew-setup.service && \\",
            "    /usr/bin/systemctl preset brew-update.timer && \\",
            "    /usr/bin/systemctl preset brew-upgrade.timer",
            *brew_login_fragment_run_lines(),
            *brew_setup_staging_run_lines(),
            "",
        ]
        if brew_start is not None:
            return lines[:brew_start] + brew_lines + lines[brew_end:]
        # Insert after the FROM line (and any blank line following it).
        insert_at = from_index + 1
        if insert_at < len(lines) and not lines[insert_at].strip():
            insert_at += 1
        return lines[:insert_at] + brew_lines + lines[insert_at:]

    def patch_container_justfile(self, existing_text: str) -> str:
        # The template Justfile already has sensible defaults; we only patch the
        # image name so the local build target matches the chosen repo name.
        # This regex targets the older upstream Justfile shape (image name
        # sourced via env() with an inline default). Newer snapshots source
        # image name from image-template.env instead (see
        # patch_image_template_env), so this silently no-ops there by design.
        updated = re.sub(
            r'^export image_name := env\("IMAGE_NAME",\s*"[^"]*"\)(.*)$',
            f'export image_name := env("IMAGE_NAME", "{self.config.repo_name}")\\1',
            existing_text,
            count=1,
            flags=re.MULTILINE,
        )
        updated = self.patch_container_rechunk_config_arg(updated)
        updated = self.patch_spawn_vm_rebuild(updated)
        return ensure_trailing_newline(updated)

    def patch_spawn_vm_rebuild(self, justfile_text: str) -> str:
        # `spawn-vm`'s rebuild option forwards its own arguments to the wrong
        # recipe. build-vm is an alias for build-qcow2, whose parameters are
        # target_image and tag -- so `just spawn-vm 1 qcow2` asks for the
        # container image "1" at tag "qcow2" instead of rebuilding the
        # configured one, and the selected disk type is consumed as that tag
        # rather than choosing anything. Verified by running the real recipe
        # with a `just` stub first on PATH for the nested call: the command it
        # issues is `just build-vm 1 qcow2`.
        #
        # build-vm is also the wrong family. It converts an existing container
        # to a disk; rebuild-<type> is the helper that rebuilds the container
        # first, which is what "rebuild" asked for. rebuild-qcow2, rebuild-raw
        # and rebuild-iso all exist and default target_image and tag correctly,
        # so dispatching by type needs no arguments at all -- and the output
        # path systemd-vmspawn reads below then matches the type just built.
        #
        # Matched on upstream's exact line, so it no-ops if that recipe is
        # rewritten, like every other patcher here.
        return justfile_text.replace(SPAWN_VM_REBUILD_LINE, SPAWN_VM_REBUILD_FIXED, 1)

    def patch_container_rechunk_config_arg(self, justfile_text: str) -> str:
        # Existing managed repositories may still have either of two unsafe
        # `rechunk` shapes. The older one exports the full `podman inspect`
        # output as CHUNKAH_CONFIG_STR, then passes it to
        # `podman run -e CHUNKAH_CONFIG_STR ...`. For a base image that is
        # itself already chunked -- which in practice means most Universal
        # Blue images (Bazzite, Aurora, Bluefin, ...) -- that environment can
        # exceed the kernel's argument/environment size limit, making every
        # subsequent podman invocation fail with "Argument list too long."
        # A newer upstream shape derives a local mktemp directory from
        # target_image; registry-qualified names contain slashes, which mktemp
        # interprets as nonexistent parent directories. Rewrite both exact
        # legacy shapes while leaving the corrected bundled snapshot unchanged.
        # See maintenance_notes.txt.
        #
        # chunkah also accepts this same data via a mounted file (--config
        # <path>, per its own README), which has no such limit. Rewrite legacy
        # recipes to use that instead. The mount's `Z` flag is load-bearing on
        # SELinux-enforcing hosts (Fedora/bootc runners): without it the
        # container gets "Permission denied" reading the mounted file, a
        # second real failure mode this patch was verified against, not just
        # the ARG_MAX one. Matched on the legacy recipe's exact literal text;
        # if that recipe's shape differs, this silently no-ops like every
        # other patcher in this file.
        #
        # Cleanup of the temp config file uses `trap ... EXIT`, not a plain
        # `rm -f` at the end of the recipe. The recipe runs under `set -e`;
        # a bare trailing `rm -f` only runs on the success path, so if
        # `podman run` (chunkah) fails, `set -e` aborts the script right
        # there and the temp file -- containing the full image inspect
        # output -- is left behind. `trap` guarantees the cleanup runs on
        # every exit path, failure included. Flagged by a maintainer
        # (renner0e) reviewing the upstream issue for this same fix.
        vulnerable_output_dir = '    CHUNKAH_OUTPUT_DIR="$(mktemp -d ./"${target_image}"_chunkah_XXXXXX)"'
        safe_output_dir = '    CHUNKAH_OUTPUT_DIR="$(mktemp -d ./aib_chunkah_XXXXXX)"'
        updated = justfile_text.replace(vulnerable_output_dir, safe_output_dir, 1)

        old_block = (
            '    export CHUNKAH_CONFIG_STR=$(podman inspect "${target_image}")\n'
            '    podman run --rm --mount=type=image,src="${target_image}",target=/chunkah \\\n'
            '    -e CHUNKAH_CONFIG_STR quay.io/coreos/chunkah:latest \\\n'
            '    build \\\n'
            '    --verbose \\\n'
            '    --compressed \\\n'
            '    --max-layers 128 \\\n'
            '    --prune /sysroot/ \\\n'
            '    --label ostree.commit- --label ostree.final-diffid- \\\n'
            '    --tag "${target_image}:${tag}" | podman load\n'
        )
        new_block = (
            '    CHUNKAH_CONFIG_FILE=$(mktemp)\n'
            '    trap \'rm -f "${CHUNKAH_CONFIG_FILE}"\' EXIT\n'
            '    podman inspect "${target_image}" > "${CHUNKAH_CONFIG_FILE}"\n'
            '    podman run --rm --mount=type=image,src="${target_image}",target=/chunkah \\\n'
            '    -v "${CHUNKAH_CONFIG_FILE}:/chunkah-config.json:ro,Z" quay.io/coreos/chunkah:latest \\\n'
            '    build \\\n'
            '    --verbose \\\n'
            '    --compressed \\\n'
            '    --max-layers 128 \\\n'
            '    --prune /sysroot/ \\\n'
            '    --label ostree.commit- --label ostree.final-diffid- \\\n'
            '    --config /chunkah-config.json \\\n'
            '    --tag "${target_image}:${tag}" | podman load\n'
        )
        if old_block in updated:
            updated = updated.replace(old_block, new_block, 1)
        return updated

    def patch_image_template_env(self, existing_text: str) -> str:
        # image-template.env is dotenv-loaded by the Justfile, and its values are
        # interpolated directly into shell commands and label strings. Only the
        # three fields we own are rewritten, plus the builder image pin; every
        # other line (including comments) passes through untouched so future
        # upstream additions to this file are preserved across updates.
        def sanitize_env_value(value: str) -> str:
            # These characters would either break the double-quoted shell value,
            # let it escape into command substitution (e.g. via $(...)), or (for
            # line breaks) split the value across multiple physical lines. The
            # rewrite regexes below are per-line, so an embedded line break
            # would otherwise make this patcher silently stop matching that
            # field on every subsequent update. "Line break" is every boundary
            # str.splitlines() recognises, not only \n and \r: the file itself
            # is split on real line endings only (file_lines), but a U+2028 (or
            # \v, \f, U+0085) in a value the tool writes is still a line break
            # to some readers of this file, so it is dropped (#527).
            for char in ('"', "\\", "$", "`"):
                value = value.replace(char, "")
            return re.sub("[\n\r\v\f\x1c\x1d\x1e\x85\u2028\u2029]", "", value)

        repo_name = self.config.repo_name
        github_user = sanitize_env_value(self.config.github_user)
        image_desc = sanitize_env_value(self.config.image_desc)

        text = re.sub(
            r"^IMAGE_NAME=.*$",
            lambda _match: f"IMAGE_NAME={repo_name}",
            existing_text,
            count=1,
            flags=re.MULTILINE,
        )
        text = re.sub(
            r'^REPO_ORGANIZATION=".*"$',
            lambda _match: f'REPO_ORGANIZATION="{github_user}"',
            text,
            count=1,
            flags=re.MULTILINE,
        )
        text = re.sub(
            r'^IMAGE_DESC=".*"$',
            lambda _match: f'IMAGE_DESC="{image_desc}"',
            text,
            count=1,
            flags=re.MULTILINE,
        )
        # The same builder the disk workflow runs, for the local `just
        # build-qcow2` path -- see patch_disk_builder_image(). Anchored at the
        # line start like the three above.
        output: list[str] = []
        for line in file_lines(text):
            pinned = None if line[:1].isspace() else pin_disk_builder_image_line(line)
            output.append(line if pinned is None else pinned)
        return ensure_trailing_newline("\n".join(output))

    def patch_container_workflow(self, existing_text: str, *, default_branch: str = "main") -> str:
        # This patcher updates the bundled template workflow in place. The main
        # goals are:
        # - pin actions to SHAs
        # - keep our state file out of push triggers
        # - wire in image description and signing conditions safely
        branch_if = "github.event_name != 'pull_request' && github.ref == format('refs/heads/{0}', github.event.repository.default_branch)"
        sign_if = f"{branch_if} && env.{SIGNING_ENABLED_ENV[0]} == 'true'"
        lines = file_lines(existing_text)
        if STATE_FILE not in existing_text:
            lines = add_paths_ignore_entry(lines, f"'{STATE_FILE}'", ("- '**/README.md'", '- "**/README.md"'))
        scalar_body = block_scalar_body_indexes(lines)
        output: list[str] = []
        resume_at = 0
        for index, line in enumerate(lines):
            if index < resume_at:
                continue
            line = pin_action_uses_line(line)
            stripped = line.strip()
            if stripped.startswith("- cron:"):
                indent = line[: len(line) - len(line.lstrip())]
                output.append(f"{indent}- cron: '{DEFAULT_GITHUB_BUILD_CRON}'")
                continue
            if stripped.startswith("IMAGE_DESC:") and index not in scalar_body:
                # Rewritten where it stands. A top-level, job or step env
                # entry is equally the key, and writing it at two spaces
                # moved a nested one out of its mapping (#524). A value
                # continued over deeper lines -- `>-` and a folded
                # description -- goes with the line it belonged to, or
                # its remains would be orphaned under the new one.
                indent = line[: len(line) - len(line.lstrip())]
                output.append(f"{indent}IMAGE_DESC: {yaml_scalar(self.config.image_desc)}")
                resume_at = index + 1
                for later in range(index + 1, len(lines)):
                    if not lines[later].strip():
                        continue
                    if len(lines[later]) - len(lines[later].lstrip()) <= len(indent):
                        break
                    resume_at = later + 1
                continue
            output.append(line)
        text = patch_workflow_signing_steps("\n".join(output), branch_if=branch_if, sign_if=sign_if)
        text = patch_cosign_compatibility(text)
        text = self.patch_workflow_branch_filters(text, default_branch)
        # Remove before adding: a repository generated earlier has the key and
        # password at job level, and they have to go, not merely be joined by
        # the boolean -- but only once the step rewrite above has taken every
        # condition off them.
        text = strip_legacy_signing_job_env(text)
        text = ensure_workflow_job_env_entries(text, [SIGNING_ENABLED_ENV])
        text = self.patch_container_rechunk_step(text)
        text = strip_permission_entries(text, UNUSED_WORKFLOW_PERMISSIONS)
        return ensure_trailing_newline(text)

    def patch_container_rechunk_step(self, workflow_text: str) -> str:
        # The bundled workflow rechunks with rpm-ostree by default and ships a
        # commented-out Chunkah alternative (https://github.com/coreos/chunkah).
        # Chunkah is the newer, distro-agnostic rechunker, so we enable it by
        # default instead. Matching is scoped to non-comment lines so the
        # commented alternative block, and workflows where this step was
        # removed or never existed, are left untouched.
        # The recipe swap is scoped to the rechunk step's own body. A managed
        # repository may legitimately call `just ostree-rechunk` from a step of
        # its own (a diagnostic or a hand-written variant), and since existing
        # repositories are patched in place on update rather than replaced, a
        # file-wide substitution would silently rewrite that user's step too.
        # "Rechunk with Chunkah" counts as an in-scope step name so a workflow
        # left half-switched by an older tool version heals on its next update.
        lines = file_lines(workflow_text)
        output: list[str] = []
        in_rechunk_step = False
        step_indent = 0
        for line in lines:
            stripped = line.strip()
            indent = len(line) - len(line.lstrip())
            if stripped.startswith("#"):
                output.append(line)
                continue
            if stripped in RECHUNK_STEP_NAMES:
                in_rechunk_step = True
                step_indent = indent
                output.append(f"{line[:indent]}- name: Rechunk with Chunkah")
                continue
            if in_rechunk_step and stripped and indent <= step_indent:
                # The next step item, or any dedent back out to the job body,
                # ends this step.
                in_rechunk_step = False
            if in_rechunk_step:
                line = RECHUNK_RECIPE_RE.sub(r"\1\2rechunk", line)
            output.append(line)
        patched = ensure_trailing_newline("\n".join(output))

        # Once the step above is switched to Chunkah, upstream's own
        # commented-out "if you are feeling adventurous" alternative is
        # stale: it still suggests switching to Chunkah, and still contains
        # a commented copy of the very step that's now active just above
        # it. Strip it so the generated workflow doesn't carry a confusing,
        # self-contradictory leftover. Matched on upstream's exact literal
        # text in both of its shipped spellings (see
        # STALE_CHUNKAH_COMMENT_BLOCKS), same as every other patcher in this
        # file: silently no-ops if that text has drifted.
        for stale_comment_block in STALE_CHUNKAH_COMMENT_BLOCKS:
            if stale_comment_block in patched:
                return patched.replace(stale_comment_block, "", 1)
        return patched

    def patch_container_disk_workflow(self, existing_text: str, *, default_branch: str = "main") -> str:
        lines = [pin_action_uses_line(line) for line in file_lines(existing_text)]
        text = self.patch_workflow_path_filters("\n".join(lines))
        text = self.patch_disk_artifact_names(text)
        text = self.patch_disk_workflow_platform(text)
        text = self.patch_disk_builder_image(text)
        text = strip_permission_entries(text, UNUSED_WORKFLOW_PERMISSIONS)
        return self.patch_workflow_branch_filters(text, default_branch)

    def patch_workflow_path_filters(self, workflow_text: str) -> str:
        # GitHub matches a path filter against the complete path from the
        # repository root and rejects "." and ".." in a glob outright, so the
        # bundled workflow's './disk_config/disk.toml' matches nothing: the
        # pull-request validation those three filters configure never runs on
        # a change to the files they name. actionlint reports each as
        # "'.' and '..' are not allowed in glob path".
        #
        # Scoped twice over, because a relative path is only wrong in this one
        # place. './disk_config/iso.toml' appears again further down as an
        # input to the builder action, where it is an ordinary relative path
        # and correct as written -- so the rewrite is confined to entries
        # under a paths: key, and to a paths: key inside the `on:` block. An
        # action input happens to be able to be called "paths" too, and its
        # values are not GitHub filter patterns.
        lines = file_lines(workflow_text)
        output: list[str] = []
        in_triggers = False
        filter_indent: int | None = None
        for line in lines:
            stripped = line.strip()
            indent = len(line) - len(line.lstrip())
            if stripped and indent == 0:
                in_triggers = is_workflow_on_block(stripped)
                filter_indent = None
                output.append(line)
                continue
            if in_triggers and workflow_block_key(stripped) in {"paths", "paths-ignore"}:
                filter_indent = indent
                output.append(line)
                continue
            if filter_indent is not None:
                if stripped.startswith("- ") and indent > filter_indent:
                    output.append(RELATIVE_PATH_FILTER_RE.sub(r"\1\2\3", line))
                    continue
                filter_indent = None
            output.append(line)
        return ensure_trailing_newline("\n".join(output))


    def patch_disk_artifact_names(self, workflow_text: str) -> str:
        # The disk job is a matrix over disk-type, and its upload step names no
        # artifact -- so both jobs upload as upload-artifact's default name,
        # "artifact", with overwrite enabled. Whichever finishes second deletes
        # the other format's successful output before uploading its own, and
        # two jobs racing for one artifact name can also collide outright. A
        # manually dispatched build with S3 upload off is meant to leave both
        # downloadable formats in the completed run; it left one.
        #
        # matrix.disk-type alone is enough to make the name unique: artifacts
        # are scoped to a workflow run, and the matrix is over disk types only
        # -- the architecture is chosen once per run, not per job. The image
        # name is prefixed because a downloaded archive should say what it is.
        def patch_step(step_lines: list[str]) -> list[str]:
            if not any(UPLOAD_ARTIFACT_ACTION in line for line in step_lines):
                return step_lines
            with_indent: int | None = None
            # Always assigned before it is read: the `with:` line that sets
            # with_indent sets this too, and nothing reads it until then.
            insert_at = 0
            for index, line in enumerate(step_lines):
                stripped = line.strip()
                indent = len(line) - len(line.lstrip())
                if with_indent is None:
                    if workflow_block_key(stripped) == "with":
                        with_indent = indent
                        insert_at = index + 1
                    continue
                if not stripped:
                    # The bundled step ends on a whitespace-only line. Skipping
                    # it rather than treating it as the end of the block keeps
                    # the new key inside `with:` instead of after the blank.
                    continue
                if indent <= with_indent:
                    break
                if workflow_key(stripped) == "name":
                    # Already named, by upstream or by an earlier run of this
                    # patcher. Leave whatever is there alone.
                    return step_lines
                insert_at = index + 1
            if with_indent is None:
                return step_lines
            named = f"{' ' * (with_indent + 2)}name: {DISK_ARTIFACT_NAME}"
            return step_lines[:insert_at] + [named] + step_lines[insert_at:]

        return ensure_trailing_newline("\n".join(patch_workflow_steps(workflow_text, patch_step)))


    def patch_disk_workflow_platform(self, workflow_text: str) -> str:
        # The image workflow builds one native x86_64 image: a single
        # ubuntu-26.04 job, a plain `just build`, no --platform, no
        # multi-architecture manifest. The disk workflow nonetheless offered
        # arm64 and ran a native ARM builder against that same tag.
        # bootc-image-builder requires the builder and the bootc image to agree
        # on architecture, and the pinned action does not synthesize the
        # missing variant, so choosing ARM could not produce a matching
        # operating-system image -- and a multi-architecture *base* image does
        # not make the customized build on top of it multi-architecture.
        #
        # There is also no default for a non-dispatch event: on a pull request
        # inputs.platform is unset, so the ternary selects the ARM runner while
        # the two step conditions below read the same unset input in opposite
        # directions. Removing the input removes that inconsistency with it,
        # rather than leaving a second expression to keep in step.
        #
        # So the disk workflow is restricted to the architecture this tool
        # actually publishes. Offering the other one is not a runner label away
        # -- it needs the image workflow to build and publish the variant
        # first. See #236.
        lines = self.strip_disk_platform_input(file_lines(workflow_text))
        output: list[str] = []
        for line in lines:
            match = DISK_RUNNER_CHOICE_RE.match(line)
            if match:
                prefix, amd64_runner = match.groups()
                indent = line[: len(line) - len(line.lstrip())]
                output.append(f"{indent}# Only x86_64 is published, so disk builds run on the x86_64 runner.")
                output.append(f"{prefix}{amd64_runner}")
                continue
            output.append(line)
        output = self.strip_disk_platform_conditions(output)
        return ensure_trailing_newline("\n".join(output))

    def strip_disk_platform_input(self, lines: Sequence[str]) -> list[str]:
        # Drop the `platform:` key and everything nested under it, scoped to
        # the workflow_dispatch inputs so a job-level or step-level key of the
        # same name elsewhere is untouched.
        output: list[str] = []
        in_dispatch = False
        inputs_indent: int | None = None
        skip_indent: int | None = None
        for line in lines:
            stripped = line.strip()
            indent = len(line) - len(line.lstrip())
            if skip_indent is not None:
                if not stripped or indent > skip_indent:
                    continue
                skip_indent = None
            if workflow_block_key(stripped) == "workflow_dispatch" and indent == 2:
                in_dispatch = True
                inputs_indent = None
            elif indent <= 2 and stripped and workflow_key(stripped) is not None:
                in_dispatch = False
                inputs_indent = None
            if in_dispatch and workflow_block_key(stripped) == "inputs":
                inputs_indent = indent
                output.append(line)
                continue
            # inputs_indent is cleared by the top-level key that ends the
            # workflow_dispatch block, so a "platform:" still measured against
            # it is inside the dispatch inputs and nowhere else.
            if inputs_indent is not None and indent == inputs_indent + 2 and workflow_block_key(stripped) == "platform":
                skip_indent = indent
                continue
            output.append(line)
        return output

    def strip_disk_platform_conditions(self, lines: Sequence[str]) -> list[str]:
        # An ARM-only step goes with ARM; a not-ARM condition is now always
        # true, so only the condition goes. Anything else mentioning the input
        # is left alone, the way every patcher here no-ops on text it does not
        # recognise -- and the generated-project test asserts no reference to
        # inputs.platform survives, so a third condition fails loudly instead
        # of shipping a workflow that cannot resolve it.
        def patch_step(step_lines: list[str]) -> list[str]:
            if any(line.strip() == DISK_ARM_ONLY_IF for line in step_lines):
                return []
            return [line for line in step_lines if line.strip() != DISK_NON_ARM_IF]

        return patch_workflow_steps("\n".join(lines), patch_step)

    def patch_disk_builder_image(self, workflow_text: str) -> str:
        # The bundled workflow names bootc-image-builder by its :latest tag and
        # hands it to the builder action as `builder-image:`. The action is
        # pinned by SHA; the image it runs to produce every disk artifact the
        # repository publishes was the one input nothing pinned. Rewritten to
        # the digest in BOOTC_IMAGE_BUILDER_IMAGE, matched on the repository
        # so an earlier pin is refreshed and a builder the user swapped in is
        # left alone.
        #
        # Scoped to the top-level env: block. The value is read once, as
        # `${{ env.BIB_IMAGE }}`, and a step-level key that happened to share
        # the name would not be the one the action reads.
        lines = file_lines(workflow_text)
        output: list[str] = []
        in_env = False
        for line in lines:
            stripped = line.strip()
            indent = len(line) - len(line.lstrip())
            if stripped and indent == 0:
                in_env = workflow_block_key(stripped) == "env"
                output.append(line)
                continue
            pinned = pin_disk_builder_image_line(line) if in_env else None
            output.append(line if pinned is None else pinned)
        return ensure_trailing_newline("\n".join(output))

    def patch_workflow_branch_filters(self, workflow_text: str, default_branch: str) -> str:
        # Points every pull_request and push trigger at the default branch.
        # It runs over owner-edited text on every update, so it reads the
        # shape the file already has rather than assuming the snapshot's
        # (#523): an entry written at a different indent from the entries
        # beside it either mixes indentation inside one sequence -- a parse
        # error -- or folds into the entry above as one scalar, "main - main",
        # which matches no branch. Both leave a repository that builds nothing.
        #
        # Scoped to the `on:` block, the way patch_workflow_path_filters is:
        # a job may be called `push` too, and a `branches:` key inserted into
        # a job is a key Actions rejects.
        entry = yaml_plain_or_scalar(default_branch)

        def patch_trigger(block: list[str], trigger_indent: int) -> list[str]:
            content = [
                (index, len(line) - len(line.lstrip()), line.strip())
                for index, line in enumerate(block)
                if line.strip() and not line.strip().startswith("#")
            ]
            filter_indent = content[0][1] if content else trigger_indent + 2
            filter_keys: dict[str, int] = {}
            for index, indent, stripped in content:
                key = workflow_key(stripped) if indent == filter_indent else None
                if key is not None:
                    filter_keys.setdefault(key, index)
            # Actions refuses `branches` and `branches-ignore` on one event.
            # A trigger filtered by exclusion is the owner's choice, and
            # rewriting it into an inclusion list would be guessing at intent.
            if "branches-ignore" in filter_keys:
                return block
            prefix = " " * filter_indent
            key_index = filter_keys.get("branches")
            if key_index is None:
                return [f"{prefix}branches:", f"{prefix}  - {entry}", *block]
            key_line = block[key_index]
            is_block_key = workflow_block_key(key_line.strip()) is not None
            # The key's value is every deeper line, plus -- for a block key --
            # the entries of an indentless sequence at the key's own indent,
            # which is how PyYAML and ruamel write one. Comments inside it are
            # the owner's and stay; every entry goes, so no stale branch
            # survives behind a comment line.
            value_end = key_index + 1
            for index, indent, stripped in content:
                if index <= key_index:
                    continue
                is_entry = stripped == "-" or stripped.startswith("- ")
                if indent > filter_indent or (is_block_key and indent == filter_indent and is_entry):
                    value_end = index + 1
                    continue
                break
            if is_block_key:
                # Where the existing entries sit, so the new one joins the
                # same sequence -- key indent plus two only for an empty list.
                entry_indent = block_sequence_entry_indent(block, key_index)
            else:
                # An inline value, "branches: [main]", cannot take a block
                # entry beneath it; rewrite it to the block form.
                key_line = f"{prefix}branches:"
                entry_indent = prefix + "  "
            kept = [
                line for line in block[key_index + 1 : value_end] if not line.strip() or line.strip().startswith("#")
            ]
            return [*block[:key_index], key_line, f"{entry_indent}- {entry}", *kept, *block[value_end:]]

        lines = file_lines(workflow_text)
        output: list[str] = []
        in_triggers = False
        trigger_indent: int | None = None
        index = 0
        while index < len(lines):
            line = lines[index]
            stripped = line.strip()
            indent = len(line) - len(line.lstrip())
            index += 1
            if not stripped or stripped.startswith("#"):
                output.append(line)
                continue
            if indent == 0:
                in_triggers = is_workflow_on_block(stripped)
                trigger_indent = None
                output.append(line)
                continue
            if not in_triggers:
                output.append(line)
                continue
            if trigger_indent is None:
                trigger_indent = indent
            output.append(line)
            # Only block-style triggers can take a branches: key. An inline
            # flow mapping such as "push: { branches: [main] }" already owns
            # its filter inline; nesting another one under it is a parse
            # error, so it is left exactly as written.
            if indent != trigger_indent or workflow_block_key(stripped) not in {"pull_request", "push"}:
                continue
            # The trigger's block runs to the next line at or above its own
            # indent that is not a comment: a sibling trigger or the next
            # top-level key. That sibling is recognised by position, not by
            # a trailing colon -- the bundled BlueBuild snapshot ships
            # "  workflow_dispatch: # allow manually triggering builds", and
            # absorbing it into pull_request once wrote the filter onto the
            # wrong trigger and let PR builds fire from every branch.
            block_start = index
            while index < len(lines):
                block_line = lines[index]
                block_stripped = block_line.strip()
                block_indent = len(block_line) - len(block_line.lstrip())
                if block_stripped and not block_stripped.startswith("#") and block_indent <= trigger_indent:
                    break
                index += 1
            output.extend(patch_trigger(lines[block_start:index], trigger_indent))
        return ensure_trailing_newline("\n".join(output))

    def patch_bluebuild_action_inputs(self, workflow_text: str) -> str:
        def patch_step(step_lines: list[str]) -> list[str]:
            if not step_lines:
                return []
            if not any(re.search(r"uses:\s+blue-build/github-action@", line) for line in step_lines):
                return step_lines
            with_index = next((idx for idx, step_line in enumerate(step_lines) if step_line.strip() == "with:"), None)
            if with_index is None:
                return step_lines
            # The inputs go at the indent the owner's own inputs use. Written
            # at `with:` plus two beside inputs at plus four, they close the
            # mapping early and the next old input is a parse error (#524).
            # The same indent is what the drops below match keys at.
            entry_prefix = block_mapping_entry_indent(step_lines, with_index)
            entry_indent = len(entry_prefix)

            def drop_entries(source: list[str], prefixes: tuple[str, ...]) -> list[str]:
                # Drop "key: value" entries by key, along with any block-scalar
                # or continuation lines indented under them, so removing an
                # entry cannot leave orphaned value lines behind.
                kept: list[str] = []
                skipping = False
                for candidate in source:
                    if candidate.startswith(prefixes):
                        skipping = True
                        continue
                    if skipping:
                        candidate_stripped = candidate.strip()
                        candidate_indent = len(candidate) - len(candidate.lstrip())
                        # A blank line does not end the entry: block scalars
                        # (">-", "|") legitimately contain blank lines, and
                        # treating one as a terminator kept the scalar's
                        # remaining lines - orphaned under with: once their key
                        # was gone, which GitHub Actions rejects as invalid
                        # YAML. Only a nonblank line at the entry's own
                        # indentation or less closes it.
                        if not candidate_stripped or candidate_indent > entry_indent:
                            continue
                        skipping = False
                    kept.append(candidate)
                return kept

            # rechunk/build_chunked_oci conflict with chunkah in the action's
            # input validation, so drop them before adding chunkah below (a
            # hand-edited or previously-generated workflow may already set one).
            conflicting_prefixes = (f"{entry_prefix}rechunk:", f"{entry_prefix}build_chunked_oci:")
            step_lines = drop_entries(step_lines, conflicting_prefixes)
            wanted_lines = [
                f"{entry_prefix}push: ${{{{ github.event_name != 'pull_request' && github.ref == format('refs/heads/{{0}}', github.event.repository.default_branch) && 'true' || 'false' }}}}",
                f"{entry_prefix}build_opts: ${{{{ github.event_name == 'pull_request' && '--no-sign' || '' }}}}",
                # Chunkah is the newer, distro-agnostic rechunker (blue-build/github-action v1.12+).
                f"{entry_prefix}chunkah: 'true'",
            ]
            if all(line in step_lines for line in wanted_lines):
                return step_lines
            # These three inputs are ours to own, so strip any existing spelling
            # by key and reinsert canonically. Deciding "missing" by exact line
            # equality left a differently-valued `push:` in place (hand-edited,
            # or written by an older version of this tool with different
            # expression text) and inserted a second one, producing duplicate
            # keys in a single mapping - which GitHub Actions rejects outright,
            # so no build runs at all. This is the same prefix-based removal
            # already used for rechunk/build_chunked_oci just above.
            wanted_prefixes = tuple(
                f"{entry_prefix}{key}:" for key in ("push", "build_opts", "chunkah")
            )
            step_lines = drop_entries(step_lines, wanted_prefixes)
            with_index = next(
                idx for idx, step_line in enumerate(step_lines) if step_line.strip() == "with:"
            )
            return step_lines[: with_index + 1] + wanted_lines + step_lines[with_index + 1 :]

        return ensure_trailing_newline("\n".join(patch_workflow_steps(workflow_text, patch_step)))

    def patch_bluebuild_workflow(self, existing_text: str, *, default_branch: str = "main") -> str:
        # The BlueBuild workflow is simpler than the Containerfile one: a single
        # monolithic action handles the build. We pin the action, update the
        # schedule, add state-file ignore, and fix branch filters.
        lines = file_lines(existing_text)
        if STATE_FILE not in existing_text:
            lines = add_paths_ignore_entry(lines, f"'{STATE_FILE}'", ('- "**.md"', "- '**.md'"))
        output: list[str] = []
        replaced_cron_indent: int | None = None
        for line in lines:
            line = pin_action_uses_line(line)
            stripped = line.strip()
            if replaced_cron_indent is not None:
                # Upstream explains its own schedule in a comment under the
                # cron entry; once the entry is replaced it describes a time
                # the file no longer uses, so drop it (#706).
                line_indent = len(line) - len(line.lstrip())
                if stripped.startswith("#") and line_indent > replaced_cron_indent:
                    continue
                replaced_cron_indent = None
            if stripped.startswith("- cron:"):
                indent = line[: len(line) - len(line.lstrip())]
                output.append(f"{indent}- cron: '{DEFAULT_GITHUB_BUILD_CRON}'")
                replaced_cron_indent = len(indent)
                continue
            output.append(line)
        text = "\n".join(output)
        text = self.patch_workflow_branch_filters(text, default_branch)
        text = self.patch_bluebuild_action_inputs(text)
        return ensure_trailing_newline(text)

    def installer_profile(self) -> str:
        # The profile names are upstream's file names, and they describe the
        # desktop the config was written for rather than what it does.
        # iso-gnome.toml leaves account creation to a first-boot wizard;
        # iso-kde.toml has Anaconda ask for the user itself. That is the real
        # split, and it is BaseImage.first_boot_setup, not the desktop: this
        # used to key on a set of KDE names, which handed Sway Atomic the
        # gnome config and an ISO that installs a system with no account
        # (#361). A base the catalog does not know keeps the gnome config.
        matched = self.match_base_image(self.config.base_image_uri)
        if matched and not matched.first_boot_setup:
            return "kde"
        return "gnome"

    def installer_config_name(self) -> str:
        return f"iso-{self.installer_profile()}.toml"

    def patch_installer_config(self, existing_text: str) -> str:
        lines = file_lines(existing_text)
        image_ref = self.published_image_ref()
        for index, line in enumerate(lines):
            match = INSTALLER_SWITCH_RE.match(line)
            if not match:
                continue
            prefix, _current_ref, suffix = match.groups()
            replacement = f"{prefix}{image_ref}{suffix}"
            if self.config.signing_enabled and INSTALLER_UNVERIFIED_SWITCH_COMMENT[0] not in lines:
                lines[index : index + 1] = [*INSTALLER_UNVERIFIED_SWITCH_COMMENT, replacement]
            else:
                lines[index] = replacement
            break
        return ensure_trailing_newline("\n".join(lines))

    def write_installer_configs(self, base_dir: Path) -> None:
        disk_dir = managed_path(base_dir, "disk_config")
        if not disk_dir.exists():
            return
        for name in ("iso-gnome.toml", "iso-kde.toml"):
            path = managed_path(base_dir, f"disk_config/{name}")
            if path.exists():
                path.write_text(self.patch_installer_config(path.read_text()))
        selected_name = self.installer_config_name()
        selected_path = managed_path(base_dir, f"disk_config/{selected_name}")
        if selected_path.exists():
            iso_text = selected_path.read_text()
        else:
            template_path = CONTAINERFILE_TEMPLATE_DIR / "disk_config" / selected_name
            if not template_path.is_file():
                raise CommandError(f"Bundled installer config not found: {selected_name}")
            iso_text = template_path.read_text()
        managed_path(base_dir, "disk_config/iso.toml").write_text(self.patch_installer_config(iso_text))

    def _split_image_ref(self, uri: str) -> tuple[str, str]:
        # BlueBuild recipes separate "base-image" and "image-version" so we need
        # to split a combined URI like "ghcr.io/ublue-os/bazzite:stable".
        # A digest-pinned ref ("...@sha256:...") has no tag and its colon belongs
        # to the digest, so it cannot be split into this pair at all: BlueBuild
        # rejoins the two as "<base-image>:<image-version>", which for a digest
        # would yield "...@sha256:abc...:latest" and fail every build. Callers
        # must reject digests before they get here - validate_config does - so
        # reaching this branch is a bug, not a user error.
        if "@" in uri:
            raise CommandError(
                "BlueBuild recipes cannot express a digest-pinned base image. "
                f"Choose a tagged base image instead of {uri}, or use the Containerfile method."
            )
        if ":" in uri:
            base, tag = uri.rsplit(":", 1)
            return base, tag
        return uri, "latest"

    def generate_recipe(self) -> str:
        # Generate a BlueBuild recipe YAML from Config without needing pyyaml.
        # Every user-supplied scalar goes through yaml_scalar(). The token
        # validators are not enough on their own: PACKAGE_TOKEN_RE allows ":",
        # so a name like "epel:" would otherwise emit "- epel:", which YAML
        # parses as a mapping instead of the string BlueBuild's schema expects.
        # The repo name is the same rule for a different reason: it is a
        # perfectly good container name, but "null", "false" and "123" are
        # YAML literals, so emitted bare they reach BlueBuild as null, a
        # boolean and an integer against a schema that requires a string.
        # base-image is not quoted because it is not user-supplied -- it is
        # whichever curated URI match_base_image() accepted.
        base_image, image_version = self._split_image_ref(self.config.base_image_uri)
        lines = [
            "---",
            f"# yaml-language-server: $schema={BLUEBUILD_RECIPE_SCHEMA}",
            f"name: {yaml_scalar(self.config.repo_name)}",
            f"description: {yaml_scalar(self.config.image_desc)}",
            "",
            f"base-image: {base_image}",
            f"image-version: {yaml_scalar(image_version)}",
            "",
            "modules:",
            "  - type: files",
            "    files:",
            "      - source: system",
            "        destination: /",
        ]

        if self.config.brew_enabled:
            lines.extend([
                "",
                "  - type: containerfile",
                "    snippets:",
                f"      - COPY --from={UNIVERSAL_BLUE_BREW_IMAGE} /system_files /",
                "      - |",
                "        RUN --mount=type=cache,dst=/var/cache \\",
                "            --mount=type=cache,dst=/var/log \\",
                "            --mount=type=tmpfs,dst=/tmp \\",
                "            /usr/bin/systemctl preset brew-setup.service && \\",
                "            /usr/bin/systemctl preset brew-update.timer && \\",
                "            /usr/bin/systemctl preset brew-upgrade.timer",
                # A second literal block, so the fragment step stays one
                # snippet BlueBuild hands to the build shell intact. Its
                # printf lines are not YAML - inside a literal block scalar
                # nothing in them is interpreted - but they only survive that
                # way if the block is theirs alone.
                "      - |",
                *brew_login_fragment_run_lines(indent="        "),
                # And a third, for the same reason: one snippet per RUN, so
                # BlueBuild hands each to the build shell intact.
                "      - |",
                *brew_setup_staging_run_lines(indent="        "),
            ])

        if self.config.copr_repos or self.config.packages or self.config.removed_packages:
            lines.extend(["", "  - type: dnf"])
            if self.config.copr_repos:
                # BlueBuild's dnf module leaves the COPRs it enabled in place
                # unless cleanup is set, and it defaults to false. Without it
                # the image ships with every COPR still enabled, where the
                # Containerfile method disables each one in build.sh.
                lines.extend(["    repos:", "      cleanup: true", "      copr:"])
                for repo in self.config.copr_repos:
                    lines.append(f"        - {yaml_scalar(repo)}")
            if self.config.packages:
                lines.extend(["    install:", "      packages:"])
                for pkg in self.config.packages:
                    lines.append(f"        - {yaml_scalar(pkg)}")
            if self.config.removed_packages:
                lines.extend(["    remove:", "      packages:"])
                for pkg in self.config.removed_packages:
                    lines.append(f"        - {yaml_scalar(pkg)}")

        if self.config.services:
            lines.extend(["", "  - type: systemd", "    system:", "      enabled:"])
            for svc in self.config.services:
                lines.append(f"        - {yaml_scalar(svc)}")

        lines.extend(["", "  - type: signing"])
        return "\n".join(lines) + "\n"

    def write_bluebuild_project_files(self, base_dir: Path, *, include_workflow: bool, default_branch: str = "main") -> None:
        # This is the "materialize the repo" step for BlueBuild mode. The recipe
        # YAML replaces the Containerfile + build.sh used by Containerfile mode.
        readme_path = managed_path(base_dir, "README.md")
        gitignore_path = managed_path(base_dir, ".gitignore")
        recipe_path = managed_path(base_dir, "recipes/recipe.yml")
        workflow_path = managed_path(base_dir, ".github/workflows/build.yml")

        readme_path.write_text(self.generate_readme())

        existing_gitignore = file_lines(gitignore_path.read_text()) if gitignore_path.exists() else []
        for entry in ["cosign.key", "cosign.private"]:
            if entry not in existing_gitignore:
                existing_gitignore.append(entry)
        gitignore_path.write_text(ensure_trailing_newline("\n".join(existing_gitignore)))

        recipe_path.parent.mkdir(parents=True, exist_ok=True)
        recipe_path.write_text(self.generate_recipe())

        if self.generated_cosign_pub is not None:
            managed_path(base_dir, "cosign.pub").write_text(ensure_trailing_newline(self.generated_cosign_pub))

        if include_workflow:
            workflow_path.parent.mkdir(parents=True, exist_ok=True)
            if not workflow_path.exists():
                # Restore from the bundled template snapshot so updates can
                # recreate a workflow that was manually deleted.
                template_workflow = BLUEBUILD_TEMPLATE_DIR / ".github/workflows/build.yml"
                if template_workflow.exists():
                    shutil.copy2(template_workflow, workflow_path)
            if workflow_path.exists():
                workflow_path.write_text(self.patch_bluebuild_workflow(workflow_path.read_text(), default_branch=default_branch))

    def write_container_project_files(self, base_dir: Path, *, include_workflow: bool, default_branch: str = "main") -> None:
        # This is the "materialize the repo" step for Containerfile mode. It
        # patches template-owned files where possible and generates tool-owned
        # files where needed.
        readme_path = managed_path(base_dir, "README.md")
        gitignore_path = managed_path(base_dir, ".gitignore")
        justfile_path = managed_path(base_dir, "Justfile")
        env_path = managed_path(base_dir, "image-template.env")
        containerfile_path = managed_path(base_dir, "Containerfile")
        workflow_path = managed_path(base_dir, ".github/workflows/build.yml")

        readme_path.write_text(self.generate_readme())

        existing_gitignore = file_lines(gitignore_path.read_text()) if gitignore_path.exists() else []
        for entry in ["cosign.key", "_build*/", "output/", "*_chunkah_*"]:
            if entry not in existing_gitignore:
                existing_gitignore.append(entry)
        gitignore_path.write_text(ensure_trailing_newline("\n".join(existing_gitignore)))

        managed_path(base_dir, "build_files").mkdir(parents=True, exist_ok=True)
        # A regenerated Containerfile COPYs system_files into ctx, so the
        # directory has to exist even when the user has no overlay yet.
        managed_path(base_dir, "system_files").mkdir(parents=True, exist_ok=True)
        existing_containerfile = containerfile_path.read_text() if containerfile_path.exists() else None
        containerfile_path.write_text(self.render_containerfile(existing_containerfile))
        build_sh = managed_path(base_dir, "build_files/build.sh")
        build_sh.write_text(self.generate_build_sh())
        build_sh.chmod(0o755)
        if self.generated_cosign_pub is not None:
            managed_path(base_dir, "cosign.pub").write_text(ensure_trailing_newline(self.generated_cosign_pub))

        if not justfile_path.exists():
            # Restore from the bundled template snapshot so updates can recreate
            # a Justfile that was manually deleted, matching the pattern used
            # for the BlueBuild and Containerfile-method workflow files.
            template_justfile = CONTAINERFILE_TEMPLATE_DIR / "Justfile"
            if template_justfile.exists():
                shutil.copy2(template_justfile, justfile_path)
        justfile_text = ""
        if justfile_path.exists():
            justfile_text = justfile_path.read_text()
            justfile_path.write_text(self.patch_container_justfile(justfile_text))
        if not env_path.exists() and "image-template.env" in justfile_text:
            # Restored independently of the Justfile above: a repo can lose
            # just this file (e.g. a partial manual edit) while keeping an
            # otherwise-intact Justfile that still depends on it. Keyed on the
            # Justfile actually referencing image-template.env so older-shape
            # repos (whose Justfile never dotenv-loads it) do not gain an
            # inert copy of the file on update.
            template_env = CONTAINERFILE_TEMPLATE_DIR / "image-template.env"
            if template_env.exists():
                shutil.copy2(template_env, env_path)
        if env_path.exists():
            env_path.write_text(self.patch_image_template_env(env_path.read_text()))

        self.write_installer_configs(base_dir)

        if include_workflow:
            workflow_path.parent.mkdir(parents=True, exist_ok=True)
            if not workflow_path.exists():
                # Restore from the bundled template snapshot so updates can
                # recreate a workflow that was manually deleted. A repaired
                # repository then builds exactly as a new one does: the same
                # Justfile-driven build, Chunkah rechunk and tags, from the one
                # patched source rather than a second hand-written workflow.
                template_workflow = CONTAINERFILE_TEMPLATE_DIR / ".github/workflows/build.yml"
                if template_workflow.exists():
                    shutil.copy2(template_workflow, workflow_path)
            if workflow_path.exists():
                workflow_path.write_text(self.patch_container_workflow(workflow_path.read_text(), default_branch=default_branch))
            disk_workflow_path = managed_path(base_dir, ".github/workflows/build-disk.yml")
            if disk_workflow_path.exists():
                disk_workflow_path.write_text(self.patch_container_disk_workflow(disk_workflow_path.read_text(), default_branch=default_branch))

    def write_project_files(self, base_dir: Path, *, include_workflow: bool, default_branch: str = "main") -> None:
        # Always write the canonical state file first. That way the repo can be
        # updated later even if a human edits generated files by hand.
        self.validate_config()
        base_dir.mkdir(parents=True, exist_ok=True)
        managed_path(base_dir, STATE_FILE).write_text(json.dumps(self.state_payload(), indent=2) + "\n")
        if self.config.method == "bluebuild":
            self.write_bluebuild_project_files(base_dir, include_workflow=include_workflow, default_branch=default_branch)
        else:
            self.write_container_project_files(base_dir, include_workflow=include_workflow, default_branch=default_branch)

    def generate_containerfile(self) -> str:
        # The Containerfile is intentionally small. Most customization lives in
        # build_files/build.sh so users can inspect a simpler mutation layer.
        lines = [
            "FROM scratch AS ctx",
            "COPY build_files /",
            "COPY system_files /system_files",
            "",
            f"FROM {self.config.base_image_uri}",
            "",
        ]
        if self.config.brew_enabled:
            lines.extend([
                f"COPY --from={UNIVERSAL_BLUE_BREW_IMAGE} /system_files /",
                "RUN --mount=type=cache,dst=/var/cache \\",
                "    --mount=type=cache,dst=/var/log \\",
                "    --mount=type=tmpfs,dst=/tmp \\",
                "    /usr/bin/systemctl preset brew-setup.service && \\",
                "    /usr/bin/systemctl preset brew-update.timer && \\",
                "    /usr/bin/systemctl preset brew-upgrade.timer",
                *brew_login_fragment_run_lines(),
                *brew_setup_staging_run_lines(),
                "",
            ])
        lines.extend([
            "RUN --mount=type=bind,from=ctx,source=/,target=/ctx \\",
            "    --mount=type=cache,dst=/var/cache \\",
            "    --mount=type=cache,dst=/var/log \\",
            "    --mount=type=tmpfs,dst=/tmp \\",
            "    /ctx/build.sh",
            "",
            "RUN bootc container lint",
            "",
        ])
        return "\n".join(lines)

    def generate_build_sh(self) -> str:
        # build.sh is where user selections become actual package/service
        # changes inside the image. Values are shell-quoted before this point.
        lines = ["#!/bin/bash", "", "set -ouex pipefail", ""]
        # Newer upstream Containerfile snapshots stage a system_files/ overlay
        # into the ctx build stage. Guarded so old-shape repos and from-scratch
        # Containerfiles (which never COPY system_files into ctx) stay safe.
        lines.extend(
            [
                "if [ -d /ctx/system_files ]; then",
                "    cp -avf /ctx/system_files/. /",
                "fi",
                "",
            ]
        )
        if self.config.copr_repos:
            lines.append("# Enable COPR repositories")
            for repo in self.config.copr_repos:
                lines.append(f"dnf5 -y copr enable {shell_quote(repo)}")
            lines.append("")
        if self.config.removed_packages:
            lines.append("# Remove packages from the base image when they are installed")
            lines.append("packages_to_remove=()")
            lines.append("for pkg in \\")
            for pkg in self.config.removed_packages:
                lines.append(f"    {shell_quote(pkg)} \\")
            lines[-1] = lines[-1].removesuffix(" \\")
            lines.extend(
                [
                    "do",
                    '    if rpm -q --quiet "$pkg"; then',
                    '        packages_to_remove+=("$pkg")',
                    "    else",
                    '        echo "Skipping removal of $pkg because it is not installed in the base image."',
                    "    fi",
                    "done",
                    'if ((${#packages_to_remove[@]})); then',
                    '    dnf5 remove -y "${packages_to_remove[@]}"',
                    "fi",
                    "",
                ]
            )
        if self.config.packages:
            lines.append("# Install packages")
            lines.append("dnf5 install -y \\")
            for index, pkg in enumerate(self.config.packages):
                suffix = " \\" if index < len(self.config.packages) - 1 else ""
                lines.append(f"    {shell_quote(pkg)}{suffix}")
            lines.append("")
        else:
            lines.extend(["# dnf5 install -y <your-packages-here>", ""])
        if self.config.copr_repos:
            lines.append("# Disable COPRs so they do not persist in the final image")
            for repo in self.config.copr_repos:
                lines.append(f"dnf5 -y copr disable {shell_quote(repo)}")
            lines.append("")
        if self.config.copr_repos or self.config.removed_packages or self.config.packages:
            lines.append("# Clean dnf metadata before the final image is committed")
            lines.append("dnf5 clean all")
            lines.append("")
        if self.config.services:
            lines.append("# Enable systemd services")
            for service in self.config.services:
                lines.append(f"systemctl enable {shell_quote(service)}")
            lines.append("")
        return "\n".join(lines).rstrip() + "\n"

    def generate_readme(self) -> str:
        # The generated project README is intentionally brief and practical:
        # what base image was chosen, what package requests were configured, and
        # how to use the resulting image once GitHub finishes building it.
        base_name = self.config.base_image_name or self.config.base_image_uri
        owner = self.config.github_user or "your-user"
        image_ref = self.published_image_ref(owner)
        image_repository = image_ref.removesuffix(":latest")
        packages = "\n".join(f"- `{pkg}`" for pkg in self.config.packages) or "- None selected yet."
        copr_repos = "\n".join(f"- `{repo}`" for repo in self.config.copr_repos) or "- None."
        services = "\n".join(f"- `{service}`" for service in self.config.services) or "- None."
        removed_packages = "\n".join(f"- `{pkg}`" for pkg in self.config.removed_packages) or "- None."
        # A public repository does not make its packages public: visibility is
        # a separate setting on the package that does not inherit repository
        # access. Left at its default, the first build publishes an image that
        # `bootc switch` cannot read on a host with no GHCR credentials -- so
        # this belongs before the switch command, not as a troubleshooting
        # note after it.
        package_access_lines = [
            "## Before The First Switch",
            "",
            "The first build publishes",
            "",
            f"    {image_ref}",
            "",
            "as a **private** package. That is GitHub's default for a newly published package,",
            "and it does not change with the repository's own visibility, so `bootc switch` on a",
            "machine with no registry credentials cannot read it yet.",
            "",
            "Make it readable once, from the package's own page:",
            "",
            f"1. Open <{ghcr_package_page_url(owner, self.config.repo_name)}>",
            "2. **Package settings** -> **Change visibility** -> **Public**",
            "",
            "Keeping it private is fine too, but then the machine needs GHCR pull credentials for",
            f"root before the switch below will work. See <{BOOTC_REGISTRY_DOCS_URL}>.",
            "",
        ]
        signing_policy_lines: list[str] = []
        if self.config.signing_enabled:
            # /etc/pki/containers and /etc/containers/registries.d are both
            # machine-wide, so the repository name alone is not a unique
            # filename: two generated repositories with the same name under
            # different owners would install over each other's key while both
            # policy entries kept pointing at the one path. Owner-qualify the
            # key the same way the discovery file is already qualified.
            trust_basename = f"{owner.lower()}-{self.config.repo_name}"
            key_path = f"/etc/pki/containers/{trust_basename}.pub"
            signing_policy_lines = [
                "## Trusting The Signing Key",
                "",
                "This repository signs every published image. Before switching, clone this repo",
                "and install its committed public key:",
                "",
                "```bash",
                f"sudo install -Dm0644 cosign.pub {key_path}",
                "```",
                "",
                "The filename carries the owner because `/etc/pki/containers` is shared by every",
                "image this machine trusts.",
                "",
                # Telling the reader to paste a bare object member into
                # policy.json leaves them to work out the comma, and the stock
                # Fedora policy has no `docker` object to paste it into at all
                # -- so the literal instruction produced unparseable JSON and a
                # switch that fails closed. Do the merge for them instead.
                "Then add this repository to `/etc/containers/policy.json`. This command adds one",
                "entry, keeps every other entry, creates `transports` -> `docker` if the file has",
                "none -- the stock Fedora policy does not -- and always writes valid JSON:",
                "",
                "```bash",
                "sudo python3 - <<'EOF'",
                "import json, pathlib",
                "",
                'path = pathlib.Path("/etc/containers/policy.json")',
                "policy = json.loads(path.read_text())",
                'docker = policy.setdefault("transports", {}).setdefault("docker", {})',
                f'docker["{image_repository}"] = [',
                "    {",
                '        "type": "sigstoreSigned",',
                f'        "keyPath": "{key_path}",',
                '        "signedIdentity": {"type": "matchRepository"},',
                "    }",
                "]",
                'path.write_text(json.dumps(policy, indent=4) + "\\n")',
                "EOF",
                "```",
                "",
                "It reads and parses the file before writing anything, so an already-broken",
                "`policy.json` stops it rather than being overwritten. To edit the file by hand",
                "instead, add this member to the `docker` object, comma-separated from whatever",
                "is already there:",
                "",
                "```json",
                f'"{image_repository}": [',
                "  {",
                '    "type": "sigstoreSigned",',
                f'    "keyPath": "{key_path}",',
                '    "signedIdentity": { "type": "matchRepository" }',
                "  }",
                "]",
                "```",
                "",
                "Cosign stores these signatures as registry attachments, whose lookup is disabled",
                "by default. As root, create the repository-specific discovery file",
                f"`/etc/containers/registries.d/{trust_basename}.yaml` with:",
                "",
                "```yaml",
                "docker:",
                f"  {image_repository}:",
                "    use-sigstore-attachments: true",
                "```",
                "",
                "Reinstall `cosign.pub` after rotating the repository's signing key.",
                "",
            ]
        using_image_lines = [
            *package_access_lines,
            *signing_policy_lines,
            "## Using The Image",
            "",
            "After the first successful GitHub Actions build finishes, switch to it with:",
            "",
            "```bash",
            self.bootc_switch_command(image_ref, signing_enabled=self.config.signing_enabled),
            "systemctl reboot",
            "```",
        ]
        if self.config.signing_enabled:
            using_image_lines.extend(
                [
                    "",
                    "`--enforce-container-sigpolicy` verifies this switch against the policy above",
                    "and keeps signature verification enabled for later `bootc upgrade` operations.",
                    "Dropping the flag disables verification for both the switch and those upgrades.",
                ]
            )
        if self.carried_scan_customizations():
            using_image_lines = [
                *package_access_lines,
                *signing_policy_lines,
                "## Using The Image",
                "",
                SCAN_SWITCH_LEAD_IN,
                "Run these commands in the same session before rebooting:",
                "",
                "```bash",
                "sudo rpm-ostree reset",
                self.bootc_switch_command(image_ref, signing_enabled=self.config.signing_enabled),
                "systemctl reboot",
                "```",
                "",
                "Do not reboot between `rpm-ostree reset` and `bootc switch`.",
                "",
                # With no category flags, reset clears overlays, overrides and
                # initramfs customization alike -- not only the packages this
                # image reproduces. Presenting it as the last step of carrying
                # customizations over read as though it undid exactly what had
                # been carried, and anything else on the system went with it.
                "`rpm-ostree reset` removes **every** layered package, override and initramfs",
                "customization on this system, not only the ones this image reproduces. Run",
                "`rpm-ostree status` first and check for anything -- a local RPM, a replaced",
                "base package -- that this image does not build in.",
            ]
            if self.config.signing_enabled:
                using_image_lines.extend(
                    [
                        "",
                        "`--enforce-container-sigpolicy` verifies this switch against the policy above",
                        "and keeps signature verification enabled for later `bootc upgrade` operations.",
                        "Dropping the flag disables verification for both the switch and those upgrades.",
                    ]
                )

        sections = [
            f"# Custom {base_name} Image",
            "",
            self.config.image_desc,
            "",
            "This repository builds a custom bootc image on GitHub Actions.",
            "",
            "| Setting | Value |",
            "|---------|-------|",
            f"| Repository | `{owner}/{self.config.repo_name}` |",
            f"| Base Image | `{base_name}` |",
            f"| Base Image URI | `{self.config.base_image_uri}` |",
            f"| Published Image | `{image_ref}` |",
            f"| Build Method | `{METHOD_DISPLAY.get(self.config.method, self.config.method)}` |",
            "",
            f"## Managed By {TOOL_NAME}",
            "",
            f"This repo is managed by `{TOOL_SLUG}`. `{STATE_FILE}` is the saved settings file and source of truth for future updates.",
            "",
            f"If you hand-edit this repo after `{TOOL_SLUG}` creates or manages it, stop using `{TOOL_SLUG}` for this repo.",
            "",
            f"Later tool-driven updates rewrite managed files and can overwrite manual changes, especially `README.md` and `{'recipes/recipe.yml' if self.config.method == 'bluebuild' else 'build_files/build.sh'}`.",
            "",
            "## Requested Packages",
            "",
            f"These are the package names requested by this repo's {'recipe' if self.config.method == 'bluebuild' else 'generated build script'}.",
            self.requested_packages_note(),
            "",
            packages,
            "",
            "## COPR Repositories",
            "",
            copr_repos,
            "",
            "## Enabled Services",
            "",
            services,
            "",
            "## Removed Base Packages",
            "",
            removed_packages,
            "",
            *using_image_lines,
        ]
        return "\n".join(sections).rstrip() + "\n"

    def run_main(self) -> None:
        if not command_exists("gum"):
            self.preflight()
            return
        self.clear()
        self.banner()
        self.startup_requirements()
        self.preflight()
        self.main_menu()


def usage_text() -> str:
    # Kept deliberately short: the tool is a guided TUI, so this exists to
    # answer "what is this and how do I start it" for someone who typed
    # --help at a packaged container entrypoint, not to document the wizard.
    return "\n".join(
        [
            f"{TOOL_NAME} {VERSION}",
            "",
            f"Usage: {TOOL_COMMAND} [option]",
            "",
            "Run with no options to start the guided terminal interface.",
            "",
            "Options:",
            "  -h, --help     Show this help and exit.",
            "  -V, --version  Show the version and exit.",
            "",
            f"Requires {', '.join(PRECHECK_REQUIRED_TOOLS)} and a GitHub login (gh auth login).",
            f"Also requires {', '.join(HOST_REQUIRED_TOOLS)}, already present on rpm-ostree desktops.",
        ]
    )


def main() -> None:
    # Match the whole argument list, not just argv[1]: the tool is a guided
    # wizard, so anything it does not recognise (`-v`, `-hV`, a typo, a stray
    # trailing word, `--version --bogus`) must fail here rather than clear the
    # screen and wait at a prompt inside a script or a `podman run`.
    arguments = sys.argv[1:]
    if arguments in (["--version"], ["-V"]):
        print(f"{TOOL_COMMAND} {VERSION}")
        raise SystemExit(0)
    if arguments in (["--help"], ["-h"]):
        print(usage_text())
        raise SystemExit(0)
    if arguments:
        print(f"{TOOL_COMMAND}: unrecognized arguments: {' '.join(arguments)}", file=sys.stderr)
        print(file=sys.stderr)
        print(usage_text(), file=sys.stderr)
        raise SystemExit(2)
    app = App()
    try:
        app.run_main()
    except ScreenBack:
        print()
        raise SystemExit(0)
    except CommandError as exc:
        app.gum.error(str(exc))
        raise SystemExit(1) from exc
    except KeyboardInterrupt:
        print()
        raise SystemExit(130)


if __name__ == "__main__":
    main()