otherwise-cli 0.1.0

package/src/storage/db.js

@@ -0,0 +1,1135 @@
+import Database from "better-sqlite3";
+import { randomUUID } from "crypto";
+import { homedir } from "os";
+import { join } from "path";
+import { mkdirSync, existsSync } from "fs";
+
+let db = null;
+
+/** UUID regex for validation */
+const UUID_REGEX =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+export function isValidChatId(id) {
+  if (id == null || typeof id !== "string") return false;
+  return UUID_REGEX.test(id);
+}
+
+/**
+ * Get the database directory path
+ */
+function getDbPath() {
+  const dataDir = join(homedir(), ".otherwise");
+  if (!existsSync(dataDir)) {
+    mkdirSync(dataDir, { recursive: true });
+  }
+  return join(dataDir, "otherwise.db");
+}
+
+/**
+ * Initialize the database and create tables
+ */
+export async function initDb() {
+  const dbPath = getDbPath();
+  db = new Database(dbPath);
+
+  // Enable WAL mode for better concurrent access
+  db.pragma("journal_mode = WAL");
+
+  // Create tables
+  db.exec(`
+    -- Chats table
+    CREATE TABLE IF NOT EXISTS chats (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      title TEXT,
+      created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+      updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
+    );
+
+    -- Messages table
+    CREATE TABLE IF NOT EXISTS messages (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      chat_id INTEGER NOT NULL REFERENCES chats(id) ON DELETE CASCADE,
+      role TEXT NOT NULL CHECK (role IN ('user', 'assistant', 'system')),
+      content TEXT NOT NULL,
+      metadata JSON,
+      created_at DATETIME DEFAULT CURRENT_TIMESTAMP
+    );
+
+    -- Index for faster message lookup by chat
+    CREATE INDEX IF NOT EXISTS idx_messages_chat_id ON messages(chat_id);
+
+    -- Embeddings table for memory visualization
+    CREATE TABLE IF NOT EXISTS embeddings (
+      chat_id INTEGER PRIMARY KEY REFERENCES chats(id) ON DELETE CASCADE,
+      embedding BLOB NOT NULL,
+      provider TEXT DEFAULT 'openai',
+      updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
+    );
+
+    -- Scheduled tasks table
+    CREATE TABLE IF NOT EXISTS scheduled_tasks (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      cron_expression TEXT NOT NULL,
+      description TEXT NOT NULL,
+      next_run DATETIME,
+      last_run DATETIME,
+      enabled INTEGER DEFAULT 1,
+      created_at DATETIME DEFAULT CURRENT_TIMESTAMP
+    );
+
+    -- Index for finding due tasks
+    CREATE INDEX IF NOT EXISTS idx_scheduled_tasks_next_run ON scheduled_tasks(next_run);
+
+    -- File snapshots table for undo on regeneration
+    -- Stores file content BEFORE write_file/edit_file tool modifies it
+    CREATE TABLE IF NOT EXISTS file_snapshots (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      chat_id INTEGER NOT NULL,
+      message_index INTEGER NOT NULL,
+      tool_call_id TEXT,
+      file_path TEXT NOT NULL,
+      original_content TEXT,
+      file_existed INTEGER NOT NULL DEFAULT 1,
+      created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+      UNIQUE(chat_id, message_index, file_path)
+    );
+
+    -- Index for fast lookup during revert
+    CREATE INDEX IF NOT EXISTS idx_file_snapshots_chat_message ON file_snapshots(chat_id, message_index);
+
+    -- RAG Documents table for document storage
+    CREATE TABLE IF NOT EXISTS rag_documents (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      name TEXT NOT NULL,
+      chunk_count INTEGER DEFAULT 0,
+      file_count INTEGER DEFAULT 1,
+      files TEXT,
+      summary TEXT,
+      upload_date DATETIME DEFAULT CURRENT_TIMESTAMP,
+      created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+      updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
+    );
+
+    -- RAG Chunks table for document chunks with embeddings
+    CREATE TABLE IF NOT EXISTS rag_chunks (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      doc_id INTEGER NOT NULL REFERENCES rag_documents(id) ON DELETE CASCADE,
+      text TEXT NOT NULL,
+      page_number INTEGER,
+      chunk_index INTEGER NOT NULL,
+      embedding BLOB NOT NULL,
+      created_at DATETIME DEFAULT CURRENT_TIMESTAMP
+    );
+
+    -- Index for fast chunk lookup by document
+    CREATE INDEX IF NOT EXISTS idx_rag_chunks_doc_id ON rag_chunks(doc_id);
+
+    -- Shell undo log for revert on regeneration (Strategy 1: undo shell commands like mkdir)
+    CREATE TABLE IF NOT EXISTS shell_undo_log (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      chat_id INTEGER NOT NULL,
+      message_index INTEGER NOT NULL,
+      tool_call_id TEXT,
+      op TEXT NOT NULL,
+      path TEXT,
+      path_src TEXT,
+      path_dest TEXT,
+      cwd TEXT,
+      created_at DATETIME DEFAULT CURRENT_TIMESTAMP
+    );
+    CREATE INDEX IF NOT EXISTS idx_shell_undo_log_chat_message ON shell_undo_log(chat_id, message_index);
+  `);
+
+  // Migration: add created_dir to file_snapshots if missing (Strategy 2: undo dirs created by write_file)
+  const tableInfo = db.prepare("PRAGMA table_info(file_snapshots)").all();
+  if (!tableInfo.some((col) => col.name === "created_dir")) {
+    db.exec("ALTER TABLE file_snapshots ADD COLUMN created_dir TEXT");
+  }
+
+  // Migration: add cloud_chat_id to chats for CLI→Supabase sync (frontend reads from Supabase only)
+  const chatsInfo = db.prepare("PRAGMA table_info(chats)").all();
+  if (!chatsInfo.some((col) => col.name === "cloud_chat_id")) {
+    db.exec("ALTER TABLE chats ADD COLUMN cloud_chat_id TEXT");
+  }
+
+  // Migration: integer chat id -> UUID (unified local/cloud id)
+  const idCol = chatsInfo.find((c) => c.name === "id");
+  if (idCol && idCol.type.toUpperCase() === "INTEGER") {
+    if (process.env.SILENT_MODE !== "true") {
+      console.log("Database: migrating chat ids to UUID...");
+    }
+    const idMap = new Map(); // old integer id -> new uuid
+
+    db.exec(`
+      CREATE TABLE chats_new (
+        id TEXT PRIMARY KEY,
+        title TEXT,
+        created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+        updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+        cloud_chat_id TEXT
+      );
+    `);
+    const oldChats = db.prepare("SELECT * FROM chats").all();
+    const insertChat = db.prepare(
+      "INSERT INTO chats_new (id, title, created_at, updated_at, cloud_chat_id) VALUES (?, ?, ?, ?, ?)",
+    );
+    for (const c of oldChats) {
+      const uuid =
+        c.cloud_chat_id && UUID_REGEX.test(String(c.cloud_chat_id))
+          ? c.cloud_chat_id
+          : randomUUID();
+      idMap.set(c.id, uuid);
+      insertChat.run(
+        uuid,
+        c.title,
+        c.created_at,
+        c.updated_at,
+        c.cloud_chat_id || null,
+      );
+    }
+
+    db.exec(`
+      CREATE TABLE messages_new (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        chat_id TEXT NOT NULL,
+        role TEXT NOT NULL CHECK (role IN ('user', 'assistant', 'system')),
+        content TEXT NOT NULL,
+        metadata JSON,
+        created_at DATETIME DEFAULT CURRENT_TIMESTAMP
+      );
+      CREATE INDEX IF NOT EXISTS idx_messages_new_chat_id ON messages_new(chat_id);
+    `);
+    const oldMessages = db.prepare("SELECT * FROM messages").all();
+    const insertMsg = db.prepare(
+      "INSERT INTO messages_new (chat_id, role, content, metadata, created_at) VALUES (?, ?, ?, ?, ?)",
+    );
+    for (const m of oldMessages) {
+      const newChatId = idMap.get(m.chat_id);
+      if (newChatId)
+        insertMsg.run(newChatId, m.role, m.content, m.metadata, m.created_at);
+    }
+
+    db.exec(`
+      CREATE TABLE embeddings_new (
+        chat_id TEXT PRIMARY KEY,
+        embedding BLOB NOT NULL,
+        provider TEXT DEFAULT 'openai',
+        updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
+      );
+    `);
+    const oldEmbeddings = db.prepare("SELECT * FROM embeddings").all();
+    const insertEmb = db.prepare(
+      "INSERT INTO embeddings_new (chat_id, embedding, provider, updated_at) VALUES (?, ?, ?, ?)",
+    );
+    for (const e of oldEmbeddings) {
+      const newChatId = idMap.get(e.chat_id);
+      if (newChatId)
+        insertEmb.run(newChatId, e.embedding, e.provider, e.updated_at);
+    }
+
+    db.exec(`
+      CREATE TABLE file_snapshots_new (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        chat_id TEXT NOT NULL,
+        message_index INTEGER NOT NULL,
+        tool_call_id TEXT,
+        file_path TEXT NOT NULL,
+        original_content TEXT,
+        file_existed INTEGER NOT NULL DEFAULT 1,
+        created_dir TEXT,
+        created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+        UNIQUE(chat_id, message_index, file_path)
+      );
+      CREATE INDEX IF NOT EXISTS idx_file_snapshots_new_chat_message ON file_snapshots_new(chat_id, message_index);
+    `);
+    const oldSnapshots = db.prepare("SELECT * FROM file_snapshots").all();
+    const insertSnap = db.prepare(
+      "INSERT INTO file_snapshots_new (chat_id, message_index, tool_call_id, file_path, original_content, file_existed, created_dir, created_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?)",
+    );
+    for (const s of oldSnapshots) {
+      const newChatId = idMap.get(s.chat_id);
+      if (newChatId)
+        insertSnap.run(
+          newChatId,
+          s.message_index,
+          s.tool_call_id,
+          s.file_path,
+          s.original_content,
+          s.file_existed,
+          s.created_dir,
+          s.created_at,
+        );
+    }
+
+    db.exec(`
+      CREATE TABLE shell_undo_log_new (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        chat_id TEXT NOT NULL,
+        message_index INTEGER NOT NULL,
+        tool_call_id TEXT,
+        op TEXT NOT NULL,
+        path TEXT,
+        path_src TEXT,
+        path_dest TEXT,
+        cwd TEXT,
+        created_at DATETIME DEFAULT CURRENT_TIMESTAMP
+      );
+      CREATE INDEX IF NOT EXISTS idx_shell_undo_log_new_chat_message ON shell_undo_log_new(chat_id, message_index);
+    `);
+    const oldUndos = db.prepare("SELECT * FROM shell_undo_log").all();
+    const insertUndo = db.prepare(
+      "INSERT INTO shell_undo_log_new (chat_id, message_index, tool_call_id, op, path, path_src, path_dest, cwd, created_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)",
+    );
+    for (const u of oldUndos) {
+      const newChatId = idMap.get(u.chat_id);
+      if (newChatId)
+        insertUndo.run(
+          newChatId,
+          u.message_index,
+          u.tool_call_id,
+          u.op,
+          u.path,
+          u.path_src,
+          u.path_dest,
+          u.cwd,
+          u.created_at,
+        );
+    }
+
+    db.exec(`
+      DROP TABLE shell_undo_log;
+      DROP TABLE file_snapshots;
+      DROP TABLE embeddings;
+      DROP TABLE messages;
+      DROP TABLE chats;
+      ALTER TABLE chats_new RENAME TO chats;
+      ALTER TABLE messages_new RENAME TO messages;
+      ALTER TABLE embeddings_new RENAME TO embeddings;
+      ALTER TABLE file_snapshots_new RENAME TO file_snapshots;
+      ALTER TABLE shell_undo_log_new RENAME TO shell_undo_log;
+    `);
+    if (process.env.SILENT_MODE !== "true") {
+      console.log("Database: migration to UUID chat ids complete.");
+    }
+  }
+
+  if (process.env.SILENT_MODE !== "true") {
+    console.log("Database initialized at:", dbPath);
+  }
+  return db;
+}
+
+/**
+ * Get the database instance
+ */
+export function getDb() {
+  if (!db) {
+    throw new Error("Database not initialized. Call initDb() first.");
+  }
+  return db;
+}
+
+/**
+ * Close the database connection
+ */
+export function closeDb() {
+  if (db) {
+    db.close();
+    db = null;
+  }
+}
+
+// ============================================
+// Chat Operations
+// ============================================
+
+/**
+ * Create a new chat with a UUID id (same id can be used for cloud/Supabase).
+ * @param {string|null} title - Chat title
+ * @param {string|null} id - Optional UUID to use (e.g. from Supabase); if not provided, one is generated
+ * @returns {string} The chat id (UUID)
+ */
+export function createChat(title = null, id = null) {
+  const chatId = id && UUID_REGEX.test(String(id)) ? id : randomUUID();
+  getDb()
+    .prepare("INSERT INTO chats (id, title, cloud_chat_id) VALUES (?, ?, ?)")
+    .run(chatId, title, id && UUID_REGEX.test(String(id)) ? id : null);
+  return chatId;
+}
+
+export function getChat(id) {
+  return getDb().prepare("SELECT * FROM chats WHERE id = ?").get(id);
+}
+
+/** Get local chat id by cloud chat UUID. With unified ids, local id equals cloud id. */
+export function getLocalChatIdByCloudId(cloudChatId) {
+  if (!cloudChatId || typeof cloudChatId !== "string") return null;
+  const row = getDb()
+    .prepare("SELECT id FROM chats WHERE id = ? OR cloud_chat_id = ?")
+    .get(cloudChatId, cloudChatId);
+  return row ? row.id : null;
+}
+
+/** Set cloud_chat_id for an existing local chat (after creating in Supabase) */
+export function setCloudChatId(localChatId, cloudChatId) {
+  getDb()
+    .prepare("UPDATE chats SET cloud_chat_id = ? WHERE id = ?")
+    .run(cloudChatId, localChatId);
+}
+
+export function getAllChats() {
+  return getDb().prepare("SELECT * FROM chats ORDER BY updated_at DESC").all();
+}
+
+export function updateChatTitle(id, title) {
+  getDb()
+    .prepare(
+      "UPDATE chats SET title = ?, updated_at = CURRENT_TIMESTAMP WHERE id = ?",
+    )
+    .run(title, id);
+}
+
+export function deleteChat(id) {
+  const db = getDb();
+  db.prepare("DELETE FROM messages WHERE chat_id = ?").run(id);
+  db.prepare("DELETE FROM embeddings WHERE chat_id = ?").run(id);
+  db.prepare("DELETE FROM chats WHERE id = ?").run(id);
+}
+
+// ============================================
+// Message Operations
+// ============================================
+
+export function addMessage(chatId, role, content, metadata = null) {
+  const result = getDb()
+    .prepare(
+      `
+    INSERT INTO messages (chat_id, role, content, metadata) VALUES (?, ?, ?, ?)
+  `,
+    )
+    .run(chatId, role, content, metadata ? JSON.stringify(metadata) : null);
+
+  // Update chat timestamp
+  getDb()
+    .prepare("UPDATE chats SET updated_at = CURRENT_TIMESTAMP WHERE id = ?")
+    .run(chatId);
+
+  return result.lastInsertRowid;
+}
+
+export function getMessages(chatId) {
+  const messages = getDb()
+    .prepare(
+      `
+    SELECT * FROM messages WHERE chat_id = ? ORDER BY created_at ASC
+  `,
+    )
+    .all(chatId);
+
+  return messages.map((m) => ({
+    ...m,
+    metadata: m.metadata ? JSON.parse(m.metadata) : null,
+  }));
+}
+
+export function deleteMessage(id) {
+  getDb().prepare("DELETE FROM messages WHERE id = ?").run(id);
+}
+
+// ============================================
+// Memory Search Operations
+// ============================================
+
+/**
+ * Extract a snippet showing where the match was found with context
+ * @param {string} content - Full message content
+ * @param {string} query - Search query
+ * @param {number} contextChars - Characters of context on each side
+ * @returns {string} Snippet with match highlighted
+ */
+function extractMatchSnippet(content, query, contextChars = 80) {
+  if (!content || !query) return "";
+
+  const lowerContent = content.toLowerCase();
+  const lowerQuery = query.toLowerCase();
+  const matchIndex = lowerContent.indexOf(lowerQuery);
+
+  if (matchIndex === -1) return content.substring(0, 150) + "...";
+
+  const start = Math.max(0, matchIndex - contextChars);
+  const end = Math.min(
+    content.length,
+    matchIndex + query.length + contextChars,
+  );
+
+  let snippet = "";
+  if (start > 0) snippet += "...";
+  snippet += content.substring(start, end);
+  if (end < content.length) snippet += "...";
+
+  return snippet;
+}
+
+/**
+ * Text search across chats and messages with better snippets
+ * @param {string} query - Search query string
+ * @param {number} limit - Maximum results to return
+ * @returns {Array} Matching chats with relevant snippets
+ */
+export function searchChatsText(query, limit = 10) {
+  const searchPattern = `%${query}%`;
+  const db = getDb();
+
+  // First, find all matching messages with their chat info
+  const matchingMessages = db
+    .prepare(
+      `
+    SELECT 
+      m.chat_id,
+      m.role,
+      m.content,
+      m.created_at as message_date,
+      c.title,
+      c.updated_at
+    FROM messages m
+    JOIN chats c ON c.id = m.chat_id
+    WHERE m.content LIKE ?
+    ORDER BY c.updated_at DESC, m.created_at DESC
+  `,
+    )
+    .all(searchPattern);
+
+  // Also find chats matching by title
+  const titleMatches = db
+    .prepare(
+      `
+    SELECT id, title, updated_at
+    FROM chats
+    WHERE title LIKE ?
+    ORDER BY updated_at DESC
+  `,
+    )
+    .all(searchPattern);
+
+  // Group by chat and pick best snippet
+  const chatMap = new Map();
+
+  // Add title matches first
+  for (const chat of titleMatches) {
+    if (!chatMap.has(chat.id)) {
+      chatMap.set(chat.id, {
+        id: chat.id,
+        title: chat.title,
+        updated_at: chat.updated_at,
+        match_type: "title",
+        matching_snippet: `Title matches: "${chat.title}"`,
+        match_count: 0,
+      });
+    }
+  }
+
+  // Add message matches with snippets
+  for (const msg of matchingMessages) {
+    const existing = chatMap.get(msg.chat_id);
+    const snippet = extractMatchSnippet(msg.content, query);
+    const roleLabel = msg.role === "user" ? "You said" : "I said";
+
+    if (!existing) {
+      chatMap.set(msg.chat_id, {
+        id: msg.chat_id,
+        title: msg.title,
+        updated_at: msg.updated_at,
+        match_type: "content",
+        matching_snippet: `${roleLabel}: "${snippet}"`,
+        match_count: 1,
+      });
+    } else {
+      existing.match_count++;
+      // Keep the first (most recent) snippet but update count
+      if (existing.match_type === "title") {
+        // Title matched, but also has content match - upgrade snippet
+        existing.matching_snippet = `${roleLabel}: "${snippet}"`;
+        existing.match_type = "both";
+      }
+    }
+  }
+
+  // Convert to array and limit
+  const results = Array.from(chatMap.values())
+    .sort((a, b) => new Date(b.updated_at) - new Date(a.updated_at))
+    .slice(0, limit);
+
+  return results;
+}
+
+/**
+ * Get chat with all its messages for full context
+ * @param {number} chatId - The chat ID
+ * @returns {Object|null} Chat with messages array, or null if not found
+ */
+export function getChatWithMessages(chatId) {
+  const db = getDb();
+
+  const chat = db.prepare("SELECT * FROM chats WHERE id = ?").get(chatId);
+  if (!chat) return null;
+
+  const messages = db
+    .prepare(
+      `
+    SELECT role, content, created_at 
+    FROM messages 
+    WHERE chat_id = ? 
+    ORDER BY created_at ASC
+  `,
+    )
+    .all(chatId);
+
+  return { ...chat, messages };
+}
+
+// ============================================
+// Embedding Operations
+// ============================================
+
+export function saveEmbedding(chatId, embedding, provider = "openai") {
+  // Convert array to Buffer
+  const buffer = Buffer.from(new Float32Array(embedding).buffer);
+
+  getDb()
+    .prepare(
+      `
+    INSERT OR REPLACE INTO embeddings (chat_id, embedding, provider, updated_at) 
+    VALUES (?, ?, ?, CURRENT_TIMESTAMP)
+  `,
+    )
+    .run(chatId, buffer, provider);
+}
+
+export function getEmbedding(chatId) {
+  const row = getDb()
+    .prepare("SELECT * FROM embeddings WHERE chat_id = ?")
+    .get(chatId);
+  if (!row) return null;
+
+  // Convert Buffer back to array
+  const embedding = Array.from(
+    new Float32Array(
+      row.embedding.buffer,
+      row.embedding.byteOffset,
+      row.embedding.length / 4,
+    ),
+  );
+  return { ...row, embedding };
+}
+
+export function getAllEmbeddings() {
+  const rows = getDb().prepare("SELECT * FROM embeddings").all();
+  return rows.map((row) => ({
+    ...row,
+    embedding: Array.from(
+      new Float32Array(
+        row.embedding.buffer,
+        row.embedding.byteOffset,
+        row.embedding.length / 4,
+      ),
+    ),
+  }));
+}
+
+// ============================================
+// Scheduled Task Operations
+// ============================================
+
+export function createScheduledTask(cronExpression, description) {
+  const result = getDb()
+    .prepare(
+      `
+    INSERT INTO scheduled_tasks (cron_expression, description) VALUES (?, ?)
+  `,
+    )
+    .run(cronExpression, description);
+  return result.lastInsertRowid;
+}
+
+export function getScheduledTasks(enabledOnly = true) {
+  if (enabledOnly) {
+    return getDb()
+      .prepare(
+        "SELECT * FROM scheduled_tasks WHERE enabled = 1 ORDER BY next_run ASC",
+      )
+      .all();
+  }
+  return getDb()
+    .prepare("SELECT * FROM scheduled_tasks ORDER BY created_at DESC")
+    .all();
+}
+
+export function getScheduledTask(id) {
+  return getDb().prepare("SELECT * FROM scheduled_tasks WHERE id = ?").get(id);
+}
+
+export function updateScheduledTaskNextRun(id, nextRun) {
+  getDb()
+    .prepare("UPDATE scheduled_tasks SET next_run = ? WHERE id = ?")
+    .run(nextRun, id);
+}
+
+export function markScheduledTaskRun(id) {
+  getDb()
+    .prepare(
+      "UPDATE scheduled_tasks SET last_run = CURRENT_TIMESTAMP WHERE id = ?",
+    )
+    .run(id);
+}
+
+export function disableScheduledTask(id) {
+  getDb()
+    .prepare("UPDATE scheduled_tasks SET enabled = 0 WHERE id = ?")
+    .run(id);
+}
+
+export function deleteScheduledTask(id) {
+  getDb().prepare("DELETE FROM scheduled_tasks WHERE id = ?").run(id);
+}
+
+// ============================================
+// File Snapshot Operations (for undo on regeneration)
+// ============================================
+
+/** Max size (bytes) for original_content in file_snapshots; larger files are not snapshotted (revert will skip them) */
+const MAX_SNAPSHOT_CONTENT_BYTES = 2 * 1024 * 1024; // 2MB
+
+/**
+ * Save a file snapshot before a tool modifies the file
+ * Uses INSERT OR IGNORE to keep only the first (original) snapshot per file per message.
+ * Skips saving if originalContent exceeds MAX_SNAPSHOT_CONTENT_BYTES to avoid DB bloat and OOM.
+ * @param {number} chatId - The chat ID
+ * @param {number} messageIndex - Index of the assistant message containing the tool call
+ * @param {string} toolCallId - Unique ID of the tool call
+ * @param {string} filePath - Absolute path to the file
+ * @param {string|null} originalContent - Content before modification (null if file didn't exist)
+ * @param {boolean} fileExisted - Whether the file existed before the tool call
+ * @param {string|null} createdDir - If write_file created the parent dir, its absolute path (for revert)
+ */
+export function saveFileSnapshot(
+  chatId,
+  messageIndex,
+  toolCallId,
+  filePath,
+  originalContent,
+  fileExisted,
+  createdDir = null,
+) {
+  const contentLength =
+    originalContent != null
+      ? typeof originalContent === "string"
+        ? Buffer.byteLength(originalContent, "utf8")
+        : originalContent.length
+      : 0;
+  if (contentLength > MAX_SNAPSHOT_CONTENT_BYTES) {
+    if (process.env.SILENT_MODE !== "true") {
+      console.warn(
+        "[db] Skipping file snapshot (too large):",
+        filePath,
+        `${(contentLength / 1024 / 1024).toFixed(2)}MB > ${MAX_SNAPSHOT_CONTENT_BYTES / 1024 / 1024}MB`,
+      );
+    }
+    return;
+  }
+  // Use INSERT OR IGNORE to keep only the first snapshot per file per message
+  // This ensures we capture the ORIGINAL state before any modifications
+  getDb()
+    .prepare(
+      `
+    INSERT OR IGNORE INTO file_snapshots (chat_id, message_index, tool_call_id, file_path, original_content, file_existed, created_dir)
+    VALUES (?, ?, ?, ?, ?, ?, ?)
+  `,
+    )
+    .run(
+      chatId,
+      messageIndex,
+      toolCallId,
+      filePath,
+      originalContent,
+      fileExisted ? 1 : 0,
+      createdDir,
+    );
+}
+
+/**
+ * Get all snapshots that need to be reverted for a regeneration
+ * Returns snapshots where messageIndex >= fromMessageIndex
+ * @param {number} chatId - The chat ID
+ * @param {number} fromMessageIndex - The message index being regenerated (inclusive)
+ * @returns {Array} Snapshots to revert, ordered by message_index DESC (revert newest first)
+ */
+export function getSnapshotsToRevert(chatId, fromMessageIndex) {
+  return getDb()
+    .prepare(
+      `
+    SELECT * FROM file_snapshots 
+    WHERE chat_id = ? AND message_index >= ?
+    ORDER BY message_index DESC, id DESC
+  `,
+    )
+    .all(chatId, fromMessageIndex);
+}
+
+/**
+ * Delete snapshots after they've been reverted
+ * @param {number} chatId - The chat ID
+ * @param {number} fromMessageIndex - Delete snapshots at or after this index
+ */
+export function deleteSnapshots(chatId, fromMessageIndex) {
+  getDb()
+    .prepare(
+      `
+    DELETE FROM file_snapshots WHERE chat_id = ? AND message_index >= ?
+  `,
+    )
+    .run(chatId, fromMessageIndex);
+}
+
+/**
+ * Delete all snapshots for a chat (used when chat is deleted)
+ * @param {number} chatId - The chat ID
+ */
+export function deleteAllChatSnapshots(chatId) {
+  getDb().prepare("DELETE FROM file_snapshots WHERE chat_id = ?").run(chatId);
+}
+
+/**
+ * Get all snapshots for a chat (for debugging/inspection)
+ * @param {number} chatId - The chat ID
+ * @returns {Array} All snapshots for the chat
+ */
+export function getChatSnapshots(chatId) {
+  return getDb()
+    .prepare(
+      `
+    SELECT * FROM file_snapshots WHERE chat_id = ? ORDER BY message_index ASC, id ASC
+  `,
+    )
+    .all(chatId);
+}
+
+// ============================================
+// Shell Undo Log (Strategy 1: undo shell commands on regeneration)
+// ============================================
+
+/**
+ * Save a reversible shell operation for undo on regeneration
+ * @param {number} chatId - The chat ID
+ * @param {number} messageIndex - Index of the assistant message
+ * @param {string|null} toolCallId - Unique ID of the tool call
+ * @param {object} entry - { op, path?, path_src?, path_dest?, cwd }
+ */
+export function saveShellUndo(chatId, messageIndex, toolCallId, entry) {
+  getDb()
+    .prepare(
+      `
+    INSERT INTO shell_undo_log (chat_id, message_index, tool_call_id, op, path, path_src, path_dest, cwd)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+  `,
+    )
+    .run(
+      chatId,
+      messageIndex,
+      toolCallId,
+      entry.op,
+      entry.path ?? null,
+      entry.path_src ?? null,
+      entry.path_dest ?? null,
+      entry.cwd ?? null,
+    );
+}
+
+/**
+ * Get shell undo entries to revert for a regeneration (newest first for reverse-order revert)
+ * @param {number} chatId - The chat ID
+ * @param {number} fromMessageIndex - The message index being regenerated (inclusive)
+ * @returns {Array} Entries to revert, ordered by message_index DESC, id DESC
+ */
+export function getShellUndosToRevert(chatId, fromMessageIndex) {
+  return getDb()
+    .prepare(
+      `
+    SELECT * FROM shell_undo_log
+    WHERE chat_id = ? AND message_index >= ?
+    ORDER BY message_index DESC, id DESC
+  `,
+    )
+    .all(chatId, fromMessageIndex);
+}
+
+/**
+ * Delete shell undo entries after they've been reverted
+ * @param {number} chatId - The chat ID
+ * @param {number} fromMessageIndex - Delete entries at or after this index
+ */
+export function deleteShellUndos(chatId, fromMessageIndex) {
+  getDb()
+    .prepare(
+      `
+    DELETE FROM shell_undo_log WHERE chat_id = ? AND message_index >= ?
+  `,
+    )
+    .run(chatId, fromMessageIndex);
+}
+
+/**
+ * Delete all shell undo entries for a chat (e.g. when chat is deleted)
+ * @param {number} chatId - The chat ID
+ */
+export function deleteAllChatShellUndos(chatId) {
+  getDb().prepare("DELETE FROM shell_undo_log WHERE chat_id = ?").run(chatId);
+}
+
+// ============================================
+// RAG Document Operations
+// ============================================
+
+/**
+ * Create a new RAG document
+ * @param {Object} doc - Document data { name, chunkCount, fileCount, files, summary }
+ * @returns {number} Document ID
+ */
+export function createRagDocument(doc) {
+  const result = getDb()
+    .prepare(
+      `
+    INSERT INTO rag_documents (name, chunk_count, file_count, files, summary, upload_date)
+    VALUES (?, ?, ?, ?, ?, ?)
+  `,
+    )
+    .run(
+      doc.name,
+      doc.chunkCount || 0,
+      doc.fileCount || 1,
+      doc.files || null,
+      doc.summary || null,
+      doc.uploadDate || new Date().toISOString(),
+    );
+  return result.lastInsertRowid;
+}
+
+/**
+ * Get all RAG documents
+ * @returns {Array} All documents
+ */
+export function getAllRagDocuments() {
+  return getDb()
+    .prepare(
+      `
+    SELECT id, name, chunk_count as chunkCount, file_count as fileCount, 
+           files, summary, upload_date as uploadDate, created_at, updated_at
+    FROM rag_documents 
+    ORDER BY created_at DESC
+  `,
+    )
+    .all();
+}
+
+/**
+ * Get a single RAG document by ID
+ * @param {number} id - Document ID
+ * @returns {Object|null} Document or null
+ */
+export function getRagDocument(id) {
+  return getDb()
+    .prepare(
+      `
+    SELECT id, name, chunk_count as chunkCount, file_count as fileCount,
+           files, summary, upload_date as uploadDate, created_at, updated_at
+    FROM rag_documents WHERE id = ?
+  `,
+    )
+    .get(id);
+}
+
+/**
+ * Update a RAG document
+ * @param {number} id - Document ID
+ * @param {Object} updates - Fields to update
+ */
+export function updateRagDocument(id, updates) {
+  const fields = [];
+  const values = [];
+
+  if (updates.name !== undefined) {
+    fields.push("name = ?");
+    values.push(updates.name);
+  }
+  if (updates.chunkCount !== undefined) {
+    fields.push("chunk_count = ?");
+    values.push(updates.chunkCount);
+  }
+  if (updates.summary !== undefined) {
+    fields.push("summary = ?");
+    values.push(updates.summary);
+  }
+
+  if (fields.length === 0) return;
+
+  fields.push("updated_at = CURRENT_TIMESTAMP");
+  values.push(id);
+
+  getDb()
+    .prepare(
+      `
+    UPDATE rag_documents SET ${fields.join(", ")} WHERE id = ?
+  `,
+    )
+    .run(...values);
+}
+
+/**
+ * Delete a RAG document and its chunks
+ * @param {number} id - Document ID
+ */
+export function deleteRagDocument(id) {
+  const db = getDb();
+  db.prepare("DELETE FROM rag_chunks WHERE doc_id = ?").run(id);
+  db.prepare("DELETE FROM rag_documents WHERE id = ?").run(id);
+}
+
+/**
+ * Add chunks for a RAG document
+ * @param {number} docId - Document ID
+ * @param {Array} chunks - Array of { text, pageNumber, chunkIndex, embedding }
+ */
+export function addRagChunks(docId, chunks) {
+  const db = getDb();
+  const insert = db.prepare(`
+    INSERT INTO rag_chunks (doc_id, text, page_number, chunk_index, embedding)
+    VALUES (?, ?, ?, ?, ?)
+  `);
+
+  const insertMany = db.transaction((items) => {
+    for (const chunk of items) {
+      // Convert embedding array to Buffer
+      const embeddingBuffer = Buffer.from(
+        new Float32Array(chunk.embedding).buffer,
+      );
+      insert.run(
+        docId,
+        chunk.text,
+        chunk.pageNumber || null,
+        chunk.chunkIndex,
+        embeddingBuffer,
+      );
+    }
+  });
+
+  insertMany(chunks);
+
+  // Update document chunk count
+  db.prepare("UPDATE rag_documents SET chunk_count = ? WHERE id = ?").run(
+    chunks.length,
+    docId,
+  );
+}
+
+/**
+ * Get all chunks for a RAG document
+ * @param {number} docId - Document ID
+ * @returns {Array} Chunks with embeddings converted to arrays
+ */
+export function getRagChunksByDocument(docId) {
+  const chunks = getDb()
+    .prepare(
+      `
+    SELECT id, doc_id as docId, text, page_number as pageNumber, chunk_index as chunkIndex, embedding
+    FROM rag_chunks WHERE doc_id = ?
+    ORDER BY chunk_index ASC
+  `,
+    )
+    .all(docId);
+
+  // Convert embedding Buffers back to arrays
+  return chunks.map((chunk) => ({
+    ...chunk,
+    embedding: Array.from(
+      new Float32Array(
+        chunk.embedding.buffer,
+        chunk.embedding.byteOffset,
+        chunk.embedding.length / 4,
+      ),
+    ),
+  }));
+}
+
+/**
+ * Get chunks from multiple documents for RAG search
+ * @param {Array<number>} docIds - Array of document IDs
+ * @returns {Array} Chunks with embeddings
+ */
+export function getRagChunksByDocuments(docIds) {
+  if (!docIds || docIds.length === 0) return [];
+
+  const placeholders = docIds.map(() => "?").join(",");
+  const chunks = getDb()
+    .prepare(
+      `
+    SELECT id, doc_id as docId, text, page_number as pageNumber, chunk_index as chunkIndex, embedding
+    FROM rag_chunks WHERE doc_id IN (${placeholders})
+    ORDER BY doc_id, chunk_index ASC
+  `,
+    )
+    .all(...docIds);
+
+  // Convert embedding Buffers back to arrays
+  return chunks.map((chunk) => ({
+    ...chunk,
+    embedding: Array.from(
+      new Float32Array(
+        chunk.embedding.buffer,
+        chunk.embedding.byteOffset,
+        chunk.embedding.length / 4,
+      ),
+    ),
+  }));
+}
+
+export default {
+  initDb,
+  getDb,
+  closeDb,
+  createChat,
+  getChat,
+  getLocalChatIdByCloudId,
+  setCloudChatId,
+  getAllChats,
+  updateChatTitle,
+  deleteChat,
+  addMessage,
+  getMessages,
+  deleteMessage,
+  searchChatsText,
+  getChatWithMessages,
+  saveEmbedding,
+  getEmbedding,
+  getAllEmbeddings,
+  createScheduledTask,
+  getScheduledTasks,
+  getScheduledTask,
+  updateScheduledTaskNextRun,
+  markScheduledTaskRun,
+  disableScheduledTask,
+  deleteScheduledTask,
+  // File snapshot operations for undo on regeneration
+  saveFileSnapshot,
+  getSnapshotsToRevert,
+  deleteSnapshots,
+  deleteAllChatSnapshots,
+  getChatSnapshots,
+  // RAG document operations
+  createRagDocument,
+  getAllRagDocuments,
+  getRagDocument,
+  updateRagDocument,
+  deleteRagDocument,
+  addRagChunks,
+  getRagChunksByDocument,
+  getRagChunksByDocuments,
+};