anvil-dev-framework 0.1.6

package/global/tools/anvil-memory/src/db.ts

@@ -0,0 +1,638 @@
+/**
+ * Anvil Memory Database Module
+ *
+ * SQLite database operations using bun:sqlite with FTS5 full-text search.
+ */
+
+import { Database } from 'bun:sqlite';
+import { homedir } from 'os';
+import { join, dirname } from 'path';
+import { existsSync, mkdirSync } from 'fs';
+import type { DbConfig, Observation, Session, Checkpoint, RalphIteration, Prompt } from './types.ts';
+
+// Current schema version
+const SCHEMA_VERSION = 1;
+
+// Default database path
+const DEFAULT_DB_PATH = join(homedir(), '.anvil', 'memory.db');
+
+/**
+ * SQL schema for anvil-memory database
+ */
+const SCHEMA_SQL = `
+-- Schema version tracking
+CREATE TABLE IF NOT EXISTS schema_version (
+  version INTEGER PRIMARY KEY,
+  applied_at TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+-- Observations table (main records)
+CREATE TABLE IF NOT EXISTS observations (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  timestamp TEXT NOT NULL DEFAULT (datetime('now')),
+  type TEXT NOT NULL CHECK (type IN (
+    'bugfix', 'feature', 'refactor', 'discovery', 'decision',
+    'change', 'checkpoint', 'ralph_iteration', 'handoff',
+    'shard', 'linear_sync', 'session_request'
+  )),
+  title TEXT NOT NULL,
+  content TEXT NOT NULL,
+  project TEXT,
+  files TEXT,           -- JSON array of file paths
+  concepts TEXT,        -- JSON array of concept tags
+  work_tokens INTEGER,
+  session_id INTEGER REFERENCES sessions(id),
+  linear_issue TEXT
+);
+
+-- Observations FTS5 virtual table
+CREATE VIRTUAL TABLE IF NOT EXISTS observations_fts USING fts5(
+  title,
+  content,
+  concepts,
+  files,
+  content='observations',
+  content_rowid='id',
+  tokenize='porter unicode61'
+);
+
+-- Sessions table (conversation boundaries)
+CREATE TABLE IF NOT EXISTS sessions (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  started_at TEXT NOT NULL DEFAULT (datetime('now')),
+  ended_at TEXT,
+  project TEXT NOT NULL,
+  branch TEXT,
+  git_hash TEXT,
+  context_peak_percent INTEGER,
+  summary TEXT
+);
+
+-- Sessions FTS5 virtual table
+CREATE VIRTUAL TABLE IF NOT EXISTS sessions_fts USING fts5(
+  summary,
+  project,
+  content='sessions',
+  content_rowid='id',
+  tokenize='porter unicode61'
+);
+
+-- Checkpoints table (CCS events)
+CREATE TABLE IF NOT EXISTS checkpoints (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  timestamp TEXT NOT NULL DEFAULT (datetime('now')),
+  level TEXT NOT NULL CHECK (level IN ('L1', 'L2', 'L3')),
+  context_percent INTEGER NOT NULL,
+  handoff_file TEXT,
+  session_id INTEGER REFERENCES sessions(id),
+  resumed INTEGER DEFAULT 0,
+  resume_session_id INTEGER REFERENCES sessions(id)
+);
+
+-- Ralph iterations table
+CREATE TABLE IF NOT EXISTS ralph_iterations (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  session_id TEXT NOT NULL,           -- Ralph session ID (not FK)
+  iteration INTEGER NOT NULL,
+  started_at TEXT NOT NULL DEFAULT (datetime('now')),
+  ended_at TEXT,
+  status TEXT NOT NULL CHECK (status IN ('running', 'completed', 'failed', 'checkpointed')),
+  items_completed INTEGER,
+  items_total INTEGER,
+  checkpoint_id INTEGER REFERENCES checkpoints(id)
+);
+
+-- Prompts table (user messages)
+CREATE TABLE IF NOT EXISTS prompts (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  timestamp TEXT NOT NULL DEFAULT (datetime('now')),
+  content TEXT NOT NULL,
+  project TEXT,
+  session_id INTEGER REFERENCES sessions(id)
+);
+
+-- Prompts FTS5 virtual table
+CREATE VIRTUAL TABLE IF NOT EXISTS prompts_fts USING fts5(
+  content,
+  content='prompts',
+  content_rowid='id',
+  tokenize='porter unicode61'
+);
+
+-- Indexes for common queries
+CREATE INDEX IF NOT EXISTS idx_observations_timestamp ON observations(timestamp DESC);
+CREATE INDEX IF NOT EXISTS idx_observations_type ON observations(type);
+CREATE INDEX IF NOT EXISTS idx_observations_project ON observations(project);
+CREATE INDEX IF NOT EXISTS idx_observations_session ON observations(session_id);
+CREATE INDEX IF NOT EXISTS idx_observations_linear ON observations(linear_issue);
+
+CREATE INDEX IF NOT EXISTS idx_sessions_project ON sessions(project);
+CREATE INDEX IF NOT EXISTS idx_sessions_started ON sessions(started_at DESC);
+
+CREATE INDEX IF NOT EXISTS idx_checkpoints_session ON checkpoints(session_id);
+CREATE INDEX IF NOT EXISTS idx_checkpoints_timestamp ON checkpoints(timestamp DESC);
+
+CREATE INDEX IF NOT EXISTS idx_ralph_session ON ralph_iterations(session_id);
+CREATE INDEX IF NOT EXISTS idx_ralph_status ON ralph_iterations(status);
+
+CREATE INDEX IF NOT EXISTS idx_prompts_session ON prompts(session_id);
+CREATE INDEX IF NOT EXISTS idx_prompts_timestamp ON prompts(timestamp DESC);
+`;
+
+/**
+ * FTS5 triggers to keep search indexes in sync
+ */
+const TRIGGER_SQL = `
+-- Observations FTS triggers
+CREATE TRIGGER IF NOT EXISTS observations_ai AFTER INSERT ON observations BEGIN
+  INSERT INTO observations_fts(rowid, title, content, concepts, files)
+  VALUES (NEW.id, NEW.title, NEW.content, NEW.concepts, NEW.files);
+END;
+
+CREATE TRIGGER IF NOT EXISTS observations_ad AFTER DELETE ON observations BEGIN
+  INSERT INTO observations_fts(observations_fts, rowid, title, content, concepts, files)
+  VALUES ('delete', OLD.id, OLD.title, OLD.content, OLD.concepts, OLD.files);
+END;
+
+CREATE TRIGGER IF NOT EXISTS observations_au AFTER UPDATE ON observations BEGIN
+  INSERT INTO observations_fts(observations_fts, rowid, title, content, concepts, files)
+  VALUES ('delete', OLD.id, OLD.title, OLD.content, OLD.concepts, OLD.files);
+  INSERT INTO observations_fts(rowid, title, content, concepts, files)
+  VALUES (NEW.id, NEW.title, NEW.content, NEW.concepts, NEW.files);
+END;
+
+-- Sessions FTS triggers
+CREATE TRIGGER IF NOT EXISTS sessions_ai AFTER INSERT ON sessions
+WHEN NEW.summary IS NOT NULL BEGIN
+  INSERT INTO sessions_fts(rowid, summary, project)
+  VALUES (NEW.id, NEW.summary, NEW.project);
+END;
+
+CREATE TRIGGER IF NOT EXISTS sessions_ad AFTER DELETE ON sessions
+WHEN OLD.summary IS NOT NULL BEGIN
+  INSERT INTO sessions_fts(sessions_fts, rowid, summary, project)
+  VALUES ('delete', OLD.id, OLD.summary, OLD.project);
+END;
+
+-- Update trigger: only delete from FTS if old row had summary (was in FTS)
+CREATE TRIGGER IF NOT EXISTS sessions_au AFTER UPDATE ON sessions
+WHEN OLD.summary IS NOT NULL BEGIN
+  INSERT INTO sessions_fts(sessions_fts, rowid, summary, project)
+  VALUES ('delete', OLD.id, OLD.summary, OLD.project);
+  INSERT INTO sessions_fts(rowid, summary, project)
+  VALUES (NEW.id, COALESCE(NEW.summary, ''), NEW.project);
+END;
+
+-- Insert into FTS when summary is added for first time (was NULL, now has value)
+CREATE TRIGGER IF NOT EXISTS sessions_au_insert AFTER UPDATE ON sessions
+WHEN OLD.summary IS NULL AND NEW.summary IS NOT NULL BEGIN
+  INSERT INTO sessions_fts(rowid, summary, project)
+  VALUES (NEW.id, NEW.summary, NEW.project);
+END;
+
+-- Prompts FTS triggers
+CREATE TRIGGER IF NOT EXISTS prompts_ai AFTER INSERT ON prompts BEGIN
+  INSERT INTO prompts_fts(rowid, content)
+  VALUES (NEW.id, NEW.content);
+END;
+
+CREATE TRIGGER IF NOT EXISTS prompts_ad AFTER DELETE ON prompts BEGIN
+  INSERT INTO prompts_fts(prompts_fts, rowid, content)
+  VALUES ('delete', OLD.id, OLD.content);
+END;
+
+CREATE TRIGGER IF NOT EXISTS prompts_au AFTER UPDATE ON prompts BEGIN
+  INSERT INTO prompts_fts(prompts_fts, rowid, content)
+  VALUES ('delete', OLD.id, OLD.content);
+  INSERT INTO prompts_fts(rowid, content)
+  VALUES (NEW.id, NEW.content);
+END;
+`;
+
+/**
+ * Database manager for Anvil Memory
+ */
+export class AnvilMemoryDb {
+  private db: Database;
+  private path: string;
+
+  constructor(dbPath?: string) {
+    this.path = dbPath ?? DEFAULT_DB_PATH;
+
+    // Ensure directory exists
+    const dir = dirname(this.path);
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true });
+    }
+
+    // Open database
+    this.db = new Database(this.path, { create: true });
+
+    // Enable WAL mode for better concurrency
+    this.db.exec('PRAGMA journal_mode = WAL');
+    this.db.exec('PRAGMA foreign_keys = ON');
+  }
+
+  /**
+   * Initialize database with schema
+   */
+  init(): { created: boolean; version: number } {
+    const existingVersion = this.getSchemaVersion();
+
+    if (existingVersion === 0) {
+      // Fresh database - create schema
+      this.db.exec(SCHEMA_SQL);
+      this.db.exec(TRIGGER_SQL);
+      this.setSchemaVersion(SCHEMA_VERSION);
+      return { created: true, version: SCHEMA_VERSION };
+    }
+
+    if (existingVersion < SCHEMA_VERSION) {
+      // TODO: Run migrations
+      this.setSchemaVersion(SCHEMA_VERSION);
+      return { created: false, version: SCHEMA_VERSION };
+    }
+
+    return { created: false, version: existingVersion };
+  }
+
+  /**
+   * Get current schema version
+   */
+  getSchemaVersion(): number {
+    try {
+      const result = this.db.query<{ version: number }, []>(
+        'SELECT MAX(version) as version FROM schema_version'
+      ).get();
+      return result?.version ?? 0;
+    } catch {
+      // Table doesn't exist yet
+      return 0;
+    }
+  }
+
+  /**
+   * Set schema version
+   */
+  private setSchemaVersion(version: number): void {
+    this.db.run('INSERT INTO schema_version (version) VALUES (?)', [version]);
+  }
+
+  /**
+   * Run integrity check
+   */
+  integrityCheck(): { ok: boolean; errors: string[] } {
+    const results = this.db.query<{ integrity_check: string }, []>(
+      'PRAGMA integrity_check'
+    ).all();
+
+    const errors = results
+      .map((r) => r.integrity_check)
+      .filter((r) => r !== 'ok');
+
+    return {
+      ok: errors.length === 0,
+      errors,
+    };
+  }
+
+  /**
+   * Get database config info
+   */
+  getConfig(): DbConfig {
+    return {
+      path: this.path,
+      migrated: this.getSchemaVersion() > 0,
+      version: this.getSchemaVersion(),
+    };
+  }
+
+  /**
+   * Close database connection
+   */
+  close(): void {
+    this.db.close();
+  }
+
+  /**
+   * Get raw database handle (for advanced queries)
+   */
+  getDb(): Database {
+    return this.db;
+  }
+
+  // ============================================
+  // Observation CRUD
+  // ============================================
+
+  createObservation(obs: Omit<Observation, 'id'>): Observation {
+    const stmt = this.db.prepare(`
+      INSERT INTO observations (timestamp, type, title, content, project, files, concepts, work_tokens, session_id, linear_issue)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `);
+
+    const result = stmt.run(
+      obs.timestamp ?? new Date().toISOString(),
+      obs.type,
+      obs.title,
+      obs.content,
+      obs.project ?? null,
+      obs.files ? JSON.stringify(obs.files) : null,
+      obs.concepts ? JSON.stringify(obs.concepts) : null,
+      obs.work_tokens ?? null,
+      obs.session_id ?? null,
+      obs.linear_issue ?? null
+    );
+
+    return { ...obs, id: Number(result.lastInsertRowid) };
+  }
+
+  getObservation(id: number): Observation | null {
+    const row = this.db.query<Record<string, unknown>, [number]>(`
+      SELECT * FROM observations WHERE id = ?
+    `).get(id);
+
+    if (!row) return null;
+
+    return this.rowToObservation(row);
+  }
+
+  searchObservations(query: string, limit = 20): Observation[] {
+    const rows = this.db.query<Record<string, unknown>, [string, number]>(`
+      SELECT o.* FROM observations o
+      JOIN observations_fts fts ON o.id = fts.rowid
+      WHERE observations_fts MATCH ?
+      ORDER BY rank
+      LIMIT ?
+    `).all(query, limit);
+
+    return rows.map((row) => this.rowToObservation(row));
+  }
+
+  getRecentObservations(limit = 20, types?: string[], project?: string): Observation[] {
+    let sql = 'SELECT * FROM observations WHERE 1=1';
+    const params: (string | number)[] = [];
+
+    if (types && types.length > 0) {
+      sql += ` AND type IN (${types.map(() => '?').join(',')})`;
+      params.push(...types);
+    }
+
+    if (project) {
+      sql += ' AND project = ?';
+      params.push(project);
+    }
+
+    sql += ' ORDER BY timestamp DESC LIMIT ?';
+    params.push(limit);
+
+    // Use run for dynamic queries to avoid type issues
+    const stmt = this.db.prepare(sql);
+    const rows = stmt.all(...params) as Record<string, unknown>[];
+    return rows.map((row) => this.rowToObservation(row));
+  }
+
+  private rowToObservation(row: Record<string, unknown>): Observation {
+    return {
+      id: row.id as number,
+      timestamp: row.timestamp as string,
+      type: row.type as Observation['type'],
+      title: row.title as string,
+      content: row.content as string,
+      project: row.project as string | undefined,
+      files: row.files ? JSON.parse(row.files as string) : undefined,
+      concepts: row.concepts ? JSON.parse(row.concepts as string) : undefined,
+      work_tokens: row.work_tokens as number | undefined,
+      session_id: row.session_id as number | undefined,
+      linear_issue: row.linear_issue as string | undefined,
+    };
+  }
+
+  // ============================================
+  // Session CRUD
+  // ============================================
+
+  createSession(session: Omit<Session, 'id'>): Session {
+    const stmt = this.db.prepare(`
+      INSERT INTO sessions (started_at, ended_at, project, branch, git_hash, context_peak_percent, summary)
+      VALUES (?, ?, ?, ?, ?, ?, ?)
+    `);
+
+    const result = stmt.run(
+      session.started_at ?? new Date().toISOString(),
+      session.ended_at ?? null,
+      session.project,
+      session.branch ?? null,
+      session.git_hash ?? null,
+      session.context_peak_percent ?? null,
+      session.summary ?? null
+    );
+
+    return { ...session, id: Number(result.lastInsertRowid) };
+  }
+
+  getSession(id: number): Session | null {
+    const row = this.db.query<Record<string, unknown>, [number]>(`
+      SELECT * FROM sessions WHERE id = ?
+    `).get(id);
+
+    if (!row) return null;
+
+    return {
+      id: row.id as number,
+      started_at: row.started_at as string,
+      ended_at: row.ended_at as string | undefined,
+      project: row.project as string,
+      branch: row.branch as string | undefined,
+      git_hash: row.git_hash as string | undefined,
+      context_peak_percent: row.context_peak_percent as number | undefined,
+      summary: row.summary as string | undefined,
+    };
+  }
+
+  endSession(id: number, summary?: string, contextPeakPercent?: number): void {
+    this.db.run(`
+      UPDATE sessions
+      SET ended_at = datetime('now'),
+          summary = COALESCE(?, summary),
+          context_peak_percent = COALESCE(?, context_peak_percent)
+      WHERE id = ?
+    `, [summary ?? null, contextPeakPercent ?? null, id]);
+  }
+
+  // ============================================
+  // Checkpoint CRUD
+  // ============================================
+
+  createCheckpoint(checkpoint: Omit<Checkpoint, 'id'>): Checkpoint {
+    const stmt = this.db.prepare(`
+      INSERT INTO checkpoints (timestamp, level, context_percent, handoff_file, session_id, resumed, resume_session_id)
+      VALUES (?, ?, ?, ?, ?, ?, ?)
+    `);
+
+    const result = stmt.run(
+      checkpoint.timestamp ?? new Date().toISOString(),
+      checkpoint.level,
+      checkpoint.context_percent,
+      checkpoint.handoff_file ?? null,
+      checkpoint.session_id ?? null,
+      checkpoint.resumed ? 1 : 0,
+      checkpoint.resume_session_id ?? null
+    );
+
+    return { ...checkpoint, id: Number(result.lastInsertRowid) };
+  }
+
+  getCheckpoint(id: number): Checkpoint | null {
+    const row = this.db.query<Record<string, unknown>, [number]>(`
+      SELECT * FROM checkpoints WHERE id = ?
+    `).get(id);
+
+    if (!row) return null;
+
+    return {
+      id: row.id as number,
+      timestamp: row.timestamp as string,
+      level: row.level as Checkpoint['level'],
+      context_percent: row.context_percent as number,
+      handoff_file: row.handoff_file as string | undefined,
+      session_id: row.session_id as number | undefined,
+      resumed: Boolean(row.resumed),
+      resume_session_id: row.resume_session_id as number | undefined,
+    };
+  }
+
+  // ============================================
+  // Ralph Iteration CRUD
+  // ============================================
+
+  createRalphIteration(iteration: Omit<RalphIteration, 'id'>): RalphIteration {
+    const stmt = this.db.prepare(`
+      INSERT INTO ralph_iterations (session_id, iteration, started_at, ended_at, status, items_completed, items_total, checkpoint_id)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+    `);
+
+    const result = stmt.run(
+      iteration.session_id,
+      iteration.iteration,
+      iteration.started_at ?? new Date().toISOString(),
+      iteration.ended_at ?? null,
+      iteration.status,
+      iteration.items_completed ?? null,
+      iteration.items_total ?? null,
+      iteration.checkpoint_id ?? null
+    );
+
+    return { ...iteration, id: Number(result.lastInsertRowid) };
+  }
+
+  updateRalphIteration(id: number, updates: Partial<RalphIteration>): void {
+    const sets: string[] = [];
+    const params: (string | number | null)[] = [];
+
+    if (updates.ended_at !== undefined) {
+      sets.push('ended_at = ?');
+      params.push(updates.ended_at ?? null);
+    }
+    if (updates.status !== undefined) {
+      sets.push('status = ?');
+      params.push(updates.status);
+    }
+    if (updates.items_completed !== undefined) {
+      sets.push('items_completed = ?');
+      params.push(updates.items_completed ?? null);
+    }
+    if (updates.items_total !== undefined) {
+      sets.push('items_total = ?');
+      params.push(updates.items_total ?? null);
+    }
+    if (updates.checkpoint_id !== undefined) {
+      sets.push('checkpoint_id = ?');
+      params.push(updates.checkpoint_id ?? null);
+    }
+
+    if (sets.length > 0) {
+      params.push(id);
+      const stmt = this.db.prepare(`UPDATE ralph_iterations SET ${sets.join(', ')} WHERE id = ?`);
+      stmt.run(...params);
+    }
+  }
+
+  /**
+   * Retrieves a Ralph iteration by ID.
+   *
+   * @param id - The unique identifier of the Ralph iteration
+   * @returns The Ralph iteration record, or null if not found
+   */
+  getRalphIteration(id: number): RalphIteration | null {
+    const row = this.db.query<Record<string, unknown>, [number]>(`
+      SELECT * FROM ralph_iterations WHERE id = ?
+    `).get(id);
+
+    if (!row) return null;
+
+    return {
+      id: row.id as number,
+      session_id: row.session_id as string,
+      iteration: row.iteration as number,
+      started_at: row.started_at as string,
+      ended_at: row.ended_at as string | undefined,
+      status: row.status as RalphIteration['status'],
+      items_completed: row.items_completed as number | undefined,
+      items_total: row.items_total as number | undefined,
+      checkpoint_id: row.checkpoint_id as number | undefined,
+    };
+  }
+
+  // ============================================
+  // Prompt CRUD
+  // ============================================
+
+  createPrompt(prompt: Omit<Prompt, 'id'>): Prompt {
+    const stmt = this.db.prepare(`
+      INSERT INTO prompts (timestamp, content, project, session_id)
+      VALUES (?, ?, ?, ?)
+    `);
+
+    const result = stmt.run(
+      prompt.timestamp ?? new Date().toISOString(),
+      prompt.content,
+      prompt.project ?? null,
+      prompt.session_id ?? null
+    );
+
+    return { ...prompt, id: Number(result.lastInsertRowid) };
+  }
+
+  searchPrompts(query: string, limit = 20): Prompt[] {
+    const rows = this.db.query<Record<string, unknown>, [string, number]>(`
+      SELECT p.* FROM prompts p
+      JOIN prompts_fts fts ON p.id = fts.rowid
+      WHERE prompts_fts MATCH ?
+      ORDER BY rank
+      LIMIT ?
+    `).all(query, limit);
+
+    return rows.map((row) => ({
+      id: row.id as number,
+      timestamp: row.timestamp as string,
+      content: row.content as string,
+      project: row.project as string | undefined,
+      session_id: row.session_id as number | undefined,
+    }));
+  }
+}
+
+/**
+ * Get default database path
+ */
+export function getDefaultDbPath(): string {
+  return DEFAULT_DB_PATH;
+}
+
+/**
+ * Check if database exists
+ */
+export function dbExists(path?: string): boolean {
+  return existsSync(path ?? DEFAULT_DB_PATH);
+}