topodb-cli 0.0.11

Command-line interface for the TopoDB agent-memory engine
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

//! JSON emit + exit-code helpers shared by every `topodb-cli` command.
//!
//! The contract (see the plan's Global Constraints): success is a JSON value
//! on stdout with exit 0; failure is `{"error":{"kind","message"}}` on stderr
//! with exit 3 for a lock contention error (`Busy`), exit 2 for a
//! rejected/bad-input condition (engine `Rejected`, scope parse failure, ...),
//! or exit 1 for an internal/storage/db-open failure. clap's own usage errors
//! (missing `--db`, unknown subcommand, ...) are left to clap, whose default
//! exit code is already 2 — callers never route those through `fail`.

use serde_json::Value;

/// Print `value` to stdout — compact JSON, or pretty-printed if `pretty` is
/// set — and exit 0. Never returns.
pub fn ok(value: &Value, pretty: bool) -> ! {
    let rendered = if pretty {
        serde_json::to_string_pretty(value)
    } else {
        serde_json::to_string(value)
    };
    match rendered {
        Ok(rendered) => {
            println!("{rendered}");
            std::process::exit(0);
        }
        // Unreachable in practice (a serde_json::Value always serializes),
        // but the no-panic-on-runtime-paths contract means even this goes
        // through fail() rather than expect()/unwrap().
        Err(e) => fail("internal", &format!("serializing output: {e}"), 1),
    }
}

/// Print `{"error":{"kind": kind, "message": message}}` to stderr and exit
/// `code`. Never returns. `code` is the caller's choice: 2 for a
/// rejected/bad-input condition, 1 for an internal/storage failure.
pub fn fail(kind: &str, message: &str, code: i32) -> ! {
    let body = serde_json::json!({ "error": { "kind": kind, "message": message } });
    eprintln!("{body}");
    std::process::exit(code);
}

/// Maps a `TopoError` to the right `(kind, exit-code)` pair and calls
/// [`fail`]: `Rejected` (bad input the caller can fix — an undeclared index,
/// an empty batch, a malformed query) is `("rejected", 2)`; `Busy` (lock
/// contention) is `("busy", 3)`; every other variant (`Storage`, `Encoding`,
/// `Compacted`, `Closed`, `UnsupportedFormat`) is `("internal", 1)` — the
/// caller can't fix those by changing their input.
pub fn fail_engine(e: &topodb::TopoError) -> ! {
    match e {
        topodb::TopoError::Rejected(_) => fail("rejected", &e.to_string(), 2),
        topodb::TopoError::Busy => fail("busy", &e.to_string(), 3),
        _ => fail("internal", &e.to_string(), 1),
    }
}

/// Emit either the text form (when `text_mode` and a text rendering exists)
/// or the JSON value. `text` is `None` for commands without a text renderer,
/// which fall back to JSON even in text mode. Never returns.
pub fn render(json: &Value, text: Option<String>, text_mode: bool, pretty: bool) -> ! {
    if text_mode {
        if let Some(t) = text {
            println!("{t}");
            std::process::exit(0);
        }
    }
    ok(json, pretty)
}

/// One-line stderr note disambiguating "empty result" from "wrong scope"
/// (fixes D1). Printed only for empty reads; stdout is untouched.
pub fn empty_scope_echo(scope: &str, source: &str) {
    eprintln!("topodb: 0 matches in scope {scope} (source: {source})");
}

/// One-line stderr note naming an applied created-time filter — the CLI
/// twin of the MCP result's `applied_time_filter`. Printed whenever a
/// filter ran, explicit or rewritten; stdout is untouched.
pub fn time_filter_echo(desc: &str, source: &str) {
    eprintln!("topodb: time filter: {desc} (source: {source})");
}