frame_cli/error.rs
1//! Typed failures for every `frame` verb — each one loud, each one carrying
2//! its fix.
3
4use std::io;
5use std::net::SocketAddr;
6use std::path::PathBuf;
7use std::time::Duration;
8
9use thiserror::Error;
10
11use crate::doctor::MissingTools;
12use crate::scaffold::NewError;
13
14/// Typed refusal or failure from any `frame` verb.
15#[derive(Debug, Error)]
16pub enum CliError {
17 /// The dev loop refused to start or died with a typed report (F-7b).
18 #[error("frame dev: {detail}")]
19 Dev {
20 /// The typed failure, rendered.
21 detail: String,
22 },
23
24 /// Scaffold generation refused or failed.
25 #[error(transparent)]
26 New(#[from] NewError),
27
28 /// Initialising the new application's git repository failed (a git command
29 /// that ran refused — never a missing-git or already-in-a-repo condition,
30 /// which `frame new` reports and continues past).
31 #[error(transparent)]
32 Git(#[from] crate::scaffold::GitError),
33
34 /// A verb's prerequisite tools are missing (with install links).
35 #[error(transparent)]
36 MissingTools(#[from] MissingTools),
37
38 /// The real-browser proof has no browser to drive.
39 #[error("{reason}")]
40 MissingChrome {
41 /// The refusal, naming the probed path and the install link.
42 reason: String,
43 },
44
45 /// The verb was run outside a Frame application.
46 #[error(
47 "not inside a Frame application: no frame.toml in `{start}` or any parent directory; \
48 run this inside an application created by `frame new` (or create one: `frame new my_app`)"
49 )]
50 NotAnApplication {
51 /// Directory the search started from.
52 start: PathBuf,
53 },
54
55 /// The application's `frame.toml` failed to load or validate.
56 #[error("`{path}` is not a valid frame.toml")]
57 Config {
58 /// The config file that failed.
59 path: PathBuf,
60 /// The host's own typed load failure (boxed: the host error is
61 /// large, and `Result` should stay lean on the Ok path).
62 #[source]
63 source: Box<frame_host::HostError>,
64 },
65
66 /// `frame host` failed to boot or serve.
67 #[error("frame host failed")]
68 Host {
69 /// The host's own typed failure (boxed as above).
70 #[source]
71 source: Box<frame_host::HostError>,
72 },
73
74 /// A build or verification command exited unsuccessfully.
75 #[error("`{command}` failed with {status}; its output above names the failure")]
76 CommandFailed {
77 /// The command line that failed.
78 command: String,
79 /// Its exit status.
80 status: String,
81 },
82
83 /// A command could not be spawned at all (present prerequisites were
84 /// already checked, so this is an unexpected process failure, not a
85 /// missing tool).
86 #[error("`{command}` could not be started: {source}")]
87 CommandSpawn {
88 /// The command line that failed to start.
89 command: String,
90 /// The underlying process error.
91 #[source]
92 source: io::Error,
93 },
94
95 /// A named filesystem operation failed.
96 #[error("{operation} `{path}` failed: {source}")]
97 Io {
98 /// Operation that failed.
99 operation: &'static str,
100 /// File or directory involved.
101 path: PathBuf,
102 /// Underlying filesystem error.
103 #[source]
104 source: io::Error,
105 },
106
107 /// The current directory could not be read.
108 #[error("reading the current directory failed: {source}")]
109 CurrentDir {
110 /// Underlying filesystem error.
111 #[source]
112 source: io::Error,
113 },
114
115 /// The async runtime backing `frame run` could not be built.
116 #[error("starting frame's process supervisor failed: {source}")]
117 Runtime {
118 /// Underlying runtime construction error.
119 #[source]
120 source: io::Error,
121 },
122
123 /// An EXPLICITLY-stated frame.toml socket is already taken — named before
124 /// the host even tries to bind it, with the frame.toml key that holds it
125 /// and the coherence rule for changing it. Only stated addresses are
126 /// probed; a portless config (no `[frame].bind`, no `[bus]`) has nothing to
127 /// probe because the host prefers-and-walks / OS-assigns those ports.
128 #[error(
129 "cannot start the {role}: the port named by frame.toml `{key}` ({addr}) is unavailable \
130 ({source}). {coherence}"
131 )]
132 PortUnavailable {
133 /// Which socket role is blocked (page server / bus / bus health /
134 /// websocket).
135 role: &'static str,
136 /// The frame.toml key that holds this socket's address.
137 key: &'static str,
138 /// The address the host would have bound.
139 addr: SocketAddr,
140 /// The coherence rule to honour when moving this port.
141 coherence: &'static str,
142 /// The underlying bind failure (address-in-use, permission, …).
143 #[source]
144 source: io::Error,
145 },
146
147 /// The booted application never started accepting connections.
148 #[error(
149 "the application booted but `{bind}` never accepted a connection within {deadline:?}; \
150 its output above names what went wrong"
151 )]
152 NeverReady {
153 /// The configured page-server address.
154 bind: String,
155 /// How long frame waited.
156 deadline: Duration,
157 },
158
159 /// The application ignored a stop request past the teardown deadline.
160 #[error(
161 "the application did not exit within {deadline:?} of SIGTERM and was killed; \
162 this is a bug in the application's shutdown path"
163 )]
164 TeardownTimeout {
165 /// How long frame waited before killing it.
166 deadline: Duration,
167 },
168
169 /// One or more scopes of a multi-part verdict failed.
170 #[error("{verb}: FAIL ({})", failed.join(", "))]
171 VerdictFailed {
172 /// The verb whose verdict failed.
173 verb: &'static str,
174 /// The scopes that failed.
175 failed: Vec<String>,
176 },
177
178 /// The doctor found problems.
179 #[error(
180 "frame doctor found {problems} problem(s); each line above carries its fix and install link"
181 )]
182 DoctorProblems {
183 /// How many problems the walkthrough found.
184 problems: usize,
185 },
186}