worktrunk 0.36.0

//! Worktrunk error types and formatting
//!
//! This module provides typed error handling:
//!
//! - **`GitError`** - A typed enum for domain errors that can be pattern-matched
//!   and tested. Use `.into()` to convert to `anyhow::Error` while preserving the
//!   type for pattern matching. Display produces styled output for users.
//!
//! - **`WorktrunkError`** - A minimal enum for semantic errors that need
//!   special handling (exit codes, silent errors).

use std::borrow::Cow;
use std::path::PathBuf;

use color_print::{cformat, cwrite};
use shell_escape::escape;

use super::HookType;
use crate::path::format_path_for_display;
use crate::styling::{
    ERROR_SYMBOL, HINT_SYMBOL, error_message, format_bash_with_gutter, format_with_gutter,
    hint_message, info_message, suggest_command,
};

/// Platform-specific reference type (PR vs MR).
///
/// Used to unify error handling for GitHub PRs and GitLab MRs.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum RefType {
    /// GitHub Pull Request
    Pr,
    /// GitLab Merge Request
    Mr,
}

impl RefType {
    /// Returns the number prefix symbol for this reference type.
    /// - PR: "#" (e.g., "PR #42")
    /// - MR: "!" (e.g., "MR !42")
    pub fn symbol(self) -> &'static str {
        match self {
            Self::Pr => "#",
            Self::Mr => "!",
        }
    }

    /// Returns the short name for this reference type.
    pub fn name(self) -> &'static str {
        match self {
            Self::Pr => "PR",
            Self::Mr => "MR",
        }
    }

    /// Returns the plural form of the short name.
    pub fn name_plural(self) -> &'static str {
        match self {
            Self::Pr => "PRs",
            Self::Mr => "MRs",
        }
    }

    /// Returns the CLI syntax prefix (e.g., "pr:" or "mr:").
    pub fn syntax(self) -> &'static str {
        match self {
            Self::Pr => "pr:",
            Self::Mr => "mr:",
        }
    }

    /// Returns a display string like "PR #42" or "MR !42".
    pub fn display(self, number: u32) -> String {
        format!("{} {}{}", self.name(), self.symbol(), number)
    }
}

/// Common display fields for PR/MR context.
///
/// Implemented by both `PrInfo` and `MrInfo` to enable unified formatting.
pub trait RefContext {
    fn ref_type(&self) -> RefType;
    fn number(&self) -> u32;
    fn title(&self) -> &str;
    fn author(&self) -> &str;
    fn state(&self) -> &str;
    fn draft(&self) -> bool;
    fn url(&self) -> &str;

    /// The source branch reference for display.
    ///
    /// For same-repo PRs/MRs: just the branch name (e.g., `feature-auth`)
    /// For fork PRs/MRs: `owner:branch` format (e.g., `contributor:feature-fix`)
    fn source_ref(&self) -> String;
}

/// Information about a failed command, for display in error messages.
///
/// Separates the command string from exit information so Display impls
/// can style each part differently (bold command, gray exit code).
#[derive(Debug, Clone)]
pub struct FailedCommand {
    /// The full command string, e.g., "git worktree add /path -b fix main"
    pub command: String,
    /// Exit information, e.g., "exit code 255" or "killed by signal"
    pub exit_info: String,
}

/// Extra CLI context for enriching `wt switch` suggestions in error hints.
///
/// When a switch error is raised deep in the planning layer, the error only knows
/// the branch name. The command handler wraps the error with this context so the
/// Display impl can produce a fully copy-pasteable suggestion including flags like
/// `--execute` and trailing args.
#[derive(Debug, Clone)]
pub struct SwitchSuggestionCtx {
    pub extra_flags: Vec<String>,
    pub trailing_args: Vec<String>,
}

impl SwitchSuggestionCtx {
    /// Append extra flags and trailing args to a suggested command string.
    ///
    /// Clap's `#[arg(last = true)]` on `execute_args` means `--` always routes
    /// to execute_args, so a dash-prefixed branch can't coexist with `--execute`
    /// via the CLI. The suggested command therefore never has a pre-existing `--`
    /// separator when this context is applied.
    fn apply(&self, cmd: String) -> String {
        let mut result = cmd;
        // Flags are pre-escaped at construction (handle_switch.rs uses shell_escape)
        for flag in &self.extra_flags {
            result.push(' ');
            result.push_str(flag);
        }
        if !self.trailing_args.is_empty() {
            result.push_str(" --");
            for arg in &self.trailing_args {
                result.push(' ');
                result.push_str(&escape(Cow::Borrowed(arg.as_str())));
            }
        }
        result
    }
}

/// Domain errors for git and worktree operations.
///
/// This enum provides structured error data that can be pattern-matched and tested.
/// Each variant stores the data needed to construct a user-facing error message.
/// Display produces styled output with emoji and colors.
///
/// # Usage
///
/// ```ignore
/// // Return a typed error (Display produces styled output)
/// return Err(GitError::DetachedHead { action: Some("merge".into()) }.into());
///
/// // Pattern match on errors
/// if let Some(GitError::BranchAlreadyExists { branch }) = err.downcast_ref() {
///     println!("Branch {} exists", branch);
/// }
/// ```
#[derive(Debug, Clone)]
pub enum GitError {
    // Git state errors
    DetachedHead {
        action: Option<String>,
    },
    UncommittedChanges {
        action: Option<String>,
        /// Branch name (for multi-worktree operations)
        branch: Option<String>,
        /// When true, hint mentions --force as an alternative to stashing
        force_hint: bool,
    },
    BranchAlreadyExists {
        branch: String,
    },
    BranchNotFound {
        branch: String,
        /// Show hint about creating the branch. Set to false for remove operations
        /// where suggesting creation doesn't make sense.
        show_create_hint: bool,
        /// Pre-formatted label for the last fetch time (e.g., "3h ago", "never").
        /// When present, the list-branches hint includes the fetch age as a parenthetical.
        last_fetch_ago: Option<String>,
    },
    /// Reference (branch, tag, commit) not found - used when any commit-ish is accepted
    ReferenceNotFound {
        reference: String,
    },

