feat(3216): swarmctl shell completions

Mirrors hivectl exactly: a `completions <shell>` verb that walks the
live clap tree, and a package that pipes it into installShellCompletion
for bash/zsh/fish. Generating from the command tree rather than writing a
script by hand is what keeps completions from drifting away from the
verbs they complete — the same reason `markdown-docs` renders the docs
from that tree.

Dispatched before PathArgs::resolve() for the same reason markdown-docs
is: emitting a completion script needs none of the SWARMCTL_AUTHELIA_*
deployment env vars, and requiring them would make the package's own
build-time invocation fail — exactly where it runs.

swarmctl leaves mkBinPackage for its own derivation, since the extractor
installs a binary and nothing else.

swarmctl/src/main.rs

@@ -143,6 +143,21 @@ enum Verb {
     /// outside a real deployment — exactly where the docs build runs it.
     #[command(hide = true)]
     MarkdownDocs,
+    /// Generate a shell completion script for `swarmctl` and print it to
+    /// stdout.
+    ///
+    /// Supports bash, zsh, fish, elvish and powershell. The nix package
+    /// already installs bash/zsh/fish system-wide; this is for ad-hoc or
+    /// other-shell use.
+    ///
+    /// Dispatched before `PathArgs::resolve()` for the same reason as
+    /// `markdown-docs`: emitting a completion script needs none of the
+    /// `SWARMCTL_AUTHELIA_*` deployment env vars, and requiring them would
+    /// make the package's own build-time invocation fail.
+    Completions {
+        /// Shell to emit completions for.
+        shell: clap_complete::Shell,
+    },
 }
 
 #[derive(Subcommand)]
@@ -209,6 +224,19 @@ fn main() -> Result<()> {
             print!("{}", clap_markdown::help_markdown::<Cli>());
             Ok(())
         }
+        Verb::Completions { shell } => {
+            // Generated from the live clap tree — the same single source
+            // of truth `markdown-docs` renders — so completions cannot
+            // drift from the actual verbs and flags.
+            use clap::CommandFactory as _;
+            clap_complete::generate(
+                shell,
+                &mut Cli::command(),
+                "swarmctl",
+                &mut std::io::stdout(),
+            );
+            Ok(())
+        }
     }
 }