feat(cargo-mono): improve runtime error messaging with actionable hints (#292)

## Summary
- standardize cargo-mono runtime errors to a single-line `summary +
Hint:` format
- add stable error-kind labels and include them in stderr output
(`cargo-mono error [kind]: ...`)
- improve actionable runtime error messages across
git/workspace/versioning/targeting/publish flows
- improve publish failure details in JSON (`failed[].error`) with
hint-based fallback messages
- sync cargo-mono docs with the runtime error UX contract

## Testing
- `cargo test -p cargo-mono`
- `cargo test`

Author: kdy1

crates/cargo-mono/src/commands/publish.rs

@@ -17,7 +17,7 @@ use tracing::{info, warn};
 use crate::{
     cli::PublishArgs,
     commands::{print_output, targeting},
-    errors::{CargoMonoError, Result},
+    errors::{message_with_hint, CargoMonoError, ErrorKind, Result},
     types::{OutputFormat, PublishSkipReason},
     workspace::Workspace,
     CargoMonoApp,
@@ -322,11 +322,11 @@ pub fn execute(args: &PublishArgs, output: OutputFormat, app: &CargoMonoApp) ->
                     failed.push(FailedPackage {
                         name: package_name.clone(),
                         attempts,
-                        error: if details.is_empty() {
-                            format!("publish failed with status {}", publish_output.status)
-                        } else {
-                            details
-                        },
+                        error: format_publish_failure(
+                            &package_name,
+                            &publish_output.status.to_string(),
+                            &details,
+                        ),
                     });
                     published_or_skipped = true;
                     break;
@@ -336,9 +336,9 @@ pub fn execute(args: &PublishArgs, output: OutputFormat, app: &CargoMonoApp) ->
 
         if !published_or_skipped {
             failed.push(FailedPackage {
-                name: package_name,
+                name: package_name.clone(),
                 attempts,
-                error: "publish did not complete within retry limit".to_string(),
+                error: format_publish_retry_limit_failure(&package_name, attempts),
             });
         }
     }
@@ -851,9 +851,40 @@ fn run_publish_command(package: &str, dry_run: bool, registry: Option<&str>) ->
         command.arg("--registry").arg(registry);
     }
 
-    command
-        .output()
-        .map_err(|error| CargoMonoError::cargo(format!("Failed to execute cargo publish: {error}")))
+    command.output().map_err(|error| {
+        CargoMonoError::with_hint(
+            ErrorKind::Cargo,
+            format!("Failed to start `cargo publish` for package `{package}`: {error}"),
+            "Ensure Cargo is installed, the package exists, and registry credentials are \
+             configured before retrying.",
+        )
+    })
+}
+
+fn format_publish_failure(package: &str, status: &str, raw_details: &str) -> String {
+    let details = compact_error_details(raw_details);
+    let summary = if details.is_empty() {
+        format!("`cargo publish` failed for package `{package}` with status {status}.")
+    } else {
+        format!("`cargo publish` failed for package `{package}`: {details}")
+    };
+    message_with_hint(
+        summary,
+        "Verify package metadata, registry access, and network connectivity, then retry.",
+    )
+}
+
+fn format_publish_retry_limit_failure(package: &str, attempts: usize) -> String {
+    message_with_hint(
+        format!(
+            "`cargo publish` did not complete for package `{package}` within {attempts} attempts."
+        ),
+        "Wait for index propagation or rate limits to clear, then rerun publish.",
+    )
+}
+
+fn compact_error_details(raw: &str) -> String {
+    raw.split_whitespace().collect::<Vec<_>>().join(" ")
 }
 
 fn retry_delay(attempt: usize) -> Duration {
@@ -961,6 +992,30 @@ mod tests {
         ));
     }
 