    // Worktree errors
    NotInWorktree {
        /// The action that requires being in a worktree
        action: Option<String>,
    },
    WorktreeMissing {
        branch: String,
    },
    RemoteOnlyBranch {
        branch: String,
        remote: String,
    },
    WorktreePathOccupied {
        branch: String,
        path: PathBuf,
        occupant: Option<String>,
    },
    WorktreePathExists {
        branch: String,
        path: PathBuf,
        create: bool,
    },
    WorktreeCreationFailed {
        branch: String,
        base_branch: Option<String>,
        error: String,
        /// The git command that failed, shown separately from git output
        command: Option<FailedCommand>,
    },
    WorktreeRemovalFailed {
        branch: String,
        path: PathBuf,
        error: String,
        /// Top-level entries remaining in the directory (for "Directory not empty" diagnostics)
        remaining_entries: Option<Vec<String>>,
    },
    CannotRemoveMainWorktree,
    CannotRemoveDefaultBranch {
        branch: String,
    },
    WorktreeLocked {
        branch: String,
        path: PathBuf,
        reason: Option<String>,
    },

    // Merge/push errors
    ConflictingChanges {
        target_branch: String,
        files: Vec<String>,
        worktree_path: PathBuf,
    },
    NotFastForward {
        target_branch: String,
        commits_formatted: String,
        in_merge_context: bool,
    },
    RebaseConflict {
        target_branch: String,
        git_output: String,
    },
    NotRebased {
        target_branch: String,
    },
    PushFailed {
        target_branch: String,
        error: String,
    },

    // Validation/other errors
    NotInteractive,
    HookCommandNotFound {
        name: String,
        available: Vec<String>,
    },
    ParseError {
        message: String,
    },
    WorktreeIncludeParseError {
        error: String,
    },
    LlmCommandFailed {
        command: String,
        error: String,
        /// Full command to reproduce the failure, e.g., "wt step commit --show-prompt | llm"
        reproduction_command: Option<String>,
    },
    ProjectConfigNotFound {
        config_path: PathBuf,
    },
    WorktreeNotFound {
        branch: String,
    },
    /// --create flag used with pr:/mr: syntax (conflict - branch already exists)
    RefCreateConflict {
        ref_type: RefType,
        number: u32,
        branch: String,
    },
    /// --base flag used with pr:/mr: syntax (conflict - base is predetermined)
    RefBaseConflict {
        ref_type: RefType,
        number: u32,
    },
    /// Branch exists but is tracking a different PR/MR
    BranchTracksDifferentRef {
        branch: String,
        ref_type: RefType,
        number: u32,
    },
    /// No remote found for the repository where the PR lives
    NoRemoteForRepo {
        owner: String,
        repo: String,
        /// Suggested URL to add as a remote (derived from primary remote's protocol/host)
        suggested_url: String,
    },
    /// CLI API command failed with unrecognized error (gh or glab)
    CliApiError {
        ref_type: RefType,
        /// Short description of what failed
        message: String,
        /// Full stderr output for debugging
        stderr: String,
    },
    Other {
        message: String,
    },

    /// Wrapper that enriches an inner error's switch suggestions with CLI context.
    ///
    /// The inner error renders normally, but any `wt switch` suggestion includes
    /// the extra flags and trailing args from the context.
    WithSwitchSuggestion {
        source: Box<GitError>,
        ctx: SwitchSuggestionCtx,
    },
}

impl std::error::Error for GitError {}

