feat(man): add check/generate CLI with roff and man subcommands

Replace the simple stdout-only binary with a proper CLI that supports:
- `pdu-man-page generate roff 1` — render roff source to stdout
- `pdu-man-page generate man 1` — render man page via man(1) to stdout
- `pdu-man-page check roff 1` — verify exports/pdu.1 is up-to-date
- `pdu-man-page check man 1` — verify exports/pdu.1.man is up-to-date

The sync test now spawns the binary with `check` (like sync_ai_instructions),
and the `man` test is gated behind a `man-test` feature since it requires
man(1) to be installed.

https://claude.ai/code/session_01CrXuWDMVQsiUBoy6ceACsF

Author: claude

Cargo.toml

@@ -64,6 +64,7 @@ default = ["cli"]
 json = ["serde/derive", "serde_json"]
 cli = ["clap/derive", "clap_complete", "clap-utilities", "json"]
 cli-completions = ["cli"]
+man-test = []
 ai-instructions = ["clap/derive"]
 
 [dependencies]

cli/man_page.rs

@@ -1,5 +1,120 @@
+use clap::{Parser, ValueEnum};
 use parallel_disk_usage::man_page::render_man_page;
+use std::process::{Command, ExitCode};
 
-fn main() {
-    print!("{}", render_man_page());
+const MANWIDTH: &str = "120";
+
+/// Manage generated man pages.
+#[derive(Debug, Parser)]
+struct Args {
+    /// Action to take.
+    #[clap(value_enum)]
+    action: Action,
+    /// Type of file to target.
+    #[clap(value_enum)]
+    kind: Kind,
+    /// Number of the man page.
+    #[clap(value_enum)]
+    page: Page,
+}
+
+#[derive(Debug, Clone, ValueEnum)]
+enum Action {
+    /// Check whether the man page is up-to-date.
+    Check,
+    /// Generate the man page.
+    Generate,
+}
+
+#[derive(Debug, Clone, ValueEnum)]
+enum Kind {
+    /// Check or generate the roff file (`pdu.N`) from `Args`.
+    Roff,
+    /// Check or generate the man file (`pdu.N.man`) from the generated roff file (`pdu.N`).
+    Man,
+}
+
+#[derive(Debug, Clone, ValueEnum)]
+enum Page {
+    #[clap(name = "1")]
+    One,
+}
+
+impl Page {
+    fn number(&self) -> u8 {
+        match self {
+            Page::One => 1,
+        }
+    }
+}
+
+fn roff_path(page_num: u8) -> String {
+    format!("exports/pdu.{page_num}")
+}
+
+fn man_path(page_num: u8) -> String {
+    format!("exports/pdu.{page_num}.man")
+}
+
+fn render_man_output(page_num: u8) -> Result<String, String> {
+    let roff_file = roff_path(page_num);
+    let output = Command::new("man")
+        .env("MANWIDTH", MANWIDTH)
+        .arg(format!("./{roff_file}"))
+        .output()
+        .map_err(|error| format!("failed to run man: {error}"))?;
+    if !output.status.success() {
+        let stderr = String::from_utf8_lossy(&output.stderr);
+        return Err(format!("man failed: {stderr}"));
+    }
+    let content = String::from_utf8(output.stdout)
+        .map_err(|error| format!("man output is not UTF-8: {error}"))?;
+    Ok(content
+        .lines()
+        .map(str::trim_end)
+        .collect::<Vec<_>>()
+        .join("\n"))
+}
+
+fn check_file(path: &str, expected: &str) -> ExitCode {
+    match std::fs::read_to_string(path) {
+        Ok(actual) if actual == *expected => ExitCode::SUCCESS,
+        Ok(_) => {
+            eprintln!("{path} is outdated, run ./generate-completions.sh to update it");
+            ExitCode::FAILURE
+        }
+        Err(error) => {
+            eprintln!("error reading {path}: {error}");
+            ExitCode::FAILURE
+        }
+    }
+}
+
+fn main() -> ExitCode {
+    let args = Args::parse();
+    let page_num = args.page.number();
+    match (args.action, args.kind) {
+        (Action::Generate, Kind::Roff) => {
+            print!("{}", render_man_page());
+            ExitCode::SUCCESS
+        }
+        (Action::Generate, Kind::Man) => match render_man_output(page_num) {
+            Ok(content) => {
+                print!("{content}");
+                ExitCode::SUCCESS
+            }
+            Err(error) => {
+                eprintln!("error: {error}");
+                ExitCode::FAILURE
+            }
+        },
+        (Action::Check, Kind::Roff) => check_file(&roff_path(page_num), &render_man_page()),
+        (Action::Check, Kind::Man) => match render_man_output(page_num) {
+            Ok(expected) => check_file(&man_path(page_num), &expected),
+            Err(error) => {
+                eprintln!("error: {error}");
+                ExitCode::FAILURE
+            }
+        },
+    }
 }

generate-completions.sh

@@ -17,5 +17,5 @@ gen elvish completion.elv
 ./run.sh pdu --help | sed 's/[[:space:]]*$//' > exports/long.help
 ./run.sh pdu -h | sed 's/[[:space:]]*$//' > exports/short.help
 ./run.sh pdu-usage-md > USAGE.md
-./run.sh pdu-man-page > exports/pdu.1
-MANWIDTH=120 man ./exports/pdu.1 | sed 's/[[:space:]]*$//' > exports/pdu.1.man
+./run.sh pdu-man-page generate roff 1 > exports/pdu.1
+./run.sh pdu-man-page generate man 1 > exports/pdu.1.man

tests/sync_man_page.rs

@@ -1,20 +1,49 @@
-//! The following test checks whether the man page file is outdated.
+//! The following tests check whether the man page files are outdated.
 //!
-//! If the test fails, run `./generate-completions.sh` on the root of the repo to update the man page.
+//! If the tests fail, run `./generate-completions.sh` on the root of the repo to update the man page.
 
 // Since the CLI in Windows looks a little different, and I am way too lazy to make two versions
-// of man page files, the following test would only run in UNIX-like environment.
+// of man page files, the following tests would only run in UNIX-like environment.
 #![cfg(unix)]
 #![cfg(feature = "cli")]
 
-use parallel_disk_usage::man_page::render_man_page;
+use command_extra::CommandExtra;
+use std::process::Command;
 
-#[test]
-fn man_page() {
-    let received = render_man_page();
-    let expected = include_str!("../exports/pdu.1");
+const PDU_MAN_PAGE: &str = env!("CARGO_BIN_EXE_pdu-man-page");
+
+fn check(kind: &str, page: &str) {
+    let output = Command::new(PDU_MAN_PAGE)
+        .with_args(["check", kind, page])
+        .with_current_dir(env!("CARGO_MANIFEST_DIR"))
+        .output()
+        .expect("spawn pdu-man-page");
+    let stdout = String::from_utf8_lossy(&output.stdout);
+    let stdout = stdout.trim();
+    if !stdout.is_empty() {
+        eprintln!("STDOUT:\n{stdout}\n");
+    }
+    let stderr = String::from_utf8_lossy(&output.stderr);
+    let stderr = stderr.trim();
+    if !stderr.is_empty() {
+        eprintln!("STDERR:\n{stderr}\n");
+    }
     assert!(
-        received == expected,
+        output.status.success(),
         "man page is outdated, run ./generate-completions.sh to update it",
     );
 }
+
+#[test]
+fn roff() {
+    check("roff", "1");
+}
+
+#[test]
+#[cfg_attr(
+    not(feature = "man-test"),
+    ignore = "requires man(1); enable with --features man-test"
+)]
+fn man() {
+    check("man", "1");
+}