sqlite_graphrag/commands/
history.rs

1//! Handler for the `history` CLI subcommand.
2
3use crate::errors::AppError;
4use crate::i18n::errors_msg;
5use crate::output;
6use crate::paths::AppPaths;
7use crate::storage::connection::open_ro;
8use rusqlite::params;
9use rusqlite::OptionalExtension;
10use serde::Serialize;
11
12#[derive(clap::Args)]
13pub struct HistoryArgs {
14    /// Memory name as a positional argument. Alternative to `--name`.
15    #[arg(value_name = "NAME", conflicts_with = "name")]
16    pub name_positional: Option<String>,
17    /// Memory name whose version history will be returned. Includes soft-deleted memories
18    /// so that `restore --version <V>` workflow remains discoverable after `forget`.
19    #[arg(long)]
20    pub name: Option<String>,
21    #[arg(long, default_value = "global")]
22    pub namespace: Option<String>,
23    #[arg(long, help = "No-op; JSON is always emitted on stdout")]
24    pub json: bool,
25    #[arg(long, env = "SQLITE_GRAPHRAG_DB_PATH")]
26    pub db: Option<String>,
27}
28
29#[derive(Serialize)]
30struct HistoryVersion {
31    version: i64,
32    name: String,
33    #[serde(rename = "type")]
34    memory_type: String,
35    description: String,
36    body: String,
37    metadata: String,
38    change_reason: String,
39    changed_by: Option<String>,
40    created_at: i64,
41    created_at_iso: String,
42}
43
44#[derive(Serialize)]
45struct HistoryResponse {
46    name: String,
47    namespace: String,
48    /// True when the memory is currently soft-deleted (forgotten).
49    /// Allows the user to discover the version for `restore` even after `forget`.
50    deleted: bool,
51    versions: Vec<HistoryVersion>,
52    /// Total execution time in milliseconds from handler start to serialisation.
53    elapsed_ms: u64,
54}
55
56pub fn run(args: HistoryArgs) -> Result<(), AppError> {
57    let inicio = std::time::Instant::now();
58    // Resolve name from positional or --name flag; both are optional, at least one is required.
59    let name = args.name_positional.or(args.name).ok_or_else(|| {
60        AppError::Validation("name required: pass as positional argument or via --name".to_string())
61    })?;
62    let namespace = crate::namespace::resolve_namespace(args.namespace.as_deref())?;
63    let paths = AppPaths::resolve(args.db.as_deref())?;
64    if !paths.db.exists() {
65        return Err(AppError::NotFound(errors_msg::database_not_found(
66            &paths.db.display().to_string(),
67        )));
68    }
69    let conn = open_ro(&paths.db)?;
70
71    // v1.0.22 P0: query direta SEM filtro deleted_at — history DEVE retornar versões
72    // de memórias forgotten para que o usuário descubra a versão em `restore`.
73    // O find_by_name antigo filtrava deleted_at IS NULL e gerava dead-end no workflow forget+restore.
74    let row: Option<(i64, Option<i64>)> = conn
75        .query_row(
76            "SELECT id, deleted_at FROM memories WHERE namespace = ?1 AND name = ?2",
77            params![namespace, name],
78            |r| Ok((r.get(0)?, r.get(1)?)),
79        )
80        .optional()?;
81    let (memory_id, deleted_at) =
82        row.ok_or_else(|| AppError::NotFound(errors_msg::memory_not_found(&name, &namespace)))?;
83    let deleted = deleted_at.is_some();
84
85    let mut stmt = conn.prepare(
86        "SELECT version, name, type, description, body, metadata,
87                change_reason, changed_by, created_at
88         FROM memory_versions
89         WHERE memory_id = ?1
90         ORDER BY version ASC",
91    )?;
92
93    let versions = stmt
94        .query_map(params![memory_id], |r| {
95            let created_at: i64 = r.get(8)?;
96            let created_at_iso = crate::tz::epoch_to_iso(created_at);
97            Ok(HistoryVersion {
98                version: r.get(0)?,
99                name: r.get(1)?,
100                memory_type: r.get(2)?,
101                description: r.get(3)?,
102                body: r.get(4)?,
103                metadata: r.get(5)?,
104                change_reason: r.get(6)?,
105                changed_by: r.get(7)?,
106                created_at,
107                created_at_iso,
108            })
109        })?
110        .collect::<Result<Vec<_>, _>>()?;
111
112    output::emit_json(&HistoryResponse {
113        name,
114        namespace,
115        deleted,
116        versions,
117        elapsed_ms: inicio.elapsed().as_millis() as u64,
118    })?;
119
120    Ok(())
121}
122
123#[cfg(test)]
124mod tests {
125    #[test]
126    fn epoch_zero_gera_iso_valido() {
127        // epoch_to_iso uses chrono-tz with explicit offset (+00:00 for UTC)
128        let iso = crate::tz::epoch_to_iso(0);
129        assert!(iso.starts_with("1970-01-01T00:00:00"), "obtido: {iso}");
130        assert!(iso.contains("00:00"), "deve conter offset, obtido: {iso}");
131    }
132
133    #[test]
134    fn epoch_tipico_gera_iso_rfc3339() {
135        let iso = crate::tz::epoch_to_iso(1_745_000_000);
136        assert!(!iso.is_empty(), "created_at_iso não deve ser vazio");
137        assert!(iso.contains('T'), "created_at_iso deve conter separador T");
138        // Com UTC o offset é +00:00; verifica formato geral sem depender do fuso global
139        assert!(
140            iso.contains('+') || iso.contains('-'),
141            "deve conter sinal de offset, obtido: {iso}"
142        );
143    }
144
145    #[test]
146    fn epoch_invalido_retorna_fallback() {
147        let iso = crate::tz::epoch_to_iso(i64::MIN);
148        assert!(
149            !iso.is_empty(),
150            "epoch inválido deve retornar fallback não-vazio"
151        );
152    }
153}
sqlite_graphrag/commands/history.rs

sqlite_graphrag/commands/
history.rs
