Skip to main content

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}