vta_cli_common/
render.rs

1use ratatui::{
2    buffer::{Buffer, CellDiffOption},
3    layout::Rect,
4    style::{Color, Modifier},
5    widgets::Widget,
6};
7use std::sync::OnceLock;
8use std::sync::atomic::{AtomicBool, AtomicU8, Ordering};
9
10// ── Bin-name registration ───────────────────────────────────────────
11//
12// pnm-cli and cnm-cli both consume this crate's shared command
13// handlers. When one of those handlers needs to point the operator at a
14// follow-up command (e.g. context-create → "did you mean to run X
15// instead?"), it must use the binary the operator actually invoked,
16// not a hard-coded `pnm`. Each CLI binary calls `set_bin_name("pnm")`
17// or `set_bin_name("cnm")` at startup; handlers read via `bin_name()`
18// and fall back to "vta" if neither was registered (the offline `vta
19// bootstrap …` path also calls into shared modules).
20
21static BIN_NAME: OnceLock<&'static str> = OnceLock::new();
22
23/// Register the binary name used in operator-facing hints. Call once at
24/// CLI startup. Only the first call sticks; later calls are ignored so
25/// that nested invocations (e.g. unit tests) don't clobber it.
26pub fn set_bin_name(name: &'static str) {
27    let _ = BIN_NAME.set(name);
28}
29
30/// The binary name registered via [`set_bin_name`]. Defaults to `"vta"`
31/// (the offline binary's name) when nothing has been registered, so
32/// shared handlers still produce a syntactically valid command string.
33pub fn bin_name() -> &'static str {
34    BIN_NAME.get().copied().unwrap_or("vta")
35}
36
37// ── Full-display toggle ─────────────────────────────────────────────
38//
39// CLI global `--full-display` flag. When enabled, list commands emit
40// every identifier in full (no ratatui-Table truncation) as a sequence
41// of key-value blocks. Default rendering stays as the compact table
42// for a readable overview; full display is the escape hatch for
43// copying complete DIDs, key ids, template names, etc.
44
45static FULL_DISPLAY: AtomicBool = AtomicBool::new(false);
46
47/// Enable or disable full-display output. Called once at CLI startup
48/// from the global flag.
49pub fn set_full_display(enabled: bool) {
50    FULL_DISPLAY.store(enabled, Ordering::Relaxed);
51}
52
53/// Current full-display mode. List commands check this to choose
54/// between table and full-form output.
55pub fn is_full_display() -> bool {
56    FULL_DISPLAY.load(Ordering::Relaxed)
57}
58
59/// Emit a list entry as aligned `label: value` lines. Used in
60/// full-display mode where ratatui-Table truncation would hide full
61/// identifiers.
62///
63/// `pairs` is `[(label, value)]`. Labels are padded to the widest so
64/// values line up vertically. A trailing blank line separates entries.
65pub fn print_full_entry(pairs: &[(&str, &str)]) {
66    let widest = pairs.iter().map(|(l, _)| l.len()).max().unwrap_or(0);
67    for (label, value) in pairs {
68        let pad = " ".repeat(widest.saturating_sub(label.len()));
69        println!("  {label}:{pad}  {DIM}{value}{RESET}");
70    }
71    println!();
72}
73
74/// Print a bold section heading used above a list of full-display
75/// entries. Matches the title style of the table-mode block borders.
76pub fn print_full_list_title(title: &str, count: usize) {
77    println!();
78    println!("{BOLD}{title} ({count}){RESET}");
79    println!();
80}
81
82// ── Output format ───────────────────────────────────────────────────
83//
84// Global `--json` flag. When enabled, list commands emit a single JSON
85// document instead of the ratatui table / full-display rendering. This
86// is the automation entry point — scripts piping `pnm acl list --json`
87// into `jq` get a stable shape, while interactive operators get the
88// human-readable default.
89
90/// Output format selected by the operator.
91#[derive(Debug, Clone, Copy, PartialEq, Eq)]
92pub enum OutputFormat {
93    Human,
94    Json,
95}
96
97static OUTPUT_FORMAT: AtomicU8 = AtomicU8::new(0); // 0 = Human, 1 = Json
98
99/// Register the output format. Called once at CLI startup from the
100/// global `--json` flag.
101pub fn set_output_format(format: OutputFormat) {
102    OUTPUT_FORMAT.store(
103        match format {
104            OutputFormat::Human => 0,
105            OutputFormat::Json => 1,
106        },
107        Ordering::Relaxed,
108    );
109}
110
111/// Current output format. Default `Human`.
112pub fn output_format() -> OutputFormat {
113    if OUTPUT_FORMAT.load(Ordering::Relaxed) == 1 {
114        OutputFormat::Json
115    } else {
116        OutputFormat::Human
117    }
118}
119
120/// Returns true when the operator passed `--json`. List commands check
121/// this and dispatch to a JSON serializer instead of their human-
122/// readable renderer.
123#[must_use]
124pub fn is_json_output() -> bool {
125    output_format() == OutputFormat::Json
126}
127
128/// Pretty-print a serializable value as JSON to stdout. Used by list
129/// commands when [`is_json_output`] is true. Errors here are surfaced
130/// as a CLI error rather than a panic so the caller can render via
131/// `print_cli_error`.
132pub fn print_json<T: serde::Serialize>(value: &T) -> Result<(), serde_json::Error> {
133    let text = serde_json::to_string_pretty(value)?;
134    println!("{text}");
135    Ok(())
136}
137
138// ── ANSI constants ──────────────────────────────────────────────────
139
140pub const BOLD: &str = "\x1b[1m";
141pub const DIM: &str = "\x1b[2m";
142pub const GREEN: &str = "\x1b[32m";
143pub const RED: &str = "\x1b[31m";
144pub const CYAN: &str = "\x1b[36m";
145pub const YELLOW: &str = "\x1b[33m";
146pub const RESET: &str = "\x1b[0m";
147
148// ── Error reporting ─────────────────────────────────────────────────
149
150/// Print a CLI error to stderr in a form an operator can act on.
151///
152/// Downcasts to [`vta_sdk::error::VtaError`] when possible and emits a
153/// tailored remediation hint for the common failure modes (auth, network,
154/// forbidden, validation). Falls back to the raw error message + source
155/// chain for anything else, so unknown failures still get their underlying
156/// cause surfaced.
157///
158/// Call this from the top-level CLI match instead of `eprintln!("Error:
159/// {e}")` — the raw form loses auth/network context that operators need
160/// to fix things themselves.
161pub fn print_cli_error(err: &(dyn std::error::Error + 'static)) {
162    use vta_sdk::error::VtaError;
163    if let Some(vta_err) = err.downcast_ref::<VtaError>() {
164        match vta_err {
165            VtaError::Auth(msg) => {
166                eprintln!("{RED}\u{2717}{RESET} Authentication failed: {msg}");
167                eprintln!(
168                    "  {DIM}Token may be expired. Try `pnm setup` to re-authenticate, or check \
169                     that the VTA's `/auth` endpoint is reachable.{RESET}"
170                );
171            }
172            VtaError::Forbidden(msg) => {
173                eprintln!("{RED}\u{2717}{RESET} Forbidden: {msg}");
174                eprintln!(
175                    "  {DIM}Your role or context access doesn't permit this operation. \
176                     Inspect with `pnm acl get <your-did>`.{RESET}"
177                );
178            }
179            VtaError::NotFound(msg) => {
180                eprintln!("{RED}\u{2717}{RESET} Not found: {msg}");
181            }
182            VtaError::Conflict(msg) => {
183                // The SDK preserves the full 409 JSON body so programmatic
184                // callers can extract structured fields (e.g. `mediator_did`).
185                // For humans, surface the `message` (or `error`) field rather
186                // than dumping the raw JSON; fall back to the raw text for
187                // non-JSON bodies.
188                eprintln!(
189                    "{RED}\u{2717}{RESET} Conflict: {}",
190                    extract_human_message(msg)
191                );
192            }
193            VtaError::Gone(msg) => {
194                let bin = bin_name();
195                eprintln!("{RED}\u{2717}{RESET} Resource is gone: {msg}");
196                eprintln!(
197                    "  {DIM}This usually means the bootstrap carve-out has already been used. \
198                     For a second admin, run `{bin} bootstrap provision-request` from the new \
199                     operator's host and have an existing admin run \
200                     `{bin} bootstrap provision-integration` against this VTA.{RESET}"
201                );
202            }
203            VtaError::Validation(msg) => {
204                eprintln!("{RED}\u{2717}{RESET} Invalid request: {msg}");
205            }
206            VtaError::Network(e) => {
207                eprintln!("{RED}\u{2717}{RESET} Network error: {e}");
208                eprintln!("  {DIM}Is the VTA reachable? Check its URL with `pnm vta info`.{RESET}");
209            }
210            VtaError::Server { status, body } => {
211                eprintln!("{RED}\u{2717}{RESET} Server error (HTTP {status}): {body}");
212                eprintln!(
213                    "  {DIM}This is a VTA-side failure. Check server logs or contact the operator.{RESET}"
214                );
215            }
216            VtaError::UnsupportedTransport(msg) => {
217                eprintln!("{RED}\u{2717}{RESET} Unsupported transport: {msg}");
218                eprintln!(
219                    "  {DIM}This operation requires a specific transport (REST or DIDComm). \
220                     Check which mode your CLI is in and whether the endpoint supports it.{RESET}"
221                );
222            }
223            VtaError::DidcommTransport(msg) => {
224                eprintln!("{RED}\u{2717}{RESET} DIDComm transport error: {msg}");
225                eprintln!(
226                    "  {DIM}Mediator or peer unreachable. Retry after checking mediator \
227                     connectivity.{RESET}"
228                );
229            }
230            VtaError::DidcommRemote { code, comment } => {
231                eprintln!("{RED}\u{2717}{RESET} Remote error ({code}): {comment}");
232            }
233            VtaError::Protocol(msg) => {
234                eprintln!("{RED}\u{2717}{RESET} Protocol error: {msg}");
235            }
236            // ── Runtime service-management variants (T0.2) ────────
237            VtaError::LastServiceRefused => {
238                let bin = bin_name();
239                eprintln!(
240                    "{RED}\u{2717}{RESET} Refused: would leave the VTA with no advertised services."
241                );
242                eprintln!(
243                    "  {DIM}At least one transport (REST or DIDComm) must remain advertised. \
244                     Enable the other transport first via `{bin} services <kind> enable …`, \
245                     then retry.{RESET}"
246                );
247            }
248            VtaError::ServiceNotPresent => {
249                let bin = bin_name();
250                eprintln!("{RED}\u{2717}{RESET} Service is not present.");
251                eprintln!(
252                    "  {DIM}The service kind isn't currently enabled. Use `{bin} services \
253                     <kind> enable …` to bring it online before updating, disabling, or rolling \
254                     it back.{RESET}"
255                );
256            }
257            VtaError::ServiceAlreadyEnabled => {
258                let bin = bin_name();
259                eprintln!("{RED}\u{2717}{RESET} Service is already enabled.");
260                eprintln!(
261                    "  {DIM}Use `{bin} services <kind> update …` to change its configuration, \
262                     or `{bin} services <kind> disable` to remove it.{RESET}"
263                );
264            }
265            VtaError::MediatorHandshakeFailed { reason } => {
266                eprintln!("{RED}\u{2717}{RESET} Mediator handshake failed: {reason}");
267                eprintln!(
268                    "  {DIM}Confirm the mediator DID is correct and the mediator is reachable. \
269                     The reason above is the specific cause from the handshake protocol.{RESET}"
270                );
271            }
272            VtaError::DrainTtlOutOfBounds {
273                min,
274                max,
275                requested,
276            } => {
277                eprintln!(
278                    "{RED}\u{2717}{RESET} Drain TTL {requested}s is outside the allowed range \
279                     [{min}s, {max}s]."
280                );
281                eprintln!(
282                    "  {DIM}Pick a value within those bounds. The minimum applies when the \
283                     command is delivered over DIDComm transport (so the listener stays up long \
284                     enough for the response).{RESET}"
285                );
286            }
287            VtaError::NoPriorMutation => {
288                let bin = bin_name();
289                eprintln!("{RED}\u{2717}{RESET} No prior mutation to roll back.");
290                eprintln!(
291                    "  {DIM}Use `{bin} services <kind> {{enable,update,disable}} …` directly \
292                     instead of rollback.{RESET}"
293                );
294            }
295            other => eprintln!("{RED}\u{2717}{RESET} Error: {other}"),
296        }
297        return;
298    }
299    eprintln!("{RED}\u{2717}{RESET} Error: {err}");
300    let mut source = err.source();
301    while let Some(s) = source {
302        eprintln!("  {DIM}caused by: {s}{RESET}");
303        source = s.source();
304    }
305}
306
307/// Pull a human-readable line out of a (possibly JSON) error body.
308///
309/// The SDK hands `VtaError::Conflict` the *raw* 409 response body so that
310/// programmatic callers can deserialize structured fields. For terminal
311/// output we don't want to dump JSON at the operator, so prefer the body's
312/// `message` field, then its `error` field, and only fall back to the raw
313/// text when the body isn't the expected JSON shape.
314fn extract_human_message(body: &str) -> String {
315    serde_json::from_str::<serde_json::Value>(body)
316        .ok()
317        .and_then(|v| {
318            v.get("message")
319                .or_else(|| v.get("error"))
320                .and_then(|m| m.as_str())
321                .map(str::to_string)
322        })
323        .unwrap_or_else(|| body.to_string())
324}
325
326// ── Ratatui rendering helpers ───────────────────────────────────────
327
328pub fn print_widget(widget: impl Widget, height: u16) {
329    let width = ratatui::crossterm::terminal::size().map_or(120, |(w, _)| w);
330    let area = Rect::new(0, 0, width, height);
331    let mut buf = Buffer::empty(area);
332    widget.render(area, &mut buf);
333
334    let mut out = String::new();
335    for y in 0..height {
336        let mut cur_fg = Color::Reset;
337        let mut cur_bg = Color::Reset;
338        let mut cur_mod = Modifier::empty();
339
340        for x in 0..width {
341            let cell = &buf[(x, y)];
342            if cell.diff_option == CellDiffOption::Skip {
343                continue;
344            }
345
346            if cell.fg != cur_fg || cell.bg != cur_bg || cell.modifier != cur_mod {
347                out.push_str("\x1b[0m");
348                push_ansi_fg(&mut out, cell.fg);
349                push_ansi_bg(&mut out, cell.bg);
350                push_ansi_mod(&mut out, cell.modifier);
351                cur_fg = cell.fg;
352                cur_bg = cell.bg;
353                cur_mod = cell.modifier;
354            }
355
356            out.push_str(cell.symbol());
357        }
358        out.push_str("\x1b[0m\n");
359    }
360
361    print!("{out}");
362}
363
364pub fn push_ansi_fg(out: &mut String, color: Color) {
365    use std::fmt::Write as _;
366    match color {
367        Color::Reset => {}
368        Color::Black => out.push_str("\x1b[30m"),
369        Color::Red => out.push_str("\x1b[31m"),
370        Color::Green => out.push_str("\x1b[32m"),
371        Color::Yellow => out.push_str("\x1b[33m"),
372        Color::Blue => out.push_str("\x1b[34m"),
373        Color::Magenta => out.push_str("\x1b[35m"),
374        Color::Cyan => out.push_str("\x1b[36m"),
375        Color::Gray => out.push_str("\x1b[37m"),
376        Color::DarkGray => out.push_str("\x1b[90m"),
377        Color::LightRed => out.push_str("\x1b[91m"),
378        Color::LightGreen => out.push_str("\x1b[92m"),
379        Color::LightYellow => out.push_str("\x1b[93m"),
380        Color::LightBlue => out.push_str("\x1b[94m"),
381        Color::LightMagenta => out.push_str("\x1b[95m"),
382        Color::LightCyan => out.push_str("\x1b[96m"),
383        Color::White => out.push_str("\x1b[97m"),
384        Color::Rgb(r, g, b) => {
385            let _ = write!(out, "\x1b[38;2;{r};{g};{b}m");
386        }
387        Color::Indexed(i) => {
388            let _ = write!(out, "\x1b[38;5;{i}m");
389        }
390    }
391}
392
393pub fn push_ansi_bg(out: &mut String, color: Color) {
394    use std::fmt::Write as _;
395    match color {
396        Color::Reset => {}
397        Color::Black => out.push_str("\x1b[40m"),
398        Color::Red => out.push_str("\x1b[41m"),
399        Color::Green => out.push_str("\x1b[42m"),
400        Color::Yellow => out.push_str("\x1b[43m"),
401        Color::Blue => out.push_str("\x1b[44m"),
402        Color::Magenta => out.push_str("\x1b[45m"),
403        Color::Cyan => out.push_str("\x1b[46m"),
404        Color::Gray => out.push_str("\x1b[47m"),
405        Color::DarkGray => out.push_str("\x1b[100m"),
406        Color::LightRed => out.push_str("\x1b[101m"),
407        Color::LightGreen => out.push_str("\x1b[102m"),
408        Color::LightYellow => out.push_str("\x1b[103m"),
409        Color::LightBlue => out.push_str("\x1b[104m"),
410        Color::LightMagenta => out.push_str("\x1b[105m"),
411        Color::LightCyan => out.push_str("\x1b[106m"),
412        Color::White => out.push_str("\x1b[107m"),
413        Color::Rgb(r, g, b) => {
414            let _ = write!(out, "\x1b[48;2;{r};{g};{b}m");
415        }
416        Color::Indexed(i) => {
417            let _ = write!(out, "\x1b[48;5;{i}m");
418        }
419    }
420}
421
422pub fn push_ansi_mod(out: &mut String, modifier: Modifier) {
423    if modifier.contains(Modifier::BOLD) {
424        out.push_str("\x1b[1m");
425    }
426    if modifier.contains(Modifier::DIM) {
427        out.push_str("\x1b[2m");
428    }
429    if modifier.contains(Modifier::ITALIC) {
430        out.push_str("\x1b[3m");
431    }
432    if modifier.contains(Modifier::UNDERLINED) {
433        out.push_str("\x1b[4m");
434    }
435    if modifier.contains(Modifier::REVERSED) {
436        out.push_str("\x1b[7m");
437    }
438    if modifier.contains(Modifier::CROSSED_OUT) {
439        out.push_str("\x1b[9m");
440    }
441}
442
443pub fn print_section(title: &str) {
444    let pad = 46usize.saturating_sub(title.len());
445    println!(
446        "\n{DIM}──{RESET} {BOLD}{title}{RESET} {DIM}{}{RESET}",
447        "─".repeat(pad)
448    );
449}
450
451#[cfg(test)]
452mod tests {
453    use super::extract_human_message;
454
455    #[test]
456    fn prefers_message_field() {
457        let body = r#"{"error":"didcomm_already_enabled","message":"DIDComm is already enabled.","mediator_did":"did:peer:2.med"}"#;
458        assert_eq!(extract_human_message(body), "DIDComm is already enabled.");
459    }
460
461    #[test]
462    fn falls_back_to_error_field_when_no_message() {
463        let body = r#"{"error":"duplicate_key"}"#;
464        assert_eq!(extract_human_message(body), "duplicate_key");
465    }
466
467    #[test]
468    fn falls_back_to_raw_text_for_non_json() {
469        let body = "plain conflict text";
470        assert_eq!(extract_human_message(body), "plain conflict text");
471    }
472
473    #[test]
474    fn falls_back_to_raw_text_when_fields_missing() {
475        // Valid JSON but neither `message` nor `error` present → raw text.
476        let body = r#"{"detail":"something"}"#;
477        assert_eq!(extract_human_message(body), body);
478    }
479}
vta_cli_common/render.rs

vta_cli_common/
render.rs