impl GitError {
    /// Format with optional switch suggestion context.
    ///
    /// Most variants ignore `ctx`. The three that render `wt switch` suggestions
    /// (`BranchAlreadyExists`, `BranchNotFound`, `WorktreePathExists`) use it
    /// to append extra flags and trailing args for a copy-pasteable command.
    fn fmt_with_ctx(
        &self,
        f: &mut std::fmt::Formatter<'_>,
        ctx: Option<&SwitchSuggestionCtx>,
    ) -> std::fmt::Result {
        match self {
            GitError::WithSwitchSuggestion { source, ctx } => source.fmt_with_ctx(f, Some(ctx)),

            GitError::DetachedHead { action } => {
                let message = match action {
                    Some(action) => cformat!("Cannot {action}: not on a branch (detached HEAD)"),
                    None => "Not on a branch (detached HEAD)".to_string(),
                };
                write!(
                    f,
                    "{}\n{}",
                    error_message(&message),
                    hint_message(cformat!(
                        "To switch to a branch, run <underline>git switch <<branch>></>"
                    ))
                )
            }

            GitError::UncommittedChanges {
                action,
                branch,
                force_hint,
            } => {
                let message = match (action, branch) {
                    (Some(action), Some(b)) => {
                        cformat!("Cannot {action}: <bold>{b}</> has uncommitted changes")
                    }
                    (Some(action), None) => {
                        cformat!("Cannot {action}: working tree has uncommitted changes")
                    }
                    (None, Some(b)) => {
                        cformat!("<bold>{b}</> has uncommitted changes")
                    }
                    (None, None) => cformat!("Working tree has uncommitted changes"),
                };
                let hint = if *force_hint {
                    // Construct full command: "wt remove [branch] --force"
                    let args: Vec<&str> = branch.as_deref().into_iter().collect();
                    let cmd = suggest_command("remove", &args, &["--force"]);
                    cformat!(
                        "Commit or stash changes first, or to lose uncommitted changes, run <underline>{cmd}</>"
                    )
                } else {
                    "Commit or stash changes first".to_string()
                };
                write!(f, "{}\n{}", error_message(&message), hint_message(hint))
            }

            GitError::BranchAlreadyExists { branch } => {
                let mut switch_cmd = suggest_command("switch", &[branch], &[]);
                if let Some(ctx) = ctx {
                    switch_cmd = ctx.apply(switch_cmd);
                }
                write!(
                    f,
                    "{}\n{}",
                    error_message(cformat!("Branch <bold>{branch}</> already exists")),
                    hint_message(cformat!(
                        "To switch to the existing branch, run without <underline>--create</>: <underline>{switch_cmd}</>"
                    ))
                )
            }

            GitError::BranchNotFound {
                branch,
                show_create_hint,
                last_fetch_ago,
            } => {
                let list_cmd = suggest_command("list", &[], &["--branches", "--remotes"]);
                let hint = if *show_create_hint {
                    let mut create_cmd = suggest_command("switch", &[branch], &["--create"]);
                    if let Some(ctx) = ctx {
                        create_cmd = ctx.apply(create_cmd);
                    }
                    let fetch_note = last_fetch_ago.as_ref().map(|ago| cformat!(" ({ago})"));
                    cformat!(
                        "To create a new branch, run <underline>{create_cmd}</>; to list branches, run <underline>{list_cmd}</>{note}",
                        note = fetch_note.as_deref().unwrap_or("")
                    )
                } else {
                    cformat!("To list branches, run <underline>{list_cmd}</>")
                };
                write!(
                    f,
                    "{}\n{}",
                    error_message(cformat!("No branch named <bold>{branch}</>")),
                    hint_message(hint)
                )
            }

            GitError::ReferenceNotFound { reference } => {
                write!(
                    f,
                    "{}",
                    error_message(cformat!(
                        "No branch, tag, or commit named <bold>{reference}</>"
                    ))
                )
            }

            GitError::NotInWorktree { action } => {
                let message = match action {
                    Some(action) => cformat!("Cannot {action}: not in a worktree"),
                    None => "Not in a worktree".to_string(),
                };
                write!(
                    f,
                    "{}\n{}",
                    error_message(&message),
                    hint_message(cformat!(
                        "Run from inside a worktree, or specify a branch name"
                    ))
                )
            }

            GitError::WorktreeMissing { branch } => {
                write!(
                    f,
                    "{}\n{}",
                    error_message(cformat!("Worktree directory missing for <bold>{branch}</>")),
                    hint_message(cformat!(
                        "To clean up, run <underline>git worktree prune</>"
                    ))
                )
            }

            GitError::RemoteOnlyBranch { branch, remote } => {
                let cmd = suggest_command("switch", &[branch], &[]);
                cwrite!(
                    f,
                    "{ERROR_SYMBOL} <red>Branch <bold>{branch}</> exists only on remote ({remote}/{branch})</>\n{HINT_SYMBOL} <dim>To create a local worktree, run <underline>{cmd}</></>"
                )
            }

            GitError::WorktreePathOccupied {
                branch,
                path,
                occupant,
            } => {
                let path_display = format_path_for_display(path);
                let reason = if let Some(occupant_branch) = occupant {
                    cformat!(
                        "there's a worktree at the expected path <bold>{path_display}</> on branch <bold>{occupant_branch}</>"
                    )
                } else {
                    cformat!(
                        "there's a detached worktree at the expected path <bold>{path_display}</>"
                    )
                };
                let escaped_path = escape(path.to_string_lossy());
                let escaped_branch = escape(Cow::Borrowed(branch.as_str()));
                let command = format!("cd {escaped_path} && git switch {escaped_branch}");
                write!(
                    f,
                    "{}\n{}",
                    error_message(cformat!("Cannot switch to <bold>{branch}</> — {reason}")),
                    hint_message(cformat!(
                        "To switch the worktree at <underline>{path_display}</> to <underline>{branch}</>, run <underline>{command}</>"
                    ))
                )
            }

            GitError::WorktreePathExists {
                branch,
                path,
                create,
            } => {
                let path_display = format_path_for_display(path);
                let flags: &[&str] = if *create {
                    &["--create", "--clobber"]
                } else {
                    &["--clobber"]
                };
                let mut switch_cmd = suggest_command("switch", &[branch], flags);
                if let Some(ctx) = ctx {
                    switch_cmd = ctx.apply(switch_cmd);
                }
                write!(
                    f,
                    "{}\n{}",
                    error_message(cformat!(
                        "Directory already exists: <bold>{path_display}</>"
                    )),
                    hint_message(cformat!(
                        "To remove manually, run <underline>rm -rf {path_display}</>; to overwrite (with backup), run <underline>{switch_cmd}</>"
                    ))
                )
            }

            GitError::WorktreeCreationFailed {
                branch,
                base_branch,
                error,
                command,
            } => {
                let header = if let Some(base) = base_branch {
                    error_message(cformat!(
                        "Failed to create worktree for <bold>{branch}</> from base <bold>{base}</>"
                    ))
                } else {
                    error_message(cformat!("Failed to create worktree for <bold>{branch}</>"))
                };
                write!(f, "{}", format_error_block(header, error))?;
                if let Some(cmd) = command {
                    write!(
                        f,
                        "\n{}\n{}",
                        hint_message(cformat!("Failed command, <underline>{}</>:", cmd.exit_info)),
                        format_bash_with_gutter(&cmd.command)
                    )?;
                }
                Ok(())
            }

            GitError::WorktreeRemovalFailed {
                branch,
                path,
                error,
                remaining_entries,
            } => {
                let path_display = format_path_for_display(path);
                let header = error_message(cformat!(
                    "Failed to remove worktree for <bold>{branch}</> @ <bold>{path_display}</>"
                ));
                write!(f, "{}", format_error_block(header, error))?;
                if let Some(entries) = remaining_entries {
                    const MAX_SHOWN: usize = 10;
                    let listing = if entries.len() > MAX_SHOWN {
                        let shown = entries[..MAX_SHOWN].join(", ");
                        let remaining = entries.len() - MAX_SHOWN;
                        format!("{shown}, and {remaining} more")
                    } else {
                        entries.join(", ")
                    };
                    write!(
                        f,
                        "\n{}",
                        hint_message(cformat!("Remaining in directory: <underline>{listing}</>"))
                    )?;
                }
                if error.contains("not empty") {
                    write!(
                        f,
                        "\n{}",
                        hint_message(cformat!(
                            "A background process may be writing files; try <underline>wt remove</> (without --foreground)"
                        ))
                    )?;
                }
                Ok(())
            }

            GitError::CannotRemoveMainWorktree => {
                write!(
                    f,
                    "{}",
                    error_message("The main worktree cannot be removed")
                )
            }

            GitError::CannotRemoveDefaultBranch { branch } => {
                let cmd = suggest_command("remove", &[branch], &["-D"]);
                write!(
                    f,
                    "{}",
                    error_message(cformat!(
                        "Cannot remove the default branch <bold>{branch}</>"
                    ))
                )?;
                write!(
                    f,
                    "\n{}",
                    hint_message(cformat!("To force-delete, run <underline>{cmd}</>"))
                )
            }

            GitError::WorktreeLocked {
                branch,
                path,
                reason,
            } => {
                let reason_text = match reason {
                    Some(r) if !r.is_empty() => format!(" ({r})"),
                    _ => String::new(),
                };
                let path_display = format_path_for_display(path);
                write!(
                    f,
                    "{}\n{}",
                    error_message(cformat!(
                        "Cannot remove <bold>{branch}</>, worktree is locked{reason_text}"
                    )),
                    hint_message(cformat!(
                        "To unlock, run <underline>git worktree unlock {path_display}</>"
                    ))
                )
            }

            GitError::ConflictingChanges {
                target_branch,
                files,
                worktree_path,
            } => {
                write!(
                    f,
                    "{}",
                    error_message(cformat!(
                        "Can't push to local <bold>{target_branch}</> branch: conflicting uncommitted changes"
                    ))
                )?;
                if !files.is_empty() {
                    let joined_files = files.join("\n");
                    write!(f, "\n{}", format_with_gutter(&joined_files, None))?;
                }
                let path_display = format_path_for_display(worktree_path);
                write!(
                    f,
                    "\n{}",
                    hint_message(format!(
                        "Commit or stash these changes in {path_display} first"
                    ))
                )
            }

            GitError::NotFastForward {
                target_branch,
                commits_formatted,
                in_merge_context,
            } => {
                write!(
                    f,
                    "{}",
                    error_message(cformat!(
                        "Can't push to local <bold>{target_branch}</> branch: it has newer commits"
                    ))
                )?;
                if !commits_formatted.is_empty() {
                    write!(f, "\n{}", format_with_gutter(commits_formatted, None))?;
                }
                // Context-appropriate hint
                let merge_cmd = suggest_command("merge", &[target_branch], &[]);
                if *in_merge_context {
                    write!(
                        f,
                        "\n{}",
                        hint_message(cformat!(
                            "To incorporate these changes, run <underline>{merge_cmd}</> again"
                        ))
                    )
                } else {
                    let rebase_cmd = suggest_command("step", &["rebase", target_branch], &[]);
                    write!(
                        f,
                        "\n{}",
                        hint_message(cformat!(
                            "To rebase onto <underline>{target_branch}</>, run <underline>{rebase_cmd}</>"
                        ))
                    )
                }
            }

            GitError::RebaseConflict {
                target_branch,
                git_output,
            } => {
                write!(
                    f,
                    "{}",
                    error_message(cformat!("Rebase onto <bold>{target_branch}</> incomplete"))
                )?;
                if !git_output.is_empty() {
                    write!(f, "\n{}", format_with_gutter(git_output, None))
                } else {
                    write!(
                        f,
                        "\n{}\n{}",
                        hint_message(cformat!(
                            "To continue after resolving conflicts, run <underline>git rebase --continue</>"
                        )),
                        hint_message(cformat!("To abort, run <underline>git rebase --abort</>"))
                    )
                }
            }

            GitError::NotRebased { target_branch } => {
                let rebase_cmd = suggest_command("step", &["rebase", target_branch], &[]);
                write!(
                    f,
                    "{}\n{}",
                    error_message(cformat!("Branch not rebased onto <bold>{target_branch}</>")),
                    hint_message(cformat!(
                        "To rebase first, run <underline>{rebase_cmd}</>; or remove <underline>--no-rebase</>"
                    ))
                )
            }

            GitError::PushFailed {
                target_branch,
                error,
            } => {
                let header = error_message(cformat!(
                    "Can't push to local <bold>{target_branch}</> branch"
                ));
                write!(f, "{}", format_error_block(header, error))
            }

            GitError::NotInteractive => {
                let approvals_cmd = suggest_command("hook", &["approvals", "add"], &[]);
                write!(
                    f,
                    "{}\n{}",
                    error_message("Cannot prompt for approval in non-interactive environment"),
                    hint_message(cformat!(
                        "To skip prompts in CI/CD, add <underline>--yes</>; to pre-approve commands, run <underline>{approvals_cmd}</>"
                    ))
                )
            }

            GitError::HookCommandNotFound { name, available } => {
                if available.is_empty() {
                    write!(
                        f,
                        "{}",
                        error_message(cformat!(
                            "No command named <bold>{name}</> (hook has no named commands)"
                        ))
                    )
                } else {
                    let available_str = available
                        .iter()
                        .map(|s| cformat!("<bold>{s}</>"))
                        .collect::<Vec<_>>()
                        .join(", ");
                    write!(
                        f,
                        "{}",
                        error_message(cformat!(
                            "No command named <bold>{name}</> (available: {available_str})"
                        ))
                    )
                }
            }

            GitError::LlmCommandFailed {
                command,
                error,
                reproduction_command,
            } => {
                let error_header = error_message("Commit generation command failed");
                let error_block = format_error_block(error_header, error);
                // Show full pipeline command if available, otherwise just the LLM command
                let display_command = reproduction_command.as_ref().unwrap_or(command);
                let command_gutter = format_with_gutter(display_command, None);
                write!(
                    f,
                    "{}\n{}\n{}",
                    error_block,
                    info_message("Ran command:"),
                    command_gutter
                )
            }

            GitError::ProjectConfigNotFound { config_path } => {
                let path_display = format_path_for_display(config_path);
                write!(
                    f,
                    "{}\n{}",
                    error_message("No project configuration found"),
                    hint_message(cformat!(
                        "Create a config file at: <underline>{path_display}</>"
                    ))
                )
            }

            GitError::ParseError { message } => {
                write!(f, "{}", error_message(message))
            }

            GitError::WorktreeIncludeParseError { error } => {
                let header = error_message(cformat!("Error parsing <bold>.worktreeinclude</>"));
                write!(f, "{}", format_error_block(header, error))
            }

            GitError::WorktreeNotFound { branch } => {
                let switch_cmd = suggest_command("switch", &[branch], &[]);
                write!(
                    f,
                    "{}\n{}",
                    error_message(cformat!("Branch <bold>{branch}</> has no worktree")),
                    hint_message(cformat!(
                        "To create a worktree, run <underline>{switch_cmd}</>"
                    ))
                )
            }

            GitError::RefCreateConflict {
                ref_type,
                number,
                branch,
            } => {
                let name = ref_type.name();
                let syntax = ref_type.syntax();
                write!(
                    f,
                    "{}\n{}",
                    error_message(cformat!(
                        "Cannot create branch for <bold>{syntax}{number}</> — {name} already has branch <bold>{branch}</>"
                    )),
                    hint_message(cformat!(
                        "To switch to it: <underline>wt switch {syntax}{number}</>"
                    ))
                )
            }

            GitError::RefBaseConflict { ref_type, number } => {
                let syntax = ref_type.syntax();
                let name_plural = ref_type.name_plural();
                write!(
                    f,
                    "{}\n{}",
                    error_message(cformat!(
                        "Cannot use <bold>--base</> with <bold>{syntax}{number}</>"
                    )),
                    hint_message(cformat!(
                        "{name_plural} already have a base; remove <underline>--base</>"
                    ))
                )
            }

            GitError::BranchTracksDifferentRef {
                branch,
                ref_type,
                number,
            } => {
                // The ref's branch name conflicts with an existing local branch.
                // We can't use a different local name because git push requires
                // the local and remote branch names to match (with push.default=current).
                let escaped = escape(Cow::Borrowed(branch.as_str()));
                let old_name = format!("{branch}-old");
                let escaped_old = escape(Cow::Borrowed(&old_name));
                let name = ref_type.name();
                let symbol = ref_type.symbol();
                write!(
                    f,
                    "{}\n{}",
                    error_message(cformat!(
                        "Branch <bold>{branch}</> exists but doesn't track {name} {symbol}{number}"
                    )),
                    hint_message(cformat!(
                        "To free the name, run <underline>git branch -m -- {escaped} {escaped_old}</>"
                    ))
                )
            }

            GitError::NoRemoteForRepo {
                owner,
                repo,
                suggested_url,
            } => {
                write!(
                    f,
                    "{}\n{}",
                    error_message(cformat!("No remote found for <bold>{owner}/{repo}</>")),
                    hint_message(cformat!(
                        "Add the remote: <underline>git remote add upstream {suggested_url}</>"
                    ))
                )
            }

            GitError::CliApiError {
                message, stderr, ..
            } => {
                write!(f, "{}", format_error_block(error_message(message), stderr))
            }

            GitError::Other { message } => {
                write!(f, "{}", error_message(message))
            }
        }
    }
}

