Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

44.5 KB
Raw Blame
use std::ffi::OsString;

use colored::Colorize;
use serde_json::{Map, Value};
use unicode_width::UnicodeWidthStr;

use crate::{
    error::Error,
    i18n::{Language, copy},
    output::OutputFormat,
    terminal_ui::{fit_to_display_width, truncate_to_display_width},
    theme,
};

const CARD_WIDTH: usize = 72;

#[derive(Debug, Clone, PartialEq, Eq)]
pub(crate) struct ErrorAction {
    command: String,
    description: String,
}

impl ErrorAction {
    pub(crate) fn new(command: impl Into<String>, description: impl Into<String>) -> Self {
        Self {
            command: command.into(),
            description: description.into(),
        }
    }
}

#[derive(Debug, Clone, PartialEq, Eq)]
pub(crate) struct ErrorReport {
    command: Option<String>,
    usage: Option<String>,
    title: String,
    message: String,
    suggestion: Option<String>,
    detail: Option<String>,
    actions: Vec<ErrorAction>,
}

impl ErrorReport {
    pub(crate) fn new(title: impl Into<String>, message: impl Into<String>) -> Self {
        Self {
            command: None,
            usage: None,
            title: title.into(),
            message: message.into(),
            suggestion: None,
            detail: None,
            actions: Vec::new(),
        }
    }

    pub(crate) fn with_command(mut self, command: impl Into<String>) -> Self {
        self.command = Some(command.into());
        self
    }

    pub(crate) fn with_usage(mut self, usage: impl Into<String>) -> Self {
        self.usage = Some(usage.into());
        self
    }

    pub(crate) fn with_suggestion(mut self, suggestion: impl Into<String>) -> Self {
        self.suggestion = Some(suggestion.into());
        self
    }

    pub(crate) fn with_detail(mut self, detail: impl Into<String>) -> Self {
        self.detail = Some(detail.into());
        self
    }

    pub(crate) fn with_actions(mut self, actions: Vec<ErrorAction>) -> Self {
        self.actions = actions;
        self
    }
}

pub(crate) fn print_report(report: &ErrorReport, verbose: bool) {
    eprint!("{}", render_report(report, verbose));
}

pub(crate) fn print_runtime_error(
    command: &str,
    error: &Error,
    format: OutputFormat,
    compact: bool,
    verbose: bool,
) {
    if matches!(format, OutputFormat::Json) {
        eprintln!("{}", render_json_error(error, compact));
    } else {
        print_report(&report_for_runtime_error(command, error), verbose);
    }
}

fn render_json_error(error: &Error, compact: bool) -> String {
    let (message, details): (String, Option<&Value>) = match error {
        Error::Api {
            message, details, ..
        } => (message.clone(), details.as_ref()),
        _ => (error.to_string(), None),
    };

    let mut body = Map::new();
    body.insert("code".to_string(), Value::String(error.code().to_string()));
    body.insert("message".to_string(), Value::String(message));
    if let Some(details) = details {
        body.insert("details".to_string(), details.clone());
    }
    let envelope = serde_json::json!({"ok": false, "error": body});
    if compact {
        envelope.to_string()
    } else {
        serde_json::to_string_pretty(&envelope).unwrap_or_else(|_| envelope.to_string())
    }
}

pub(crate) fn report_for_clap_error(args: &[OsString], clap_output: &str) -> ErrorReport {
    let language = Language::current();
    let command = display_command(args);
    let usage = parse_usage(clap_output);

    if is_setup_cli_command(args) {
        return ErrorReport::new(
            copy(language, "Command Error", "命令错误"),
            copy(
                language,
                "Use ov config to add, edit, or delete configs.",
                "请使用 ov config 添加、编辑或删除配置。",
            ),
        )
        .with_command(command)
        .with_optional_usage(usage)
        .with_suggestion("ov config")
        .with_actions(vec![
            ErrorAction::new(
                "ov config",
                copy(
                    language,
                    "Add, edit, or delete configs",
                    "添加、编辑或删除配置",
                ),
            ),
            ErrorAction::new(
                "ov config show",
                copy(language, "Show the active config", "显示当前配置"),
            ),
            ErrorAction::new(
                "ov config validate",
                copy(language, "Check the active config", "检查当前配置"),
            ),
        ]);
    }

    let unknown = parse_unknown_subcommand(clap_output);
    let suggestion = parse_clap_subcommand_suggestion(clap_output)
        .map(|suggested| qualified_suggestion(args, &suggested));
    let mut actions = Vec::new();
    if let Some(suggestion) = suggestion.as_ref() {
        actions.push(ErrorAction::new(
            suggestion,
            copy(language, "Run the suggested command", "运行建议的命令"),
        ));
    }
    let help_command = usage
        .as_deref()
        .and_then(help_command_from_usage)
        .unwrap_or_else(|| "ov --help".to_string());
    let help_description = if help_command == "ov --help" {
        copy(language, "Show all commands", "查看所有命令")
    } else {
        copy(language, "Show this command's help", "查看此命令帮助")
    };
    actions.push(ErrorAction::new(help_command, help_description));

    let message = unknown
        .map(|value| match language {
            Language::En => format!("Unknown command: {value}."),
            Language::ZhCn => format!("未知命令:{value}。"),
        })
        .unwrap_or_else(|| first_error_line(clap_output));

    let mut report = ErrorReport::new(copy(language, "Command Error", "命令错误"), message)
        .with_command(command)
        .with_optional_usage(usage)
        .with_actions(actions);
    if let Some(suggestion) = suggestion {
        report = report.with_suggestion(suggestion);
    }
    report
}

