family-ai-agent 1.0.6 → 1.0.7

package/src/database/migrations/migrator.ts

@@ -0,0 +1,325 @@
+/**
+ * Database Migrator
+ *
+ * Handles automatic schema migrations with version tracking.
+ * Supports both PostgreSQL and SQLite.
+ */
+
+import type { DatabaseAdapter, Migration, MigrationResult } from '../types.js';
+import { createLogger } from '../../utils/logger.js';
+import { MemoryError } from '../../utils/errors.js';
+
+const logger = createLogger('Migrator');
+
+/**
+ * Schema version record
+ */
+interface SchemaVersion {
+  version: number;
+  name: string;
+  applied_at: number | Date;
+  checksum: string | null;
+}
+
+/**
+ * Database migrator for schema version management
+ */
+export class Migrator {
+  private migrations: Migration[] = [];
+  private adapter: DatabaseAdapter;
+
+  constructor(adapter: DatabaseAdapter) {
+    this.adapter = adapter;
+  }
+
+  /**
+   * Register a migration
+   */
+  register(migration: Migration): void {
+    // Check for duplicate versions
+    if (this.migrations.some((m) => m.version === migration.version)) {
+      throw new MemoryError(`Duplicate migration version: ${migration.version}`);
+    }
+
+    this.migrations.push(migration);
+    this.migrations.sort((a, b) => a.version - b.version);
+  }
+
+  /**
+   * Register multiple migrations
+   */
+  registerAll(migrations: Migration[]): void {
+    for (const migration of migrations) {
+      this.register(migration);
+    }
+  }
+
+  /**
+   * Ensure schema_versions table exists
+   */
+  private async ensureVersionTable(): Promise<void> {
+    const sql = `
+      CREATE TABLE IF NOT EXISTS schema_versions (
+        version INTEGER PRIMARY KEY,
+        name TEXT NOT NULL,
+        applied_at ${this.adapter.type === 'postgresql' ? 'TIMESTAMP WITH TIME ZONE' : 'INTEGER'} NOT NULL,
+        checksum TEXT
+      )
+    `;
+    await this.adapter.query(sql);
+  }
+
+  /**
+   * Get current schema version
+   */
+  async getCurrentVersion(): Promise<number> {
+    try {
+      await this.ensureVersionTable();
+      const result = await this.adapter.query<{ max_version: number | null }>(
+        'SELECT MAX(version) as max_version FROM schema_versions'
+      );
+      return result.rows[0]?.max_version ?? 0;
+    } catch (error) {
+      logger.debug('Could not get current version, assuming 0', { error });
+      return 0;
+    }
+  }
+
+  /**
+   * Get all applied migrations
+   */
+  async getAppliedMigrations(): Promise<SchemaVersion[]> {
+    await this.ensureVersionTable();
+    const result = await this.adapter.query<SchemaVersion>(
+      'SELECT version, name, applied_at, checksum FROM schema_versions ORDER BY version ASC'
+    );
+    return result.rows;
+  }
+
+  /**
+   * Get pending migrations
+   */
+  async getPendingMigrations(): Promise<Migration[]> {
+    const currentVersion = await this.getCurrentVersion();
+    return this.migrations.filter((m) => m.version > currentVersion);
+  }
+
+  /**
+   * Run all pending migrations
+   */
+  async migrate(): Promise<MigrationResult[]> {
+    const pending = await this.getPendingMigrations();
+    const results: MigrationResult[] = [];
+
+    if (pending.length === 0) {
+      logger.debug('No pending migrations');
+      return results;
+    }
+
+    logger.info('Running migrations', { count: pending.length });
+
+    for (const migration of pending) {
+      const result = await this.runMigration(migration);
+      results.push(result);
+
+      if (!result.success) {
+        logger.error('Migration failed, stopping', { version: migration.version });
+        break;
+      }
+    }
+
+    return results;
+  }
+
+  /**
+   * Run a single migration
+   */
+  private async runMigration(migration: Migration): Promise<MigrationResult> {
+    const start = Date.now();
+
+    logger.info('Running migration', {
+      version: migration.version,
+      name: migration.name,
+    });
+
+    try {
+      await this.adapter.transaction(async (client) => {
+        // Run the migration
+        await migration.up(this.adapter);
+
+        // Record the migration
+        const now = this.adapter.type === 'postgresql'
+          ? 'NOW()'
+          : String(Date.now());
+
+        await this.adapter.query(
+          `INSERT INTO schema_versions (version, name, applied_at, checksum) VALUES ($1, $2, ${
+            this.adapter.type === 'postgresql' ? 'NOW()' : '$3'
+          }, $${this.adapter.type === 'postgresql' ? '3' : '4'})`,
+          this.adapter.type === 'postgresql'
+            ? [migration.version, migration.name, this.computeChecksum(migration)]
+            : [migration.version, migration.name, Date.now(), this.computeChecksum(migration)]
+        );
+      });
+
+      const durationMs = Date.now() - start;
+      logger.info('Migration completed', {
+        version: migration.version,
+        durationMs,
+      });
+
+      return {
+        version: migration.version,
+        name: migration.name,
+        success: true,
+        durationMs,
+      };
+    } catch (error) {
+      const durationMs = Date.now() - start;
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+
+      logger.error('Migration failed', {
+        version: migration.version,
+        error: errorMessage,
+      });
+
+      return {
+        version: migration.version,
+        name: migration.name,
+        success: false,
+        error: errorMessage,
+        durationMs,
+      };
+    }
+  }
+
+  /**
+   * Rollback to a specific version
+   */
+  async rollback(targetVersion: number): Promise<MigrationResult[]> {
+    const currentVersion = await this.getCurrentVersion();
+    const results: MigrationResult[] = [];
+
+    if (targetVersion >= currentVersion) {
+      logger.debug('Nothing to rollback');
+      return results;
+    }
+
+    // Get migrations to rollback (in reverse order)
+    const toRollback = this.migrations
+      .filter((m) => m.version > targetVersion && m.version <= currentVersion)
+      .reverse();
+
+    logger.info('Rolling back migrations', { count: toRollback.length });
+
+    for (const migration of toRollback) {
+      const result = await this.runRollback(migration);
+      results.push(result);
+
+      if (!result.success) {
+        logger.error('Rollback failed, stopping', { version: migration.version });
+        break;
+      }
+    }
+
+    return results;
+  }
+
+  /**
+   * Run a single rollback
+   */
+  private async runRollback(migration: Migration): Promise<MigrationResult> {
+    const start = Date.now();
+
+    logger.info('Rolling back migration', {
+      version: migration.version,
+      name: migration.name,
+    });
+
+    try {
+      await this.adapter.transaction(async () => {
+        // Run the down migration
+        await migration.down(this.adapter);
+
+        // Remove the migration record
+        await this.adapter.query(
+          'DELETE FROM schema_versions WHERE version = $1',
+          [migration.version]
+        );
+      });
+
+      const durationMs = Date.now() - start;
+      logger.info('Rollback completed', {
+        version: migration.version,
+        durationMs,
+      });
+
+      return {
+        version: migration.version,
+        name: migration.name,
+        success: true,
+        durationMs,
+      };
+    } catch (error) {
+      const durationMs = Date.now() - start;
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+
+      logger.error('Rollback failed', {
+        version: migration.version,
+        error: errorMessage,
+      });
+
+      return {
+        version: migration.version,
+        name: migration.name,
+        success: false,
+        error: errorMessage,
+        durationMs,
+      };
+    }
+  }
+
+  /**
+   * Compute checksum for a migration
+   */
+  private computeChecksum(migration: Migration): string {
+    // Simple checksum based on function string representation
+    const str = migration.up.toString() + migration.down.toString();
+    let hash = 0;
+    for (let i = 0; i < str.length; i++) {
+      const char = str.charCodeAt(i);
+      hash = ((hash << 5) - hash) + char;
+      hash = hash & hash; // Convert to 32bit integer
+    }
+    return hash.toString(16);
+  }
+
+  /**
+   * Verify migration integrity
+   */
+  async verify(): Promise<{ valid: boolean; issues: string[] }> {
+    const applied = await this.getAppliedMigrations();
+    const issues: string[] = [];
+
+    for (const record of applied) {
+      const migration = this.migrations.find((m) => m.version === record.version);
+
+      if (!migration) {
+        issues.push(`Applied migration v${record.version} not found in registered migrations`);
+        continue;
+      }
+
+      const currentChecksum = this.computeChecksum(migration);
+      if (record.checksum && record.checksum !== currentChecksum) {
+        issues.push(`Migration v${record.version} checksum mismatch (code may have changed)`);
+      }
+    }
+
+    return {
+      valid: issues.length === 0,
+      issues,
+    };
+  }
+}
+
+export default Migrator;