impl std::fmt::Display for GitError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        self.fmt_with_ctx(f, None)
    }
}

/// Semantic errors that require special handling in main.rs
///
/// Most errors use anyhow::bail! with formatted messages. This enum is only
/// for cases that need exit code extraction or special handling.
#[derive(Debug)]
pub enum WorktrunkError {
    /// Child process exited with non-zero code (preserves exit code for signals)
    ChildProcessExited { code: i32, message: String },
    /// Hook command failed
    HookCommandFailed {
        hook_type: HookType,
        command_name: Option<String>,
        error: String,
        exit_code: Option<i32>,
    },
    /// Command was not approved by user (silent error)
    CommandNotApproved,
    /// Error already displayed, just exit with given code (silent error)
    AlreadyDisplayed { exit_code: i32 },
}

impl std::fmt::Display for WorktrunkError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            WorktrunkError::ChildProcessExited { message, .. } => {
                write!(f, "{}", error_message(message))
            }
            WorktrunkError::HookCommandFailed {
                hook_type,
                command_name,
                error,
                ..
            } => {
                // Note: Callers that support --no-hooks should add the hint themselves
                if let Some(name) = command_name {
                    write!(
                        f,
                        "{}",
                        error_message(cformat!(
                            "{hook_type} command failed: <bold>{name}</>: {error}"
                        ))
                    )
                } else {
                    write!(
                        f,
                        "{}",
                        error_message(format!("{hook_type} command failed: {error}"))
                    )
                }
            }
            WorktrunkError::CommandNotApproved => {
                Ok(()) // on_skip callback handles the printing
            }
            WorktrunkError::AlreadyDisplayed { .. } => {
                Ok(()) // error already shown via output functions
            }
        }
    }
}