pub(crate) fn report_for_message_error(
    command: impl Into<String>,
    title: impl Into<String>,
    message: impl Into<String>,
    actions: Vec<ErrorAction>,
) -> ErrorReport {
    ErrorReport::new(title, message)
        .with_command(command)
        .with_actions(actions)
}

pub(crate) fn report_for_plain_help_error(
    command: impl Into<String>,
    help_command: impl Into<String>,
) -> ErrorReport {
    let language = Language::current();
    let help_command = help_command.into();
    ErrorReport::new(
        copy(language, "Command Error", "命令错误"),
        copy(
            language,
            "Plain help is not supported for this command. Use prefixed help instead.",
            "此命令不支持 plain help。请改用带前缀的 help。",
        ),
    )
    .with_command(command)
    .with_suggestion(help_command.clone())
    .with_actions(vec![ErrorAction::new(
        help_command,
        copy(language, "Show this command's help", "查看此命令帮助"),
    )])
}

pub(crate) fn report_for_runtime_error(command: impl Into<String>, error: &Error) -> ErrorReport {
    let language = Language::current();
    let command = command.into();
    match error {
        Error::MissingConfig => ErrorReport::new(
            copy(language, "Configuration Error", "配置错误"),
            copy(
                language,
                "No ovcli.conf detected. Run ov config to create one before using server commands.",
                "未检测到 ovcli.conf。请先运行 ov config 创建配置,再使用服务器命令。",
            ),
        )
        .with_command(command)
        .with_actions(vec![ErrorAction::new(
            "ov config",
            copy(language, "Create a config", "创建配置"),
        )]),
        Error::Config(message) => ErrorReport::new(copy(language, "Configuration Error", "配置错误"), message)
            .with_command(command)
            .with_actions(config_error_actions(message, language)),
        Error::Language(message) => ErrorReport::new(copy(language, "Language Error", "语言错误"), message)
            .with_command(command)
            .with_actions(vec![
                ErrorAction::new("ov language en", copy(language, "Use English", "使用英文")),
                ErrorAction::new("ov language zh-CN", copy(language, "Use Simplified Chinese", "使用简体中文")),
            ]),
        Error::Timeout(message) => ErrorReport::new(
            copy(language, "Request Timeout", "请求超时"),
            copy(
                language,
                "OpenViking did not respond before the configured timeout expired.",
                "OpenViking 未在配置的超时时间内响应。",
            ),
        )
        .with_command(command)
        .with_detail(message)
        .with_actions(vec![
            ErrorAction::new("ov config", copy(language, "Increase the request timeout", "提高请求超时时间")),
            ErrorAction::new("ov config show", copy(language, "Show the active config", "查看当前配置")),
        ]),
        Error::Network(message) => ErrorReport::new(
            copy(language, "Connection Error", "连接错误"),
            format!(
                "{} {}",
                copy(
                    language,
                    "Could not reach OpenViking. Check the detail first, then whether the server is running and the URL is correct.",
                    "无法连接 OpenViking。请先查看详情,再确认服务器是否运行、URL 是否正确。"
                ),
                detail_line(language, message),
            ),
        )
        .with_command(command)
        .with_actions(vec![
            ErrorAction::new("ov config validate", copy(language, "Check the active config", "检查当前配置")),
            ErrorAction::new("ov health", copy(language, "Run a quick server health check", "快速检查服务器健康状态")),
            ErrorAction::new("ov config switch", copy(language, "Switch to another config", "切换到其他配置")),
        ]),
        Error::Api {
            message, details, ..
        } if error.code() == "REFRESH_FAILED" => {
            let retry_command = command.clone();
            let mut report = ErrorReport::new(
                copy(language, "Compile Refresh Failed", "Compile 刷新失败"),
                api_error_message(error.code(), message),
            )
            .with_command(command)
            .with_actions(vec![
                ErrorAction::new(
                    retry_command,
                    copy(
                        language,
                        "Retry safely; matching files stay unchanged and refresh runs again",
                        "安全重试;相同内容不会重复写入,并会重新执行刷新",
                    ),
                ),
                ErrorAction::new(
                    "ov status",
                    copy(
                        language,
                        "Check OpenViking service status",
                        "检查 OpenViking 服务状态",
                    ),
                ),
            ]);
            if let Some(details) = details {
                report = report.with_detail(details.to_string());
            }
            report
        }
        Error::Api { message, .. } if error.code() == "UNAUTHENTICATED" => ErrorReport::new(
            copy(language, "Authentication Error", "认证错误"),
            api_error_message(error.code(), message),
        )
        .with_command(command)
        .with_actions(vec![
            ErrorAction::new("ov config", copy(language, "Edit this config", "编辑这个配置")),
            ErrorAction::new("ov config switch", copy(language, "Use another config", "使用其他配置")),
        ]),
        Error::Api { message, details, .. } => {
            let mut report = ErrorReport::new(
                copy(language, "OpenViking API Error", "OpenViking API 错误"),
                api_error_message(error.code(), message),
            )
            .with_command(command);
            if let Some(details) = details {
                report = report.with_detail(details.to_string());
            }
            report
        }
        Error::Client(message) => ErrorReport::new(
            copy(language, "Command Error", "命令错误"),
            sentence_case_error(message),
        )
            .with_command(command.clone())
            .with_actions(contextual_help_actions(&command, language)),
        Error::Parse(message) => ErrorReport::new(
            copy(language, "Parse Error", "解析错误"),
            sentence_case_error(message),
        )
            .with_command(command.clone())
            .with_actions(contextual_help_actions(&command, language)),
        Error::Output(message) => ErrorReport::new(copy(language, "Output Error", "输出错误"), message).with_command(command),
        Error::InvalidPath(message) => ErrorReport::new(
            copy(language, "Invalid Path", "路径无效"),
            sentence_case_error(message),
        )
            .with_command(command.clone())
            .with_actions(contextual_help_actions(&command, language)),
        Error::Io(error) => ErrorReport::new(copy(language, "IO Error", "IO 错误"), copy(language, "OpenViking could not read or write a file.", "OpenViking 无法读取或写入文件。"))
            .with_command(command)
            .with_detail(error.to_string()),
        Error::Serialization(error) => {
            ErrorReport::new(copy(language, "Serialization Error", "序列化错误"), copy(language, "OpenViking could not parse structured data.", "OpenViking 无法解析结构化数据。"))
                .with_command(command)
                .with_detail(error.to_string())
        }
        Error::Zip(error) => ErrorReport::new(copy(language, "Archive Error", "压缩包错误"), copy(language, "OpenViking could not process the archive.", "OpenViking 无法处理压缩包。"))
            .with_command(command)
            .with_detail(error.to_string()),
        Error::AlreadyReported => ErrorReport::new(copy(language, "Command Error", "命令错误"), copy(language, "The command failed.", "命令执行失败。"))
            .with_command(command),
    }
}

