lib: Add --download-only flag for upgrade

Add support for downloading and staging updates without automatic
application on reboot. This allows users to prepare updates and apply
them at a controlled time.

User-facing changes:
- Add --download-only flag to bootc upgrade command
- bootc upgrade --download-only: stages deployment in download-only mode
- bootc upgrade (no flags): clears download-only mode if present
- bootc upgrade --apply: clears download-only mode and immediately reboots
- bootc upgrade --check: read-only, doesn't change download-only state
- bootc status shows "Download-only: yes/no" for staged deployments in verbose mode
- Garbage collection automatically cleans up unreferenced images after staging

Implementation details:
- Internally uses OSTree finalization locking APIs
- Sets opts.locked in SysrootDeployTreeOpts when staging deployments
- Added change_finalization() method to SysrootLock wrapper
- Tracks lock state changes separately from image digest changes
- Field name in BootEntry is download_only (Rust), downloadOnly (JSON)
- Verbose status display uses "Download-only" label (matches Soft-reboot pattern)
- Uses deployment.is_finalization_locked() API (OSTree v2023.8+)
- Always emits downloadOnly field in JSON output for consistency

Testing and documentation:
- New dedicated test: test-25-download-only-upgrade.nu (4-boot workflow)
- Test verifies: switch → upgrade --download-only → reboot (stays old) →
  re-stage → upgrade (clear) → reboot (applies)
- Updated docs/src/upgrades.md with comprehensive workflow examples
- Includes notes about reboot behavior and image switching
- Generated man pages and JSON schemas updated
- All test fixtures updated with downloadOnly field

The download-only flag is only available for upgrade, not switch.
The implementation is designed to support future composefs backend.

Assisted-by: Claude Code (Sonnet 4.5)
Signed-off-by: Wei Shi <wshi@redhat.com>

Author: shi2wei3

crates/lib/src/bootc_composefs/status.rs