impl std::error::Error for WorktrunkError {}

/// Extract exit code from WorktrunkError, if applicable
pub fn exit_code(err: &anyhow::Error) -> Option<i32> {
    // Check for wrapped HookErrorWithHint first
    if let Some(wrapper) = err.downcast_ref::<HookErrorWithHint>() {
        return exit_code(&wrapper.inner);
    }
    err.downcast_ref::<WorktrunkError>().and_then(|e| match e {
        WorktrunkError::ChildProcessExited { code, .. } => Some(*code),
        WorktrunkError::HookCommandFailed { exit_code, .. } => *exit_code,
        WorktrunkError::CommandNotApproved => None,
        WorktrunkError::AlreadyDisplayed { exit_code } => Some(*exit_code),
    })
}

/// If the error is a HookCommandFailed, wrap it to add a hint about using --no-hooks.
///
/// ## When to use
///
/// Use this for commands where a hook runs as a side effect of the user's intent:
/// - `wt merge` - user wants to merge, hooks run as part of that
/// - `wt commit` - user wants to commit, pre-commit hooks run
/// - `wt switch --create` - user wants a worktree, post-create hooks run
///
/// ## When NOT to use
///
/// Don't use for `wt hook <type>` - the user explicitly asked to run hooks,
/// so suggesting `--no-hooks` makes no sense.
pub fn add_hook_skip_hint(err: anyhow::Error) -> anyhow::Error {
    // Extract hook_type first (if applicable), then decide whether to wrap
    let hook_type = err
        .downcast_ref::<WorktrunkError>()
        .and_then(|wt_err| match wt_err {
            WorktrunkError::HookCommandFailed { hook_type, .. } => Some(*hook_type),
            _ => None,
        });

    match hook_type {
        Some(hook_type) => HookErrorWithHint {
            inner: err,
            hook_type,
        }
        .into(),
        None => err,
    }
}

/// Wrapper that displays a HookCommandFailed error with the --no-hooks hint.
/// Created by `add_hook_skip_hint()` for commands that support `--no-hooks`.
#[derive(Debug)]
pub struct HookErrorWithHint {
    inner: anyhow::Error,
    hook_type: HookType,
}

impl std::fmt::Display for HookErrorWithHint {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        // Display the original error (always HookCommandFailed - validated by add_hook_skip_hint)
        write!(f, "{}", self.inner)?;
        // Can't derive command from hook type (e.g., PreRemove is used by both `wt remove` and `wt merge`)
        write!(
            f,
            "\n{}",
            hint_message(cformat!(
                "To skip {} hooks, re-run with <underline>--no-hooks</>",
                self.hook_type
            ))
        )
    }
}

impl std::error::Error for HookErrorWithHint {
    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
        self.inner.source()
    }
}