fn config_error_actions(message: &str, language: Language) -> Vec<ErrorAction> {
    if is_config_file_load_error(message) {
        return vec![ErrorAction::new(
            "ov config",
            copy(
                language,
                "Repair or recreate the active config",
                "修复或重新创建当前配置",
            ),
        )];
    }

    vec![
        ErrorAction::new(
            "ov config",
            copy(language, "Add or edit a config", "添加或编辑配置"),
        ),
        ErrorAction::new(
            "ov config show",
            copy(language, "Show the active config", "显示当前配置"),
        ),
    ]
}

fn is_config_file_load_error(message: &str) -> bool {
    message.starts_with("Failed to read config file:")
        || message.starts_with("Failed to parse config file:")
}

fn contextual_help_actions(command: &str, language: Language) -> Vec<ErrorAction> {
    let help_command = contextual_help_command(command).unwrap_or_else(|| "ov --help".to_string());
    let description = if help_command.ends_with(" --help") && help_command != "ov --help" {
        copy(language, "Show this command's help", "查看此命令帮助")
    } else {
        copy(language, "Show all commands", "查看所有命令")
    };
    vec![ErrorAction::new(help_command, description)]
}

fn contextual_help_command(command: &str) -> Option<String> {
    let tokens = command.split_whitespace().collect::<Vec<_>>();
    let program = *tokens.first()?;
    let root = *tokens.get(1)?;

    match root {
        "config" => Some(group_help_command(
            program,
            root,
            tokens.get(2).copied(),
            &["show", "validate", "switch"],
        )),
        "task" => Some(task_help_command(program, &tokens)),
        "admin" => Some(group_help_command(
            program,
            root,
            tokens.get(2).copied(),
            &[
                "create-account",
                "list-accounts",
                "delete-account",
                "register-user",
                "list-users",
                "create-group",
                "list-groups",
                "list-group-members",
                "add-group-member",
                "remove-group-member",
                "delete-group",
                "remove-user",
                "set-role",
                "regenerate-key",
                "set-account-settings",
            ],
        )),
        "system" => Some(system_help_command(program, &tokens)),
        "session" => Some(group_help_command(
            program,
            root,
            tokens.get(2).copied(),
            &[
                "new",
                "list",
                "get",
                "get-session-context",
                "get-session-archive",
                "delete",
                "add-message",
                "add-messages",
                "commit",
            ],
        )),
        "privacy" => Some(group_help_command(
            program,
            root,
            tokens.get(2).copied(),
            &[
                "categories",
                "list",
                "get",
                "upsert",
                "versions",
                "version",
                "activate",
            ],
        )),
        "observer" => Some(group_help_command(
            program,
            root,
            tokens.get(2).copied(),
            &[
                "queue",
                "vikingdb",
                "models",
                "transaction",
                "retrieval",
                "filesystem",
                "system",
            ],
        )),
        command if is_contextual_top_level_command(command) => {
            Some(format!("{program} {command} --help"))
        }
        _ => None,
    }
}