+    #[test]
+    fn format_publish_failure_uses_status_when_no_details_exist() {
+        let message = format_publish_failure("alpha", "exit status: 101", "");
+        assert!(message
+            .contains("`cargo publish` failed for package `alpha` with status exit status: 101."));
+        assert!(message.contains("Hint: "));
+    }
+
+    #[test]
+    fn format_publish_failure_compacts_multiline_details() {
+        let message = format_publish_failure("alpha", "ignored", "error:\nnetwork timeout\n");
+        assert!(
+            message.contains("`cargo publish` failed for package `alpha`: error: network timeout")
+        );
+        assert!(message.contains("Hint: "));
+    }
+
+    #[test]
+    fn format_publish_retry_limit_failure_includes_hint() {
+        let message = format_publish_retry_limit_failure("alpha", 3);
+        assert!(message.contains("within 3 attempts."));
+        assert!(message.contains("Hint: "));
+    }
+
     #[test]
     fn sparse_index_path_matches_registry_rules() {
         assert_eq!(sparse_index_path_for_crate("a"), "1/a");

crates/cargo-mono/src/commands/targeting.rs

@@ -2,7 +2,7 @@ use std::collections::BTreeSet;
 
 use crate::{
     cli::{ChangedArgs, TargetArgs},
-    errors::{CargoMonoError, Result},
+    errors::{CargoMonoError, ErrorKind, Result},
     git,
     types::TargetSelector,
     workspace::Workspace,
@@ -48,10 +48,11 @@ pub fn resolve_targets(
             .collect::<Vec<_>>();
 
         if !missing.is_empty() {
-            return Err(CargoMonoError::invalid_input(format!(
-                "Unknown package(s): {}",
-                missing.join(", ")
-            )));
+            return Err(CargoMonoError::with_hint(
+                ErrorKind::InvalidInput,
+                format!("Unknown package selector(s): {}", missing.join(", ")),
+                "Run `cargo mono list` to view valid workspace package names.",
+            ));
         }
 
         return Ok(ResolvedTargets {

crates/cargo-mono/src/errors.rs

@@ -23,6 +23,16 @@ impl ErrorKind {
             Self::Conflict => 5,
         }
     }
+
+    pub fn label(self) -> &'static str {
+        match self {
+            Self::Internal => "internal",
+            Self::InvalidInput => "invalid-input",
+            Self::Git => "git",
+            Self::Cargo => "cargo",
+            Self::Conflict => "conflict",
+        }
+    }
 }
 
 #[derive(Debug, Error)]
@@ -40,6 +50,10 @@ impl CargoMonoError {
         }
     }
 
+    pub fn with_hint(kind: ErrorKind, summary: impl AsRef<str>, hint: impl AsRef<str>) -> Self {
+        Self::new(kind, message_with_hint(summary, hint))
+    }
+
     pub fn internal(message: impl Into<String>) -> Self {
         Self::new(ErrorKind::Internal, message)
     }
@@ -67,31 +81,51 @@ impl CargoMonoError {
 
 impl From<io::Error> for CargoMonoError {
     fn from(value: io::Error) -> Self {
-        Self::internal(format!("I/O error: {value}"))
+        Self::with_hint(
+            ErrorKind::Internal,
+            format!("I/O operation failed: {value}"),
+            "Verify paths and permissions, then retry the command.",
+        )
     }
 }
 
 impl From<cargo_metadata::Error> for CargoMonoError {
     fn from(value: cargo_metadata::Error) -> Self {
-        Self::cargo(format!("cargo metadata error: {value}"))
+        Self::with_hint(
+            ErrorKind::Cargo,
+            format!("Failed to load workspace metadata via cargo: {value}"),
+            "Run `cargo metadata` in this workspace to reproduce and inspect the root cause.",
+        )
     }
 }
 
 impl From<serde_json::Error> for CargoMonoError {
     fn from(value: serde_json::Error) -> Self {
-        Self::internal(format!("JSON error: {value}"))
+        Self::with_hint(
+            ErrorKind::Internal,
+            format!("Failed to parse JSON content: {value}"),
+            "Check the JSON payload for syntax issues near the reported location.",
+        )
     }
 }
 
 impl From<semver::Error> for CargoMonoError {
     fn from(value: semver::Error) -> Self {
-        Self::invalid_input(format!("Invalid semantic version: {value}"))
+        Self::with_hint(
+            ErrorKind::InvalidInput,
+            format!("Invalid semantic version: {value}"),
+            "Use a valid SemVer value such as `1.2.3` or `1.2.3-rc.1`.",
+        )
     }
 }
 
 impl From<toml_edit::TomlError> for CargoMonoError {
     fn from(value: toml_edit::TomlError) -> Self {
-        Self::internal(format!("TOML error: {value}"))
+        Self::with_hint(
+            ErrorKind::Internal,
+            format!("Failed to parse TOML document: {value}"),
+            "Check TOML syntax in Cargo manifests and retry.",
+        )
     }
 }
 
@@ -101,6 +135,52 @@ impl From<CargoMonoError> for io::Error {
     }
 }
 
-pub fn with_context<E: fmt::Display>(kind: ErrorKind, context: &str, error: E) -> CargoMonoError {
-    CargoMonoError::new(kind, format!("{context}: {error}"))
+pub fn message_with_hint(summary: impl AsRef<str>, hint: impl AsRef<str>) -> String {
+    format!("{} Hint: {}", summary.as_ref(), hint.as_ref())
+}
+
+pub fn with_context<E: fmt::Display>(
+    kind: ErrorKind,
+    context: &str,
+    error: E,
+    hint: &str,
+) -> CargoMonoError {
+    CargoMonoError::with_hint(kind, format!("{context}: {error}"), hint)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{message_with_hint, CargoMonoError, ErrorKind};
+
+    #[test]
+    fn error_kind_labels_are_stable() {
+        assert_eq!(ErrorKind::Internal.label(), "internal");
+        assert_eq!(ErrorKind::InvalidInput.label(), "invalid-input");
+        assert_eq!(ErrorKind::Git.label(), "git");
+        assert_eq!(ErrorKind::Cargo.label(), "cargo");
+        assert_eq!(ErrorKind::Conflict.label(), "conflict");
+    }
+
+    #[test]
+    fn message_with_hint_uses_single_line_contract() {
+        let message = message_with_hint("Unable to read manifest.", "Check file permissions.");
+        assert_eq!(
+            message,
+            "Unable to read manifest. Hint: Check file permissions."
+        );
+    }
+
+    #[test]
+    fn with_hint_formats_error_message() {
+        let error = CargoMonoError::with_hint(
+            ErrorKind::InvalidInput,
+            "Invalid package selector.",
+            "Run `cargo mono list`.",
+        );
+        assert_eq!(error.kind, ErrorKind::InvalidInput);
+        assert_eq!(
+            error.message,
+            "Invalid package selector. Hint: Run `cargo mono list`."
+        );
+    }
 }

crates/cargo-mono/src/git.rs

@@ -23,6 +23,8 @@ pub fn merge_base(base_ref: &str) -> Result<String> {
             ErrorKind::Git,
             &format!("Failed to resolve merge-base for base ref `{base_ref}`"),
             error,
+            "Ensure the base ref exists locally (for example, run `git fetch`) and retry with \
+             `--base <ref>`.",
         )
     })
 }
