circuschief 0.1.0

package/packages/server/src/db/migrations/canvasItemsMigrations.js

@@ -0,0 +1,109 @@
+/**
+ * Migrations for the canvas_items table.
+ * Each export is an array of { name, up(db) } migration objects.
+ */
+import { addColumnIfMissing, getColumns, getTableSql } from './migrationUtils.js';
+
+/**
+ * Migrate canvas_items table to include 'code' in type CHECK constraint.
+ * SQLite doesn't support ALTER TABLE to modify constraints, so we recreate the table.
+ */
+function migrateCanvasItemsTypeConstraint(db) {
+  const tableSql = getTableSql(db, 'canvas_items');
+
+  // If schema already includes 'code', no migration needed
+  if (tableSql?.includes("'code'")) {
+    return;
+  }
+
+  db.exec(`
+    CREATE TABLE canvas_items_new (
+      id TEXT PRIMARY KEY,
+      session_id TEXT REFERENCES sessions(id) ON DELETE CASCADE,
+      type TEXT NOT NULL CHECK (type IN ('image', 'markdown', 'text', 'json', 'pdf', 'code')),
+      content TEXT,
+      data TEXT,
+      mime_type TEXT,
+      filename TEXT,
+      label TEXT,
+      width INTEGER,
+      height INTEGER,
+      created_at INTEGER NOT NULL DEFAULT (unixepoch() * 1000)
+    );
+
+    INSERT INTO canvas_items_new SELECT * FROM canvas_items;
+
+    DROP TABLE canvas_items;
+
+    ALTER TABLE canvas_items_new RENAME TO canvas_items;
+
+    CREATE INDEX IF NOT EXISTS idx_canvas_session ON canvas_items(session_id);
+  `);
+}
+
+/**
+ * Migrate canvas_items table to drop label column.
+ */
+function migrateCanvasItemsDropLabel(db) {
+  const columns = getColumns(db, 'canvas_items');
+
+  // If label column doesn't exist, migration already done
+  if (!columns.includes('label')) {
+    return;
+  }
+
+  db.exec(`
+    CREATE TABLE canvas_items_new (
+      id TEXT PRIMARY KEY,
+      session_id TEXT REFERENCES sessions(id) ON DELETE CASCADE,
+      type TEXT NOT NULL CHECK (type IN ('image', 'markdown', 'text', 'json', 'pdf', 'code')),
+      content TEXT,
+      data TEXT,
+      mime_type TEXT,
+      filename TEXT,
+      width INTEGER,
+      height INTEGER,
+      deleted_at INTEGER,
+      created_at INTEGER NOT NULL DEFAULT (unixepoch() * 1000)
+    );
+
+    INSERT INTO canvas_items_new (id, session_id, type, content, data, mime_type, filename, width, height, deleted_at, created_at)
+    SELECT id, session_id, type, content, data, mime_type, filename, width, height, deleted_at, created_at FROM canvas_items;
+
+    DROP TABLE canvas_items;
+
+    ALTER TABLE canvas_items_new RENAME TO canvas_items;
+
+    CREATE INDEX IF NOT EXISTS idx_canvas_session ON canvas_items(session_id);
+    CREATE INDEX IF NOT EXISTS idx_canvas_deleted ON canvas_items(deleted_at);
+  `);
+}
+
+/** @type {Array<{name: string, up: (db: import('better-sqlite3').Database) => void}>} */
+export const canvasItemsMigrations = [
+  {
+    name: 'canvas_items-migrate-type-constraint',
+    up(db) { migrateCanvasItemsTypeConstraint(db); },
+  },
+  {
+    name: 'canvas_items-add-deleted_at',
+    up(db) {
+      addColumnIfMissing(db, 'canvas_items', 'deleted_at', 'INTEGER');
+      db.exec('CREATE INDEX IF NOT EXISTS idx_canvas_deleted ON canvas_items(deleted_at)');
+    },
+  },
+  {
+    name: 'canvas_items-drop-label',
+    up(db) { migrateCanvasItemsDropLabel(db); },
+  },
+  {
+    name: 'canvas_items-add-updated_at',
+    up(db) {
+      const columns = getColumns(db, 'canvas_items');
+      if (!columns.includes('updated_at')) {
+        db.exec('ALTER TABLE canvas_items ADD COLUMN updated_at INTEGER');
+        db.exec('UPDATE canvas_items SET updated_at = created_at WHERE updated_at IS NULL');
+      }
+    },
+  },
+];

