status: Render cached update info in human-readable output

After running `bootc upgrade --check`, the registry metadata for a
newer image is cached in ostree commit metadata. The `bootc status`
command already reads this into the `cachedUpdate` field and exposes
it in JSON/YAML output, but the human-readable output never displayed
it. This meant users had to parse structured output or re-run
`upgrade --check` to see available updates.

Render the cached update inline with each deployment entry, showing
version, timestamp, and digest when the cached digest differs from
the currently deployed image.

Relates: https://issues.redhat.com/browse/RHEL-139384

Assisted-by: OpenCode (Claude claude-opus-4-6)
Signed-off-by: Colin Walters <walters@verbum.org>

Author: cgwalters

crates/lib/src/fixtures/spec-booted-update-same-digest.yaml

@@ -0,0 +1,38 @@
+apiVersion: org.containers.bootc/v1alpha1
+kind: BootcHost
+metadata:
+  name: host
+spec:
+  image:
+    image: quay.io/centos-bootc/centos-bootc:stream9
+    transport: registry
+  bootOrder: default
+status:
+  staged: null
+  booted:
+    image:
+      image:
+        image: quay.io/centos-bootc/centos-bootc:stream9
+        transport: registry
+      architecture: arm64
+      version: stream9.20240807.0
+      timestamp: null
+      imageDigest: sha256:47e5ed613a970b6574bfa954ab25bb6e85656552899aa518b5961d9645102b38
+    cachedUpdate:
+      image:
+        image: quay.io/centos-bootc/centos-bootc:stream9
+        transport: registry
+      architecture: arm64
+      version: stream9.20240807.0
+      timestamp: null
+      imageDigest: sha256:47e5ed613a970b6574bfa954ab25bb6e85656552899aa518b5961d9645102b38
+    incompatible: false
+    pinned: false
+    downloadOnly: false
+    ostree:
+      checksum: 439f6bd2e2361bee292c1f31840d798c5ac5ba76483b8021dc9f7b0164ac0f48
+      deploySerial: 0
+      stateroot: default
+  rollback: null
+  rollbackQueued: false
+  type: bootcHost

crates/lib/src/fixtures/spec-booted-with-update-no-version.yaml

@@ -0,0 +1,38 @@
+apiVersion: org.containers.bootc/v1alpha1
+kind: BootcHost
+metadata:
+  name: host
+spec:
+  image:
+    image: quay.io/centos-bootc/centos-bootc:stream9
+    transport: registry
+  bootOrder: default
+status:
+  staged: null
+  booted:
+    image:
+      image:
+        image: quay.io/centos-bootc/centos-bootc:stream9
+        transport: registry
+      architecture: arm64
+      version: stream9.20240807.0
+      timestamp: null
+      imageDigest: sha256:47e5ed613a970b6574bfa954ab25bb6e85656552899aa518b5961d9645102b38
+    cachedUpdate:
+      image:
+        image: quay.io/centos-bootc/centos-bootc:stream9
+        transport: registry
+      architecture: arm64
+      version: null
+      timestamp: null
+      imageDigest: sha256:b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1
+    incompatible: false
+    pinned: false
+    downloadOnly: false
+    ostree:
+      checksum: 439f6bd2e2361bee292c1f31840d798c5ac5ba76483b8021dc9f7b0164ac0f48
+      deploySerial: 0
+      stateroot: default
+  rollback: null
+  rollbackQueued: false
+  type: bootcHost

crates/lib/src/fixtures/spec-booted-with-update.yaml

@@ -0,0 +1,38 @@
+apiVersion: org.containers.bootc/v1alpha1
+kind: BootcHost
+metadata:
+  name: host
+spec:
+  image:
+    image: quay.io/centos-bootc/centos-bootc:stream9
+    transport: registry
+  bootOrder: default
+status:
+  staged: null
+  booted:
+    image:
+      image:
+        image: quay.io/centos-bootc/centos-bootc:stream9
+        transport: registry
+      architecture: arm64
+      version: stream9.20240807.0
+      timestamp: "2024-08-07T12:00:00Z"
+      imageDigest: sha256:47e5ed613a970b6574bfa954ab25bb6e85656552899aa518b5961d9645102b38
+    cachedUpdate:
+      image:
+        image: quay.io/centos-bootc/centos-bootc:stream9
+        transport: registry
+      architecture: arm64
+      version: stream9.20240901.0
+      timestamp: "2024-09-01T12:00:00Z"
+      imageDigest: sha256:a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0
+    incompatible: false
+    pinned: false
+    downloadOnly: false
+    ostree:
+      checksum: 439f6bd2e2361bee292c1f31840d798c5ac5ba76483b8021dc9f7b0164ac0f48
+      deploySerial: 0
+      stateroot: default
+  rollback: null
+  rollbackQueued: false
+  type: bootcHost

crates/lib/src/status.rs

@@ -606,6 +606,39 @@ fn write_download_only(
     Ok(())
 }
 