fn group_help_command(
    program: &str,
    root: &str,
    leaf: Option<&str>,
    known_leaves: &[&str],
) -> String {
    match leaf {
        Some(leaf) if known_leaves.contains(&leaf) => format!("{program} {root} {leaf} --help"),
        _ => format!("{program} {root} --help"),
    }
}

fn task_help_command(program: &str, tokens: &[&str]) -> String {
    match tokens.get(2).copied() {
        Some("watch") => match tokens.get(3).copied() {
            Some(leaf)
                if ["ls", "show", "rm", "pause", "resume", "update", "trigger"].contains(&leaf) =>
            {
                format!("{program} task watch {leaf} --help")
            }
            _ => format!("{program} task watch --help"),
        },
        Some("status" | "cancel" | "list") => format!("{program} task {} --help", tokens[2]),
        _ => format!("{program} task --help"),
    }
}

fn system_help_command(program: &str, tokens: &[&str]) -> String {
    match tokens.get(2).copied() {
        Some("crypto") => match tokens.get(3).copied() {
            Some("init-key") => format!("{program} system crypto init-key --help"),
            _ => format!("{program} system crypto --help"),
        },
        Some("wait" | "status" | "health" | "consistency") => {
            format!("{program} system {} --help", tokens[2])
        }
        _ => format!("{program} system --help"),
    }
}

fn is_contextual_top_level_command(command: &str) -> bool {
    matches!(
        command,
        "add-resource"
            | "add-skill"
            | "ls"
            | "tree"
            | "mkdir"
            | "rm"
            | "mv"
            | "stat"
            | "read"
            | "abstract"
            | "overview"
            | "write"
            | "get"
            | "find"
            | "search"
            | "grep"
            | "glob"
            | "add-memory"
            | "export"
            | "backup"
            | "import"
            | "restore"
            | "tui"
            | "chat"
            | "wait"
            | "status"
            | "health"
            | "reindex"
            | "language"
    )
}

fn api_error_message(code: &str, message: &str) -> String {
    if message.is_empty() {
        format!("[{code}] OpenViking returned an error")
    } else {
        format!("[{code}] {message}")
    }
}

pub(crate) fn render_report(report: &ErrorReport, verbose: bool) -> String {
    render_report_with_width(report, verbose, error_output_width())
}

fn render_report_with_width(report: &ErrorReport, verbose: bool, width: usize) -> String {
    let mut output = String::new();
    let language = Language::current();
    let try_command = try_command_for_report(report);

    if let Some(command) = report.command.as_deref() {
        if width >= CARD_WIDTH {
            output.push_str(&format!("{}\n\n", theme::strong(command)));
        } else {
            output.push_str(&format!(
                "{}\n\n",
                theme::strong(truncate_to_display_width(command, width))
            ));
        }
    }
    if let Some(usage) = report.usage.as_deref() {
        if width >= CARD_WIDTH {
            output.push_str(&format!(
                "{} {}\n",
                theme::warning(copy(language, "Usage:", "用法:")).bold(),
                theme::strong(usage)
            ));
            output.push_str(&format!(
                "{} {}\n\n",
                theme::muted(copy(language, "Try:", "可尝试:")),
                theme::command(&try_command)
            ));
        } else {
            output.push_str(&format!(
                "{}\n",
                theme::warning(truncate_to_display_width(
                    &format!("{} {usage}", copy(language, "Usage:", "用法:")),
                    width
                ))
                .bold()
            ));
            output.push_str(&format!(
                "{}\n\n",
                theme::muted(truncate_to_display_width(
                    &format!("{} {try_command}", copy(language, "Try:", "可尝试:")),
                    width
                ))
            ));
        }
    }

    output.push_str(&render_card(report, verbose, width));

    if !report.actions.is_empty() {
        output.push_str("\n\n");
        output.push_str(&format!(
            "{}\n",
            theme::strong(copy(language, "Next:", "下一步:"))
        ));
        let command_width = action_command_width(&report.actions, width);
        for action in &report.actions {
            output.push_str(&render_action_line(action, command_width, width));
            output.push('\n');
        }
    } else {
        output.push('\n');
    }

    output
}

trait OptionalUsage {
    fn with_optional_usage(self, usage: Option<String>) -> Self;
}

impl OptionalUsage for ErrorReport {
    fn with_optional_usage(self, usage: Option<String>) -> Self {
        if let Some(usage) = usage {
            self.with_usage(usage)
        } else {
            self
        }
    }
}

