browser_automation_cli/
error.rs

1//! Typed CLI errors with sysexits-style exit codes.
2//!
3//! # Error kinds
4//!
5//! `ErrorKind` maps to process exit codes used by the binary and JSON envelopes.
6//!
7//! # Examples
8//!
9//! ```
10//! use browser_automation_cli::error::{CliError, ErrorKind};
11//!
12//! let err = CliError::with_suggestion(
13//!     ErrorKind::Unavailable,
14//!     "chrome not found",
15//!     "install Chromium or Google Chrome",
16//! );
17//! assert_eq!(err.exit_code(), 69);
18//! assert_eq!(err.kind().as_str(), "unavailable");
19//! ```
20
21use std::fmt;
22
23/// High-level failure category mapped to a process exit code.
24#[derive(Debug, Clone, Copy, PartialEq, Eq)]
25pub enum ErrorKind {
26    /// Invalid usage or clap parse failure (`2`).
27    Usage,
28    /// Invalid data or payload (`65`).
29    Data,
30    /// Required input missing (`66`).
31    NoInput,
32    /// Browser or dependency unavailable (`69`).
33    Unavailable,
34    /// Internal software failure (`70`).
35    Software,
36    /// Browser runtime failure (`70`).
37    Browser,
38    /// CDP/protocol failure (`70`).
39    Protocol,
40    /// Wall-clock timeout (`124`).
41    Timeout,
42    /// Cancelled by signal (`130`).
43    Cancelled,
44    /// Broken pipe on stdout (`141`).
45    BrokenPipe,
46    /// Configuration error (`78`).
47    Config,
48    /// I/O failure (`74`).
49    Io,
50}
51
52impl ErrorKind {
53    /// Process exit code for this kind.
54    pub fn exit_code(self) -> u8 {
55        match self {
56            ErrorKind::Usage => 2,
57            ErrorKind::Data => 65,
58            ErrorKind::NoInput => 66,
59            ErrorKind::Unavailable => 69,
60            ErrorKind::Software | ErrorKind::Browser | ErrorKind::Protocol => 70,
61            ErrorKind::Config => 78,
62            ErrorKind::Io => 74,
63            ErrorKind::Timeout => 124,
64            ErrorKind::Cancelled => 130,
65            ErrorKind::BrokenPipe => 141,
66        }
67    }
68
69    /// Stable machine-readable kind string for JSON envelopes.
70    pub fn as_str(self) -> &'static str {
71        match self {
72            ErrorKind::Usage => "usage",
73            ErrorKind::Data => "data",
74            ErrorKind::NoInput => "no-input",
75            ErrorKind::Unavailable => "unavailable",
76            ErrorKind::Software => "software",
77            ErrorKind::Browser => "browser",
78            ErrorKind::Protocol => "protocol",
79            ErrorKind::Timeout => "timeout",
80            ErrorKind::Cancelled => "cancelled",
81            ErrorKind::BrokenPipe => "broken-pipe",
82            ErrorKind::Config => "config",
83            ErrorKind::Io => "io",
84        }
85    }
86}
87
88/// Typed CLI error with optional remediation hint.
89#[derive(Debug, Clone)]
90pub struct CliError {
91    kind: ErrorKind,
92    message: String,
93    suggestion: Option<String>,
94}
95
96impl CliError {
97    /// Create an error without a suggestion.
98    pub fn new(kind: ErrorKind, message: impl Into<String>) -> Self {
99        Self {
100            kind,
101            message: message.into(),
102            suggestion: None,
103        }
104    }
105
106    /// Create an error with a short remediation suggestion for agents.
107    pub fn with_suggestion(
108        kind: ErrorKind,
109        message: impl Into<String>,
110        suggestion: impl Into<String>,
111    ) -> Self {
112        Self {
113            kind,
114            message: message.into(),
115            suggestion: Some(suggestion.into()),
116        }
117    }
118
119    /// Error category.
120    pub fn kind(&self) -> ErrorKind {
121        self.kind
122    }
123
124    /// Human-readable message (also used in JSON `error.message`).
125    pub fn message(&self) -> &str {
126        &self.message
127    }
128
129    /// Optional remediation hint.
130    pub fn suggestion(&self) -> Option<&str> {
131        self.suggestion.as_deref()
132    }
133
134    /// Process exit code for this error.
135    pub fn exit_code(&self) -> u8 {
136        self.kind.exit_code()
137    }
138}
139
140impl fmt::Display for CliError {
141    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
142        write!(f, "{}", self.message)
143    }
144}
145
146impl std::error::Error for CliError {}
browser_automation_cli/error.rs

browser_automation_cli/
error.rs