@@ -234,6 +234,7 @@ async fn boot_entry_from_composefs_deployment(
         cached_update: None,
         incompatible: false,
         pinned: false,
+        download_only: false, // Not yet supported for composefs backend
         store: None,
         ostree: None,
         composefs: Some(crate::spec::BootEntryComposefs {

crates/lib/src/cli.rs

@@ -100,6 +100,14 @@ pub(crate) struct UpgradeOpts {
     #[clap(long = "soft-reboot", conflicts_with = "check")]
     pub(crate) soft_reboot: Option<SoftRebootMode>,
 
+    /// Download and stage the update without applying it.
+    ///
+    /// Download the update and ensure it's retained on disk for the lifetime of this system boot,
+    /// but it will not be applied on reboot. If the system is rebooted without applying the update,
+    /// the image will be eligible for garbage collection again.
+    #[clap(long, conflicts_with_all = ["check", "apply"])]
+    pub(crate) download_only: bool,
+
     #[clap(flatten)]
     pub(crate) progress: ProgressOptions,
 }
@@ -962,7 +970,35 @@ async fn upgrade(
             .map(|img| &img.manifest_digest == fetched_digest)
             .unwrap_or_default();
         if staged_unchanged {
-            println!("Staged update present, not changed.");
+            let staged_deployment = storage.get_ostree()?.staged_deployment();
+            let mut download_only_changed = false;
+
+            if let Some(staged) = staged_deployment {
+                // Handle download-only mode based on flags
+                if opts.download_only {
+                    // --download-only: set download-only mode
+                    if !staged.is_finalization_locked() {
+                        storage.get_ostree()?.change_finalization(&staged)?;
+                        println!("Image downloaded, but will not be applied on reboot");
+                        download_only_changed = true;
+                    }
+                } else if !opts.check {
+                    // --apply or no flags: clear download-only mode
+                    // (skip if --check, which is read-only)
+                    if staged.is_finalization_locked() {
+                        storage.get_ostree()?.change_finalization(&staged)?;
+                        println!("Staged deployment will now be applied on reboot");
+                        download_only_changed = true;
+                    }
+                }
+            } else if opts.download_only || opts.apply {
+                anyhow::bail!("No staged deployment found");
+            }
+
+            if !download_only_changed {
+                println!("Staged update present, not changed");
+            }
+
             handle_staged_soft_reboot(booted_ostree, opts.soft_reboot, &host)?;
             if opts.apply {
                 crate::reboot::reboot()?;
@@ -972,7 +1008,15 @@ async fn upgrade(
         } else {
             let stateroot = booted_ostree.stateroot();
             let from = MergeState::from_stateroot(storage, &stateroot)?;
-            crate::deploy::stage(storage, from, &fetched, &spec, prog.clone()).await?;
+            crate::deploy::stage(
+                storage,
+                from,
+                &fetched,
+                &spec,
+                prog.clone(),
+                opts.download_only,
+            )
+            .await?;
             changed = true;
             if let Some(prev) = booted_image.as_ref() {
                 if let Some(fetched_manifest) = fetched.get_manifest(repo)? {
@@ -1077,7 +1121,7 @@ async fn switch_ostree(
 
     let stateroot = booted_ostree.stateroot();
     let from = MergeState::from_stateroot(storage, &stateroot)?;
-    crate::deploy::stage(storage, from, &fetched, &new_spec, prog.clone()).await?;
+    crate::deploy::stage(storage, from, &fetched, &new_spec, prog.clone(), false).await?;
 
     storage.update_mtime()?;
 
@@ -1206,7 +1250,7 @@ async fn edit_ostree(
 
     let stateroot = booted_ostree.stateroot();
     let from = MergeState::from_stateroot(storage, &stateroot)?;
-    crate::deploy::stage(storage, from, &fetched, &new_spec, prog.clone()).await?;
+    crate::deploy::stage(storage, from, &fetched, &new_spec, prog.clone(), false).await?;
 
     storage.update_mtime()?;
 

crates/lib/src/deploy.rs

@@ -581,6 +581,7 @@ async fn deploy(
     from: MergeState,
     image: &ImageState,
     origin: &glib::KeyFile,
+    lock_finalization: bool,
 ) -> Result<Deployment> {
     // Compute the kernel argument overrides. In practice today this API is always expecting
     // a merge deployment. The kargs code also always looks at the booted root (which
@@ -608,6 +609,9 @@ async fn deploy(
             let stateroot = Some(stateroot);
             let mut opts = ostree::SysrootDeployTreeOpts::default();
 
+            // Set finalization lock if requested
+            opts.locked = lock_finalization;
+
             // Because the C API expects a Vec<&str>, convert the Cmdline to string slices.
             // The references borrow from the Cmdline, which outlives this usage.
             let override_kargs_refs = override_kargs
@@ -691,6 +695,7 @@ pub(crate) async fn stage(
     image: &ImageState,
     spec: &RequiredHostSpec<'_>,
     prog: ProgressWriter,
+    lock_finalization: bool,
 ) -> Result<()> {
     // Log the staging operation to systemd journal with comprehensive upgrade information
     const STAGE_JOURNAL_ID: &str = "8f7a2b1c3d4e5f6a7b8c9d0e1f2a3b4c";
@@ -748,7 +753,8 @@ pub(crate) async fn stage(
     })
     .await;
     let origin = origin_from_imageref(spec.image)?;
-    let deployment = crate::deploy::deploy(sysroot, from, image, &origin).await?;
+    let deployment =
+        crate::deploy::deploy(sysroot, from, image, &origin, lock_finalization).await?;
 
     subtask.completed = true;
     subtasks.push(subtask.clone());

crates/lib/src/fixtures/spec-booted-pinned.yaml

@@ -21,6 +21,7 @@ status:
     cachedUpdate: null
     incompatible: false
     pinned: true
+    downloadOnly: false
     ostree:
       checksum: 439f6bd2e2361bee292c1f31840d798c5ac5ba76483b8021dc9f7b0164ac0f48
       deploySerial: 0
@@ -37,6 +38,7 @@ status:
     cachedUpdate: null
     incompatible: false
     pinned: true
+    downloadOnly: false
     ostree:
       checksum: 99b2cc3b6edce9ebaef6a6076effa5ee3e1dcff3523016ffc94a1b27c6c67e12
       deploySerial: 0

crates/lib/src/fixtures/spec-only-booted.yaml

@@ -21,6 +21,7 @@ status:
     cachedUpdate: null
     incompatible: false
     pinned: false
+    downloadOnly: false
     ostree:
       checksum: 439f6bd2e2361bee292c1f31840d798c5ac5ba76483b8021dc9f7b0164ac0f48
       deploySerial: 0

crates/lib/src/fixtures/spec-ostree-remote.yaml

@@ -20,6 +20,7 @@ status:
       imageDigest: sha256:b5bb9d8014a0f9b1d61e21e796d78dccdf1352f23cd32812f4850b878ae4944c
     incompatible: false
     pinned: false
+    downloadOnly: false
     ostree:
       checksum: 41af286dc0b172ed2f1ca934fd2278de4a1192302ffa07087cea2682e7d372e3
       deploySerial: 0

crates/lib/src/fixtures/spec-ostree-to-bootc.yaml

@@ -20,6 +20,7 @@ status:
     cachedUpdate: null
     incompatible: false
     pinned: false
+    downloadOnly: false
     store: ostreeContainer
     ostree:
       checksum: 05cbf6dcae32e7a1c5a0774a648a073a5834a305ca92204b53fb6c281fe49db1
@@ -30,6 +31,7 @@ status:
     cachedUpdate: null
     incompatible: false
     pinned: false
+    downloadOnly: false
     store: null
     ostree:
       checksum: f9fa3a553ceaaaf30cf85bfe7eed46a822f7b8fd7e14c1e3389cbc3f6d27f791

crates/lib/src/fixtures/spec-rfe-ostree-deployment.yaml

@@ -11,6 +11,7 @@ status:
     cachedUpdate: null
     incompatible: true
     pinned: false
+    downloadOnly: false
     store: null
     ostree:
       checksum: 1c24260fdd1be20f72a4a97a75c582834ee3431fbb0fa8e4f482bb219d633a45
@@ -21,6 +22,7 @@ status:
     cachedUpdate: null
     incompatible: false
     pinned: false
+    downloadOnly: false
     store: null
     ostree:
       checksum: f9fa3a553ceaaaf30cf85bfe7eed46a822f7b8fd7e14c1e3389cbc3f6d27f791

crates/lib/src/fixtures/spec-staged-booted.yaml

@@ -21,6 +21,7 @@ status:
       imageDigest: sha256:16dc2b6256b4ff0d2ec18d2dbfb06d117904010c8cf9732cdb022818cf7a7566
     incompatible: false
     pinned: false
+    downloadOnly: false
     ostree:
       checksum: 3c6dad657109522e0b2e49bf44b5420f16f0b438b5b9357e5132211cfbad135d
       deploySerial: 0
@@ -37,6 +38,7 @@ status:
       imageDigest: sha256:736b359467c9437c1ac915acaae952aad854e07eb4a16a94999a48af08c83c34
     incompatible: false
     pinned: false
+    downloadOnly: false
     ostree:
       checksum: 26836632adf6228d64ef07a26fd3efaf177104efd1f341a2cf7909a3e4e2c72c
       deploySerial: 0

crates/lib/src/fixtures/spec-staged-download-only.yaml

@@ -0,0 +1,45 @@
+apiVersion: org.containers.bootc/v1alpha1
+kind: BootcHost
+metadata:
+  name: host
+spec:
+  image:
+    image: quay.io/example/someimage:latest
+    transport: registry
+    signature: insecure
+status:
+  staged:
+    image:
+      image:
+        image: quay.io/example/someimage:latest
+        transport: registry
+        signature: insecure
+      architecture: arm64
+      version: nightly
+      timestamp: 2023-10-14T19:22:15.42Z
+      imageDigest: sha256:16dc2b6256b4ff0d2ec18d2dbfb06d117904010c8cf9732cdb022818cf7a7566
+    incompatible: false
+    pinned: false
+    downloadOnly: true
+    ostree:
+      checksum: 3c6dad657109522e0b2e49bf44b5420f16f0b438b5b9357e5132211cfbad135d
+      deploySerial: 0
+      stateroot: default
+  booted:
+    image:
+      image:
+        image: quay.io/example/someimage:latest
+        transport: registry
+        signature: insecure
+      architecture: arm64
+      version: nightly
+      timestamp: 2023-09-30T19:22:16Z
+      imageDigest: sha256:736b359467c9437c1ac915acaae952aad854e07eb4a16a94999a48af08c83c34
+    incompatible: false
+    pinned: false
+    ostree:
+      checksum: 26836632adf6228d64ef07a26fd3efaf177104efd1f341a2cf7909a3e4e2c72c
+      deploySerial: 0
+      stateroot: default
+  rollback: null
+  isContainer: false