status: Output targeted message in non-bootc case, update docs

- Output a clear message when we're not booted
- Update the docs and help to reflect current reality (e.g.
  format is stable) and include some guidance on use cases

Signed-off-by: Colin Walters <[email protected]>

Author: cgwalters

lib/src/cli.rs

@@ -369,10 +369,19 @@ pub(crate) enum Opt {
     Edit(EditOpts),
     /// Display status
     ///
-    /// This will output a YAML-formatted object using a schema intended to match a Kubernetes resource
-    /// that describes the state of the booted system.
+    /// If standard output is a terminal, this will output a description of the bootc system state.
+    /// If standard output is not a terminal, output a YAML-formatted object using a schema
+    /// intended to match a Kubernetes resource that describes the state of the booted system.
     ///
-    /// The exact API format is not currently declared stable.
+    /// ## Parsing output via programs
+    ///
+    /// Either the default YAML format or `--format=json` can be used. Do not attempt to
+    /// explicitly parse the output of `--format=humanreadable` as it will very likely
+    /// change over time.
+    ///
+    /// ## Programmatically detecting whether the system is deployed via bootc
+    ///
+    /// Invoke e.g. `bootc status --json`, and check if `status.booted` is not `null`.
     Status(StatusOpts),
     /// Adds a transient writable overlayfs on `/usr` that will be discarded on reboot.
     ///

lib/src/status.rs

@@ -364,8 +364,7 @@ fn human_render_ostree(mut out: impl Write, slot_name: &str, _ostree_commit: &st
     Ok(())
 }
 
-/// Implementation of rendering our host structure in a "human readable" way.
-fn human_readable_output(mut out: impl Write, host: &Host) -> Result<()> {
+fn human_readable_output_booted(mut out: impl Write, host: &Host) -> Result<()> {
     for (slot_name, status) in [
         ("staged", &host.status.staged),
         ("booted", &host.status.booted),
@@ -386,6 +385,16 @@ fn human_readable_output(mut out: impl Write, host: &Host) -> Result<()> {
     Ok(())
 }
 
+/// Implementation of rendering our host structure in a "human readable" way.
+fn human_readable_output(mut out: impl Write, host: &Host) -> Result<()> {
+    if host.status.booted.is_some() {
+        human_readable_output_booted(out, host)?;
+    } else {
+        writeln!(out, "System is not deployed via bootc.")?;
+    }
+    Ok(())
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -465,15 +474,7 @@ mod tests {
         // staged/rollback image, no booted
         let w = human_status_from_spec_fixture(include_str!("fixtures/spec-staged-rollback.yaml"))
             .expect("No spec found");
-        let expected = indoc::indoc! { r"
-    Current staged image: quay.io/example/someimage:latest
-        Image version: nightly (2023-10-14 19:22:15 UTC)
-        Image digest: sha256:16dc2b6256b4ff0d2ec18d2dbfb06d117904010c8cf9732cdb022818cf7a7566
-    No booted image present
-    Current rollback image: quay.io/example/someimage:latest
-        Image version: nightly (2023-09-30 19:22:16 UTC)
-        Image digest: sha256:736b359467c9437c1ac915acaae952aad854e07eb4a16a94999a48af08c83c34
-    "};
+        let expected = "System is not deployed via bootc.\n";
         similar_asserts::assert_eq!(w, expected);
     }