/// Format an error with header and gutter content
fn format_error_block(header: impl Into<String>, error: &str) -> String {
    let header = header.into();
    let trimmed = error.trim();
    if trimmed.is_empty() {
        header
    } else {
        format!("{header}\n{}", format_with_gutter(trimmed, None))
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use insta::assert_snapshot;

    #[test]
    fn snapshot_into_preserves_type_for_display() {
        // .into() preserves type so we can downcast and use Display
        let err: anyhow::Error = GitError::BranchAlreadyExists {
            branch: "main".into(),
        }
        .into();

        let downcast = err.downcast_ref::<GitError>().expect("Should downcast");
        assert_snapshot!(downcast.to_string(), @"
        ✗ Branch main already exists
        ↳ To switch to the existing branch, run without --create: wt switch main
        ");
    }

    #[test]
    fn test_pattern_matching_with_into() {
        let err: anyhow::Error = GitError::BranchAlreadyExists {
            branch: "main".into(),
        }
        .into();

        if let Some(GitError::BranchAlreadyExists { branch }) = err.downcast_ref::<GitError>() {
            assert_eq!(branch, "main");
        } else {
            panic!("Failed to downcast and pattern match");
        }
    }

    #[test]
    fn snapshot_worktree_error_with_path_and_create() {
        let err = GitError::WorktreePathExists {
            branch: "feature".to_string(),
            path: PathBuf::from("/some/path"),
            create: true,
        };
        assert_snapshot!(err.to_string(), @"
        ✗ Directory already exists: /some/path
        ↳ To remove manually, run rm -rf /some/path; to overwrite (with backup), run wt switch --create --clobber feature
        ");
    }

    #[test]
    fn test_exit_code() {
        // ChildProcessExited
        let err: anyhow::Error = WorktrunkError::ChildProcessExited {
            code: 42,
            message: "test".into(),
        }
        .into();
        assert_eq!(exit_code(&err), Some(42));

        // HookCommandFailed with code
        let err: anyhow::Error = WorktrunkError::HookCommandFailed {
            hook_type: HookType::PreMerge,
            command_name: Some("test".into()),
            error: "failed".into(),
            exit_code: Some(1),
        }
        .into();
        assert_eq!(exit_code(&err), Some(1));

        // HookCommandFailed without code
        let err: anyhow::Error = WorktrunkError::HookCommandFailed {
            hook_type: HookType::PreMerge,
            command_name: None,
            error: "failed".into(),
            exit_code: None,
        }
        .into();
        assert_eq!(exit_code(&err), None);

        // CommandNotApproved, AlreadyDisplayed, GitError
        assert_eq!(exit_code(&WorktrunkError::CommandNotApproved.into()), None);
        assert_eq!(
            exit_code(&WorktrunkError::AlreadyDisplayed { exit_code: 5 }.into()),
            Some(5)
        );
        assert_eq!(
            exit_code(&GitError::DetachedHead { action: None }.into()),
            None
        );

        // Wrapped hook error
        let inner: anyhow::Error = WorktrunkError::HookCommandFailed {
            hook_type: HookType::PreCommit,
            command_name: Some("lint".into()),
            error: "failed".into(),
            exit_code: Some(7),
        }
        .into();
        assert_eq!(exit_code(&add_hook_skip_hint(inner)), Some(7));
    }

    #[test]
    fn snapshot_add_hook_skip_hint() {
        // Wraps HookCommandFailed with --no-hooks hint
        let inner: anyhow::Error = WorktrunkError::HookCommandFailed {
            hook_type: HookType::PreMerge,
            command_name: Some("test".into()),
            error: "failed".into(),
            exit_code: Some(1),
        }
        .into();
        assert_snapshot!(add_hook_skip_hint(inner).to_string(), @"
        ✗ pre-merge command failed: test: failed
        ↳ To skip pre-merge hooks, re-run with --no-hooks
        ");

        // pre-commit hook type
        let inner: anyhow::Error = WorktrunkError::HookCommandFailed {
            hook_type: HookType::PreCommit,
            command_name: Some("build".into()),
            error: "Build failed".into(),
            exit_code: Some(1),
        }
        .into();
        assert_snapshot!(add_hook_skip_hint(inner).to_string(), @"
        ✗ pre-commit command failed: build: Build failed
        ↳ To skip pre-commit hooks, re-run with --no-hooks
        ");

        // Passes through non-hook errors unchanged (no --no-hooks hint)
        let err: anyhow::Error = WorktrunkError::ChildProcessExited {
            code: 1,
            message: "test".into(),
        }
        .into();
        assert!(!add_hook_skip_hint(err).to_string().contains("--no-hooks"));

        let err: anyhow::Error = GitError::DetachedHead { action: None }.into();
        assert!(!add_hook_skip_hint(err).to_string().contains("--no-hooks"));

        let err: anyhow::Error = GitError::Other {
            message: "some error".into(),
        }
        .into();
        assert!(!add_hook_skip_hint(err).to_string().contains("--no-hooks"));
    }

    #[test]
    fn test_format_error_block() {
        let header = "Error occurred".to_string();
        assert_snapshot!(format_error_block(header.clone(), "  some error text  "), @"
        Error occurred
          some error text
        ");

        // Empty/whitespace returns header only
        assert_eq!(format_error_block(header.clone(), ""), header);
        assert_eq!(format_error_block(header.clone(), "   \n\t  "), header);
    }

    #[test]
    fn snapshot_worktrunk_error_display() {
        let err = WorktrunkError::ChildProcessExited {
            code: 1,
            message: "Command failed".into(),
        };
        assert_snapshot!(err.to_string(), @"✗ Command failed");

        let err = WorktrunkError::HookCommandFailed {
            hook_type: HookType::PreMerge,
            command_name: Some("lint".into()),
            error: "lint failed".into(),
            exit_code: Some(1),
        };
        assert_snapshot!(err.to_string(), @"✗ pre-merge command failed: lint: lint failed");

        let err = WorktrunkError::HookCommandFailed {
            hook_type: HookType::PreStart,
            command_name: None,
            error: "setup failed".into(),
            exit_code: None,
        };
        assert_snapshot!(err.to_string(), @"✗ pre-start command failed: setup failed");

        // Silent errors produce empty output
        assert_eq!(format!("{}", WorktrunkError::CommandNotApproved), "");
        assert_eq!(
            format!("{}", WorktrunkError::AlreadyDisplayed { exit_code: 1 }),
            ""
        );
    }

    #[test]
    fn snapshot_not_in_worktree() {
        let err = GitError::NotInWorktree {
            action: Some("resolve @".into()),
        };
        assert_snapshot!(err.to_string(), @"
        ✗ Cannot resolve @: not in a worktree
        ↳ Run from inside a worktree, or specify a branch name
        ");

        let err = GitError::NotInWorktree { action: None };
        assert_snapshot!(err.to_string(), @"
        ✗ Not in a worktree
        ↳ Run from inside a worktree, or specify a branch name
        ");
    }

    #[test]
    fn snapshot_worktree_path_occupied() {
        let err = GitError::WorktreePathOccupied {
            branch: "feature".into(),
            path: PathBuf::from("/tmp/repo"),
            occupant: Some("main".into()),
        };
        assert_snapshot!(err.to_string(), @"
        ✗ Cannot switch to feature — there's a worktree at the expected path /tmp/repo on branch main
        ↳ To switch the worktree at /tmp/repo to feature, run cd /tmp/repo && git switch feature
        ");

        let err = GitError::WorktreePathOccupied {
            branch: "feature".into(),
            path: PathBuf::from("/tmp/repo"),
            occupant: None,
        };
        assert_snapshot!(err.to_string(), @"
        ✗ Cannot switch to feature — there's a detached worktree at the expected path /tmp/repo
        ↳ To switch the worktree at /tmp/repo to feature, run cd /tmp/repo && git switch feature
        ");
    }

    #[test]
    fn snapshot_worktree_path_occupied_special_chars() {
        // Spaces in path and branch name require shell escaping in the hint command
        let err = GitError::WorktreePathOccupied {
            branch: "feature/my branch".into(),
            path: PathBuf::from("/tmp/my repo"),
            occupant: Some("main".into()),
        };
        let output = err.to_string();
        // The hint command must quote the path and branch for safe shell execution
        assert!(
            output.contains("cd '/tmp/my repo' && git switch 'feature/my branch'"),
            "expected shell-escaped command in hint, got: {output}"
        );
    }

    #[test]
    fn snapshot_worktree_creation_failed() {
        let err = GitError::WorktreeCreationFailed {
            branch: "feature".into(),
            base_branch: Some("main".into()),
            error: "git error".into(),
            command: None,
        };
        assert_snapshot!(err.to_string(), @"
        ✗ Failed to create worktree for feature from base main
          git error
        ");

        let err = GitError::WorktreeCreationFailed {
            branch: "feature".into(),
            base_branch: None,
            error: "git error".into(),
            command: None,
        };
        assert_snapshot!(err.to_string(), @"
        ✗ Failed to create worktree for feature
          git error
        ");

        let err = GitError::WorktreeCreationFailed {
            branch: "feature".into(),
            base_branch: Some("main".into()),
            error: "fatal: ref exists".into(),
            command: Some(FailedCommand {
                command: "git worktree add /path -b feature main".into(),
                exit_info: "exit code 128".into(),
            }),
        };
        assert_snapshot!(err.to_string(), @"
        ✗ Failed to create worktree for feature from base main
          fatal: ref exists
        ↳ Failed command, exit code 128:
          git worktree add /path -b feature main
        ");
    }

    #[test]
    fn snapshot_worktree_locked() {
        let err = GitError::WorktreeLocked {
            branch: "feature".into(),
            path: PathBuf::from("/tmp/repo.feature"),
            reason: Some("Testing lock".into()),
        };
        assert_snapshot!(err.to_string(), @"
        ✗ Cannot remove feature, worktree is locked (Testing lock)
        ↳ To unlock, run git worktree unlock /tmp/repo.feature
        ");

        // Empty reason should not show parentheses
        let err = GitError::WorktreeLocked {
            branch: "feature".into(),
            path: PathBuf::from("/tmp/repo.feature"),
            reason: Some("".into()),
        };
        let display = err.to_string();
        assert_snapshot!(display, @"
        ✗ Cannot remove feature, worktree is locked
        ↳ To unlock, run git worktree unlock /tmp/repo.feature
        ");
        assert!(
            !display.contains("locked ("),
            "should not show parentheses without reason"
        );
    }

    #[test]
    fn snapshot_not_rebased() {
        let err = GitError::NotRebased {
            target_branch: "main".into(),
        };
        assert_snapshot!(err.to_string(), @"
        ✗ Branch not rebased onto main
        ↳ To rebase first, run wt step rebase main; or remove --no-rebase
        ");
    }

    #[test]
    fn snapshot_hook_command_not_found() {
        let err = GitError::HookCommandNotFound {
            name: "unknown".into(),
            available: vec!["lint".into(), "test".into()],
        };
        assert_snapshot!(err.to_string(), @"✗ No command named unknown (available: lint, test)");

        let err = GitError::HookCommandNotFound {
            name: "unknown".into(),
            available: vec![],
        };
        assert_snapshot!(err.to_string(), @"✗ No command named unknown (hook has no named commands)");
    }

    #[test]
    fn snapshot_llm_command_failed() {
        let err = GitError::LlmCommandFailed {
            command: "llm".into(),
            error: "connection failed".into(),
            reproduction_command: Some("wt step commit --show-prompt | llm".into()),
        };
        assert_snapshot!(err.to_string(), @"
        ✗ Commit generation command failed
          connection failed
        ○ Ran command:
          wt step commit --show-prompt | llm
        ");

        let err = GitError::LlmCommandFailed {
            command: "llm --model gpt-4".into(),
            error: "timeout".into(),
            reproduction_command: None,
        };
        assert_snapshot!(err.to_string(), @"
        ✗ Commit generation command failed
          timeout
        ○ Ran command:
          llm --model gpt-4
        ");
    }

    #[test]
    fn snapshot_uncommitted_changes() {
        // Action only (negative assertion kept: no --force)
        let err = GitError::UncommittedChanges {
            action: Some("push".into()),
            branch: None,
            force_hint: false,
        };
        let display = err.to_string();
        assert_snapshot!(display, @"
        ✗ Cannot push: working tree has uncommitted changes
        ↳ Commit or stash changes first
        ");
        assert!(!display.contains("--force"));

        // Branch only
        let err = GitError::UncommittedChanges {
            action: None,
            branch: Some("feature".into()),
            force_hint: false,
        };
        assert_snapshot!(err.to_string(), @"
        ✗ feature has uncommitted changes
        ↳ Commit or stash changes first
        ");

        // Neither action nor branch
        let err = GitError::UncommittedChanges {
            action: None,
            branch: None,
            force_hint: false,
        };
        assert_snapshot!(err.to_string(), @"
        ✗ Working tree has uncommitted changes
        ↳ Commit or stash changes first
        ");

        // With force_hint
        let err = GitError::UncommittedChanges {
            action: Some("remove worktree".into()),
            branch: Some("feature".into()),
            force_hint: true,
        };
        assert_snapshot!(err.to_string(), @"
        ✗ Cannot remove worktree: feature has uncommitted changes
        ↳ Commit or stash changes first, or to lose uncommitted changes, run wt remove --force feature
        ");
    }

    #[test]
    fn snapshot_not_fast_forward() {
        // Empty commits, outside merge context
        let err = GitError::NotFastForward {
            target_branch: "main".into(),
            commits_formatted: "".into(),
            in_merge_context: false,
        };
        assert_snapshot!(err.to_string(), @"
        ✗ Can't push to local main branch: it has newer commits
        ↳ To rebase onto main, run wt step rebase main
        ");

        // With commits, outside merge context
        let err = GitError::NotFastForward {
            target_branch: "develop".into(),
            commits_formatted: "abc123 Some commit".into(),
            in_merge_context: false,
        };
        assert_snapshot!(err.to_string(), @"
        ✗ Can't push to local develop branch: it has newer commits
          abc123 Some commit
        ↳ To rebase onto develop, run wt step rebase develop
        ");

        // In merge context
        let err = GitError::NotFastForward {
            target_branch: "main".into(),
            commits_formatted: "def456 Another commit".into(),
            in_merge_context: true,
        };
        assert_snapshot!(err.to_string(), @"
        ✗ Can't push to local main branch: it has newer commits
          def456 Another commit
        ↳ To incorporate these changes, run wt merge main again
        ");
    }

    #[test]
    fn snapshot_conflicting_changes_empty_files() {
        let err = GitError::ConflictingChanges {
            target_branch: "main".into(),
            files: vec![],
            worktree_path: PathBuf::from("/tmp/repo"),
        };
        assert_snapshot!(err.to_string(), @"
        ✗ Can't push to local main branch: conflicting uncommitted changes
        ↳ Commit or stash these changes in /tmp/repo first
        ");
    }

    #[test]
    fn snapshot_cli_api_error() {
        let err = GitError::CliApiError {
            ref_type: RefType::Pr,
            message: "gh api failed for PR #42".into(),
            stderr: "error: unexpected response\ncode: 500".into(),
        };
        assert_snapshot!(err.to_string(), @"
        ✗ gh api failed for PR #42
          error: unexpected response
          code: 500
        ");
    }

    #[test]
    fn snapshot_no_remote_for_repo() {
        let err = GitError::NoRemoteForRepo {
            owner: "upstream-owner".into(),
            repo: "upstream-repo".into(),
            suggested_url: "https://github.com/upstream-owner/upstream-repo.git".into(),
        };
        assert_snapshot!(err.to_string(), @"
        ✗ No remote found for upstream-owner/upstream-repo
        ↳ Add the remote: git remote add upstream https://github.com/upstream-owner/upstream-repo.git
        ");
    }

    #[test]
    fn snapshot_rebase_conflict_empty_output() {
        let err = GitError::RebaseConflict {
            target_branch: "main".into(),
            git_output: "".into(),
        };
        assert_snapshot!(err.to_string(), @"
        ✗ Rebase onto main incomplete
        ↳ To continue after resolving conflicts, run git rebase --continue
        ↳ To abort, run git rebase --abort
        ");
    }

    #[test]
    fn snapshot_with_switch_suggestion_branch_already_exists() {
        let err = GitError::WithSwitchSuggestion {
            source: Box::new(GitError::BranchAlreadyExists {
                branch: "emails".into(),
            }),
            ctx: SwitchSuggestionCtx {
                extra_flags: vec!["--execute=claude".into()],
                trailing_args: vec!["Check my emails".into()],
            },
        };
        assert_snapshot!(err.to_string(), @"
        ✗ Branch emails already exists
        ↳ To switch to the existing branch, run without --create: wt switch emails --execute=claude -- 'Check my emails'
        ");
    }

    #[test]
    fn snapshot_with_switch_suggestion_worktree_path_exists() {
        let err = GitError::WithSwitchSuggestion {
            source: Box::new(GitError::WorktreePathExists {
                branch: "emails".into(),
                path: PathBuf::from("/tmp/repo.emails"),
                create: true,
            }),
            ctx: SwitchSuggestionCtx {
                extra_flags: vec!["--execute=claude".into()],
                trailing_args: vec!["Check my emails".into()],
            },
        };
        assert_snapshot!(err.to_string(), @"
        ✗ Directory already exists: /tmp/repo.emails
        ↳ To remove manually, run rm -rf /tmp/repo.emails; to overwrite (with backup), run wt switch --create --clobber emails --execute=claude -- 'Check my emails'
        ");
    }

    #[test]
    fn snapshot_with_switch_suggestion_no_trailing_args() {
        let err = GitError::WithSwitchSuggestion {
            source: Box::new(GitError::BranchAlreadyExists {
                branch: "emails".into(),
            }),
            ctx: SwitchSuggestionCtx {
                extra_flags: vec!["--execute=claude".into()],
                trailing_args: vec![],
            },
        };
        assert_snapshot!(err.to_string(), @"
        ✗ Branch emails already exists
        ↳ To switch to the existing branch, run without --create: wt switch emails --execute=claude
        ");
    }

    #[test]
    fn snapshot_with_switch_suggestion_branch_not_found() {
        let err = GitError::WithSwitchSuggestion {
            source: Box::new(GitError::BranchNotFound {
                branch: "emails".into(),
                show_create_hint: true,
                last_fetch_ago: None,
            }),
            ctx: SwitchSuggestionCtx {
                extra_flags: vec!["--execute=claude".into()],
                trailing_args: vec!["Check my emails".into()],
            },
        };
        assert_snapshot!(err.to_string(), @"
        ✗ No branch named emails
        ↳ To create a new branch, run wt switch --create emails --execute=claude -- 'Check my emails'; to list branches, run wt list --branches --remotes
        ");
    }

    #[test]
    fn test_with_switch_suggestion_unwrapped_errors_unaffected() {
        // Non-switch-suggestion errors should be completely unaffected by the wrapper
        let inner = GitError::DetachedHead {
            action: Some("merge".into()),
        };
        let wrapped = GitError::WithSwitchSuggestion {
            source: Box::new(inner.clone()),
            ctx: SwitchSuggestionCtx {
                extra_flags: vec!["--execute=claude".into()],
                trailing_args: vec!["Check my emails".into()],
            },
        };
        // Errors without switch suggestions should render identically
        assert_eq!(inner.to_string(), wrapped.to_string());
    }
}