feat(nodeup): implement completions command and sync docs (#287)

## Summary
- implement `nodeup completions <shell> [command]` using `clap_complete`
- support `bash`, `zsh`, `fish`, `powershell`, `elvish`
- validate optional command scope against top-level commands and return
`invalid-input` on invalid shell/scope
- keep completions output as raw stdout script regardless of `--output`
mode
- add structured success/failure logs for completion generation
- update nodeup docs/contracts/public docs to match behavior

## Tests
- cargo test -p nodeup
- cargo test

Author: kdy1

Cargo.lock

@@ -14,6 +14,7 @@
 - Runtime selection: `default`, `override set|unset|list`, `show active-runtime`
 - Runtime-aware execution: `run`, `which`
 - Self-management: `self update|uninstall|upgrade-data`
+- Shell completion generation: `completions <shell> [command]`
 
 ## Install
 
@@ -68,6 +69,23 @@ nodeup override set lts --path /path/to/project
 - `--output human|json` is available for management commands.
 - Human mode uses pretty `tracing` logs by default.
 - JSON mode writes machine payloads to stdout and keeps logs off by default unless explicitly enabled.
+- `completions` always writes raw completion scripts to stdout, even when `--output json` is set.
+
+## Shell completions
+
+Supported shells:
+
+- `bash`
+- `zsh`
+- `fish`
+- `powershell`
+- `elvish`
+
+Command scope behavior:
+
+- `nodeup completions <shell>` generates completion output for all top-level commands.
+- `nodeup completions <shell> <command>` only accepts top-level command scopes (`toolchain`, `default`, `show`, `update`, `check`, `override`, `which`, `run`, `self`, `completions`).
+- Invalid shell or scope values fail with `invalid-input`.
 
 ## Reliability and validation
 

apps/public-docs/nodeup.mdx

@@ -8,6 +8,7 @@ readme = "README.md"
 
 [dependencies]
 clap = { version = "4.5.32", features = ["derive"] }
+clap_complete = "4.5.47"
 reqwest = { version = "0.12.14", default-features = false, features = ["blocking", "json", "rustls-tls"] }
 semver = { version = "1.0.26", features = ["serde"] }
 serde = { version = "1.0.219", features = ["derive"] }

crates/nodeup/Cargo.toml

@@ -51,12 +51,32 @@ If no selector resolves, commands fail with deterministic `not-found` errors.
   - handled failures are written to stderr as JSON envelopes
     - fields: `kind`, `message`, `exit_code`
   - default logging is off unless explicitly enabled via `RUST_LOG`
+- `completions` command:
+  - always writes raw completion script text to stdout
+  - does not wrap completion output in JSON, even when `--output json` is set
 
 Color control:
 
 - `NODEUP_LOG_COLOR=always|auto|never` (default `always`)
 - `NO_COLOR` disables color when `NODEUP_LOG_COLOR` is unset or `auto`
 
+## Completions
+
+`nodeup completions` generates shell completion scripts for:
+
+- `bash`
+- `zsh`
+- `fish`
+- `powershell`
+- `elvish`
+
+Scope filtering:
+
+- `nodeup completions <shell>` generates completions for all top-level commands.
+- `nodeup completions <shell> <command>` accepts only top-level command scopes:
+  - `toolchain`, `default`, `show`, `update`, `check`, `override`, `which`, `run`, `self`, `completions`
+  - invalid scopes fail with `invalid-input`.
+
 ## Testing Strategy
 
 `nodeup` validation combines unit tests and end-to-end CLI integration tests.

crates/nodeup/README.md

@@ -1,18 +1,215 @@
+use std::io::Write;
+
+use clap::CommandFactory;
+use clap_complete::{generate, Shell};
 use tracing::info;
 
-use crate::errors::{NodeupError, Result};
+use crate::{
+    cli::Cli,
+    errors::{NodeupError, Result},
+};
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum CompletionShell {
+    Bash,
+    Zsh,
+    Fish,
+    PowerShell,
+    Elvish,
+}
+
+impl CompletionShell {
+    fn parse(raw: &str) -> Result<Self> {
+        match raw.trim().to_ascii_lowercase().as_str() {
+            "bash" => Ok(Self::Bash),
+            "zsh" => Ok(Self::Zsh),
+            "fish" => Ok(Self::Fish),
+            "powershell" => Ok(Self::PowerShell),
+            "elvish" => Ok(Self::Elvish),
+            _ => Err(NodeupError::invalid_input(format!(
+                "Unsupported shell '{raw}'. Supported shells: bash, zsh, fish, powershell, elvish"
+            ))),
+        }
+    }
+
+    fn as_str(self) -> &'static str {
+        match self {
+            Self::Bash => "bash",
+            Self::Zsh => "zsh",
+            Self::Fish => "fish",
+            Self::PowerShell => "powershell",
+            Self::Elvish => "elvish",
+        }
+    }
+
+    fn to_clap_shell(self) -> Shell {
+        match self {
+            Self::Bash => Shell::Bash,
+            Self::Zsh => Shell::Zsh,
+            Self::Fish => Shell::Fish,
+            Self::PowerShell => Shell::PowerShell,
+            Self::Elvish => Shell::Elvish,
+        }
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum CompletionScope {
+    Toolchain,
+    Default,
+    Show,
+    Update,
+    Check,
+    Override,
+    Which,
+    Run,
+    SelfCmd,
+    Completions,
+}
+
+impl CompletionScope {
+    fn parse(raw: &str) -> Result<Self> {
+        match raw.trim() {
+            "toolchain" => Ok(Self::Toolchain),
+            "default" => Ok(Self::Default),
+            "show" => Ok(Self::Show),
+            "update" => Ok(Self::Update),
+            "check" => Ok(Self::Check),
+            "override" => Ok(Self::Override),
+            "which" => Ok(Self::Which),
+            "run" => Ok(Self::Run),
+            "self" => Ok(Self::SelfCmd),
+            "completions" => Ok(Self::Completions),
+            _ => Err(NodeupError::invalid_input(format!(
+                "Unsupported command scope '{raw}'. Supported top-level commands: toolchain, \
+                 default, show, update, check, override, which, run, self, completions"
+            ))),
+        }
+    }
+
+    fn as_str(self) -> &'static str {
+        match self {
+            Self::Toolchain => "toolchain",
+            Self::Default => "default",
+            Self::Show => "show",
+            Self::Update => "update",
+            Self::Check => "check",
+            Self::Override => "override",
+            Self::Which => "which",
+            Self::Run => "run",
+            Self::SelfCmd => "self",
+            Self::Completions => "completions",
+        }
+    }
+}
 
 pub fn completions(shell: &str, command: Option<&str>) -> Result<i32> {
-    let scope = command.unwrap_or("<all-commands>");
+    let scope_label = command.unwrap_or("<all-commands>");
+
+    let parsed_shell = CompletionShell::parse(shell).inspect_err(|error| {
+        log_generation_failure(shell, scope_label, "invalid-shell", error);
+    })?;
+
+    let parsed_scope = command
+        .map(CompletionScope::parse)
+        .transpose()
+        .inspect_err(|error| {
+            log_generation_failure(parsed_shell.as_str(), scope_label, "invalid-scope", error);
+        })?;
+
+    let script = generate_completion_script(parsed_shell, parsed_scope).inspect_err(|error| {
+        log_generation_failure(
+            parsed_shell.as_str(),
+            scope_label,
+            "generation-failed",
+            error,
+        );
+    })?;
+
+    let mut stdout = std::io::stdout();
+    stdout.write_all(&script).map_err(|error| {
+        let nodeup_error = NodeupError::internal(format!(
+            "Failed to write completion script to stdout: {error}"
+        ));
+        log_generation_failure(
+            parsed_shell.as_str(),
+            scope_label,
+            "stdout-write-failed",
+            &nodeup_error,
+        );
+        nodeup_error
+    })?;
+    stdout.flush().map_err(|error| {
+        let nodeup_error =
+            NodeupError::internal(format!("Failed to flush completion script output: {error}"));
+        log_generation_failure(
+            parsed_shell.as_str(),
+            scope_label,
+            "stdout-flush-failed",
+            &nodeup_error,
+        );
+        nodeup_error
+    })?;
+
+    info!(
+        command_path = "nodeup.completions",
+        action = "generate",
+        shell = parsed_shell.as_str(),
+        scope = scope_label,
+        scope_present = parsed_scope.is_some(),
+        outcome = "generated",
+        "Generated completion script"
+    );
+
+    Ok(0)
+}
+
+fn generate_completion_script(
+    shell: CompletionShell,
+    scope: Option<CompletionScope>,
+) -> Result<Vec<u8>> {
+    let mut root = Cli::command();
+    if let Some(scope) = scope {
+        apply_scope(&mut root, scope)?;
+    }
+
+    let mut buffer = Vec::new();
+    generate(shell.to_clap_shell(), &mut root, "nodeup", &mut buffer);
+    Ok(buffer)
+}
+
+fn apply_scope(root: &mut clap::Command, scope: CompletionScope) -> Result<()> {
+    let selected = scope.as_str();
+    if !root
+        .get_subcommands()
+        .any(|subcommand| subcommand.get_name() == selected)
+    {
+        return Err(NodeupError::invalid_input(format!(
+            "Unsupported command scope '{selected}'"
+        )));
+    }
+
+    *root = root.clone().mut_subcommands(|subcommand| {
+        if subcommand.get_name() == selected {
+            subcommand
+        } else {
+            subcommand.hide(true)
+        }
+    });
+
+    Ok(())
+}
+
+fn log_generation_failure(shell: &str, scope: &str, reason: &str, error: &NodeupError) {
     info!(
         command_path = "nodeup.completions",
         action = "generate",
         shell,
-        scope_present = command.is_some(),
-        outcome = "not-implemented",
-        "Completions generation command is not implemented yet"
+        scope,
+        scope_present = scope != "<all-commands>",
+        outcome = "failed",
+        reason,
+        error = %error.message,
+        "Failed to generate completion script"
     );
-    Err(NodeupError::not_implemented(format!(
-        "nodeup completions for shell '{shell}' and scope '{scope}' is planned for the next phase"
-    )))
 }