blotter-cli 1.1.0

Append-only friction ledger for AI agents: log the cuts that got in the way and the findings worth writing up, find what recurs, promote it into durable fixes, and verify the fixes held.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127

use crate::error::AppError;
use serde::{Deserialize, Serialize};
use serde_json::Value;
use std::io::{self, Write};

pub const CONTRACT: u8 = 6;

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Meta {
    pub contract: u8,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub file: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub agent_source: Option<String>,
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub warnings: Vec<String>,
}

impl Meta {
    pub fn new() -> Self {
        Self::default()
    }
}

impl Default for Meta {
    fn default() -> Self {
        Self {
            contract: CONTRACT,
            file: None,
            agent_source: None,
            warnings: Vec::new(),
        }
    }
}

#[derive(Debug, Serialize, Deserialize)]
pub struct SuccessEnvelope<T> {
    pub ok: bool,
    pub data: T,
    pub meta: Meta,
}

#[derive(Debug, Serialize, Deserialize)]
pub struct ErrorEnvelope {
    pub ok: bool,
    pub error: ErrorBody,
    pub meta: Meta,
}

#[derive(Debug, Serialize, Deserialize)]
pub struct ErrorBody {
    pub code: String,
    pub message: String,
    pub details: Value,
    pub retryable: bool,
    pub suggested_fix: String,
}

#[cfg(unix)]
pub fn stdout_writer() -> io::Result<Box<dyn Write>> {
    use std::os::fd::AsFd;

    let stdout = io::stdout();
    let stdout = std::fs::File::from(stdout.as_fd().try_clone_to_owned()?);
    Ok(Box::new(io::BufWriter::new(stdout)))
}

#[cfg(windows)]
pub fn stdout_writer() -> io::Result<Box<dyn Write>> {
    use std::io::IsTerminal;
    use std::os::windows::io::AsHandle;

    let stdout = io::stdout();
    // An interactive console needs Rust's console-aware writer (UTF-8 →
    // WriteConsoleW); a raw duplicated handle goes through WriteFile and the
    // active code page, producing mojibake for non-ASCII text. The handle dup
    // is only for redirected stdout, where write errors must not be suppressed.
    if stdout.is_terminal() {
        return Ok(Box::new(io::BufWriter::new(stdout)));
    }
    let stdout = std::fs::File::from(stdout.as_handle().try_clone_to_owned()?);
    Ok(Box::new(io::BufWriter::new(stdout)))
}

#[cfg(not(any(unix, windows)))]
pub fn stdout_writer() -> io::Result<Box<dyn Write>> {
    Ok(Box::new(io::BufWriter::new(io::stdout())))
}

pub fn write_success<T: Serialize>(data: T, pretty: bool, meta: Meta) -> io::Result<()> {
    let envelope = SuccessEnvelope {
        ok: true,
        data,
        meta,
    };
    let mut output = stdout_writer()?;
    if pretty {
        serde_json::to_writer_pretty(&mut output, &envelope)?;
    } else {
        serde_json::to_writer(&mut output, &envelope)?;
    }
    writeln!(output)?;
    output.flush()
}

pub fn collapse_markdown_text(text: &str) -> String {
    text.split_whitespace().collect::<Vec<_>>().join(" ")
}

pub fn write_error(error: &AppError) -> i32 {
    let envelope = ErrorEnvelope {
        ok: false,
        error: ErrorBody {
            code: error.code.into(),
            message: error.message.clone(),
            details: error.details.clone(),
            retryable: error.retryable,
            suggested_fix: error.suggested_fix.clone(),
        },
        meta: Meta::new(),
    };
    let mut output = io::BufWriter::new(io::stderr().lock());
    // There is no way to report a failure to report a failure.
    let _ = serde_json::to_writer(&mut output, &envelope);
    let _ = writeln!(output);
    error.exit_code
}