openreadout_core/envelope.rs
1//! The JSON envelope every command emits with `--json`.
2//!
3//! ```json
4//! {"ok":true,"schema_version":"2","tool":{"name":"openreadout","version":"0.1.0"},"data":{...}}
5//! {"ok":false,"schema_version":"2","tool":{...},"error":{"code":"corrupt_file","message":"...","hint":"...","exit_code":4}}
6//! ```
7
8use schemars::JsonSchema;
9use serde::{Deserialize, Serialize};
10
11use crate::Error;
12
13/// Bumped only when the shape of existing fields changes. Adding fields is not a bump.
14pub const SCHEMA_VERSION: &str = "2";
15
16/// Identifies the producing tool so consumers can reason about compatibility.
17#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
18pub struct ToolId {
19 /// Always `openreadout`.
20 pub name: String,
21 /// The tool's version (`CARGO_PKG_VERSION`).
22 pub version: String,
23}
24
25/// Structured error body. `hint` is meant to be actionable by an agent.
26#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
27pub struct ErrorBody {
28 /// Stable code: `unknown_format`, `unsupported_feature`, `corrupt_file`, `usage`, `io`, `error`,
29 /// `internal_panic` (a bug: the tool panicked; please report it).
30 pub code: String,
31 /// Human-readable description of the failure.
32 pub message: String,
33 /// What to try next, when the tool knows.
34 #[serde(skip_serializing_if = "Option::is_none")]
35 pub hint: Option<String>,
36 /// The process exit code for this error (see the crate docs).
37 pub exit_code: i32,
38}
39
40impl From<&Error> for ErrorBody {
41 fn from(e: &Error) -> Self {
42 ErrorBody {
43 code: e.code().to_string(),
44 message: e.to_string(),
45 hint: e.hint(),
46 exit_code: e.exit_code(),
47 }
48 }
49}
50
51/// Success or failure wrapper.
52#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
53pub struct Envelope<T> {
54 /// True on success (`data` present), false on failure (`error` present).
55 pub ok: bool,
56 /// [`SCHEMA_VERSION`] at the time of writing.
57 pub schema_version: String,
58 /// The producing tool.
59 pub tool: ToolId,
60 /// The input this envelope answers for, in batch mode (`--jsonl`, JSON arrays, MCP
61 /// `openreadout_batch`); absent for single-file commands.
62 #[serde(default, skip_serializing_if = "Option::is_none")]
63 pub path: Option<String>,
64 /// The command's output, on success.
65 #[serde(skip_serializing_if = "Option::is_none")]
66 pub data: Option<T>,
67 /// What went wrong, on failure.
68 #[serde(skip_serializing_if = "Option::is_none")]
69 pub error: Option<ErrorBody>,
70}
71
72impl<T> Envelope<T> {
73 /// A success envelope carrying `data`.
74 pub fn ok(tool: ToolId, data: T) -> Self {
75 Envelope {
76 ok: true,
77 schema_version: SCHEMA_VERSION.into(),
78 tool,
79 path: None,
80 data: Some(data),
81 error: None,
82 }
83 }
84 /// A failure envelope describing `e`.
85 pub fn err(tool: ToolId, e: &Error) -> Self {
86 Envelope {
87 ok: false,
88 schema_version: SCHEMA_VERSION.into(),
89 tool,
90 path: None,
91 data: None,
92 error: Some(e.into()),
93 }
94 }
95 /// Tag the envelope with the input path (batch mode).
96 pub fn with_path(mut self, path: impl Into<String>) -> Self {
97 self.path = Some(path.into());
98 self
99 }
100}