package/packages/server/src/db/migrations/conversationsMigrations.js

@@ -0,0 +1,183 @@
+/**
+ * Migrations for the conversations, conversation_messages, and message_attachments tables.
+ * Each export is an array of { name, up(db) } migration objects.
+ */
+import crypto from 'crypto';
+import { addColumnIfMissing, getColumns } from './migrationUtils.js';
+
+// Table name constants for migrations
+const TABLE_CONVERSATIONS = 'conversations';
+
+// Column type constants
+const COL_INTEGER_DEFAULT_0 = 'INTEGER DEFAULT 0';
+
+/**
+ * Create default conversations for existing sessions that don't have any
+ * and associate orphaned messages with the default conversation.
+ */
+function migrateExistingSessionsToConversations(db) {
+  const sessionsWithoutConversations = db
+    .prepare(
+      `
+      SELECT DISTINCT s.id FROM sessions s
+      LEFT JOIN conversations c ON c.session_id = s.id
+      WHERE c.id IS NULL
+      AND EXISTS (SELECT 1 FROM conversation_messages m WHERE m.session_id = s.id)
+    `
+    )
+    .all();
+
+  for (const session of sessionsWithoutConversations) {
+    const convId = crypto.randomUUID();
+    const now = Date.now();
+
+    db.prepare(
+      `INSERT INTO conversations (id, session_id, name, is_active, created_at, updated_at)
+       VALUES (?, ?, ?, 1, ?, ?)`
+    ).run(convId, session.id, 'Initial', now, now);
+
+    db.prepare(
+      `UPDATE conversation_messages SET conversation_id = ? WHERE session_id = ? AND conversation_id IS NULL`
+    ).run(convId, session.id);
+  }
+}
+
+/** @type {Array<{name: string, up: (db: import('better-sqlite3').Database) => void}>} */
+export const conversationsMigrations = [
+  // --- Session summaries PR columns ---
+  {
+    name: 'session_summaries-add-pr_merged',
+    up(db) { addColumnIfMissing(db, 'session_summaries', 'pr_merged', 'INTEGER'); },
+  },
+  {
+    name: 'session_summaries-add-pr_state',
+    up(db) { addColumnIfMissing(db, 'session_summaries', 'pr_state', 'TEXT'); },
+  },
+  {
+    name: 'session_summaries-add-has_merge_conflicts',
+    up(db) { addColumnIfMissing(db, 'session_summaries', 'has_merge_conflicts', 'INTEGER'); },
+  },
+  {
+    name: 'session_summaries-add-ci_status',
+    up(db) { addColumnIfMissing(db, 'session_summaries', 'ci_status', 'TEXT'); },
+  },
+  {
+    name: 'session_summaries-add-ci_failures',
+    up(db) { addColumnIfMissing(db, 'session_summaries', 'ci_failures', 'TEXT'); },
+  },
+  {
+    name: 'session_summaries-add-last_summarized_message_id',
+    up(db) { addColumnIfMissing(db, 'session_summaries', 'last_summarized_message_id', 'TEXT'); },
+  },
+
+  // --- Message attachments ---
+  {
+    name: 'message_attachments-add-file_path',
+    up(db) { addColumnIfMissing(db, 'message_attachments', 'file_path', 'TEXT'); },
+  },
+
+  // --- Conversation messages: conversation_id ---
+  {
+    name: 'conversation_messages-add-conversation_id',
+    up(db) {
+      const columns = getColumns(db, 'conversation_messages');
+      if (!columns.includes('conversation_id')) {
+        db.exec(
+          'ALTER TABLE conversation_messages ADD COLUMN conversation_id TEXT REFERENCES conversations(id) ON DELETE CASCADE'
+        );
+        db.exec(
+          'CREATE INDEX IF NOT EXISTS idx_messages_conversation ON conversation_messages(conversation_id)'
+        );
+      }
+    },
+  },
+
+  // --- Migrate existing sessions to conversations ---
+  {
+    name: 'conversations-migrate-existing-sessions',
+    up(db) { migrateExistingSessionsToConversations(db); },
+  },
+
+  // --- Conversations: claude_session_id ---
+  {
+    name: 'conversations-add-claude_session_id',
+    up(db) { addColumnIfMissing(db, TABLE_CONVERSATIONS, 'claude_session_id', 'TEXT'); },
+  },
+
+  // --- Conversations token usage ---
+  {
+    name: 'conversations-add-input_tokens',
+    up(db) { addColumnIfMissing(db, TABLE_CONVERSATIONS, 'input_tokens', COL_INTEGER_DEFAULT_0); },
+  },
+  {
+    name: 'conversations-add-output_tokens',
+    up(db) { addColumnIfMissing(db, TABLE_CONVERSATIONS, 'output_tokens', COL_INTEGER_DEFAULT_0); },
+  },
+  {
+    name: 'conversations-add-cache_read_input_tokens',
+    up(db) { addColumnIfMissing(db, TABLE_CONVERSATIONS, 'cache_read_input_tokens', COL_INTEGER_DEFAULT_0); },
+  },
+  {
+    name: 'conversations-add-cache_creation_input_tokens',
+    up(db) { addColumnIfMissing(db, TABLE_CONVERSATIONS, 'cache_creation_input_tokens', COL_INTEGER_DEFAULT_0); },
+  },
+  {
+    name: 'conversations-add-web_search_requests',
+    up(db) { addColumnIfMissing(db, TABLE_CONVERSATIONS, 'web_search_requests', COL_INTEGER_DEFAULT_0); },
+  },
+  {
+    name: 'conversations-add-context_window',
+    up(db) { addColumnIfMissing(db, TABLE_CONVERSATIONS, 'context_window', 'INTEGER DEFAULT 200000'); },
+  },
+  {
+    name: 'conversations-add-model',
+    up(db) { addColumnIfMissing(db, TABLE_CONVERSATIONS, 'model', 'TEXT'); },
+  },
+
+  // --- Conversation branching ---
+  {
+    name: 'conversations-add-parent_conversation_id',
+    up(db) {
+      const columns = getColumns(db, TABLE_CONVERSATIONS);
+      if (!columns.includes('parent_conversation_id')) {
+        db.exec(
+          'ALTER TABLE conversations ADD COLUMN parent_conversation_id TEXT REFERENCES conversations(id) ON DELETE SET NULL'
+        );
+        db.exec(
+          'CREATE INDEX IF NOT EXISTS idx_conversations_parent ON conversations(parent_conversation_id)'
+        );
+      }
+    },
+  },
+  {
+    name: 'conversations-add-branch_from_message_id',
+    up(db) {
+      addColumnIfMissing(
+        db, TABLE_CONVERSATIONS, 'branch_from_message_id',
+        'TEXT REFERENCES conversation_messages(id) ON DELETE SET NULL'
+      );
+    },
+  },
+
+  // --- Session todos: conversation_id ---
+  {
+    name: 'session_todos-add-conversation_id',
+    up(db) {
+      const columns = getColumns(db, 'session_todos');
+      if (!columns.includes('conversation_id')) {
+        db.exec(
+          'ALTER TABLE session_todos ADD COLUMN conversation_id TEXT REFERENCES conversations(id) ON DELETE CASCADE'
+        );
+        db.exec(
+          'CREATE INDEX IF NOT EXISTS idx_todos_conversation ON session_todos(conversation_id)'
+        );
+      }
+    },
+  },
+
+  // --- Conversation messages: model ---
+  {
+    name: 'conversation_messages-add-model',
+    up(db) { addColumnIfMissing(db, 'conversation_messages', 'model', 'TEXT'); },
+  },
+];

