trekoon 0.1.2 → 0.1.5

package/src/storage/migrations.ts

@@ -2,10 +2,142 @@ import { Database } from "bun:sqlite";
 
 import { BASE_SCHEMA_STATEMENTS, SCHEMA_VERSION } from "./schema";
 
+const BASE_MIGRATION_VERSION = 1;
 const BASE_MIGRATION_NAME = `0001_base_schema_v${SCHEMA_VERSION}`;
+const LEGACY_BASE_MIGRATION_NAME_PATTERNS: readonly string[] = [
+  "0001_base_schema_v*",
+];
 
-function hasMigration(db: Database, name: string): boolean {
-  const migrationTableExists: { count: number } | null = db
+const BASE_ROLLBACK_STATEMENTS: readonly string[] = [
+  "DROP TABLE IF EXISTS sync_conflicts;",
+  "DROP TABLE IF EXISTS sync_cursors;",
+  "DROP TABLE IF EXISTS git_context;",
+  "DROP TABLE IF EXISTS events;",
+  "DROP TABLE IF EXISTS dependencies;",
+  "DROP TABLE IF EXISTS subtasks;",
+  "DROP TABLE IF EXISTS tasks;",
+  "DROP TABLE IF EXISTS epics;",
+];
+
+const INDEX_MIGRATION_UP_STATEMENTS: readonly string[] = [
+  "CREATE INDEX IF NOT EXISTS idx_events_created_at ON events(created_at);",
+  "CREATE INDEX IF NOT EXISTS idx_events_git_branch ON events(git_branch);",
+  "CREATE INDEX IF NOT EXISTS idx_events_created_at_id ON events(created_at, id);",
+  "CREATE INDEX IF NOT EXISTS idx_dependencies_source ON dependencies(source_id);",
+  "CREATE INDEX IF NOT EXISTS idx_dependencies_depends_on ON dependencies(depends_on_id);",
+];
+
+const INDEX_MIGRATION_DOWN_STATEMENTS: readonly string[] = [
+  "DROP INDEX IF EXISTS idx_events_created_at;",
+  "DROP INDEX IF EXISTS idx_events_git_branch;",
+  "DROP INDEX IF EXISTS idx_events_created_at_id;",
+  "DROP INDEX IF EXISTS idx_dependencies_source;",
+  "DROP INDEX IF EXISTS idx_dependencies_depends_on;",
+];
+
+const EVENT_ARCHIVE_MIGRATION_UP_STATEMENTS: readonly string[] = [
+  `
+  CREATE TABLE IF NOT EXISTS event_archive (
+    id TEXT PRIMARY KEY,
+    entity_kind TEXT NOT NULL,
+    entity_id TEXT NOT NULL,
+    operation TEXT NOT NULL,
+    payload TEXT NOT NULL,
+    git_branch TEXT,
+    git_head TEXT,
+    created_at INTEGER NOT NULL,
+    updated_at INTEGER NOT NULL,
+    version INTEGER NOT NULL DEFAULT 1
+  );
+  `,
+  "CREATE INDEX IF NOT EXISTS idx_event_archive_created_at ON event_archive(created_at);",
+];
+
+const EVENT_ARCHIVE_MIGRATION_DOWN_STATEMENTS: readonly string[] = [
+  "DROP INDEX IF EXISTS idx_event_archive_created_at;",
+  "DROP TABLE IF EXISTS event_archive;",
+];
+
+interface Migration {
+  readonly version: number;
+  readonly name: string;
+  up(db: Database): void;
+  down(db: Database): void;
+}
+
+interface AppliedMigrationRow {
+  readonly version: number;
+  readonly name: string;
+  readonly applied_at: number;
+}
+
+export interface AppliedMigration {
+  readonly version: number;
+  readonly name: string;
+  readonly appliedAt: number;
+}
+
+export interface MigrationStatus {
+  readonly currentVersion: number;
+  readonly latestVersion: number;
+  readonly applied: readonly AppliedMigration[];
+  readonly pending: ReadonlyArray<{ version: number; name: string }>;
+}
+
+export interface RollbackSummary {
+  readonly fromVersion: number;
+  readonly toVersion: number;
+  readonly rolledBack: number;
+  readonly rolledBackMigrations: readonly string[];
+}
+
+const MIGRATIONS: readonly Migration[] = [
+  {
+    version: BASE_MIGRATION_VERSION,
+    name: BASE_MIGRATION_NAME,
+    up(db: Database): void {
+      for (const statement of BASE_SCHEMA_STATEMENTS) {
+        db.exec(statement);
+      }
+    },
+    down(db: Database): void {
+      for (const statement of BASE_ROLLBACK_STATEMENTS) {
+        db.exec(statement);
+      }
+    },
+  },
+  {
+    version: 2,
+    name: "0002_sync_dependency_indexes",
+    up(db: Database): void {
+      for (const statement of INDEX_MIGRATION_UP_STATEMENTS) {
+        db.exec(statement);
+      }
+    },
+    down(db: Database): void {
+      for (const statement of INDEX_MIGRATION_DOWN_STATEMENTS) {
+        db.exec(statement);
+      }
+    },
+  },
+  {
+    version: 3,
+    name: "0003_event_archive_retention",
+    up(db: Database): void {
+      for (const statement of EVENT_ARCHIVE_MIGRATION_UP_STATEMENTS) {
+        db.exec(statement);
+      }
+    },
+    down(db: Database): void {
+      for (const statement of EVENT_ARCHIVE_MIGRATION_DOWN_STATEMENTS) {
+        db.exec(statement);
+      }
+    },
+  },
+];
+
+function migrationTableExists(db: Database): boolean {
+  const row = db
     .query(
       `
       SELECT COUNT(*) AS count
@@ -15,32 +147,221 @@ function hasMigration(db: Database, name: string): boolean {
     )
     .get() as { count: number } | null;
 
-  if (!migrationTableExists || migrationTableExists.count === 0) {
-    return false;
+  return (row?.count ?? 0) > 0;
+}
+
+function hasMigrationVersionColumn(db: Database): boolean {
+  const columns = db.query("PRAGMA table_info(schema_migrations);").all() as Array<{ name: string }>;
+  return columns.some((column) => column.name === "version");
+}
+
+function ensureMigrationTable(db: Database): void {
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS schema_migrations (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      version INTEGER NOT NULL UNIQUE,
+      name TEXT NOT NULL UNIQUE,
+      applied_at INTEGER NOT NULL
+    );
+  `);
+}
+
+function ensureMigrationVersionColumn(db: Database): void {
+  if (!migrationTableExists(db) || hasMigrationVersionColumn(db)) {
+    return;
+  }
+
+  db.exec("ALTER TABLE schema_migrations ADD COLUMN version INTEGER;");
+  db.query("UPDATE schema_migrations SET version = ? WHERE version IS NULL AND name = ?;").run(BASE_MIGRATION_VERSION, BASE_MIGRATION_NAME);
+
+  for (const legacyPattern of LEGACY_BASE_MIGRATION_NAME_PATTERNS) {
+    db.query("UPDATE schema_migrations SET version = ? WHERE version IS NULL AND name GLOB ?;").run(
+      BASE_MIGRATION_VERSION,
+      legacyPattern,
+    );
+  }
+
+  db.exec("CREATE UNIQUE INDEX IF NOT EXISTS idx_schema_migrations_version ON schema_migrations(version);");
+
+  const unresolvedRow = db
+    .query(
+      `
+      SELECT COUNT(*) AS count
+      FROM schema_migrations
+      WHERE version IS NULL;
+      `,
+    )
+    .get() as { count: number } | null;
+
+  if ((unresolvedRow?.count ?? 0) > 0) {
+    throw new Error(
+      "Unable to infer one or more schema_migrations.version values during legacy upgrade. Repair schema_migrations entries manually so every row has a valid version, then rerun migrations.",
+    );
+  }
+}
+
+function validateMigrationPlan(): void {
+  const seen = new Set<number>();
+
+  for (let index = 0; index < MIGRATIONS.length; index += 1) {
+    const migration: Migration = MIGRATIONS[index]!;
+
+    if (migration.version !== index + 1) {
+      throw new Error(`Migration versions must be contiguous from 1 (found ${migration.version} at index ${index}).`);
+    }
+
+    if (seen.has(migration.version)) {
+      throw new Error(`Duplicate migration version ${migration.version}.`);
+    }
+
+    seen.add(migration.version);
+  }
+}
+
+function runExclusive<T>(db: Database, operation: () => T): T {
+  db.exec("BEGIN EXCLUSIVE TRANSACTION;");
+
+  try {
+    const result: T = operation();
+    db.exec("COMMIT;");
+    return result;
+  } catch (error: unknown) {
+    db.exec("ROLLBACK;");
+    throw error;
+  }
+}
+
+function currentVersion(db: Database): number {
+  if (!migrationTableExists(db)) {
+    return 0;
   }
 
-  const row: { count: number } | null = db
-    .query("SELECT COUNT(*) AS count FROM schema_migrations WHERE name = ?;")
-    .get(name) as { count: number } | null;
+  const row = db
+    .query("SELECT COALESCE(MAX(version), 0) AS version FROM schema_migrations;")
+    .get() as { version: number } | null;
 
-  return Boolean(row && row.count > 0);
+  return row?.version ?? 0;
+}
+
+function listAppliedMigrations(db: Database): AppliedMigrationRow[] {
+  if (!migrationTableExists(db)) {
+    return [];
+  }
+
+  return db
+    .query(
+      `
+      SELECT version, name, applied_at
+      FROM schema_migrations
+      WHERE version IS NOT NULL
+      ORDER BY version ASC;
+      `,
+    )
+    .all() as AppliedMigrationRow[];
+}
+
+function migrationForVersion(version: number): Migration {
+  const found = MIGRATIONS.find((migration) => migration.version === version);
+
+  if (!found) {
+    throw new Error(`No migration definition found for version ${version}.`);
+  }
+
+  return found;
+}
+
+function recordMigration(db: Database, migration: Migration): void {
+  db.query("INSERT INTO schema_migrations (version, name, applied_at) VALUES (?, ?, ?);").run(
+    migration.version,
+    migration.name,
+    Date.now(),
+  );
 }
 
 export function migrateDatabase(db: Database): void {
-  if (hasMigration(db, BASE_MIGRATION_NAME)) {
-    return;
+  runExclusive(db, (): void => {
+    ensureMigrationTable(db);
+    ensureMigrationVersionColumn(db);
+    validateMigrationPlan();
+
+    const version: number = currentVersion(db);
+
+    for (const migration of MIGRATIONS) {
+      if (migration.version <= version) {
+        continue;
+      }
+
+      migration.up(db);
+      recordMigration(db, migration);
+    }
+  });
+}
+
+export function describeMigrations(db: Database): MigrationStatus {
+  ensureMigrationTable(db);
+  ensureMigrationVersionColumn(db);
+  validateMigrationPlan();
+
+  const appliedRows: AppliedMigrationRow[] = listAppliedMigrations(db);
+  const latestVersion: number = MIGRATIONS[MIGRATIONS.length - 1]?.version ?? 0;
+  const activeVersion: number = appliedRows[appliedRows.length - 1]?.version ?? 0;
+  const appliedVersions = new Set(appliedRows.map((row) => row.version));
+
+  return {
+    currentVersion: activeVersion,
+    latestVersion,
+    applied: appliedRows.map((row) => ({
+      version: row.version,
+      name: row.name,
+      appliedAt: row.applied_at,
+    })),
+    pending: MIGRATIONS.filter((migration) => !appliedVersions.has(migration.version)).map((migration) => ({
+      version: migration.version,
+      name: migration.name,
+    })),
+  };
+}
+
+export function rollbackDatabase(db: Database, targetVersion: number): RollbackSummary {
+  if (!Number.isInteger(targetVersion) || targetVersion < 0) {
+    throw new Error("Rollback target version must be a non-negative integer.");
   }
 
-  const now: number = Date.now();
+  return runExclusive(db, (): RollbackSummary => {
+    ensureMigrationTable(db);
+    ensureMigrationVersionColumn(db);
+    validateMigrationPlan();
 
-  db.transaction((): void => {
-    for (const statement of BASE_SCHEMA_STATEMENTS) {
-      db.exec(statement);
+    const fromVersion: number = currentVersion(db);
+    if (targetVersion > fromVersion) {
+      throw new Error(`Cannot roll back to version ${targetVersion}; current version is ${fromVersion}.`);
     }
 
-    db.query("INSERT INTO schema_migrations (name, applied_at) VALUES (?, ?);").run(
-      BASE_MIGRATION_NAME,
-      now,
-    );
-  })();
+    const appliedDescending = db
+      .query(
+        `
+        SELECT version, name, applied_at
+        FROM schema_migrations
+        WHERE version IS NOT NULL AND version > ?
+        ORDER BY version DESC;
+        `,
+      )
+      .all(targetVersion) as AppliedMigrationRow[];
+
+    const rolledBackMigrations: string[] = [];
+
+    for (const row of appliedDescending) {
+      const migration: Migration = migrationForVersion(row.version);
+      migration.down(db);
+      db.query("DELETE FROM schema_migrations WHERE version = ?;").run(row.version);
+      rolledBackMigrations.push(migration.name);
+    }
+
+    return {
+      fromVersion,
+      toVersion: targetVersion,
+      rolledBack: appliedDescending.length,
+      rolledBackMigrations,
+    };
+  });
 }

package/src/storage/schema.ts

@@ -5,6 +5,7 @@ export const BASE_SCHEMA_STATEMENTS: readonly string[] = [
   `
   CREATE TABLE IF NOT EXISTS schema_migrations (
     id INTEGER PRIMARY KEY AUTOINCREMENT,
+    version INTEGER NOT NULL UNIQUE,
     name TEXT NOT NULL UNIQUE,
     applied_at INTEGER NOT NULL
   );

package/src/storage/types.ts

@@ -6,6 +6,7 @@ export interface MutableRow {
 
 export interface MigrationRecord {
   readonly id: number;
+  readonly version: number;
   readonly name: string;
   readonly applied_at: number;
 }

package/src/sync/service.ts

@@ -41,11 +41,19 @@ interface EventPayload {
   readonly fields?: Record<string, unknown>;
 }
 
+function isObjectRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
 function parsePayload(rawPayload: string): EventPayload {
   try {
     const parsed: unknown = JSON.parse(rawPayload);
 
-    if (typeof parsed === "object" && parsed !== null) {
+    if (isObjectRecord(parsed)) {
+      if ("fields" in parsed && !isObjectRecord(parsed.fields)) {
+        return {};
+      }
+
       return parsed as EventPayload;
     }
   } catch {