feat(cli): add --completions and --man for shell completions and man page

- Add clap_complete + clap_mangen deps
- --completions <bash|zsh|fish|powershell|elvish> emits completion script
- --man emits a roff-formatted man page
- Path arg becomes optional to allow these meta operations

Author: smorin

Cargo.lock

@@ -42,6 +42,8 @@ sha2 = "0.10"
 signal-hook = "0.3"
 # Cross-platform advisory file locking for concurrent atomic execution prevention
 fd-lock = "4"
+clap_complete = "4"
+clap_mangen = "0.2"
 
 [target.'cfg(target_os = "macos")'.dependencies]
 # macOS F_FULLFSYNC support for durable fsync

Cargo.toml

@@ -105,9 +105,9 @@ toggle --recover --recover-forward   # completes the commit
 ## Distribution
 
 - **From source:** `cargo install --path .`
-- **Shell completions:** `toggle completions bash > /etc/bash_completion.d/toggle`
+- **Shell completions:** `toggle --completions bash > /etc/bash_completion.d/toggle`
   (also `zsh`, `fish`, `powershell`, `elvish`)
-- **Man page:** `toggle man > toggle.1 && man ./toggle.1`
+- **Man page:** `toggle --man > toggle.1 && man ./toggle.1`
 - **crates.io / Homebrew:** not yet published.
 
 ---

README.md

@@ -1,13 +1,13 @@
 // Command-line interface for the Toggle CLI
 
 use clap::Parser;
+use clap_complete::Shell;
 use std::path::PathBuf;
 
 #[derive(Parser)]
 #[command(author, version, about)]
 pub struct Cli {
     /// File or directory paths to process
-    #[arg(required = true)]
     pub paths: Vec<PathBuf>,
 
     /// Line range in format <start_line>:<end_line> or <start_line>:+<count> (repeatable)
@@ -123,4 +123,14 @@ pub struct Cli {
     /// Must be combined with --recover.
     #[arg(long = "recover-forward")]
     pub recover_forward: bool,
+
+    /// Generate shell completions for the given shell to stdout.
+    /// Example: `toggle --completions bash > /etc/bash_completion.d/toggle`
+    #[arg(long = "completions", value_name = "SHELL")]
+    pub completions: Option<Shell>,
+
+    /// Generate a roff-formatted man page to stdout.
+    /// Example: `toggle --man > toggle.1 && man ./toggle.1`
+    #[arg(long = "man")]
+    pub man: bool,
 }

src/cli.rs

@@ -119,6 +119,26 @@ fn classify_error(err: &anyhow::Error) -> ExitCode {
 }
 
 fn run(cli: &Cli) -> Result<()> {
+    // ── Meta short-circuits: completions and man page ──
+    if let Some(shell) = cli.completions {
+        let mut command = <Cli as clap::CommandFactory>::command();
+        let bin = command.get_name().to_string();
+        clap_complete::generate(shell, &mut command, bin, &mut std::io::stdout());
+        return Ok(());
+    }
+    if cli.man {
+        let command = <Cli as clap::CommandFactory>::command();
+        clap_mangen::Man::new(command)
+            .render(&mut std::io::stdout())
+            .context("failed to render man page")?;
+        return Ok(());
+    }
+
+    // Path is required for everything else
+    if cli.paths.is_empty() {
+        return Err(UsageError("at least one file or directory path is required".into()).into());
+    }
+
     // ── Atomic mode: startup journal check ──
     let cwd = std::env::current_dir().unwrap_or_else(|_| PathBuf::from("."));
     let journal_path = cwd.join(journal::JOURNAL_FILENAME);

src/main.rs

@@ -2079,3 +2079,33 @@ fn check_unclosed_marker_exits_nonzero() {
     let stdout = String::from_utf8_lossy(&output.stdout);
     assert!(stdout.contains("unclosed"), "stdout: {stdout}");
 }
+
+#[test]
+fn completions_bash_emits_completion_script() {
+    let output = cmd().args(["--completions", "bash"]).output().unwrap();
+    assert!(output.status.success());
+    let stdout = String::from_utf8_lossy(&output.stdout);
+    assert!(stdout.contains("_toggle()"), "stdout: {stdout}");
+    assert!(stdout.contains("--scan"), "expected flag in completions");
+}
+
+#[test]
+fn man_page_emits_roff() {
+    let output = cmd().args(["--man"]).output().unwrap();
+    assert!(output.status.success());
+    let stdout = String::from_utf8_lossy(&output.stdout);
+    assert!(
+        stdout.contains(".TH toggle"),
+        "stdout head: {}",
+        &stdout[..stdout.len().min(200)]
+    );
+    assert!(stdout.contains(".SH NAME"), "expected NAME section");
+}
+
+#[test]
+fn no_paths_errors() {
+    cmd()
+        .assert()
+        .failure()
+        .stderr(predicate::str::contains("path is required"));
+}