Add pcf-compact tool for compacting PCF files

A small CLI on top of the reference pcf crate's Container::compacted_image
(spec section 11.5). Removes dead space between table blocks and partition
data, and trims each partition's max_length to its used_bytes.

Default operation is atomic in-place: write to sibling temp, fsync, rename.
--output writes to a separate path; --no-verify skips integrity checks;
--force allows overwriting an existing --output.

Author: claude

Cargo.toml

@@ -1,3 +1,8 @@
 [workspace]
 resolver = "2"
-members = ["reference/PCF-v1.0", "reference/PFS-MS-v1.0", "tools/pcf-debug"]
+members = [
+    "reference/PCF-v1.0",
+    "reference/PFS-MS-v1.0",
+    "tools/pcf-debug",
+    "tools/pcf-compact",
+]

tools/pcf-compact/Cargo.toml

@@ -0,0 +1,23 @@
+[package]
+name = "pcf-compact"
+version = "0.0.1"
+edition = "2021"
+rust-version = "1.75"
+license = "MIT OR Apache-2.0"
+description = "Compactor for Partitioned Container Format (PCF) files: reclaims dead space and trims reservations"
+repository = "https://github.com/kduma-OSS/Partitioned-Container-Format"
+homepage = "https://github.com/kduma-OSS/Partitioned-Container-Format"
+readme = "README.md"
+keywords = ["pcf", "container", "compact", "binary"]
+categories = ["command-line-utilities", "filesystem"]
+
+[lib]
+name = "pcf_compact"
+path = "src/lib.rs"
+
+[[bin]]
+name = "pcf-compact"
+path = "src/main.rs"
+
+[dependencies]
+pcf = { path = "../../reference/PCF-v1.0", version = "0.0.1" }

tools/pcf-compact/README.md

@@ -0,0 +1,80 @@
+# `pcf-compact`
+
+A compactor for **Partitioned Container Format (PCF)** files. It rebuilds a
+container with all dead space removed and every partition's reservation
+trimmed to its `used_bytes`, exactly as defined by spec section 11.5.
+
+The tool is a thin wrapper around the reference [`pcf`](../../reference/PCF-v1.0)
+crate's `Container::compacted_image` — the algorithm lives there. What this
+crate adds is a CLI, safe atomic file replacement, and a savings report.
+
+## Build & run
+
+From the repository root:
+
+```sh
+# build
+cargo build -p pcf-compact
+
+# produce a sample file
+cargo run -p pcf --example gen_testvector -- /tmp/tv.pcf
+
+# compact it in place
+cargo run -p pcf-compact -- /tmp/tv.pcf
+```
+
+## Usage
+
+```text
+pcf-compact <FILE> [FLAGS]
+
+FLAGS:
+    -o, --output <PATH>   write the compacted file to PATH instead of
+                          overwriting <FILE> in place
+        --no-verify       skip integrity verification before and after
+                          compaction (default: verify both)
+        --force           overwrite an existing --output path
+    -q, --quiet           suppress the savings report on stderr
+    -h, --help            show help
+```
+
+### Examples
+
+```sh
+# In-place, with verification before and after (default).
+pcf-compact container.pcf
+
+# Write the compacted copy to a new path, leave the original alone.
+pcf-compact container.pcf --output container.compact.pcf
+
+# Overwrite an existing output file.
+pcf-compact container.pcf -o out.pcf --force
+
+# Skip verification (fast path for known-good inputs).
+pcf-compact container.pcf --no-verify
+```
+
+## Atomic write guarantees
+
+In-place mode (and `--output` to a fresh path) writes via a sibling temp file
+named `<target>.pcf-compact.tmp.<pid>.<nanos>`, fsyncs the data, then issues an
+atomic `rename(2)`. On crash either the original file is intact, or the new
+file is fully durable. Stray `*.pcf-compact.tmp.*` files left after a crash
+are safe to delete.
+
+Cross-filesystem `--output` (where the temp file and target would land on
+different mount points) is rejected rather than silently falling back to a
+non-atomic copy — pick an `--output` path on the same filesystem.
+
+## What it does *not* do
+
+- Edit individual partitions (`pcf-debug` is for inspection).
+- Change the table-hash algorithm beyond normalising every table block to
+  the algorithm used by the first block in the source chain.
+- Stream: the whole file is loaded into memory.
+
+## Tests
+
+```sh
+cargo test -p pcf-compact
+```

tools/pcf-compact/src/cli.rs

@@ -0,0 +1,102 @@
+//! Command-line parsing for `pcf-compact`.
+//!
+//! Hand-written on top of [`std::env::args`] to keep the tool free of any
+//! argument-parsing dependency (matching the reference crate's minimal-deps
+//! posture). Grammar:
+//!
+//! ```text
+//! pcf-compact <FILE> [FLAGS]
+//! ```
+
+use std::path::PathBuf;
+
+#[derive(Debug, Clone)]
+pub struct Args {
+    pub file: PathBuf,
+    pub output: Option<PathBuf>,
+    pub verify: bool,
+    pub quiet: bool,
+    pub force: bool,
+}
+
+#[derive(Debug)]
+pub enum Parsed {
+    Run(Args),
+    Help,
+}
+
+const HELP: &str = "\
+pcf-compact — rebuild a Partitioned Container Format (PCF) file with all dead
+space and per-partition reservations removed (spec section 11.5).
+
+USAGE:
+    pcf-compact <FILE> [FLAGS]
+
+FLAGS:
+    -o, --output <PATH>   write the compacted file to PATH instead of
+                          overwriting <FILE> in place
+        --no-verify       skip integrity verification before and after
+                          compaction (default: verify both)
+        --force           overwrite an existing --output path
+    -q, --quiet           suppress the savings report on stderr
+    -h, --help            show this help
+
+By default the tool overwrites <FILE> atomically: it writes the compacted
+image to a sibling temp file, fsyncs it, and then renames it into place.
+";
+
+pub fn help() -> &'static str {
+    HELP
+}
+
+/// Parse arguments (excluding `argv[0]`).
+pub fn parse(argv: &[String]) -> Result<Parsed, String> {
+    let mut positionals: Vec<String> = Vec::new();
+    let mut output: Option<PathBuf> = None;
+    let mut verify = true;
+    let mut quiet = false;
+    let mut force = false;
+
+    fn value(argv: &[String], i: &mut usize, flag: &str) -> Result<String, String> {
+        *i += 1;
+        argv.get(*i)
+            .cloned()
+            .ok_or_else(|| format!("flag {flag} needs a value"))
+    }
+
+    let mut i = 0;
+    while i < argv.len() {
+        let a = argv[i].clone();
+        match a.as_str() {
+            "-h" | "--help" => return Ok(Parsed::Help),
+            "-o" | "--output" => output = Some(PathBuf::from(value(argv, &mut i, &a)?)),
+            "--no-verify" => verify = false,
+            "--force" => force = true,
+            "-q" | "--quiet" => quiet = true,
+            other if other.starts_with('-') => {
+                return Err(format!("unknown flag: {other}"));
+            }
+            _ => positionals.push(a),
+        }
+        i += 1;
+    }
+
+    if positionals.is_empty() {
+        return Err("missing FILE argument".into());
+    }
+    if positionals.len() > 1 {
+        return Err(format!(
+            "unexpected positional argument: {:?}",
+            positionals[1]
+        ));
+    }
+    let file = PathBuf::from(&positionals[0]);
+
+    Ok(Parsed::Run(Args {
+        file,
+        output,
+        verify,
+        quiet,
+        force,
+    }))
+}