fn render_card(report: &ErrorReport, verbose: bool, width: usize) -> String {
    let language = Language::current();
    let inner_width = width.saturating_sub(4).max(1);
    let title = format!("─ {} ", report.title);
    let title = truncate_to_display_width(&title, width.saturating_sub(2));
    let fill = width.saturating_sub(2 + title.width());
    let mut lines = Vec::new();

    lines.extend(wrap_text(&report.message, inner_width));
    if let Some(suggestion) = report.suggestion.as_deref() {
        lines.push(String::new());
        lines.extend(wrap_text(&did_you_mean(language, suggestion), inner_width));
    }
    if verbose && let Some(detail) = report.detail.as_deref() {
        lines.push(String::new());
        lines.extend(wrap_text(&detail_line(language, detail), inner_width));
    }

    let mut rendered = String::new();
    rendered.push_str(&format!(
        "{}{}{}{}\n",
        theme::error("╭"),
        theme::error(title).bold(),
        theme::error("─".repeat(fill)),
        theme::error("╮")
    ));
    for line in lines {
        rendered.push_str(&render_card_line(&line, inner_width));
        rendered.push('\n');
    }
    rendered.push_str(&format!(
        "{}{}{}",
        theme::error("╰"),
        theme::error("─".repeat(width.saturating_sub(2))),
        theme::error("╯")
    ));
    rendered
}

#[cfg(not(test))]
fn error_output_width() -> usize {
    crossterm::terminal::size()
        .map(|(columns, _)| crate::terminal_ui::terminal_width(columns as usize, CARD_WIDTH))
        .unwrap_or(CARD_WIDTH)
}

#[cfg(test)]
fn error_output_width() -> usize {
    CARD_WIDTH
}

fn action_command_width(actions: &[ErrorAction], width: usize) -> usize {
    let available = width.saturating_sub(4);
    let preferred = actions
        .iter()
        .map(|action| action.command.width())
        .max()
        .unwrap_or_default();

    preferred.min(available / 2).max(1)
}

fn render_action_line(action: &ErrorAction, command_width: usize, width: usize) -> String {
    if width <= 4 {
        return truncate_to_display_width(&action.command, width);
    }

    let description_width = width.saturating_sub(command_width + 4);
    let command = fit_to_display_width(&action.command, command_width);
    let description = truncate_to_display_width(&action.description, description_width);

    format!(
        "  {}  {}",
        theme::command(command).bold(),
        theme::muted(description)
    )
}

fn did_you_mean(language: Language, suggestion: &str) -> String {
    match language {
        Language::En => format!("Did you mean: {suggestion}"),
        Language::ZhCn => format!("你是不是想运行:{suggestion}"),
    }
}

fn detail_line(language: Language, detail: &str) -> String {
    match language {
        Language::En => format!("Detail: {detail}"),
        Language::ZhCn => format!("详情:{detail}"),
    }
}

fn render_card_line(line: &str, inner_width: usize) -> String {
    let width = line.width();
    let padding = inner_width.saturating_sub(width);
    format!(
        "{} {}{} {}",
        theme::error("│"),
        theme::body(line),
        " ".repeat(padding),
        theme::error("│")
    )
}

fn wrap_text(text: &str, width: usize) -> Vec<String> {
    if text.is_empty() {
        return vec![String::new()];
    }

    let mut lines = Vec::new();
    let mut current = String::new();

    for word in text.split_whitespace() {
        if current.is_empty() && word.width() > width {
            lines.push(word.to_string());
            continue;
        }

        let separator = if current.is_empty() { 0 } else { 1 };
        if !current.is_empty() && current.width() + separator + word.width() > width {
            lines.push(current);
            current = String::new();
        }
        if !current.is_empty() {
            current.push(' ');
        }
        current.push_str(word);
    }

    if !current.is_empty() {
        lines.push(current);
    }
    lines
}

pub(crate) fn display_command(args: &[OsString]) -> String {
    let mut parts = vec!["ov".to_string()];
    parts.extend(
        args.iter()
            .skip(1)
            .map(|arg| arg.to_string_lossy().into_owned()),
    );
    parts.join(" ")
}

fn is_setup_cli_command(args: &[OsString]) -> bool {
    let parts = args
        .iter()
        .skip(1)
        .map(|arg| arg.to_string_lossy())
        .collect::<Vec<_>>();
    parts.as_slice() == ["config", "setup-cli"]
}

fn parse_usage(clap_output: &str) -> Option<String> {
    clap_output
        .lines()
        .find_map(|line| line.trim().strip_prefix("Usage: "))
        .map(ToString::to_string)
}

fn parse_unknown_subcommand(clap_output: &str) -> Option<String> {
    clap_output.lines().find_map(|line| {
        let trimmed = line.trim();
        if trimmed.starts_with("error: unrecognized subcommand ") {
            first_single_quoted(trimmed)
        } else {
            None
        }
    })
}

fn parse_clap_subcommand_suggestion(clap_output: &str) -> Option<String> {
    clap_output.lines().find_map(|line| {
        let trimmed = line.trim();
        if trimmed.contains("similar subcommand") {
            first_single_quoted(trimmed)
        } else {
            None
        }
    })
}

fn first_single_quoted(value: &str) -> Option<String> {
    let start = value.find('\'')?;
    let rest = &value[start + 1..];
    let end = rest.find('\'')?;
    Some(rest[..end].to_string())
}

fn qualified_suggestion(args: &[OsString], suggested_leaf: &str) -> String {
    let mut parts = args
        .iter()
        .skip(1)
        .map(|arg| arg.to_string_lossy().into_owned())
        .collect::<Vec<_>>();
    if parts.is_empty() {
        parts.push(suggested_leaf.to_string());
    } else if let Some(last) = parts.last_mut() {
        *last = suggested_leaf.to_string();
    }

    if parts.is_empty() {
        "ov".to_string()
    } else {
        format!("ov {}", parts.join(" "))
    }
}

