Skip to main content

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}