@@ -59,8 +61,10 @@ pub fn ensure_clean_working_tree(allow_dirty: bool) -> Result<()> {
         return Ok(());
     }
 
-    Err(CargoMonoError::conflict(
-        "Working tree is dirty; re-run with --allow-dirty to bypass this check",
+    Err(CargoMonoError::with_hint(
+        ErrorKind::Conflict,
+        "Working tree is dirty and cannot pass preflight checks.",
+        "Commit or stash local changes, or rerun with `--allow-dirty` when this is intentional.",
     ))
 }
 
@@ -112,10 +116,14 @@ fn parse_paths(output: &str) -> BTreeSet<PathBuf> {
 }
 
 fn run_git(args: &[&str]) -> Result<Output> {
-    let output = Command::new("git")
-        .args(args)
-        .output()
-        .map_err(|error| with_context(ErrorKind::Git, "Failed to execute git", error))?;
+    let output = Command::new("git").args(args).output().map_err(|error| {
+        with_context(
+            ErrorKind::Git,
+            "Failed to start `git`",
+            error,
+            "Ensure `git` is installed and available in PATH.",
+        )
+    })?;
 
     ensure_success(&output, args.join(" "))?;
     Ok(output)
@@ -125,7 +133,14 @@ fn run_git_os(args: Vec<OsString>) -> Result<Output> {
     let output = Command::new("git")
         .args(args.iter().map(OsString::as_os_str))
         .output()
-        .map_err(|error| with_context(ErrorKind::Git, "Failed to execute git", error))?;
+        .map_err(|error| {
+            with_context(
+                ErrorKind::Git,
+                "Failed to start `git`",
+                error,
+                "Ensure `git` is installed and available in PATH.",
+            )
+        })?;
 
     let command = args
         .iter()
@@ -147,11 +162,18 @@ fn ensure_success(output: &Output, command: String) -> Result<()> {
     }
 
     let stderr = String::from_utf8_lossy(&output.stderr).trim().to_string();
-    let message = if stderr.is_empty() {
-        format!("git {command} failed with status {}", output.status)
+    let summary = if stderr.is_empty() {
+        format!(
+            "Git command `git {command}` failed with status {}.",
+            output.status
+        )
     } else {
-        format!("git {command} failed: {stderr}")
+        format!("Git command `git {command}` failed: {stderr}")
     };
 
-    Err(CargoMonoError::git(message))
+    Err(CargoMonoError::with_hint(
+        ErrorKind::Git,
+        summary,
+        format!("Run `git {command}` directly to inspect and resolve the underlying problem."),
+    ))
 }

crates/cargo-mono/src/main.rs

@@ -12,7 +12,11 @@ fn main() {
     match run() {
         Ok(code) => std::process::exit(code),
         Err(error) => {
-            eprintln!("cargo-mono error: {}", error.message);
+            eprintln!(
+                "cargo-mono error [{}]: {}",
+                error.kind.label(),
+                error.message
+            );
             std::process::exit(error.exit_code());
         }
     }

crates/cargo-mono/src/versioning.rs

@@ -8,7 +8,7 @@ use semver::{Prerelease, Version};
 use toml_edit::{value, DocumentMut, Item, Value};
 
 use crate::{
-    errors::{CargoMonoError, Result},
+    errors::{CargoMonoError, ErrorKind, Result},
     types::BumpLevel,
     workspace::Workspace,
 };
@@ -46,7 +46,11 @@ pub fn bump_version(current: &Version, level: BumpLevel, preid: Option<&str>) ->
         }
         BumpLevel::Prerelease => {
             let preid = preid.ok_or_else(|| {
-                CargoMonoError::invalid_input("--preid is required when --level prerelease")
+                CargoMonoError::with_hint(
+                    ErrorKind::InvalidInput,
+                    "`--preid` is required when `--level prerelease` is used.",
+                    "Provide a prerelease identifier, for example `--preid rc`.",
+                )
             })?;
 
             let next_pre = next_prerelease(current, preid)?;