feat(nodeup): add human output color controls via --color and NODEUP_COLOR (#308)

## Summary
- add global `--color <auto|always|never>` to `nodeup` management CLI
- add `NODEUP_COLOR` support with precedence `--color` > `NODEUP_COLOR`
> `NO_COLOR` > stream-aware `auto`
- introduce `output_style` module and wire styled human output through
command output + handled stderr errors
- keep JSON and completions output raw (no ANSI injection)

## Documentation
- update `docs/crates-nodeup-foundation.md` and `docs/project-nodeup.md`
with color contract invariants
- update `crates/nodeup/README.md` and `apps/public-docs/nodeup.mdx` for
user-facing color controls

## Tests
- `cargo test -p nodeup`
- `cargo test`
- `cd apps/public-docs && pnpm test`

Author: kdy1

apps/public-docs/nodeup.mdx

@@ -72,6 +72,14 @@ nodeup override set lts --path /path/to/project
 - Handled failures use an actionable message shape: `<cause>. Hint: <next action>`.
 - `completions` always writes raw completion scripts to stdout, even when `--output json` is set.
 
+Human output color control:
+
+- `--color auto|always|never` controls ANSI styling for `--output human` output.
+- `NODEUP_COLOR=auto|always|never` controls the same behavior via environment.
+- Precedence is `--color` > `NODEUP_COLOR` > `NO_COLOR` > `auto`.
+- `auto` enables color only when each output stream is attached to a terminal.
+- `--output json` and `completions` output are always emitted without ANSI styling.
+
 ## Shell completions
 
 Supported shells:

crates/nodeup/README.md

@@ -56,7 +56,16 @@ If no selector resolves, commands fail with deterministic `not-found` errors.
   - always writes raw completion script text to stdout
   - does not wrap completion output in JSON, even when `--output json` is set
 
-Color control:
+Human output color control:
+
+- Global color mode for human output: `--color auto|always|never` (default: `auto`)
+- Environment override for human output: `NODEUP_COLOR=auto|always|never`
+- Precedence: `--color` > `NODEUP_COLOR` > `NO_COLOR` > `auto`
+- `auto` enables ANSI styles per stream only when the stream is a terminal
+- `--output json` never injects ANSI styles into JSON payloads
+- `completions` output remains raw shell script text even when `--color always` is set
+
+Log color control:
 
 - `NODEUP_LOG_COLOR=always|auto|never` (default `always`)
 - `NO_COLOR` disables color when `NODEUP_LOG_COLOR` is unset or `auto`

crates/nodeup/src/cli.rs

@@ -6,6 +6,23 @@ pub enum OutputFormat {
     Json,
 }
 
+#[derive(Debug, Clone, Copy, PartialEq, Eq, ValueEnum)]
+pub enum OutputColorMode {
+    Auto,
+    Always,
+    Never,
+}
+
+impl OutputColorMode {
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::Auto => "auto",
+            Self::Always => "always",
+            Self::Never => "never",
+        }
+    }
+}
+
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum ToolchainListDetail {
     Standard,
@@ -44,6 +61,10 @@ pub struct Cli {
     #[arg(long, global = true, value_enum, default_value_t = OutputFormat::Human)]
     pub output: OutputFormat,
 
+    /// Color mode for human output (`auto`, `always`, or `never`).
+    #[arg(long, global = true, value_enum)]
+    pub color: Option<OutputColorMode>,
+
     #[command(subcommand)]
     pub command: Command,
 }

crates/nodeup/src/commands/default_cmd.rs

@@ -2,7 +2,7 @@ use serde::Serialize;
 use tracing::{info, warn};
 
 use crate::{
-    cli::OutputFormat,
+    cli::{OutputColorMode, OutputFormat},
     commands::print_output,
     errors::{ErrorKind, NodeupError, Result},
     resolver::ResolvedRuntimeTarget,
@@ -32,7 +32,12 @@ impl From<NodeupError> for DefaultResolutionError {
     }
 }
 
-pub fn execute(runtime: Option<&str>, output: OutputFormat, app: &NodeupApp) -> Result<i32> {
+pub fn execute(
+    runtime: Option<&str>,
+    output: OutputFormat,
+    color: Option<OutputColorMode>,
+    app: &NodeupApp,
+) -> Result<i32> {
     if let Some(runtime_selector) = runtime {
         let resolved = app
             .resolver
@@ -63,7 +68,7 @@ pub fn execute(runtime: Option<&str>, output: OutputFormat, app: &NodeupApp) ->
             "Default runtime set to {}",
             response.default_selector.as_deref().unwrap_or("")
         );
-        print_output(output, &human, &response)?;
+        print_output(output, color, &human, &response)?;
         return Ok(0);
     }
 
@@ -107,7 +112,7 @@ pub fn execute(runtime: Option<&str>, output: OutputFormat, app: &NodeupApp) ->
         "Default runtime is not set".to_string()
     };
 
-    print_output(output, &human, &response)?;
+    print_output(output, color, &human, &response)?;
 
     Ok(0)
 }