package/src/database/migrations/versions/001_initial.ts

@@ -0,0 +1,198 @@
+/**
+ * Migration 001: Initial Schema
+ *
+ * Creates all core tables for the Family AI Agent system.
+ */
+
+import type { DatabaseAdapter, Migration } from '../../types.js';
+
+export const migration001Initial: Migration = {
+  version: 1,
+  name: 'initial_schema',
+
+  async up(adapter: DatabaseAdapter): Promise<void> {
+    if (adapter.type === 'postgresql') {
+      // Enable pgvector extension
+      await adapter.query('CREATE EXTENSION IF NOT EXISTS vector');
+    }
+
+    // Note: For SQLite, tables are created in sqlite-adapter.ts initialize()
+    // This migration is primarily for PostgreSQL to ensure pgvector is enabled
+
+    if (adapter.type === 'postgresql') {
+      // Create conversations table
+      await adapter.query(`
+        CREATE TABLE IF NOT EXISTS conversations (
+          id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+          thread_id TEXT NOT NULL,
+          user_id TEXT,
+          created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW() NOT NULL,
+          updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW() NOT NULL
+        )
+      `);
+      await adapter.query('CREATE INDEX IF NOT EXISTS idx_conversations_thread ON conversations(thread_id)');
+      await adapter.query('CREATE INDEX IF NOT EXISTS idx_conversations_user ON conversations(user_id)');
+
+      // Create messages table
+      await adapter.query(`
+        CREATE TABLE IF NOT EXISTS messages (
+          id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+          conversation_id UUID NOT NULL REFERENCES conversations(id) ON DELETE CASCADE,
+          role TEXT NOT NULL,
+          content TEXT NOT NULL,
+          metadata JSONB DEFAULT '{}' NOT NULL,
+          created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW() NOT NULL
+        )
+      `);
+      await adapter.query('CREATE INDEX IF NOT EXISTS idx_messages_conversation ON messages(conversation_id)');
+
+      // Create long_term_memories table with pgvector
+      await adapter.query(`
+        CREATE TABLE IF NOT EXISTS long_term_memories (
+          id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+          user_id TEXT,
+          memory_type TEXT NOT NULL,
+          content TEXT NOT NULL,
+          embedding vector(1536) NOT NULL,
+          importance REAL DEFAULT 0.5 NOT NULL,
+          access_count INTEGER DEFAULT 0 NOT NULL,
+          last_accessed TIMESTAMP WITH TIME ZONE,
+          metadata JSONB DEFAULT '{}' NOT NULL,
+          created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW() NOT NULL,
+          updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW() NOT NULL
+        )
+      `);
+      await adapter.query('CREATE INDEX IF NOT EXISTS idx_memories_user ON long_term_memories(user_id)');
+      await adapter.query('CREATE INDEX IF NOT EXISTS idx_memories_type ON long_term_memories(memory_type)');
+      await adapter.query(`
+        CREATE INDEX IF NOT EXISTS idx_memories_embedding
+        ON long_term_memories USING hnsw (embedding vector_cosine_ops)
+      `);
+
+      // Create documents table
+      await adapter.query(`
+        CREATE TABLE IF NOT EXISTS documents (
+          id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+          user_id TEXT,
+          filename TEXT NOT NULL,
+          file_type TEXT,
+          file_size INTEGER,
+          content TEXT,
+          metadata JSONB DEFAULT '{}' NOT NULL,
+          created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW() NOT NULL
+        )
+      `);
+      await adapter.query('CREATE INDEX IF NOT EXISTS idx_documents_user ON documents(user_id)');
+
+      // Create document_chunks table with pgvector
+      await adapter.query(`
+        CREATE TABLE IF NOT EXISTS document_chunks (
+          id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+          document_id UUID NOT NULL REFERENCES documents(id) ON DELETE CASCADE,
+          chunk_index INTEGER NOT NULL,
+          content TEXT NOT NULL,
+          embedding vector(1536) NOT NULL,
+          metadata JSONB DEFAULT '{}' NOT NULL,
+          created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW() NOT NULL
+        )
+      `);
+      await adapter.query('CREATE INDEX IF NOT EXISTS idx_chunks_document ON document_chunks(document_id)');
+      await adapter.query(`
+        CREATE INDEX IF NOT EXISTS idx_chunks_embedding
+        ON document_chunks USING hnsw (embedding vector_cosine_ops)
+      `);
+
+      // Create checkpoints table
+      await adapter.query(`
+        CREATE TABLE IF NOT EXISTS checkpoints (
+          thread_id TEXT NOT NULL,
+          checkpoint_ns TEXT NOT NULL DEFAULT '',
+          checkpoint_id TEXT NOT NULL,
+          parent_checkpoint_id TEXT,
+          type TEXT,
+          checkpoint JSONB NOT NULL,
+          metadata JSONB DEFAULT '{}' NOT NULL,
+          created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW() NOT NULL,
+          PRIMARY KEY (thread_id, checkpoint_ns, checkpoint_id)
+        )
+      `);
+
+      // Create checkpoint_writes table
+      await adapter.query(`
+        CREATE TABLE IF NOT EXISTS checkpoint_writes (
+          thread_id TEXT NOT NULL,
+          checkpoint_ns TEXT NOT NULL DEFAULT '',
+          checkpoint_id TEXT NOT NULL,
+          task_id TEXT NOT NULL,
+          idx INTEGER NOT NULL,
+          channel TEXT NOT NULL,
+          type TEXT,
+          value JSONB,
+          created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW() NOT NULL,
+          PRIMARY KEY (thread_id, checkpoint_ns, checkpoint_id, task_id, idx)
+        )
+      `);
+
+      // Create audit_logs table
+      await adapter.query(`
+        CREATE TABLE IF NOT EXISTS audit_logs (
+          id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+          user_id TEXT,
+          agent_id TEXT,
+          action_type TEXT NOT NULL,
+          action_details JSONB DEFAULT '{}' NOT NULL,
+          input_hash TEXT,
+          output_hash TEXT,
+          status TEXT DEFAULT 'success' NOT NULL,
+          error_message TEXT,
+          execution_time_ms INTEGER,
+          ip_address TEXT,
+          user_agent TEXT,
+          success BOOLEAN DEFAULT true NOT NULL,
+          created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW() NOT NULL
+        )
+      `);
+      await adapter.query('CREATE INDEX IF NOT EXISTS idx_audit_user ON audit_logs(user_id)');
+      await adapter.query('CREATE INDEX IF NOT EXISTS idx_audit_created ON audit_logs(created_at)');
+
+      // Create tasks table
+      await adapter.query(`
+        CREATE TABLE IF NOT EXISTS tasks (
+          id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+          user_id TEXT,
+          task_type TEXT NOT NULL,
+          priority INTEGER DEFAULT 0 NOT NULL,
+          status TEXT DEFAULT 'pending' NOT NULL,
+          payload JSONB DEFAULT '{}' NOT NULL,
+          result JSONB,
+          error_message TEXT,
+          scheduled_at TIMESTAMP WITH TIME ZONE,
+          started_at TIMESTAMP WITH TIME ZONE,
+          completed_at TIMESTAMP WITH TIME ZONE,
+          retry_count INTEGER DEFAULT 0 NOT NULL,
+          max_retries INTEGER DEFAULT 3 NOT NULL,
+          created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW() NOT NULL,
+          updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW() NOT NULL
+        )
+      `);
+      await adapter.query('CREATE INDEX IF NOT EXISTS idx_tasks_status ON tasks(status)');
+      await adapter.query('CREATE INDEX IF NOT EXISTS idx_tasks_user ON tasks(user_id)');
+    }
+  },
+
+  async down(adapter: DatabaseAdapter): Promise<void> {
+    if (adapter.type === 'postgresql') {
+      await adapter.query('DROP TABLE IF EXISTS checkpoint_writes CASCADE');
+      await adapter.query('DROP TABLE IF EXISTS checkpoints CASCADE');
+      await adapter.query('DROP TABLE IF EXISTS document_chunks CASCADE');
+      await adapter.query('DROP TABLE IF EXISTS documents CASCADE');
+      await adapter.query('DROP TABLE IF EXISTS long_term_memories CASCADE');
+      await adapter.query('DROP TABLE IF EXISTS messages CASCADE');
+      await adapter.query('DROP TABLE IF EXISTS conversations CASCADE');
+      await adapter.query('DROP TABLE IF EXISTS audit_logs CASCADE');
+      await adapter.query('DROP TABLE IF EXISTS tasks CASCADE');
+    }
+  },
+};
+
+export default migration001Initial;