fn first_error_line(clap_output: &str) -> String {
    if let Some(message) = required_arguments_message(clap_output) {
        return message;
    }
    if let Some(message) = unexpected_argument_message(clap_output) {
        return message;
    }

    let Some(raw) = clap_output
        .lines()
        .find_map(|line| line.trim().strip_prefix("error: "))
    else {
        return "Command could not be parsed.".to_string();
    };

    sentence_case_error(raw)
}

fn required_arguments_message(clap_output: &str) -> Option<String> {
    let mut lines = clap_output.lines().map(str::trim);
    while let Some(line) = lines.next() {
        if line != "error: the following required arguments were not provided:" {
            continue;
        }

        let arguments = lines
            .by_ref()
            .take_while(|line| !line.is_empty())
            .filter(|line| line.starts_with('<') || line.starts_with('['))
            .map(ToString::to_string)
            .collect::<Vec<_>>();
        return Some(match arguments.as_slice() {
            [] => "Required argument missing.".to_string(),
            [argument] => format!("Required argument missing: {argument}."),
            _ => format!("Required arguments missing: {}.", arguments.join(", ")),
        });
    }

    None
}

fn unexpected_argument_message(clap_output: &str) -> Option<String> {
    clap_output.lines().find_map(|line| {
        let error = line.trim().strip_prefix("error: ")?;
        if !error.starts_with("unexpected argument ") {
            return None;
        }
        first_single_quoted(error)
            .map(|argument| format!("Unexpected argument: {argument}."))
            .or_else(|| Some(sentence_case_error(error)))
    })
}

fn sentence_case_error(raw: &str) -> String {
    let raw = raw.trim().trim_end_matches(':').trim();
    if raw.is_empty() {
        return "Command could not be parsed.".to_string();
    }

    let mut chars = raw.chars();
    let Some(first) = chars.next() else {
        return "Command could not be parsed.".to_string();
    };
    let mut message = first.to_uppercase().collect::<String>();
    message.push_str(chars.as_str());
    if !matches!(message.chars().last(), Some('.' | '?' | '!')) {
        message.push('.');
    }
    message
}

fn try_command_for_report(report: &ErrorReport) -> String {
    report
        .usage
        .as_deref()
        .and_then(help_command_from_usage)
        .unwrap_or_else(|| "ov --help".to_string())
}

fn help_command_from_usage(usage: &str) -> Option<String> {
    let mut parts = Vec::new();
    for token in usage.split_whitespace() {
        if token.starts_with('<') || token.starts_with('[') || token == "..." {
            break;
        }
        parts.push(token);
    }
    let program = parts.first()?;
    if !program.starts_with("ov") {
        return None;
    }
    if parts.len() == 1 {
        Some(format!("{program} --help"))
    } else {
        Some(format!("{} --help", parts.join(" ")))
    }
}

#[cfg(test)]
mod tests {
    use super::{
        CARD_WIDTH, ErrorAction, ErrorReport, render_json_error, render_report,
        render_report_with_width, report_for_clap_error, report_for_runtime_error,
    };
    use crate::error::Error;
    use std::ffi::OsString;
    use unicode_width::UnicodeWidthStr;

    fn os_args(args: &[&str]) -> Vec<OsString> {
        args.iter().map(OsString::from).collect()
    }

    fn strip_ansi(input: &str) -> String {
        let mut output = String::new();
        let mut chars = input.chars().peekable();

        while let Some(ch) = chars.next() {
            if ch == '\u{1b}' && chars.peek() == Some(&'[') {
                chars.next();
                for next in chars.by_ref() {
                    if next.is_ascii_alphabetic() {
                        break;
                    }
                }
            } else {
                output.push(ch);
            }
        }

        output
    }

    #[test]
    fn command_typo_uses_clap_suggestion() {
        let clap_output = "\
error: unrecognized subcommand 'configure'

  tip: a similar subcommand exists: 'config'

Usage: ov [OPTIONS] <COMMAND>
";
        let report = report_for_clap_error(&os_args(&["ov", "configure"]), clap_output);
        let rendered = strip_ansi(&render_report(&report, false));

        assert!(rendered.contains("ov configure"));
        assert!(rendered.contains("Usage: ov [OPTIONS] <COMMAND>"));
        assert!(rendered.contains("Unknown command: configure"));
        assert!(rendered.contains("Did you mean: ov config"));
        assert!(rendered.contains("ov --help"));
    }

    #[test]
    fn required_argument_error_is_sentence_case_and_specific() {
        let clap_output = "\
error: the following required arguments were not provided:
  <TASK_ID>

Usage: ov task status <TASK_ID>
";
        let report = report_for_clap_error(&os_args(&["ov", "task", "status"]), clap_output);
        let rendered = strip_ansi(&render_report(&report, false));

        assert!(rendered.contains("Required argument missing: <TASK_ID>."));
        assert!(!rendered.contains("the following required arguments were not provided:"));
        assert!(rendered.contains("Try: ov task status --help"));
        assert!(rendered.contains("ov task status --help"));
    }