+/// Render cached update information, showing what update is available.
+///
+/// This is populated by a previous `bootc upgrade --check` that found
+/// a newer image in the registry. We only display it when the cached
+/// digest differs from the currently deployed image.
+fn render_cached_update(
+    mut out: impl Write,
+    cached: &crate::spec::ImageStatus,
+    current: &crate::spec::ImageStatus,
+    prefix_len: usize,
+) -> Result<()> {
+    if cached.image_digest == current.image_digest {
+        return Ok(());
+    }
+
+    if let Some(version) = cached.version.as_deref() {
+        write_row_name(&mut out, "UpdateVersion", prefix_len)?;
+        let timestamp = cached.timestamp.as_ref().map(format_timestamp);
+        if let Some(timestamp) = timestamp {
+            writeln!(out, "{version} ({timestamp})")?;
+        } else {
+            writeln!(out, "{version}")?;
+        }
+    } else {
+        write_row_name(&mut out, "Update", prefix_len)?;
+        writeln!(out, "Available")?;
+    }
+    write_row_name(&mut out, "UpdateDigest", prefix_len)?;
+    writeln!(out, "{}", cached.image_digest)?;
+
+    Ok(())
+}
+
 /// Write the data for a container image based status.
 fn human_render_slot(
     mut out: impl Write,
@@ -664,6 +697,11 @@ fn human_render_slot(
         writeln!(out, "yes")?;
     }
 
+    // Show cached update information when available (from a previous `bootc upgrade --check`)
+    if let Some(cached) = &entry.cached_update {
+        render_cached_update(&mut out, cached, image, prefix_len)?;
+    }
+
     // Show /usr overlay status
     write_usr_overlay(&mut out, slot, host_status, prefix_len)?;
 
@@ -1249,4 +1287,56 @@ mod tests {
         "};
         similar_asserts::assert_eq!(w, expected);
     }
+
+    #[test]
+    fn test_human_readable_booted_with_cached_update() {
+        // When a cached update is present (from a previous `bootc upgrade --check`),
+        // the human-readable output should show the available update info.
+        let w =
+            human_status_from_spec_fixture(include_str!("fixtures/spec-booted-with-update.yaml"))
+                .expect("No spec found");
+        let expected = indoc::indoc! { r"
+          ● Booted image: quay.io/centos-bootc/centos-bootc:stream9
+                  Digest: sha256:47e5ed613a970b6574bfa954ab25bb6e85656552899aa518b5961d9645102b38 (arm64)
+                 Version: stream9.20240807.0 (2024-08-07T12:00:00Z)
+           UpdateVersion: stream9.20240901.0 (2024-09-01T12:00:00Z)
+            UpdateDigest: sha256:a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0
+        "};
+        similar_asserts::assert_eq!(w, expected);
+    }
+
+    #[test]
+    fn test_human_readable_cached_update_same_digest_hidden() {
+        // When the cached update has the same digest as the current image,
+        // no update line should be shown.
+        let w = human_status_from_spec_fixture(include_str!(
+            "fixtures/spec-booted-update-same-digest.yaml"
+        ))
+        .expect("No spec found");
+        assert!(
+            !w.contains("UpdateVersion:"),
+            "Should not show update version when digest matches current"
+        );
+        assert!(
+            !w.contains("UpdateDigest:"),
+            "Should not show update digest when digest matches current"
+        );
+    }
+
+    #[test]
+    fn test_human_readable_cached_update_no_version() {
+        // When the cached update has no version label, show "Available" as fallback.
+        let w = human_status_from_spec_fixture(include_str!(
+            "fixtures/spec-booted-with-update-no-version.yaml"
+        ))
+        .expect("No spec found");
+        let expected = indoc::indoc! { r"
+          ● Booted image: quay.io/centos-bootc/centos-bootc:stream9
+                  Digest: sha256:47e5ed613a970b6574bfa954ab25bb6e85656552899aa518b5961d9645102b38 (arm64)
+                 Version: stream9.20240807.0
+                  Update: Available
+            UpdateDigest: sha256:b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1
+        "};
+        similar_asserts::assert_eq!(w, expected);
+    }
 }

tmt/plans/integration.fmf

@@ -203,6 +203,14 @@ execute:
     test:
       - /tmt/tests/tests/test-37-install-no-boot-dir
 
+/plan-37-upgrade-check-status:
+  summary: Verify upgrade --check populates cached update in status
+  discover:
+    how: fmf
+    test:
+      - /tmt/tests/tests/test-37-upgrade-check-status
+  extra-fixme_skip_if_composefs: true
+
 /plan-38-install-bootloader-none:
   summary: Test bootc install with --bootloader=none
   discover:

tmt/tests/booted/test-upgrade-check-status.nu

@@ -0,0 +1,120 @@
+# number: 37
+# tmt:
+#   summary: Verify upgrade --check populates cached update in status
+#   duration: 30m
+# extra:
+#   fixme_skip_if_composefs: true
+#
+# TODO: This test uses containers-storage transport which is not yet
+# supported on the composefs backend. Remove the skip once composefs
+# supports copy-to-storage / switch --transport containers-storage.
+#
+# This test verifies that `bootc upgrade --check` caches registry
+# metadata and that `bootc status` renders the cached update.
+# Flow:
+# 1. Build derived image v1, switch to it, reboot
+# 2. Build v2, run `bootc upgrade --check`, verify status shows v2 as cached update
+# 3. Build v3, run `bootc upgrade --check` again, verify status now shows v3
+use std assert
+use tap.nu
+
+# This code runs on *each* boot.
+bootc status
+let st = bootc status --json | from json
+let booted = $st.status.booted.image
+
+def imgsrc [] {
+    "localhost/bootc-test-check"
+}
+
+# Run on the first boot - build v1 and switch to it
+def initial_build [] {
+    tap begin "upgrade --check cached update in status"
+
+    bootc image copy-to-storage
+
+    # A simple derived container that adds a file
+    "FROM localhost/bootc
+RUN echo v1 > /usr/share/test-upgrade-check
+" | save Dockerfile
+    podman build -t (imgsrc) .
+
+    # Switch into the derived image
+    bootc switch --transport containers-storage (imgsrc)
+    tmt-reboot
+}
+
+# Second boot: verify on v1, then test upgrade --check with v2 and v3
+def second_boot [] {
+    print "verifying second boot - should be on v1"
+    assert equal $booted.image.transport containers-storage
+    assert equal $booted.image.image (imgsrc)
+
+    let v1_content = open /usr/share/test-upgrade-check | str trim
+    assert equal $v1_content "v1"
+
+    let booted_digest = $booted.imageDigest
+    print $"booted digest: ($booted_digest)"
+
+    # Initially there should be no cached update
+    let initial_status = bootc status --json | from json
+    assert ($initial_status.status.booted.cachedUpdate == null) "No cached update initially"
+
+    # Build v2 with same tag - this is a newer image
+    "FROM localhost/bootc
+RUN echo v2 > /usr/share/test-upgrade-check
+" | save --force Dockerfile
+    podman build -t (imgsrc) .
+
+    # Run upgrade --check (metadata only, no deployment)
+    print "Running bootc upgrade --check for v2"
+    bootc upgrade --check
+
+    # Verify status now shows cached update
+    let status_after_v2 = bootc status --json | from json
+    assert ($status_after_v2.status.booted.cachedUpdate != null) "cachedUpdate should be populated after upgrade --check"
+
+    let v2_cached = $status_after_v2.status.booted.cachedUpdate
+    print $"v2 cached digest: ($v2_cached.imageDigest)"
+    assert ($v2_cached.imageDigest != $booted_digest) "Cached update digest should differ from booted"
+
+    # Verify human-readable output contains update info
+    let human_output = bootc status
+    print $"Human output:\n($human_output)"
+    assert ($human_output | str contains "UpdateVersion:") "Human-readable output should show UpdateVersion line"
+    assert ($human_output | str contains "UpdateDigest:") "Human-readable output should show UpdateDigest line"
+
+    # Now build v3 - another update on the same tag
+    "FROM localhost/bootc
+RUN echo v3 > /usr/share/test-upgrade-check
+" | save --force Dockerfile
+    podman build -t (imgsrc) .
+
+    # Run upgrade --check again
+    print "Running bootc upgrade --check for v3"
+    bootc upgrade --check
+
+    # Verify status now shows v3 as the cached update (not v2)
+    let status_after_v3 = bootc status --json | from json
+    assert ($status_after_v3.status.booted.cachedUpdate != null) "cachedUpdate should still be populated"
+
+    let v3_cached = $status_after_v3.status.booted.cachedUpdate
+    print $"v3 cached digest: ($v3_cached.imageDigest)"
+    assert ($v3_cached.imageDigest != $booted_digest) "v3 cached digest should differ from booted"
+    assert ($v3_cached.imageDigest != $v2_cached.imageDigest) "v3 cached digest should differ from v2"
+
+    # Verify human-readable output updated to v3
+    let human_output_v3 = bootc status
+    assert ($human_output_v3 | str contains "UpdateVersion:") "Human-readable output should still show UpdateVersion line after v3 check"
+    assert ($human_output_v3 | str contains $v3_cached.imageDigest) "Human-readable output should show v3 digest"
+
+    tap ok
+}
+
+def main [] {
+    match $env.TMT_REBOOT_COUNT? {
+        null | "0" => initial_build,
+        "1" => second_boot,
+        $o => { error make { msg: $"Invalid TMT_REBOOT_COUNT ($o)" } },
+    }
+}

tmt/tests/tests.fmf

@@ -117,6 +117,11 @@
   duration: 30m
   test: nu booted/test-install-no-boot-dir.nu
 
+/test-37-upgrade-check-status:
+  summary: Verify upgrade --check populates cached update in status
+  duration: 30m
+  test: nu booted/test-upgrade-check-status.nu
+
 /test-38-install-bootloader-none:
   summary: Test bootc install with --bootloader=none
   duration: 30m