crates/nodeup/src/commands/mod.rs

@@ -14,10 +14,11 @@ use tracing::info;
 
 use crate::{
     cli::{
-        Cli, Command, OutputFormat, OverrideCommand, SelfCommand, ShowCommand, ToolchainCommand,
-        ToolchainListDetail,
+        Cli, Command, OutputColorMode, OutputFormat, OverrideCommand, SelfCommand, ShowCommand,
+        ToolchainCommand, ToolchainListDetail,
     },
     errors::Result,
+    output_style,
     types::{
         NodeupCommand, NodeupOverrideCommand, NodeupSelfCommand, NodeupShowCommand,
         NodeupToolchainCommand,
@@ -29,21 +30,23 @@ pub fn execute(cli: Cli, app: &NodeupApp) -> Result<i32> {
     log_command_invocation(&cli.command, cli.output);
 
     match cli.command {
-        Command::Toolchain { command } => toolchain::execute(command, cli.output, app),
-        Command::Default { runtime } => default_cmd::execute(runtime.as_deref(), cli.output, app),
-        Command::Show { command } => show::execute(command, cli.output, app),
-        Command::Update { runtimes } => update_check::update(runtimes, cli.output, app),
-        Command::Check => update_check::check(cli.output, app),
-        Command::Override { command } => override_cmd::execute(command, cli.output, app),
+        Command::Toolchain { command } => toolchain::execute(command, cli.output, cli.color, app),
+        Command::Default { runtime } => {
+            default_cmd::execute(runtime.as_deref(), cli.output, cli.color, app)
+        }
+        Command::Show { command } => show::execute(command, cli.output, cli.color, app),
+        Command::Update { runtimes } => update_check::update(runtimes, cli.output, cli.color, app),
+        Command::Check => update_check::check(cli.output, cli.color, app),
+        Command::Override { command } => override_cmd::execute(command, cli.output, cli.color, app),
         Command::Which { runtime, command } => {
-            which_cmd::execute(runtime.as_deref(), &command, cli.output, app)
+            which_cmd::execute(runtime.as_deref(), &command, cli.output, cli.color, app)
         }
         Command::Run {
             install,
             runtime,
             command,
-        } => run_cmd::execute(install, &runtime, &command, cli.output, app),
-        Command::SelfCmd { command } => self_cmd::execute(command, cli.output, app),
+        } => run_cmd::execute(install, &runtime, &command, cli.output, cli.color, app),
+        Command::SelfCmd { command } => self_cmd::execute(command, cli.output, cli.color, app),
         Command::Completions { shell, command } => {
             skeleton::completions(&shell, command.as_deref())
         }
@@ -52,11 +55,12 @@ pub fn execute(cli: Cli, app: &NodeupApp) -> Result<i32> {
 
 pub fn print_output<T: Serialize>(
     output: OutputFormat,
+    color: Option<OutputColorMode>,
     human_line: &str,
     json_value: &T,
 ) -> Result<()> {
     match output {
-        OutputFormat::Human => println!("{human_line}"),
+        OutputFormat::Human => println!("{}", output_style::style_human_stdout(human_line, color)),
         OutputFormat::Json => println!("{}", serde_json::to_string_pretty(json_value)?),
     }
 

crates/nodeup/src/commands/override_cmd.rs

@@ -4,7 +4,7 @@ use serde::Serialize;
 use tracing::info;
 
 use crate::{
-    cli::{OutputFormat, OverrideCommand},
+    cli::{OutputColorMode, OutputFormat, OverrideCommand},
     commands::print_output,
     errors::Result,
     selectors::RuntimeSelector,
@@ -17,17 +17,24 @@ struct OverrideListItem {
     selector: String,
 }
 
-pub fn execute(command: OverrideCommand, output: OutputFormat, app: &NodeupApp) -> Result<i32> {
+pub fn execute(
+    command: OverrideCommand,
+    output: OutputFormat,
+    color: Option<OutputColorMode>,
+    app: &NodeupApp,
+) -> Result<i32> {
     match command {
-        OverrideCommand::List => list(output, app),
-        OverrideCommand::Set { runtime, path } => set(&runtime, path.as_deref(), output, app),
+        OverrideCommand::List => list(output, color, app),
+        OverrideCommand::Set { runtime, path } => {
+            set(&runtime, path.as_deref(), output, color, app)
+        }
         OverrideCommand::Unset { path, nonexistent } => {
-            unset(path.as_deref(), nonexistent, output, app)
+            unset(path.as_deref(), nonexistent, output, color, app)
         }
     }
 }
 
-fn list(output: OutputFormat, app: &NodeupApp) -> Result<i32> {
+fn list(output: OutputFormat, color: Option<OutputColorMode>, app: &NodeupApp) -> Result<i32> {
     let entries = app
         .overrides
         .list()?
@@ -39,11 +46,17 @@ fn list(output: OutputFormat, app: &NodeupApp) -> Result<i32> {
         .collect::<Vec<_>>();
 
     let human = format!("Configured overrides: {}", entries.len());
-    print_output(output, &human, &entries)?;
+    print_output(output, color, &human, &entries)?;
     Ok(0)
 }
 
-fn set(runtime: &str, path: Option<&str>, output: OutputFormat, app: &NodeupApp) -> Result<i32> {
+fn set(
+    runtime: &str,
+    path: Option<&str>,
+    output: OutputFormat,
+    color: Option<OutputColorMode>,
+    app: &NodeupApp,
+) -> Result<i32> {
     let target_path = match path {
         Some(path) => PathBuf::from(path),
         None => std::env::current_dir()?,
@@ -74,19 +87,20 @@ fn set(runtime: &str, path: Option<&str>, output: OutputFormat, app: &NodeupApp)
         "status": "set"
     });
 
-    print_output(output, &human, &response)?;
+    print_output(output, color, &human, &response)?;
     Ok(0)
 }
 
 fn unset(
     path: Option<&str>,
     nonexistent: bool,
     output: OutputFormat,
+    color: Option<OutputColorMode>,
     app: &NodeupApp,
 ) -> Result<i32> {
     let path = path.map(PathBuf::from);
     let removed = app.overrides.unset(path.as_deref(), nonexistent)?;
     let human = format!("Removed {} override(s)", removed.len());
-    print_output(output, &human, &removed)?;
+    print_output(output, color, &human, &removed)?;
     Ok(0)
 }

crates/nodeup/src/commands/run_cmd.rs

@@ -4,7 +4,7 @@ use serde::Serialize;
 use tracing::info;
 
 use crate::{
-    cli::OutputFormat,
+    cli::{OutputColorMode, OutputFormat},
     commands::print_output,
     errors::{NodeupError, Result},
     process::{run_command, DelegatedStdioPolicy},
@@ -25,6 +25,7 @@ pub fn execute(
     runtime: &str,
     command: &[String],
     output: OutputFormat,
+    color: Option<OutputColorMode>,
     app: &NodeupApp,
 ) -> Result<i32> {
     if command.is_empty() {
@@ -111,6 +112,6 @@ pub fn execute(
         delegated_command, exit_code
     );
 
-    print_output(output, &human, &response)?;
+    print_output(output, color, &human, &response)?;
     Ok(exit_code)
 }

crates/nodeup/src/commands/self_cmd.rs

@@ -11,7 +11,7 @@ use toml::{value::Table, Value};
 use tracing::{info, warn};
 
 use crate::{
-    cli::{OutputFormat, SelfCommand},
+    cli::{OutputColorMode, OutputFormat, SelfCommand},
     commands::print_output,
     errors::{NodeupError, Result},
     overrides::{OverrideEntry, OverridesFile, OVERRIDES_SCHEMA_VERSION},
@@ -171,15 +171,20 @@ struct SelfUpgradeDataResponse {
     overrides: SchemaMigrationResult,
 }
 
-pub fn execute(command: SelfCommand, output: OutputFormat, app: &NodeupApp) -> Result<i32> {
+pub fn execute(
+    command: SelfCommand,
+    output: OutputFormat,
+    color: Option<OutputColorMode>,
+    app: &NodeupApp,
+) -> Result<i32> {
     match command {
-        SelfCommand::Update => update(output, app),
-        SelfCommand::Uninstall => uninstall(output, app),
-        SelfCommand::UpgradeData => upgrade_data(output, app),
+        SelfCommand::Update => update(output, color, app),
+        SelfCommand::Uninstall => uninstall(output, color, app),
+        SelfCommand::UpgradeData => upgrade_data(output, color, app),
     }
 }
 
-fn update(output: OutputFormat, _app: &NodeupApp) -> Result<i32> {
+fn update(output: OutputFormat, color: Option<OutputColorMode>, _app: &NodeupApp) -> Result<i32> {
     let action = SelfAction::Update;
     let command_path = action.command_path();
 
@@ -223,12 +228,12 @@ fn update(output: OutputFormat, _app: &NodeupApp) -> Result<i32> {
         status.as_str(),
         response.target_binary
     );
-    print_output(output, &human, &response)?;
+    print_output(output, color, &human, &response)?;
 
     Ok(0)
 }
 
-fn uninstall(output: OutputFormat, app: &NodeupApp) -> Result<i32> {
+fn uninstall(output: OutputFormat, color: Option<OutputColorMode>, app: &NodeupApp) -> Result<i32> {
     let action = SelfAction::Uninstall;
 
     let mut deletion_targets = Vec::new();
@@ -305,12 +310,16 @@ fn uninstall(output: OutputFormat, app: &NodeupApp) -> Result<i32> {
         status.as_str(),
         response.removed_paths.len()
     );
-    print_output(output, &human, &response)?;
+    print_output(output, color, &human, &response)?;
 
     Ok(0)
 }
 
-fn upgrade_data(output: OutputFormat, app: &NodeupApp) -> Result<i32> {
+fn upgrade_data(
+    output: OutputFormat,
+    color: Option<OutputColorMode>,
+    app: &NodeupApp,
+) -> Result<i32> {
     let action = SelfAction::UpgradeData;
     let settings = migrate_settings_schema(app).map_err(|error| log_failure(action, error))?;
     let overrides = migrate_overrides_schema(app).map_err(|error| log_failure(action, error))?;
@@ -343,7 +352,7 @@ fn upgrade_data(output: OutputFormat, app: &NodeupApp) -> Result<i32> {
         response.settings.status.as_str(),
         response.overrides.status.as_str()
     );
-    print_output(output, &human, &response)?;
+    print_output(output, color, &human, &response)?;
 
     Ok(0)
 }