sqlite_graphrag/commands/
read.rs

1use crate::errors::AppError;
2use crate::i18n::erros;
3use crate::output;
4use crate::paths::AppPaths;
5use crate::storage::connection::open_ro;
6use crate::storage::memories;
7use serde::Serialize;
8
9#[derive(clap::Args)]
10pub struct ReadArgs {
11    #[arg(long)]
12    pub name: String,
13    #[arg(long, default_value = "global")]
14    pub namespace: Option<String>,
15    #[arg(long, hide = true, help = "No-op; JSON is always emitted on stdout")]
16    pub json: bool,
17    #[arg(long, env = "SQLITE_GRAPHRAG_DB_PATH")]
18    pub db: Option<String>,
19}
20
21#[derive(Serialize)]
22struct ReadResponse {
23    /// Campo canônico do storage. Preservado para compatibilidade com clientes v2.0.0.
24    id: i64,
25    /// Alias semântico de `id` para contrato documentado em SKILL.md e AGENT_PROTOCOL.md.
26    memory_id: i64,
27    namespace: String,
28    name: String,
29    /// Alias semântico de `memory_type` para contrato documentado.
30    #[serde(rename = "type")]
31    type_alias: String,
32    memory_type: String,
33    description: String,
34    body: String,
35    body_hash: String,
36    session_id: Option<String>,
37    source: String,
38    metadata: String,
39    /// Versão mais recente da memória, útil para controle otimista via `--expected-updated-at`.
40    version: i64,
41    created_at: i64,
42    /// Timestamp RFC 3339 UTC paralelo a `created_at` para parsers ISO 8601.
43    created_at_iso: String,
44    updated_at: i64,
45    /// Timestamp RFC 3339 UTC paralelo a `updated_at` para parsers ISO 8601.
46    updated_at_iso: String,
47    /// Tempo total de execução em milissegundos desde início do handler até serialização.
48    elapsed_ms: u64,
49}
50
51fn epoch_to_iso(epoch: i64) -> String {
52    crate::tz::epoch_para_iso(epoch)
53}
54
55pub fn run(args: ReadArgs) -> Result<(), AppError> {
56    let inicio = std::time::Instant::now();
57    let namespace = crate::namespace::resolve_namespace(args.namespace.as_deref())?;
58    let paths = AppPaths::resolve(args.db.as_deref())?;
59    let conn = open_ro(&paths.db)?;
60
61    match memories::read_by_name(&conn, &namespace, &args.name)? {
62        Some(row) => {
63            // Resolver versão atual via tabela memory_versions (maior version para este memory_id).
64            let version: i64 = conn
65                .query_row(
66                    "SELECT COALESCE(MAX(version), 1) FROM memory_versions WHERE memory_id=?1",
67                    rusqlite::params![row.id],
68                    |r| r.get(0),
69                )
70                .unwrap_or(1);
71
72            let response = ReadResponse {
73                id: row.id,
74                memory_id: row.id,
75                namespace: row.namespace,
76                name: row.name,
77                type_alias: row.memory_type.clone(),
78                memory_type: row.memory_type,
79                description: row.description,
80                body: row.body,
81                body_hash: row.body_hash,
82                session_id: row.session_id,
83                source: row.source,
84                metadata: row.metadata,
85                version,
86                created_at: row.created_at,
87                created_at_iso: epoch_to_iso(row.created_at),
88                updated_at: row.updated_at,
89                updated_at_iso: epoch_to_iso(row.updated_at),
90                elapsed_ms: inicio.elapsed().as_millis() as u64,
91            };
92            output::emit_json(&response)?;
93        }
94        None => {
95            return Err(AppError::NotFound(erros::memoria_nao_encontrada(
96                &args.name, &namespace,
97            )))
98        }
99    }
100
101    Ok(())
102}
103
104#[cfg(test)]
105mod testes {
106    use super::*;
107
108    #[test]
109    fn epoch_to_iso_converte_zero_para_epoch_unix() {
110        let resultado = epoch_to_iso(0);
111        assert!(
112            resultado.starts_with("1970-01-01T00:00:00"),
113            "epoch 0 deve mapear para 1970-01-01T00:00:00, obtido: {resultado}"
114        );
115    }
116
117    #[test]
118    fn epoch_to_iso_converte_timestamp_conhecido() {
119        let resultado = epoch_to_iso(1_705_320_000);
120        assert!(
121            resultado.starts_with("2024-01-15"),
122            "timestamp 1705320000 deve mapear para 2024-01-15, obtido: {resultado}"
123        );
124    }
125
126    #[test]
127    fn epoch_to_iso_retorna_fallback_para_epoch_negativo_invalido() {
128        let resultado = epoch_to_iso(i64::MIN);
129        assert!(
130            !resultado.is_empty(),
131            "deve retornar string não vazia mesmo para epoch inválido"
132        );
133    }
134
135    #[test]
136    fn read_response_serializa_aliases_id_e_memory_id() {
137        let resp = ReadResponse {
138            id: 42,
139            memory_id: 42,
140            namespace: "global".to_string(),
141            name: "minha-mem".to_string(),
142            type_alias: "fact".to_string(),
143            memory_type: "fact".to_string(),
144            description: "desc".to_string(),
145            body: "corpo".to_string(),
146            body_hash: "abc123".to_string(),
147            session_id: None,
148            source: "agent".to_string(),
149            metadata: "{}".to_string(),
150            version: 1,
151            created_at: 1_705_320_000,
152            created_at_iso: "2024-01-15T12:00:00Z".to_string(),
153            updated_at: 1_705_320_000,
154            updated_at_iso: "2024-01-15T12:00:00Z".to_string(),
155            elapsed_ms: 5,
156        };
157
158        let json = serde_json::to_value(&resp).expect("serialização falhou");
159        assert_eq!(json["id"], 42);
160        assert_eq!(json["memory_id"], 42);
161        assert_eq!(json["type"], "fact");
162        assert_eq!(json["memory_type"], "fact");
163        assert_eq!(json["elapsed_ms"], 5u64);
164        assert!(
165            json["session_id"].is_null(),
166            "session_id None deve serializar como null"
167        );
168    }
169
170    #[test]
171    fn read_response_session_id_some_serializa_string() {
172        let resp = ReadResponse {
173            id: 1,
174            memory_id: 1,
175            namespace: "global".to_string(),
176            name: "mem".to_string(),
177            type_alias: "skill".to_string(),
178            memory_type: "skill".to_string(),
179            description: "d".to_string(),
180            body: "b".to_string(),
181            body_hash: "h".to_string(),
182            session_id: Some("sess-123".to_string()),
183            source: "agent".to_string(),
184            metadata: "{}".to_string(),
185            version: 2,
186            created_at: 0,
187            created_at_iso: "1970-01-01T00:00:00Z".to_string(),
188            updated_at: 0,
189            updated_at_iso: "1970-01-01T00:00:00Z".to_string(),
190            elapsed_ms: 0,
191        };
192
193        let json = serde_json::to_value(&resp).expect("serialização falhou");
194        assert_eq!(json["session_id"], "sess-123");
195    }
196
197    #[test]
198    fn read_response_elapsed_ms_esta_presente() {
199        let resp = ReadResponse {
200            id: 7,
201            memory_id: 7,
202            namespace: "ns".to_string(),
203            name: "n".to_string(),
204            type_alias: "procedure".to_string(),
205            memory_type: "procedure".to_string(),
206            description: "d".to_string(),
207            body: "b".to_string(),
208            body_hash: "h".to_string(),
209            session_id: None,
210            source: "agent".to_string(),
211            metadata: "{}".to_string(),
212            version: 3,
213            created_at: 1000,
214            created_at_iso: "1970-01-01T00:16:40Z".to_string(),
215            updated_at: 2000,
216            updated_at_iso: "1970-01-01T00:33:20Z".to_string(),
217            elapsed_ms: 123,
218        };
219
220        let json = serde_json::to_value(&resp).expect("serialização falhou");
221        assert_eq!(json["elapsed_ms"], 123u64);
222        assert!(json["created_at_iso"].is_string());
223        assert!(json["updated_at_iso"].is_string());
224    }
225}
sqlite_graphrag/commands/read.rs

sqlite_graphrag/commands/
read.rs