    #[test]
    fn preview_binary_usage_points_to_preview_help() {
        let clap_output = "\
error: the following required arguments were not provided:
  <TASK_ID>

Usage: ov-preview task status <TASK_ID>
";
        let report =
            report_for_clap_error(&os_args(&["ov-preview", "task", "status"]), clap_output);
        let rendered = strip_ansi(&render_report(&report, false));

        assert!(rendered.contains("Required argument missing: <TASK_ID>."));
        assert!(rendered.contains("Try: ov-preview task status --help"));
        assert!(rendered.contains("ov-preview task status --help"));
    }

    #[test]
    fn unexpected_argument_error_is_sentence_case_and_specific() {
        let clap_output = "\
error: unexpected argument '--bad' found

Usage: ov task status <TASK_ID>
";
        let report = report_for_clap_error(
            &os_args(&["ov", "task", "status", "abc", "--bad"]),
            clap_output,
        );
        let rendered = strip_ansi(&render_report(&report, false));

        assert!(rendered.contains("Unexpected argument: --bad."));
        assert!(!rendered.contains("unexpected argument '--bad' found"));
        assert!(rendered.contains("Try: ov task status --help"));
        assert!(rendered.contains("ov task status --help"));
    }

    #[test]
    fn removed_setup_cli_only_suggests_ov_config() {
        let clap_output = "\
error: unrecognized subcommand 'setup-cli'

Usage: ov config [OPTIONS] [COMMAND]
";
        let report = report_for_clap_error(&os_args(&["ov", "config", "setup-cli"]), clap_output);
        let rendered = strip_ansi(&render_report(&report, false));

        assert!(rendered.contains("ov config setup-cli"));
        assert!(rendered.contains("Did you mean: ov config"));
        assert!(rendered.contains("ov config"));
        assert!(rendered.contains("ov config show"));
        assert!(!rendered.contains("ov config setup-cli to initialize"));
        assert!(!rendered.contains("no longer available"));
        assert!(!rendered.contains("deprecated"));
    }

    #[test]
    fn structured_api_errors_are_not_reclassified_from_message_text() {
        let error = Error::api_response(
            Some("FAILED_PRECONDITION".to_string()),
            "Apply permission at https://open.feishu.cn/app/auth?token=abc",
            Some(serde_json::json!({"feishu_code": 99991672})),
            412,
        );

        let report = report_for_runtime_error("ov add-resource", &error);
        let rendered = strip_ansi(&render_report(&report, false));
        assert!(rendered.contains("OpenViking API Error"));
        assert!(rendered.contains("[FAILED_PRECONDITION]"));
        assert!(!rendered.contains("Authentication Error"));

        let json: serde_json::Value =
            serde_json::from_str(&render_json_error(&error, true)).unwrap();
        assert_eq!(json["error"]["code"], "FAILED_PRECONDITION");
        assert_eq!(json["error"]["details"]["feishu_code"], 99991672);
    }

    #[test]
    fn compile_refresh_failure_explains_safe_retry() {
        let command = "ov compile --from viking://resources/source --to viking://resources/wiki --skill viking://agent/skills/wiki";
        let error = Error::api_response(
            Some("REFRESH_FAILED".to_string()),
            "Content is already at the requested state, but semantic/index refresh failed: injected overview failure. Re-run the same batch-write or ov compile command; matching files will remain unchanged and refresh will be retried.",
            Some(serde_json::json!({"root_uri": "viking://resources/wiki"})),
            500,
        );
        let report = report_for_runtime_error(command, &error);
        let normal = strip_ansi(&render_report(&report, false));

        assert!(normal.contains("Compile Refresh Failed"));
        assert!(normal.contains("injected"));
        assert!(normal.contains("overview"));
        assert!(normal.contains("matching files"));
        assert!(normal.contains("unchanged"));
        assert!(normal.contains(command));
        assert!(!normal.contains("ov config validate"));
    }

    #[test]
    fn local_runtime_json_error_always_has_code() {
        let error = Error::Config("Failed to parse config file".to_string());
        let json: serde_json::Value =
            serde_json::from_str(&render_json_error(&error, true)).unwrap();

        assert_eq!(json["error"]["code"], "FAILED_PRECONDITION");
    }

    #[test]
    fn plain_help_error_points_to_prefixed_help() {
        let report = super::report_for_plain_help_error("ov config help", "ov config --help");
        let rendered = strip_ansi(&render_report(&report, false));

        assert!(rendered.contains("Command Error"));
        assert!(rendered.contains("Plain help is not supported"));
        assert!(rendered.contains("Did you mean: ov config --help"));
        assert!(rendered.contains("ov config --help"));
    }

    #[test]
    fn missing_config_error_points_to_config_creation() {
        let report = report_for_runtime_error("ov ls", &Error::MissingConfig);
        let rendered = strip_ansi(&render_report(&report, false));

        assert!(rendered.contains("Configuration Error"));
        assert!(rendered.contains("No ovcli.conf detected"));
        assert!(rendered.contains("Run ov config to create one"));
        assert!(rendered.contains("ov config"));
        assert!(rendered.contains("Create a config"));
        assert!(!rendered.contains("OpenViking API Error"));
        assert!(!rendered.contains("ov config validate"));
        assert!(!rendered.contains("ov status"));
    }