package/packages/server/src/db/migrations/index.js

@@ -0,0 +1,199 @@
+/**
+ * Central registry of all database migrations in execution order.
+ *
+ * Each migration is idempotent (checks before acting), so the exact ordering
+ * only matters where there are hard dependencies (e.g. a table must exist
+ * before a column references it via FK).
+ *
+ * The ordering below mirrors the original #runMigrations() top-to-bottom flow
+ * as closely as possible.
+ */
+import { sessionsMigrations } from './sessionsMigrations.js';
+import { projectsMigrations } from './projectsMigrations.js';
+import { conversationsMigrations } from './conversationsMigrations.js';
+import { canvasItemsMigrations } from './canvasItemsMigrations.js';
+import { miscMigrations } from './miscMigrations.js';
+import { kanbanMigrations } from './kanbanMigrations.js';
+
+/**
+ * Build a lookup map from a migrations array keyed by migration name.
+ * @param {Array<{name: string, up: Function}>} migrations
+ * @returns {Map<string, {name: string, up: Function}>}
+ */
+function toLookup(migrations) {
+  const map = new Map();
+  for (const m of migrations) {
+    map.set(m.name, m);
+  }
+  return map;
+}
+
+const s = toLookup(sessionsMigrations);
+const p = toLookup(projectsMigrations);
+const c = toLookup(conversationsMigrations);
+const ci = toLookup(canvasItemsMigrations);
+const m = toLookup(miscMigrations);
+const k = toLookup(kanbanMigrations);
+
+/**
+ * Flat, ordered list of every migration, matching the original execution order
+ * from DatabaseManager.#runMigrations().
+ *
+ * @type {Array<{name: string, up: (db: import('better-sqlite3').Database) => void}>}
+ */
+// Validate that all migrations are properly defined
+function validateMigrations(migrationsArray) {
+  for (const migration of migrationsArray) {
+    if (!migration || typeof migration.up !== 'function') {
+      const name = migration?.name || 'unknown';
+      throw new Error(`Migration "${name}" is undefined or missing an up() function`);
+    }
+  }
+  return migrationsArray;
+}
+
+export const allMigrations = validateMigrations([
+  // --- Sessions initial columns ---
+  s.get('sessions-add-cost_usd'),
+  s.get('sessions-add-claude_session_id'),
+  s.get('sessions-add-model'),
+  s.get('sessions-add-provider_id-early'),
+  s.get('sessions-add-effort_level'),
+
+  // --- Projects columns ---
+  p.get('projects-add-system_prompt'),
+  p.get('projects-add-on_session_created'),
+  p.get('projects-add-on_session_deleted'),
+  p.get('projects-add-repo_url'),
+  p.get('projects-drop-summary-columns'),
+
+  // --- Sessions scheduling columns ---
+  s.get('sessions-add-scheduled_at'),
+  s.get('sessions-add-reschedule_delay_minutes'),
+  s.get('sessions-add-auto_reschedule_enabled'),
+  s.get('sessions-add-reschedule_on_token_limit'),
+  s.get('sessions-add-reschedule_on_service_error'),
+  s.get('sessions-add-max_reschedule_count'),
+  s.get('sessions-add-max_total_tokens'),
+  s.get('sessions-add-reschedule_count'),
+  s.get('sessions-add-reschedule_at_token_count'),
+
+  // --- Sessions status constraint migration (table recreation) ---
+  s.get('sessions-migrate-status-constraint'),
+
+  // --- Session summaries PR columns ---
+  c.get('session_summaries-add-pr_merged'),
+  c.get('session_summaries-add-pr_state'),
+  c.get('session_summaries-add-has_merge_conflicts'),
+  c.get('session_summaries-add-ci_status'),
+  c.get('session_summaries-add-ci_failures'),
+  c.get('session_summaries-add-last_summarized_message_id'),
+
+  // --- Sessions template chaining ---
+  s.get('sessions-add-next_template_id'),
+  s.get('sessions-add-parent_session_id'),
+  s.get('sessions-template-chaining-indexes'),
+
+  // --- Message attachments ---
+  c.get('message_attachments-add-file_path'),
+
+  // --- Conversation messages: conversation_id ---
+  c.get('conversation_messages-add-conversation_id'),
+
+  // --- Migrate existing sessions to conversations ---
+  c.get('conversations-migrate-existing-sessions'),
+
+  // --- Canvas items ---
+  ci.get('canvas_items-migrate-type-constraint'),
+  ci.get('canvas_items-add-deleted_at'),
+  ci.get('canvas_items-drop-label'),
+  ci.get('canvas_items-add-updated_at'),
+
+  // --- Conversations: claude_session_id + token usage ---
+  c.get('conversations-add-claude_session_id'),
+  c.get('conversations-add-input_tokens'),
+  c.get('conversations-add-output_tokens'),
+  c.get('conversations-add-cache_read_input_tokens'),
+  c.get('conversations-add-cache_creation_input_tokens'),
+  c.get('conversations-add-web_search_requests'),
+  c.get('conversations-add-context_window'),
+  c.get('conversations-add-model'),
+
+  // --- Sessions token usage ---
+  s.get('sessions-add-input_tokens'),
+  s.get('sessions-add-output_tokens'),
+  s.get('sessions-add-cache_read_input_tokens'),
+  s.get('sessions-add-cache_creation_input_tokens'),
+  s.get('sessions-add-web_search_requests'),
+  s.get('sessions-add-context_window'),
+
+  // --- Sessions archived / starred / manually_named ---
+  s.get('sessions-add-archived'),
+  s.get('sessions-add-starred'),
+  s.get('sessions-add-manually_named'),
+
+  // --- Project session defaults table ---
+  p.get('project_session_defaults-create-table'),
+
+  // --- Command buttons ---
+  m.get('command_buttons-add-show_on_list'),
+
+  // --- Session todos ---
+  c.get('session_todos-add-conversation_id'),
+
+  // --- Conversation branching ---
+  c.get('conversations-add-parent_conversation_id'),
+  c.get('conversations-add-branch_from_message_id'),
+
+  // --- Sessions pending prompt / slash commands / pending model / auto send ---
+  s.get('sessions-add-pending_prompt'),
+  s.get('sessions-add-slash_commands'),
+  s.get('sessions-add-pending_model'),
+  s.get('sessions-add-auto_send_pending_prompt'),
+
+  // --- Session templates ---
+  m.get('session_templates-add-model'),
+  m.get('session_templates-add-mode'),
+  m.get('session_templates-add-effort_level'),
+
+  // --- Conversation messages model ---
+  c.get('conversation_messages-add-model'),
+
+  // --- App settings table ---
+  m.get('app_settings-create-table'),
+
+  // --- Legacy model_providers cleanup ---
+  m.get('model_providers-cleanup-legacy'),
+
+  // --- Providers + provider_models tables + seed ---
+  m.get('providers-create-tables'),
+  m.get('providers-seed-built-in'),
+
+  // --- Sessions provider_id (from providers FK) ---
+  s.get('sessions-add-provider_id-from-providers'),
+
+  // --- Project session defaults provider_id / effort_level ---
+  p.get('project_session_defaults-add-provider_id'),
+  p.get('project_session_defaults-add-effort_level'),
+
+  // --- Update built-in models ---
+  m.get('providers-update-built-in-models'),
+
+  // --- Sessions agent_type ---
+  s.get('sessions-add-agent_type'),
+
+  // --- Agent call logs table ---
+  m.get('agent_call_logs-create-table'),
+
+  // --- Kanban feature ---
+  k.get('projects-add-kanban_enabled'),
+  k.get('kanban-create-tables'),
+  k.get('sessions-add-target_lane_id'),
+  k.get('sessions-add-lane_trigger_depth'),
+  k.get('session_templates-add-target_lane_id'),
+  k.get('kanban_lanes-add-on_enter_prompt'),
+  k.get('kanban_lanes-add-agent-settings'),
+
+  // --- Seed default global quick responses ---
+  m.get('quick_responses-seed-defaults'),
+]);

