cli: add deb --resume/--keep and the deb list subcommand

Wiring for the session feature: --resume optionally takes a session
id (bare --resume adopts the newest session of the tree), --keep
keeps the session after a successful build, and 'pkh deb list'
renders the read-only session table for the current tree. Listing
is a subcommand, not a mode-switching flag: pkh deb with flags
always starts a build.

src/main.rs

@@ -361,8 +361,25 @@ fn main() {
                 .arg(arg!(--mode <mode> "Change build mode [local]").required(false)
                     .long_help("Change build mode [local]\nDefault will chose depending on other parameters, don't provide if unsure"))
                 .arg(arg!(-j --jobs <jobs> "Number of parallel build jobs (default: number of CPUs available in the build context)").required(false))
+                .arg(
+                    clap::Arg::new("resume")
+                        .long("resume")
+                        .value_name("ID")
+                        .num_args(0..=1)
+                        .require_equals(false)
+                        .default_missing_value("")
+                        .help("Resume a previous build session: reuse the chroot, build dependencies and build artifacts")
+                        .long_help("Resume a previous build session of this tree: the prepared chroot and installed build dependencies are reused, and the build continues in the staged tree (make recompiles only what changed).\nWithout a value, the newest session of this tree is adopted; with an ID (as shown by 'pkh deb list'), that exact session.\nA plain build never reuses a session: everything is rechecked from scratch."),
+                )
+                .arg(arg!(--keep "Keep the build session after a successful build (for a later --resume)")
+                    .long_help("Keep the build session after a successful build, so a later 'pkh deb --resume' can iterate on it (e.g. after editing sources).\nWithout it, a successful build consumes the session (failures and interrupts always keep it)."))
                 .arg(arg!(--verbose "Show raw tool output instead of the live build view").required(false)
-                    .long_help("Show raw tool output instead of the live build view.\nAlso implied by RUST_LOG=debug for pkh's own logs.")),
+                    .long_help("Show raw tool output instead of the live build view.\nAlso implied by RUST_LOG=debug for pkh's own logs."))
+                .subcommand(
+                    Command::new("list")
+                        .about("List the resumable build sessions recorded from this tree")
+                        .long_about("List the resumable build sessions recorded from this tree, one per target (series/arch), with the id to pass to 'pkh deb --resume <id>'.\nRead-only: never builds or removes anything ('pkh prune' removes old sessions)."),
+                )
         )
         .subcommand(
             Command::new("lint")
@@ -780,6 +797,17 @@ fn main() {
         }
         Some(("deb", sub_matches)) => {
             let cwd = current_dir_or_exit();
+
+            // `pkh deb list`: read-only listing of the resumable build
+            // sessions recorded from this tree; never touches the build
+            // machinery.
+            if let Some(("list", _)) = sub_matches.subcommand() {
+                let tree = cwd.canonicalize().unwrap_or(cwd.clone());
+                let rows = pkh::deb::session::list_for_tree(&tree);
+                print!("{}", pkh::deb::session::render_session_list(&tree, &rows));
+                return;
+            }
+
             // Ctrl+C during the build must say what happened and release the
             // ephemeral chroot instead of dying on the default disposition.
             // The live view (when enabled) registers its own reporter on top
@@ -818,6 +846,15 @@ fn main() {
                 })
             });
 
+            // Session handling: --resume [<id>] and --keep (see the deb
+            // subcommand help).
+            let resume = match sub_matches.get_one::<String>("resume").map(String::as_str) {
+                Some("") => pkh::deb::SessionResume::Latest,
+                Some(id) => pkh::deb::SessionResume::Id(id.to_string()),
+                None => pkh::deb::SessionResume::Fresh,
+            };
+            let keep_session = sub_matches.get_flag("keep");
+
             // Live build view, unless --verbose (DebUi additionally disables
             // itself when stdout is not a terminal)
             let quiet = pkh::report::Quiet;
@@ -842,6 +879,8 @@ fn main() {
                     ppa,
                     inject,
                     jobs,
+                    resume,
+                    keep_session,
                     view,
                     ..Default::default()
                 })