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    /// Memory name as a positional argument. Alternative to `--name`.
12    #[arg(value_name = "NAME", conflicts_with = "name")]
13    pub name_positional: Option<String>,
14    /// Memory name to read. Returns NotFound (exit 4) if missing or soft-deleted.
15    #[arg(long)]
16    pub name: Option<String>,
17    #[arg(long, default_value = "global")]
18    pub namespace: Option<String>,
19    #[arg(long, help = "No-op; JSON is always emitted on stdout")]
20    pub json: bool,
21    #[arg(long, env = "SQLITE_GRAPHRAG_DB_PATH")]
22    pub db: Option<String>,
23}
24
25#[derive(Serialize)]
26struct ReadResponse {
27    /// Campo canônico do storage. Preservado para compatibilidade com clientes v2.0.0.
28    id: i64,
29    /// Alias semântico de `id` para contrato documentado em SKILL.md e AGENT_PROTOCOL.md.
30    memory_id: i64,
31    namespace: String,
32    name: String,
33    /// Alias semântico de `memory_type` para contrato documentado.
34    #[serde(rename = "type")]
35    type_alias: String,
36    memory_type: String,
37    description: String,
38    body: String,
39    body_hash: String,
40    session_id: Option<String>,
41    source: String,
42    metadata: serde_json::Value,
43    /// Versão mais recente da memória, útil para controle otimista via `--expected-updated-at`.
44    version: i64,
45    created_at: i64,
46    /// Timestamp RFC 3339 UTC paralelo a `created_at` para parsers ISO 8601.
47    created_at_iso: String,
48    updated_at: i64,
49    /// Timestamp RFC 3339 UTC paralelo a `updated_at` para parsers ISO 8601.
50    updated_at_iso: String,
51    /// Tempo total de execução em milissegundos desde início do handler até serialização.
52    elapsed_ms: u64,
53}
54
55fn epoch_to_iso(epoch: i64) -> String {
56    crate::tz::epoch_para_iso(epoch)
57}
58
59pub fn run(args: ReadArgs) -> Result<(), AppError> {
60    let inicio = std::time::Instant::now();
61    // Resolve name from positional or --name flag; both are optional, at least one is required.
62    let name = args.name_positional.or(args.name).ok_or_else(|| {
63        AppError::Validation("name required: pass as positional argument or via --name".to_string())
64    })?;
65    let namespace = crate::namespace::resolve_namespace(args.namespace.as_deref())?;
66    let paths = AppPaths::resolve(args.db.as_deref())?;
67    if !paths.db.exists() {
68        return Err(AppError::NotFound(
69            crate::i18n::erros::banco_nao_encontrado(&paths.db.display().to_string()),
70        ));
71    }
72    let conn = open_ro(&paths.db)?;
73
74    match memories::read_by_name(&conn, &namespace, &name)? {
75        Some(row) => {
76            // Resolver versão atual via tabela memory_versions (maior version para este memory_id).
77            let version: i64 = conn
78                .query_row(
79                    "SELECT COALESCE(MAX(version), 1) FROM memory_versions WHERE memory_id=?1",
80                    rusqlite::params![row.id],
81                    |r| r.get(0),
82                )
83                .unwrap_or(1);
84
85            let response = ReadResponse {
86                id: row.id,
87                memory_id: row.id,
88                namespace: row.namespace,
89                name: row.name,
90                type_alias: row.memory_type.clone(),
91                memory_type: row.memory_type,
92                description: row.description,
93                body: row.body,
94                body_hash: row.body_hash,
95                session_id: row.session_id,
96                source: row.source,
97                metadata: serde_json::from_str::<serde_json::Value>(&row.metadata)
98                    .unwrap_or(serde_json::Value::Null),
99                version,
100                created_at: row.created_at,
101                created_at_iso: epoch_to_iso(row.created_at),
102                updated_at: row.updated_at,
103                updated_at_iso: epoch_to_iso(row.updated_at),
104                elapsed_ms: inicio.elapsed().as_millis() as u64,
105            };
106            output::emit_json(&response)?;
107        }
108        None => {
109            return Err(AppError::NotFound(erros::memoria_nao_encontrada(
110                &name, &namespace,
111            )))
112        }
113    }
114
115    Ok(())
116}
117
118#[cfg(test)]
119mod testes {
120    use super::*;
121
122    #[test]
123    fn epoch_to_iso_converte_zero_para_epoch_unix() {
124        let resultado = epoch_to_iso(0);
125        assert!(
126            resultado.starts_with("1970-01-01T00:00:00"),
127            "epoch 0 deve mapear para 1970-01-01T00:00:00, obtido: {resultado}"
128        );
129    }
130
131    #[test]
132    fn epoch_to_iso_converte_timestamp_conhecido() {
133        let resultado = epoch_to_iso(1_705_320_000);
134        assert!(
135            resultado.starts_with("2024-01-15"),
136            "timestamp 1705320000 deve mapear para 2024-01-15, obtido: {resultado}"
137        );
138    }
139
140    #[test]
141    fn epoch_to_iso_retorna_fallback_para_epoch_negativo_invalido() {
142        let resultado = epoch_to_iso(i64::MIN);
143        assert!(
144            !resultado.is_empty(),
145            "deve retornar string não vazia mesmo para epoch inválido"
146        );
147    }
148
149    #[test]
150    fn read_response_serializa_aliases_id_e_memory_id() {
151        let resp = ReadResponse {
152            id: 42,
153            memory_id: 42,
154            namespace: "global".to_string(),
155            name: "minha-mem".to_string(),
156            type_alias: "fact".to_string(),
157            memory_type: "fact".to_string(),
158            description: "desc".to_string(),
159            body: "corpo".to_string(),
160            body_hash: "abc123".to_string(),
161            session_id: None,
162            source: "agent".to_string(),
163            metadata: serde_json::json!({}),
164            version: 1,
165            created_at: 1_705_320_000,
166            created_at_iso: "2024-01-15T12:00:00Z".to_string(),
167            updated_at: 1_705_320_000,
168            updated_at_iso: "2024-01-15T12:00:00Z".to_string(),
169            elapsed_ms: 5,
170        };
171
172        let json = serde_json::to_value(&resp).expect("serialização falhou");
173        assert_eq!(json["id"], 42);
174        assert_eq!(json["memory_id"], 42);
175        assert_eq!(json["type"], "fact");
176        assert_eq!(json["memory_type"], "fact");
177        assert_eq!(json["elapsed_ms"], 5u64);
178        assert!(
179            json["session_id"].is_null(),
180            "session_id None deve serializar como null"
181        );
182        // metadata deve serializar como objeto JSON, não como string escapada
183        assert!(
184            json["metadata"].is_object(),
185            "metadata deve ser um objeto JSON"
186        );
187    }
188
189    #[test]
190    fn read_response_session_id_some_serializa_string() {
191        let resp = ReadResponse {
192            id: 1,
193            memory_id: 1,
194            namespace: "global".to_string(),
195            name: "mem".to_string(),
196            type_alias: "skill".to_string(),
197            memory_type: "skill".to_string(),
198            description: "d".to_string(),
199            body: "b".to_string(),
200            body_hash: "h".to_string(),
201            session_id: Some("sess-123".to_string()),
202            source: "agent".to_string(),
203            metadata: serde_json::json!({}),
204            version: 2,
205            created_at: 0,
206            created_at_iso: "1970-01-01T00:00:00Z".to_string(),
207            updated_at: 0,
208            updated_at_iso: "1970-01-01T00:00:00Z".to_string(),
209            elapsed_ms: 0,
210        };
211
212        let json = serde_json::to_value(&resp).expect("serialização falhou");
213        assert_eq!(json["session_id"], "sess-123");
214    }
215
216    #[test]
217    fn read_response_elapsed_ms_esta_presente() {
218        let resp = ReadResponse {
219            id: 7,
220            memory_id: 7,
221            namespace: "ns".to_string(),
222            name: "n".to_string(),
223            type_alias: "procedure".to_string(),
224            memory_type: "procedure".to_string(),
225            description: "d".to_string(),
226            body: "b".to_string(),
227            body_hash: "h".to_string(),
228            session_id: None,
229            source: "agent".to_string(),
230            metadata: serde_json::json!({}),
231            version: 3,
232            created_at: 1000,
233            created_at_iso: "1970-01-01T00:16:40Z".to_string(),
234            updated_at: 2000,
235            updated_at_iso: "1970-01-01T00:33:20Z".to_string(),
236            elapsed_ms: 123,
237        };
238
239        let json = serde_json::to_value(&resp).expect("serialização falhou");
240        assert_eq!(json["elapsed_ms"], 123u64);
241        assert!(json["created_at_iso"].is_string());
242        assert!(json["updated_at_iso"].is_string());
243    }
244
245    #[test]
246    fn read_response_metadata_object_nao_string_escapada() {
247        // P2-A: metadata deve serializar como objeto JSON, não como string escapada.
248        let resp = ReadResponse {
249            id: 3,
250            memory_id: 3,
251            namespace: "ns".to_string(),
252            name: "meta-test".to_string(),
253            type_alias: "fact".to_string(),
254            memory_type: "fact".to_string(),
255            description: "d".to_string(),
256            body: "b".to_string(),
257            body_hash: "h".to_string(),
258            session_id: None,
259            source: "agent".to_string(),
260            metadata: serde_json::json!({"chave": "valor", "numero": 42}),
261            version: 1,
262            created_at: 0,
263            created_at_iso: "1970-01-01T00:00:00Z".to_string(),
264            updated_at: 0,
265            updated_at_iso: "1970-01-01T00:00:00Z".to_string(),
266            elapsed_ms: 1,
267        };
268
269        let json = serde_json::to_value(&resp).expect("serialização falhou");
270        // Must be object, not a JSON string containing escaped JSON.
271        assert!(json["metadata"].is_object());
272        assert_eq!(json["metadata"]["chave"], "valor");
273        assert_eq!(json["metadata"]["numero"], 42);
274    }
275
276    #[test]
277    fn read_response_metadata_fallback_para_null_em_json_invalido() {
278        // P2-A: fallback quando metadata é string inválida.
279        let raw = "json-invalido{{{";
280        let parsed =
281            serde_json::from_str::<serde_json::Value>(raw).unwrap_or(serde_json::Value::Null);
282        assert!(parsed.is_null());
283    }
284}
sqlite_graphrag/commands/read.rs

sqlite_graphrag/commands/
read.rs