package/packages/server/src/db/migrations/kanbanMigrations.js

@@ -0,0 +1,99 @@
+/**
+ * Migrations for Kanban board feature: kanban_boards, kanban_lanes,
+ * kanban_cards, kanban_card_sessions tables, and related columns on
+ * projects, sessions, and session_templates.
+ */
+import { addColumnIfMissing } from './migrationUtils.js';
+
+export const kanbanMigrations = [
+  {
+    name: 'projects-add-kanban_enabled',
+    up(db) {
+      addColumnIfMissing(db, 'projects', 'kanban_enabled', 'INTEGER NOT NULL DEFAULT 1');
+    },
+  },
+  {
+    name: 'kanban-create-tables',
+    up(db) {
+      db.exec(`
+        CREATE TABLE IF NOT EXISTS kanban_boards (
+          id TEXT PRIMARY KEY,
+          project_id TEXT NOT NULL UNIQUE REFERENCES projects(id) ON DELETE CASCADE,
+          created_at INTEGER NOT NULL DEFAULT (unixepoch() * 1000),
+          updated_at INTEGER NOT NULL DEFAULT (unixepoch() * 1000)
+        );
+
+        CREATE TABLE IF NOT EXISTS kanban_lanes (
+          id TEXT PRIMARY KEY,
+          board_id TEXT NOT NULL REFERENCES kanban_boards(id) ON DELETE CASCADE,
+          name TEXT NOT NULL,
+          sort_order INTEGER NOT NULL DEFAULT 0,
+          on_enter_template_id TEXT REFERENCES session_templates(id) ON DELETE SET NULL,
+          created_at INTEGER NOT NULL DEFAULT (unixepoch() * 1000),
+          updated_at INTEGER NOT NULL DEFAULT (unixepoch() * 1000)
+        );
+
+        CREATE TABLE IF NOT EXISTS kanban_cards (
+          id TEXT PRIMARY KEY,
+          lane_id TEXT NOT NULL REFERENCES kanban_lanes(id) ON DELETE CASCADE,
+          sort_order INTEGER NOT NULL DEFAULT 0,
+          created_at INTEGER NOT NULL DEFAULT (unixepoch() * 1000),
+          updated_at INTEGER NOT NULL DEFAULT (unixepoch() * 1000)
+        );
+
+        CREATE TABLE IF NOT EXISTS kanban_card_sessions (
+          id TEXT PRIMARY KEY,
+          card_id TEXT NOT NULL REFERENCES kanban_cards(id) ON DELETE CASCADE,
+          session_id TEXT NOT NULL UNIQUE REFERENCES sessions(id) ON DELETE CASCADE,
+          created_at INTEGER NOT NULL DEFAULT (unixepoch() * 1000)
+        );
+
+        CREATE INDEX IF NOT EXISTS idx_kanban_boards_project ON kanban_boards(project_id);
+        CREATE INDEX IF NOT EXISTS idx_kanban_lanes_board ON kanban_lanes(board_id, sort_order);
+        CREATE INDEX IF NOT EXISTS idx_kanban_cards_lane ON kanban_cards(lane_id, sort_order);
+        CREATE INDEX IF NOT EXISTS idx_kanban_card_sessions_session ON kanban_card_sessions(session_id);
+        CREATE INDEX IF NOT EXISTS idx_kanban_card_sessions_card ON kanban_card_sessions(card_id);
+      `);
+    },
+  },
+  {
+    name: 'sessions-add-target_lane_id',
+    up(db) {
+      addColumnIfMissing(db, 'sessions', 'target_lane_id', 'TEXT REFERENCES kanban_lanes(id) ON DELETE SET NULL');
+    },
+  },
+  {
+    name: 'sessions-add-lane_trigger_depth',
+    up(db) {
+      addColumnIfMissing(db, 'sessions', 'lane_trigger_depth', 'INTEGER NOT NULL DEFAULT 0');
+    },
+  },
+  {
+    name: 'session_templates-add-target_lane_id',
+    up(db) {
+      addColumnIfMissing(db, 'session_templates', 'target_lane_id', 'TEXT REFERENCES kanban_lanes(id) ON DELETE SET NULL');
+    },
+  },
+  {
+    name: 'kanban_lanes-add-on_enter_prompt',
+    up(db) {
+      addColumnIfMissing(db, 'kanban_lanes', 'on_enter_prompt', 'TEXT');
+    },
+  },
+  {
+    name: 'kanban_lanes-add-agent-settings',
+    up(db) {
+      addColumnIfMissing(db, 'kanban_lanes', 'on_enter_mode', 'TEXT');
+      addColumnIfMissing(db, 'kanban_lanes', 'on_enter_model', 'TEXT');
+      addColumnIfMissing(db, 'kanban_lanes', 'on_enter_effort_level', 'TEXT');
+      addColumnIfMissing(db, 'kanban_lanes', 'on_enter_thinking_enabled', 'INTEGER');
+      addColumnIfMissing(db, 'kanban_lanes', 'on_enter_auto_reschedule_enabled', 'INTEGER DEFAULT 0');
+      addColumnIfMissing(db, 'kanban_lanes', 'on_enter_reschedule_delay_minutes', 'INTEGER DEFAULT 15');
+      addColumnIfMissing(db, 'kanban_lanes', 'on_enter_reschedule_on_token_limit', 'INTEGER DEFAULT 1');
+      addColumnIfMissing(db, 'kanban_lanes', 'on_enter_reschedule_on_service_error', 'INTEGER DEFAULT 1');
+      addColumnIfMissing(db, 'kanban_lanes', 'on_enter_max_reschedule_count', 'INTEGER');
+      addColumnIfMissing(db, 'kanban_lanes', 'on_enter_max_total_tokens', 'INTEGER');
+      addColumnIfMissing(db, 'kanban_lanes', 'on_enter_reschedule_at_token_count', 'INTEGER');
+    },
+  },
+];