    #[test]
    fn network_error_suggests_validation_and_health_commands() {
        let error = Error::Network("HTTP request failed: connection refused".to_string());
        let report = report_for_runtime_error("ov status", &error);
        let rendered = strip_ansi(&render_report(&report, false));

        assert!(rendered.contains("Connection Error"));
        assert!(rendered.contains("Could not reach OpenViking"));
        assert!(rendered.contains("connection refused"));
        assert!(rendered.contains("ov config validate"));
        assert!(rendered.contains("ov health"));
        assert!(rendered.contains("ov config switch"));
    }

    #[test]
    fn network_error_card_shows_tls_cause_without_guessing_offline() {
        let error = Error::Network("invalid peer certificate: UnknownIssuer".to_string());
        let report = report_for_runtime_error("ov health", &error);
        let rendered = strip_ansi(&render_report(&report, false));
        let text = rendered
            .replace('│', " ")
            .split_whitespace()
            .collect::<Vec<_>>()
            .join(" ");

        assert!(
            text.contains("invalid peer certificate: UnknownIssuer"),
            "{rendered}"
        );
        assert!(!text.contains("offline"));
        assert!(!text.contains("wrong URL"));
    }

    #[test]
    fn language_error_points_to_language_commands() {
        let error = Error::Language("Unsupported language 'fr'. Use 'en' or 'zh-CN'.".to_string());
        let report = report_for_runtime_error("ov language fr", &error);
        let rendered = strip_ansi(&render_report(&report, false));

        assert!(rendered.contains("Language Error"));
        assert!(rendered.contains("Unsupported language 'fr'"));
        assert!(rendered.contains("ov language en"));
        assert!(rendered.contains("ov language zh-CN"));
        assert!(!rendered.contains("ov config"));
    }

    #[test]
    fn client_error_uses_command_specific_help_action() {
        let error = Error::Client("Specify exactly one of --content or --from-file.".to_string());
        let report = report_for_runtime_error("ov write viking://resources/a.md", &error);
        let rendered = strip_ansi(&render_report(&report, false));

        assert!(rendered.contains("Command Error"));
        assert!(rendered.contains("ov write --help"));
        assert!(!rendered.contains("ov --help  Show all commands"));
    }

    #[test]
    fn client_error_adds_terminal_punctuation() {
        let error = Error::Client("Specify exactly one of --content or --from-file".to_string());
        let report = report_for_runtime_error("ov write viking://resources/a.md", &error);
        let rendered = strip_ansi(&render_report(&report, false));

        assert!(rendered.contains("Specify exactly one of --content or --from-file."));
    }

    #[test]
    fn parse_error_uses_nested_command_specific_help_action() {
        let error = Error::Parse(
            "minutes must be > 0 (got 0). To pause a watch task, use `ov task watch pause`."
                .to_string(),
        );
        let report = report_for_runtime_error("ov task watch update demo --interval 0", &error);
        let rendered = strip_ansi(&render_report(&report, false));

        assert!(rendered.contains("Parse Error"));
        assert!(rendered.contains("Minutes must be > 0"));
        assert!(!rendered.contains("minutes must be > 0"));
        assert!(rendered.contains("ov task watch update --help"));
        assert!(!rendered.contains("ov --help  Show all commands"));
    }

    #[test]
    fn malformed_config_error_only_suggests_config_repair() {
        let error = Error::Config("Failed to parse config file: key must be a string".to_string());
        let report = report_for_runtime_error("ov ls", &error);
        let rendered = strip_ansi(&render_report(&report, false));

        assert!(rendered.contains("Configuration Error"));
        assert!(rendered.contains("Failed to parse config file"));
        assert!(rendered.contains("ov config"));
        assert!(rendered.contains("Repair or recreate the active config"));
        assert!(!rendered.contains("ov config show"));
    }

    #[test]
    fn chinese_error_card_uses_display_width_for_borders() {
        let report = ErrorReport::new("命令错误", "未知命令:con").with_suggestion("ov config");
        let rendered = strip_ansi(&render_report(&report, false));

        for line in rendered
            .lines()
            .filter(|line| line.starts_with('╭') || line.starts_with('│') || line.starts_with('╰'))
        {
            assert_eq!(line.width(), CARD_WIDTH, "{line}");
        }
    }

    #[test]
    fn error_report_respects_narrow_terminal_width() {
        let report = ErrorReport::new(
            "Command Error",
            "Plain help is not supported for this command. Use prefixed help instead.",
        )
        .with_command("ov very-long-command-name with many extra positional values")
        .with_usage("ov very-long-command-name --with-a-long-option <long-value>")
        .with_suggestion("ov --help")
        .with_actions(vec![ErrorAction::new(
            "ov --help",
            "Show this command's help",
        )]);
        let width = 32;
        let rendered = strip_ansi(&render_report_with_width(&report, false, width));

        for line in rendered.lines() {
            assert!(
                line.width() <= width,
                "line exceeded narrow width: {line:?}"
            );
        }
    }
}