package/packages/server/src/db/migrations/migrationUtils.js

@@ -0,0 +1,55 @@
+/**
+ * Utility helpers shared by migration modules.
+ *
+ * These helpers keep each migration definition concise and avoid repeating
+ * the same PRAGMA + includes() pattern in every single migration object.
+ */
+
+/**
+ * Return the column names for a given table.
+ * @param {import('better-sqlite3').Database} db
+ * @param {string} table
+ * @returns {string[]}
+ */
+export function getColumns(db, table) {
+  return db.prepare(`PRAGMA table_info(${table})`).all().map((col) => col.name);
+}
+
+/**
+ * Add a column to a table only when it does not already exist.
+ * @param {import('better-sqlite3').Database} db
+ * @param {string} table
+ * @param {string} column
+ * @param {string} definition  e.g. "TEXT", "INTEGER DEFAULT 0"
+ */
+export function addColumnIfMissing(db, table, column, definition) {
+  const columns = getColumns(db, table);
+  if (!columns.includes(column)) {
+    db.exec(`ALTER TABLE ${table} ADD COLUMN ${column} ${definition}`);
+  }
+}
+
+/**
+ * Check whether a given table exists in the database.
+ * @param {import('better-sqlite3').Database} db
+ * @param {string} table
+ * @returns {boolean}
+ */
+export function tableExists(db, table) {
+  return Boolean(db
+    .prepare("SELECT name FROM sqlite_master WHERE type='table' AND name=?")
+    .get(table));
+}
+
+/**
+ * Get the CREATE TABLE SQL for a table from sqlite_master.
+ * @param {import('better-sqlite3').Database} db
+ * @param {string} table
+ * @returns {string|undefined}
+ */
+export function getTableSql(db, table) {
+  const row = db
+    .prepare("SELECT sql FROM sqlite_master WHERE type='table' AND name=?")
+    .get(table);
+  return row?.sql;
+}