@andypai/agent-kanban 0.6.0 → 0.6.1

package/src/providers/jira.ts

@@ -1,35 +1,8 @@
 import type { Database } from 'bun:sqlite'
-import { ErrorCode, KanbanError } from '../errors'
-import type {
-  ActivityEntry,
-  BoardBootstrap,
-  BoardConfig,
-  BoardMetrics,
-  BoardView,
-  Column,
-  Priority,
-  TaskComment,
-  Task,
-} from '../types'
-import {
-  headerLower,
-  verifySha256HmacSignatureHeader,
-  type WebhookRequest,
-  type WebhookResult,
-} from '../webhooks'
-import { adfToPlainText, plainTextToAdf, type AdfDocument } from './jira-adf'
-import { JIRA_CAPABILITIES } from './capabilities'
-import { providerUpstreamError, unsupportedOperation } from './errors'
-import {
-  JiraClient,
-  decideJiraPagination,
-  normalizeJiraLabels,
-  type JiraComment,
-  type JiraIssue,
-} from './jira-client'
+import type { BoardView, ProviderTeamInfo, Task } from '../types'
+import type { JiraClient } from './jira-client'
 import {
   adjustJiraIssueCommentCount,
-  decodeColumnStatusIds,
   deleteJiraIssue,
   getCachedActivity,
   getCachedBoard,
@@ -38,8 +11,6 @@ import {
   getCachedTask,
   getCachedTasks,
   initJiraCacheSchema,
-  jiraBoardColumnRows,
-  resolveJiraColumnId,
   loadJiraSyncMeta,
   loadTeamInfo,
   pruneJiraIssuesMissingUpstream,
@@ -52,799 +23,180 @@ import {
   upsertJiraIssues,
   upsertJiraUsers,
   type JiraActivityRow,
+  type JiraCacheConfig,
+  type JiraColumnRow,
   type JiraSyncMeta,
 } from './jira-cache'
-import type {
-  CreateTaskInput,
-  KanbanProvider,
-  ProviderContext,
-  ProviderSyncStatus,
-  TaskListFilters,
-  UpdateTaskInput,
-} from './types'
-import { DEFAULT_POLLING_SYNC_INTERVAL_MS } from '../sync-config'
+import { JiraProviderCore, type JiraCachePort, type JiraProviderConfig } from './jira-core'
 
-const FULL_RECONCILE_INTERVAL_MS = 5 * 60_000
-
-function shouldRunFullReconcile(lastFullSyncAt: string | null, now: number): boolean {
-  if (!lastFullSyncAt) return true
-  const lastFullSyncAtMs = Date.parse(lastFullSyncAt)
-  if (!Number.isFinite(lastFullSyncAtMs)) return true
-  return now - lastFullSyncAtMs >= FULL_RECONCILE_INTERVAL_MS
-}
+export type { JiraProviderConfig } from './jira-core'
 
-// Default canonical->Jira priority name mapping. A Jira admin may rename
-// priorities; the write path looks up the resolved name (case-insensitive)
-// in the cached `jira_priorities` table, so renames that preserve the default
-// casing still resolve.
-const CANONICAL_TO_JIRA_DEFAULT: Record<Priority, string> = {
-  urgent: 'Highest',
-  high: 'High',
-  medium: 'Medium',
-  low: 'Low',
-}
-
-export interface JiraProviderConfig {
-  baseUrl: string
-  email: string
-  apiToken: string
-  projectKey: string
-  boardId?: number
-  defaultIssueType?: string
-  pollingSyncIntervalMs?: number
-}
+/**
+ * SQLite implementation of the JiraCachePort. Wraps the synchronous bun:sqlite
+ * free functions in jira-cache.ts as awaitable methods so the shared
+ * JiraProviderCore can drive both SQLite and Postgres uniformly.
+ */
+class SqliteJiraCache implements JiraCachePort {
+  readonly ready = Promise.resolve()
 
-export class JiraProvider implements KanbanProvider {
-  readonly type = 'jira' as const
-  private readonly client: JiraClient
-  private readonly pollingSyncIntervalMs: number
+  constructor(private readonly db: Database) {}
 
-  constructor(
-    private readonly db: Database,
-    private readonly config: JiraProviderConfig,
-    client?: JiraClient,
-  ) {
-    initJiraCacheSchema(db)
-    this.pollingSyncIntervalMs = config.pollingSyncIntervalMs ?? DEFAULT_POLLING_SYNC_INTERVAL_MS
-    this.client =
-      client ??
-      new JiraClient({
-        baseUrl: config.baseUrl,
-        email: config.email,
-        apiToken: config.apiToken,
-      })
+  async loadSyncMeta(): Promise<JiraSyncMeta> {
+    return loadJiraSyncMeta(this.db)
   }
 
-  private async sync(force = false): Promise<void> {
-    const meta = loadJiraSyncMeta(this.db)
-    const lastSyncAtMs = meta.lastSyncAt ? Date.parse(meta.lastSyncAt) : 0
-    const now = Date.now()
-    if (!force && lastSyncAtMs && now - lastSyncAtMs < this.pollingSyncIntervalMs) return
-    // `force` only bypasses the poll throttle; it must NOT imply a full
-    // 1970-based reconcile, which re-fetches every issue plus a per-issue
-    // changelog call (~minutes). Writes get read-after-write freshness from
-    // hydrateIssueByKey instead, so a forced sync stays a cheap delta.
-    const fullReconcile = shouldRunFullReconcile(meta.lastFullSyncAt, now)
-
-    // 1. Resolve project.
-    const project = await this.client.getProject(this.config.projectKey)
-    saveTeamInfo(this.db, { id: project.id, key: project.key, name: project.name })
-
-    // 2. Columns: board path OR status fallback path.
-    if (this.config.boardId !== undefined) {
-      const boardCfg = await this.client.getBoardColumns(this.config.boardId)
-      const boardId = this.config.boardId
-      const rows = jiraBoardColumnRows(boardId, boardCfg.columnConfig.columns)
-      replaceJiraColumns(this.db, rows)
-    } else {
-      const statusCats = await this.client.getProjectStatuses(project.key)
-      const seen = new Set<string>()
-      const uniqueStatuses: Array<{ id: string; name: string }> = []
-      for (const cat of statusCats) {
-        for (const s of cat.statuses) {
-          if (seen.has(s.id)) continue
-          seen.add(s.id)
-          uniqueStatuses.push({ id: s.id, name: s.name })
-        }
-      }
-      const rows = uniqueStatuses.map((s, i) => ({
-        id: `status:${s.id}`,
-        name: s.name,
-        position: i,
-        statusIds: [s.id],
-        source: 'status' as const,
-      }))
-      replaceJiraColumns(this.db, rows)
-    }
-
-    // 3. Catalogs: users + priorities + issue types in parallel.
-    // NOTE: listAssignableUsers is capped at 100 in T04; tenants with more
-    // assignable users are truncated. Pagination is out of scope for this pass.
-    const [users, priorities, issueTypes] = await Promise.all([
-      this.client.listAssignableUsers({
-        projectKey: project.key,
-        startAt: 0,
-        maxResults: 100,
-      }),
-      this.client.listPriorities(),
-      this.client.listIssueTypes({ projectId: project.id }),
-    ])
-    upsertJiraUsers(
-      this.db,
-      users.map((u) => ({
-        accountId: u.accountId,
-        displayName: u.displayName,
-        active: u.active ?? true,
-      })),
-    )
-    replaceJiraPriorities(
-      this.db,
-      priorities.map((p) => ({ id: p.id, name: p.name })),
-    )
-    replaceJiraIssueTypes(
-      this.db,
-      issueTypes.map((t) => ({ id: t.id, name: t.name })),
-    )
-
-    // 4. Delta issue fetch (paginated).
-    const since = fullReconcile ? null : meta.lastIssueUpdatedAt
-    const sinceClause = since ?? '1970-01-01 00:00'
-    const jql = `project = ${project.key} AND updated >= "${sinceClause}" ORDER BY updated ASC`
-
-    const maxResults = 100
-    let newestUpdatedAt: string | null = meta.lastIssueUpdatedAt
-    const seenIssueIds = new Set<string>()
-    const issueFields = [
-      'summary',
-      'description',
-      'status',
-      'issuetype',
-      'priority',
-      'assignee',
-      'labels',
-      'comment',
-      'created',
-      'updated',
-      'project',
-    ]
-    // /rest/api/3/search/jql paginates by an opaque nextPageToken and omits
-    // `total`, so we follow the cursor until the server reports `isLast` or stops
-    // handing back a token. The previous total/startAt loop fetched only the first
-    // page (oldest 100 by updated ASC) once `total` came back undefined, so every
-    // issue beyond the first page — including newly-created tickets on a project
-    // with >100 issues — was never cached. seenPageTokens guards against a server
-    // that repeats a cursor, which would otherwise spin this loop forever and hang
-    // the poll cycle; an empty page is not treated as terminal because a non-last
-    // page may legitimately carry a token with zero issues.
-    const seenPageTokens = new Set<string>()
-    let nextPageToken: string | undefined
-    let firstPage = true
-    let paginationComplete = false
-    while (firstPage || nextPageToken !== undefined) {
-      firstPage = false
-      const page = await this.client.listIssues({
-        jql,
-        startAt: 0,
-        maxResults,
-        fields: issueFields,
-        nextPageToken,
-      })
+  async saveSyncMeta(meta: Partial<JiraSyncMeta>): Promise<void> {
+    saveJiraSyncMeta(this.db, meta)
+  }
 
-      upsertJiraIssues(
-        this.db,
-        page.issues.map((issue) => ({
-          id: issue.id,
-          key: issue.key,
-          summary: issue.fields.summary,
-          descriptionText: issue.fields.description
-            ? adfToPlainText(issue.fields.description as AdfDocument)
-            : '',
-          statusId: issue.fields.status.id,
-          priorityName: issue.fields.priority?.name ?? null,
-          issueTypeName: issue.fields.issuetype?.name ?? '',
-          assigneeAccountId: issue.fields.assignee?.accountId ?? null,
-          assigneeName: issue.fields.assignee?.displayName ?? null,
-          labels: issue.fields.labels ?? [],
-          commentCount: issue.fields.comment?.total ?? 0,
-          projectKey: issue.fields.project?.key ?? project.key,
-          url: `${this.config.baseUrl}/browse/${issue.key}`,
-          createdAt: issue.fields.created,
-          updatedAt: issue.fields.updated,
-        })),
-      )
+  async loadTeamInfo(): Promise<ProviderTeamInfo | null> {
+    return loadTeamInfo(this.db)
+  }
 
-      for (const issue of page.issues) {
-        if (fullReconcile) seenIssueIds.add(issue.id)
-        if (newestUpdatedAt === null || issue.fields.updated > newestUpdatedAt) {
-          newestUpdatedAt = issue.fields.updated
-        }
-      }
+  async saveTeamInfo(team: ProviderTeamInfo | null): Promise<void> {
+    saveTeamInfo(this.db, team)
+  }
 
-      // Fetch changelog per changed issue so the poll-based
-      // `moved` trigger in @garage/dispatch works. Server-side dedupe
-      // keyed on (issue_id, history_id, item_field) keeps this cheap
-      // even if the same issue is updated repeatedly.
-      for (const issue of page.issues) {
-        await this.ingestIssueActivity(issue.id).catch((err) => {
-          // Activity is best-effort; the main sync shouldn't fail if
-          // one changelog call 404s or rate-limits.
-          console.warn(`[jira] activity fetch for ${issue.key} failed:`, err)
-        })
-      }
+  async replaceColumns(
+    columns: Array<{
+      id: string
+      name: string
+      position: number
+      statusIds: string[]
+      source: 'board' | 'status'
+    }>,
+    prune: boolean,
+  ): Promise<void> {
+    replaceJiraColumns(this.db, columns, prune)
+  }
 
-      const decision = decideJiraPagination(page, seenPageTokens)
-      if (decision.nextToken !== undefined) {
-        seenPageTokens.add(decision.nextToken)
-        nextPageToken = decision.nextToken
-        continue
-      }
-      paginationComplete = decision.complete
-      if (!paginationComplete) {
-        // The server stopped advancing the cursor before reporting a definitive
-        // end (stalled/contradictory). seenIssueIds is only a partial scan, so we
-        // must not treat it as authoritative for pruning below.
-        console.warn(
-          `[jira] search/jql scan ended without a definitive last page; treating as incomplete`,
-        )
-      }
-      break
-    }
+  async upsertUsers(
+    users: Array<{ accountId: string; displayName: string; active?: boolean }>,
+  ): Promise<void> {
+    upsertJiraUsers(this.db, users)
+  }
 
-    if (!paginationComplete) {
-      // The scan ended early (stalled/contradictory cursor). Leave sync metadata
-      // unchanged so this partial result is not recorded as a clean sync: lastSyncAt
-      // is not advanced, so the next sync is not throttled and retries promptly, and
-      // the full-reconcile marker stays due. The issues we did fetch are already
-      // cached (additive); we only skip pruning — which would delete issues that
-      // exist upstream on pages we never fetched — and the metadata advance.
-      return
-    }
+  async replacePriorities(
+    priorities: Array<{ id: string; name: string }>,
+    prune: boolean,
+  ): Promise<void> {
+    replaceJiraPriorities(this.db, priorities, prune)
+  }
 
-    // Prune against seenIssueIds and advance lastFullSyncAt only on a full
-    // reconcile; a delta sync's seenIssueIds is intentionally partial. (The scan
-    // is known complete here — an incomplete scan returned above.)
-    if (fullReconcile) {
-      pruneJiraIssuesMissingUpstream(this.db, project.key, [...seenIssueIds])
-    }
+  async replaceIssueTypes(
+    types: Array<{ id: string; name: string }>,
+    prune: boolean,
+  ): Promise<void> {
+    replaceJiraIssueTypes(this.db, types, prune)
+  }
 
-    // 5. Save sync meta.
-    const nextMeta: Partial<JiraSyncMeta> = {
-      projectKey: project.key,
-      boardId: this.config.boardId ?? null,
-      lastSyncAt: new Date().toISOString(),
-      lastIssueUpdatedAt: newestUpdatedAt ?? new Date().toISOString(),
-    }
-    if (fullReconcile) {
-      nextMeta.lastFullSyncAt = nextMeta.lastSyncAt
-    }
-    saveJiraSyncMeta(this.db, nextMeta)
+  async upsertIssues(issues: Parameters<JiraCachePort['upsertIssues']>[0]): Promise<void> {
+    upsertJiraIssues(this.db, issues)
   }
 
-  private resolveColumnId(input: string): string {
-    return resolveJiraColumnId(getCachedColumns(this.db), input)
+  async deleteIssue(idOrKey: string): Promise<void> {
+    deleteJiraIssue(this.db, idOrKey)
   }
 
-  private async buildBoardConfig(): Promise<BoardConfig> {
-    const cache = getCachedConfig(this.db)
-    const members = cache.users.map((u) => ({
-      name: u.displayName,
-      role: 'human' as const,
-    }))
-    const projects = cache.projectKey ? [cache.projectKey] : []
-    const discoveredAssignees = (
-      this.db
-        .query("SELECT DISTINCT assignee_name FROM jira_issues WHERE assignee_name != ''")
-        .all() as { assignee_name: string }[]
-    )
-      .map((r) => r.assignee_name)
-      .sort()
-    const discoveredProjects = projects.slice()
-    return {
-      members,
-      projects,
-      provider: 'jira',
-      discoveredAssignees,
-      discoveredProjects,
-    }
+  async pruneIssuesMissingUpstream(projectKey: string, upstreamIssueIds: string[]): Promise<void> {
+    pruneJiraIssuesMissingUpstream(this.db, projectKey, upstreamIssueIds)
   }
 
-  async syncCache(): Promise<void> {
-    await this.sync()
+  async adjustIssueCommentCount(idOrKey: string, delta: number): Promise<void> {
+    adjustJiraIssueCommentCount(this.db, idOrKey, delta)
   }
 
-  async getSyncStatus(): Promise<ProviderSyncStatus> {
-    const meta = loadJiraSyncMeta(this.db)
-    return {
-      lastSyncAt: meta.lastSyncAt,
-      lastFullSyncAt: meta.lastFullSyncAt,
-      lastWebhookAt: meta.lastWebhookAt,
-    }
+  async saveActivity(rows: JiraActivityRow[]): Promise<void> {
+    saveJiraActivity(this.db, rows)
   }
 
-  async getContext(): Promise<ProviderContext> {
-    await this.sync()
-    return {
-      provider: 'jira',
-      capabilities: JIRA_CAPABILITIES,
-      team: loadTeamInfo(this.db),
-    }
+  async getCachedActivity(params?: {
+    issueId?: string
+    limit?: number
+  }): Promise<JiraActivityRow[]> {
+    return getCachedActivity(this.db, params)
   }
 
-  async getBootstrap(): Promise<BoardBootstrap> {
-    await this.sync()
-    return {
-      provider: 'jira',
-      capabilities: JIRA_CAPABILITIES,
-      board: getCachedBoard(this.db),
-      config: await this.buildBoardConfig(),
-      metrics: null,
-      activity: [],
-      team: loadTeamInfo(this.db),
-    }
+  async getColumns(): Promise<JiraColumnRow[]> {
+    return getCachedColumns(this.db)
   }
 
-  async getBoard(): Promise<BoardView> {
-    await this.sync()
+  async getCachedBoard(): Promise<BoardView> {
     return getCachedBoard(this.db)
   }
 
-  async listColumns(): Promise<Column[]> {
-    await this.sync()
-    return getCachedColumns(this.db).map((r) => ({
-      id: r.id,
-      name: r.name,
-      position: r.position,
-      color: null,
-      created_at: '',
-      updated_at: '',
-    }))
+  async getCachedTask(lookup: string): Promise<Task | null> {
+    return getCachedTask(this.db, lookup)
+  }
+
+  async getCachedTasks(params?: { columnId?: string }): Promise<Task[]> {
+    return getCachedTasks(this.db, params)
   }
 
-  async listTasks(filters: TaskListFilters = {}): Promise<Task[]> {
-    await this.sync()
-    const columnId = filters.column ? this.resolveColumnId(filters.column) : undefined
-    let tasks = getCachedTasks(this.db, columnId ? { columnId } : undefined)
-    if (filters.priority) tasks = tasks.filter((t) => t.priority === filters.priority)
-    if (filters.assignee) tasks = tasks.filter((t) => t.assignee === filters.assignee)
-    if (filters.project) tasks = tasks.filter((t) => t.project === filters.project)
-    if (filters.sort === 'title') tasks = [...tasks].sort((a, b) => a.title.localeCompare(b.title))
-    if (filters.sort === 'updated')
-      tasks = [...tasks].sort((a, b) => b.updated_at.localeCompare(a.updated_at))
-    if (filters.limit) tasks = tasks.slice(0, filters.limit)
-    return tasks
+  async getCachedConfig(): Promise<JiraCacheConfig> {
+    return getCachedConfig(this.db)
   }
 
-  async getTask(idOrRef: string): Promise<Task> {
-    await this.sync()
-    const task = getCachedTask(this.db, idOrRef)
-    if (!task) {
-      throw new KanbanError(ErrorCode.TASK_NOT_FOUND, `No task with id '${idOrRef}'`)
-    }
-    return task
+  async getDiscoveredAssignees(): Promise<string[]> {
+    return (
+      this.db
+        .query("SELECT DISTINCT assignee_name FROM jira_issues WHERE assignee_name != ''")
+        .all() as { assignee_name: string }[]
+    )
+      .map((r) => r.assignee_name)
+      .sort()
   }
 
-  private resolveJiraPriorityName(canonical: Priority): string {
-    const wanted = CANONICAL_TO_JIRA_DEFAULT[canonical]
+  async findPriorityName(wanted: string): Promise<string | null> {
     const row = this.db
       .query('SELECT name FROM jira_priorities WHERE LOWER(name) = LOWER($name) LIMIT 1')
       .get({ $name: wanted }) as { name: string } | null
-    if (row) return row.name
-    const available = (
+    return row?.name ?? null
+  }
+
+  async getPriorityNames(): Promise<string[]> {
+    return (
       this.db.query('SELECT name FROM jira_priorities ORDER BY name').all() as { name: string }[]
     ).map((r) => r.name)
-    providerUpstreamError(
-      `Canonical priority '${canonical}' maps to Jira priority '${wanted}' which is not present in this tenant's priority catalog. Available Jira priorities: [${available
-        .map((n) => `"${n}"`)
-        .join(', ')}]`,
-    )
   }
 
-  // Empty-string / null assignee means "clear" — handled by callers; this
-  // resolver is only invoked for non-empty displayName values.
-  // Jira Cloud REST only accepts accountId for assignee writes; we never
-  // write `emailAddress`.
-  private resolveAssigneeAccountId(displayName: string): string {
+  async findActiveAssigneeAccountId(displayName: string): Promise<string | null> {
     const row = this.db
       .query(
         'SELECT account_id FROM jira_users WHERE active = 1 AND LOWER(display_name) = LOWER($name) LIMIT 1',
       )
       .get({ $name: displayName }) as { account_id: string } | null
-    if (row) return row.account_id
-    providerUpstreamError(
-      `Jira assignee '${displayName}' was not found in the cached active user list. Try 'kanban task list --assignee' to see cached names.`,
-    )
+    return row?.account_id ?? null
   }
 
-  private resolveIssueTypeId(name: string): string {
+  async findIssueTypeId(name: string): Promise<string | null> {
     const row = this.db
       .query('SELECT id FROM jira_issue_types WHERE LOWER(name) = LOWER($name) LIMIT 1')
       .get({ $name: name }) as { id: string } | null
-    if (row) return row.id
-    const available = (
-      this.db.query('SELECT name FROM jira_issue_types ORDER BY name').all() as { name: string }[]
-    ).map((r) => r.name)
-    providerUpstreamError(
-      `Jira issue type '${name}' is not present in this project's issue-type catalog. Available types: [${available
-        .map((n) => `"${n}"`)
-        .join(', ')}]`,
-    )
-  }
-
-  private normalizeProjectField(input?: string): void {
-    if (!input) return
-    if (input === this.config.projectKey) return
-    unsupportedOperation(
-      `JiraProvider is pinned to project '${this.config.projectKey}'. A different project field ('${input}') is not supported.`,
-    )
-  }
-
-  private resolveTaskByIdOrKey(idOrRef: string): Task {
-    const task = getCachedTask(this.db, idOrRef)
-    if (!task) {
-      throw new KanbanError(ErrorCode.TASK_NOT_FOUND, `No task with id '${idOrRef}'`)
-    }
-    return task
+    return row?.id ?? null
   }
 
-  private issueKeyFor(task: Task): string {
-    return task.externalRef ?? task.providerId ?? task.id.replace(/^jira:/, '')
-  }
-
-  private toTaskComment(task: Task, comment: JiraComment): TaskComment {
-    const timestamp = comment.updated ?? comment.created ?? task.updated_at
-    return {
-      id: comment.id,
-      task_id: task.id,
-      body: comment.body ? adfToPlainText(comment.body as AdfDocument) : '',
-      author: comment.author?.displayName ?? null,
-      created_at: comment.created ?? timestamp,
-      updated_at: timestamp,
-    }
-  }
-
-  // Read-after-write via the direct issue endpoint. Unlike JQL search (used by
-  // sync()), GET /issue/{key} has no search-index lag, so a just-created or
-  // just-transitioned issue is reflected immediately. This replaces the previous
-  // "create/transition then sync(true) then getCachedTask" pattern, which raced
-  // the search index (creates reported "not yet visible"; a move's new status
-  // sometimes didn't land) and forced a full whole-project reconcile per write.
-  private async hydrateIssueByKey(key: string): Promise<Task> {
-    // getIssue throws on a missing key (404), so reaching this method means the
-    // issue exists upstream. A null read-back would therefore be a genuine cache
-    // anomaly (the upsert above did not land), not an ordinary not-found — surface
-    // it rather than threading an unreachable null through every caller.
-    const issue = await this.client.getIssue(key)
-    upsertJiraIssues(this.db, [
-      {
-        id: issue.id,
-        key: issue.key,
-        summary: issue.fields.summary,
-        descriptionText: issue.fields.description
-          ? adfToPlainText(issue.fields.description as AdfDocument)
-          : '',
-        statusId: issue.fields.status.id,
-        priorityName: issue.fields.priority?.name ?? null,
-        issueTypeName: issue.fields.issuetype?.name ?? '',
-        assigneeAccountId: issue.fields.assignee?.accountId ?? null,
-        assigneeName: issue.fields.assignee?.displayName ?? null,
-        labels: issue.fields.labels ?? [],
-        commentCount: issue.fields.comment?.total ?? 0,
-        projectKey: issue.fields.project?.key ?? this.config.projectKey,
-        url: `${this.config.baseUrl}/browse/${issue.key}`,
-        createdAt: issue.fields.created,
-        updatedAt: issue.fields.updated,
-      },
-    ])
-    // Ingest the changelog like the sync loop does, so a just-applied transition
-    // is recorded in jira_activity immediately (backs getActivity and the
-    // poll-based `moved` trigger) rather than waiting for the next unthrottled
-    // sync. Best-effort: activity must not fail the mutation.
-    await this.ingestIssueActivity(issue.id).catch((err) => {
-      console.warn(`[jira] activity fetch for ${issue.key} failed:`, err)
-    })
-    const task = getCachedTask(this.db, key)
-    if (!task) {
-      providerUpstreamError(
-        `Jira issue ${key} was hydrated from GET /issue but is missing from the cache.`,
-      )
-    }
-    return task
-  }
-
-  async createTask(input: CreateTaskInput): Promise<Task> {
-    await this.sync()
-    this.normalizeProjectField(input.project)
-    const issueTypeName = this.config.defaultIssueType ?? 'Task'
-    const issueTypeId = this.resolveIssueTypeId(issueTypeName)
-    const fields: Record<string, unknown> = {
-      project: { key: this.config.projectKey },
-      summary: input.title,
-      issuetype: { id: issueTypeId },
-    }
-    if (input.description !== undefined) {
-      fields['description'] = plainTextToAdf(input.description)
-    }
-    if (input.priority !== undefined) {
-      fields['priority'] = { name: this.resolveJiraPriorityName(input.priority) }
-    }
-    if (input.assignee) {
-      fields['assignee'] = {
-        accountId: this.resolveAssigneeAccountId(input.assignee),
-      }
-    }
-    const labels = normalizeJiraLabels(input.labels)
-    if (labels.length > 0) fields['labels'] = labels
-    // Column at create-time is intentionally unsupported in Jira mode: new
-    // issues land in the project workflow's default start state. Use
-    // `moveTask` after create to change status.
-    const created = await this.client.createIssue({ fields })
-    return this.hydrateIssueByKey(created.key)
-  }
-
-  async updateTask(idOrRef: string, input: UpdateTaskInput): Promise<Task> {
-    await this.sync()
-    this.normalizeProjectField(input.project)
-    if (input.metadata !== undefined) {
-      unsupportedOperation('Jira mode does not support metadata updates')
-    }
-    const task = this.resolveTaskByIdOrKey(idOrRef)
-    if (input.expectedVersion !== undefined && task.version !== input.expectedVersion) {
-      throw new KanbanError(
-        ErrorCode.CONFLICT,
-        `Jira issue ${task.externalRef ?? idOrRef} was updated remotely (expected version ${input.expectedVersion}, current ${task.version ?? 'unknown'})`,
-      )
-    }
-    const issueKey = this.issueKeyFor(task)
-    const fields: Record<string, unknown> = {}
-    if (input.title !== undefined) fields['summary'] = input.title
-    if (input.description !== undefined) {
-      fields['description'] = plainTextToAdf(input.description)
-    }
-    if (input.priority !== undefined) {
-      fields['priority'] = { name: this.resolveJiraPriorityName(input.priority) }
-    }
-    if (input.assignee !== undefined) {
-      // Empty-string sentinel (or null) clears the assignee. Jira PUT body
-      // explicitly sends null to unassign; undefined would be stripped.
-      fields['assignee'] = input.assignee
-        ? { accountId: this.resolveAssigneeAccountId(input.assignee) }
-        : null
-    }
-    if (Object.keys(fields).length > 0) {
-      await this.client.updateIssue(issueKey, { fields })
-    }
-    return this.hydrateIssueByKey(issueKey)
-  }
-
-  async moveTask(idOrRef: string, column: string): Promise<Task> {
-    await this.sync()
-    const task = this.resolveTaskByIdOrKey(idOrRef)
-    return this.moveTaskByKey(this.issueKeyFor(task), column)
-  }
-
-  private async moveTaskByKey(issueKey: string, column: string): Promise<Task> {
-    const columnId = this.resolveColumnId(column)
-    const columnRow = getCachedColumns(this.db).find((c) => c.id === columnId)
-    if (!columnRow) {
-      throw new KanbanError(
-        ErrorCode.COLUMN_NOT_FOUND,
-        `Resolved column '${column}' but cache row missing`,
-      )
-    }
-    const statusIds = decodeColumnStatusIds(columnRow)
-    if (statusIds.length === 0) {
-      providerUpstreamError(`Column '${columnRow.name}' has no mapped Jira statuses.`)
-    }
-    // First-mapped-status deterministic choice: board columns can map to
-    // multiple Jira statuses; we transition to statusIds[0]. Operators who
-    // want a different target must reorder the board column's statuses in Jira.
-    const targetStatusId = statusIds[0]!
-    const { transitions } = await this.client.getTransitions(issueKey)
-    const match = transitions.find((t) => t.to.id === targetStatusId)
-    if (!match) {
-      const currentStatusId = getCachedTask(this.db, issueKey)?.column_id ?? '<unknown>'
-      providerUpstreamError(
-        `Cannot transition Jira issue ${issueKey} (current status id ${currentStatusId}) to column '${columnRow.name}' (target status id ${targetStatusId}). Available transitions: [${transitions
-          .map((t) => `"${t.name}"`)
-          .join(', ')}]`,
-      )
-    }
-    await this.client.transitionIssue(issueKey, match.id)
-    return this.hydrateIssueByKey(issueKey)
-  }
-
-  async deleteTask(_idOrRef: string): Promise<Task> {
-    unsupportedOperation('Task deletion is not supported in Jira mode')
-  }
-
-  async listComments(idOrRef: string): Promise<TaskComment[]> {
-    await this.sync()
-    const task = this.resolveTaskByIdOrKey(idOrRef)
-    const issueKey = this.issueKeyFor(task)
-    const comments: JiraComment[] = []
-    let startAt = 0
-
-    while (true) {
-      const page = await this.client.getComments(issueKey, { startAt, maxResults: 100 })
-      comments.push(...page.comments)
-      startAt += page.comments.length
-      if (comments.length >= page.total || page.comments.length === 0) break
-    }
-
-    return comments.map((comment) => this.toTaskComment(task, comment))
-  }
-
-  async getComment(idOrRef: string, commentId: string): Promise<TaskComment> {
-    await this.sync()
-    const task = this.resolveTaskByIdOrKey(idOrRef)
-    const comment = await this.client.getComment(this.issueKeyFor(task), commentId)
-    return this.toTaskComment(task, comment)
-  }
-
-  async comment(idOrRef: string, body: string): Promise<TaskComment> {
-    await this.sync()
-    const task = this.resolveTaskByIdOrKey(idOrRef)
-    const created = await this.client.addComment(this.issueKeyFor(task), {
-      body: plainTextToAdf(body),
-    })
-    adjustJiraIssueCommentCount(this.db, task.providerId || task.externalRef || task.id, 1)
-    return this.toTaskComment(task, created)
-  }
-
-  async updateComment(idOrRef: string, commentId: string, body: string): Promise<TaskComment> {
-    await this.sync()
-    const task = this.resolveTaskByIdOrKey(idOrRef)
-    const updated = await this.client.updateComment(this.issueKeyFor(task), commentId, {
-      body: plainTextToAdf(body),
-    })
-    return this.toTaskComment(task, updated)
-  }
-
-  async getActivity(limit?: number, taskId?: string): Promise<ActivityEntry[]> {
-    await this.sync()
-    const lookupIssueId = taskId ? this.resolveIssueIdFromTaskId(taskId) : undefined
-    const rows = getCachedActivity(this.db, {
-      ...(lookupIssueId !== undefined ? { issueId: lookupIssueId } : {}),
-      limit: limit ?? 100,
-    })
-    return rows.map((row) => this.activityRowToEntry(row))
+  async getIssueTypeNames(): Promise<string[]> {
+    return (
+      this.db.query('SELECT name FROM jira_issue_types ORDER BY name').all() as { name: string }[]
+    ).map((r) => r.name)
   }
 
-  private resolveIssueIdFromTaskId(taskId: string): string | undefined {
-    const normalized = taskId.startsWith('jira:') ? taskId.slice('jira:'.length) : taskId
+  async resolveIssueId(lookup: string): Promise<string | null> {
+    const normalized = lookup.startsWith('jira:') ? lookup.slice('jira:'.length) : lookup
     const row = this.db
       .query<
         { id: string },
         Record<string, string>
-      >(`SELECT id FROM jira_issues WHERE id = $lookup OR key = $lookup LIMIT 1`)
+      >('SELECT id FROM jira_issues WHERE id = $lookup OR key = $lookup LIMIT 1')
       .get({ $lookup: normalized })
-    return row?.id
+    return row?.id ?? null
   }
+}
 
-  private activityRowToEntry(row: JiraActivityRow): ActivityEntry {
-    // Map status field items to the same 'moved' shape the local provider
-    // emits, so dispatch's collector can trigger uniformly. Translate status
-    // ids into column ids via the cached column mapping; fall back to the raw
-    // status name for unmapped rows so we never drop activity silently.
-    const action: ActivityEntry['action'] = row.item_field === 'status' ? 'moved' : 'updated'
-    let fromCol = row.from_value
-    let toCol = row.to_value
-    if (row.item_field === 'status') {
-      fromCol = row.from_value ? (this.statusIdToColumnId(row.from_value) ?? row.from_value) : null
-      toCol = row.to_value ? (this.statusIdToColumnId(row.to_value) ?? row.to_value) : null
-    }
-    return {
-      id: `jira-activity:${row.issue_id}:${row.history_id}:${row.item_field}`,
-      task_id: `jira:${row.issue_id}`,
-      action,
-      field_changed: row.item_field,
-      old_value: fromCol,
-      new_value: toCol,
-      timestamp: row.created_at,
-    }
-  }
-
-  private statusIdToColumnId(statusId: string): string | undefined {
-    const cols = getCachedColumns(this.db)
-    for (const col of cols) {
-      if (decodeColumnStatusIds(col).includes(statusId)) return col.id
-    }
-    return undefined
-  }
-
-  private async ingestIssueActivity(issueId: string): Promise<void> {
-    const page = await this.client.getChangelog(issueId, { maxResults: 100 })
-    const rows: JiraActivityRow[] = []
-    for (const entry of page.values) {
-      for (const item of entry.items) {
-        rows.push({
-          issue_id: issueId,
-          history_id: entry.id,
-          item_field: item.field,
-          from_value: item.from ?? null,
-          to_value: item.to ?? null,
-          created_at: entry.created,
-        })
-      }
-    }
-    saveJiraActivity(this.db, rows)
-  }
-
-  async getMetrics(): Promise<BoardMetrics> {
-    unsupportedOperation('Metrics are not available in Jira mode')
-  }
-
-  async getConfig(): Promise<BoardConfig> {
-    await this.sync()
-    return this.buildBoardConfig()
-  }
-
-  async patchConfig(_input: Partial<BoardConfig>): Promise<BoardConfig> {
-    unsupportedOperation('Config mutation is not supported in Jira mode')
-  }
-
-  async handleWebhook(payload: WebhookRequest): Promise<WebhookResult> {
-    const secret = process.env['JIRA_WEBHOOK_SECRET']
-    if (secret) {
-      const sig = headerLower(payload.headers, 'x-hub-signature')
-      if (!verifySha256HmacSignatureHeader(secret, payload.rawBody, sig)) {
-        return { handled: false, unauthorized: true, message: 'Invalid signature' }
-      }
-    }
-    let body: { webhookEvent?: string; issue?: JiraIssue } = {}
-    try {
-      body = JSON.parse(payload.rawBody) as typeof body
-    } catch {
-      return { handled: false, message: 'Invalid JSON body' }
-    }
-    const event = body.webhookEvent ?? ''
-    const issue = body.issue
-    if (!issue) return { handled: false, message: `No issue in payload (${event})` }
-
-    if (event === 'jira:issue_deleted') {
-      deleteJiraIssue(this.db, issue.id)
-      saveJiraSyncMeta(this.db, { lastWebhookAt: new Date().toISOString() })
-      return { handled: true }
-    }
-
-    if (event === 'jira:issue_created' || event === 'jira:issue_updated') {
-      const projectKey = issue.fields.project?.key
-      if (projectKey !== this.config.projectKey) {
-        return {
-          handled: false,
-          message: `Ignoring issue from project '${projectKey ?? 'unknown'}'`,
-        }
-      }
-      upsertJiraIssues(this.db, [
-        {
-          id: issue.id,
-          key: issue.key,
-          summary: issue.fields.summary,
-          descriptionText: issue.fields.description
-            ? adfToPlainText(issue.fields.description as AdfDocument)
-            : '',
-          statusId: issue.fields.status.id,
-          priorityName: issue.fields.priority?.name ?? null,
-          issueTypeName: issue.fields.issuetype?.name ?? '',
-          assigneeAccountId: issue.fields.assignee?.accountId ?? null,
-          assigneeName: issue.fields.assignee?.displayName ?? null,
-          labels: issue.fields.labels ?? [],
-          commentCount: issue.fields.comment?.total ?? 0,
-          projectKey,
-          url: `${this.config.baseUrl}/browse/${issue.key}`,
-          createdAt: issue.fields.created,
-          updatedAt: issue.fields.updated,
-        },
-      ])
-      if (event === 'jira:issue_updated') {
-        await this.ingestIssueActivity(issue.id).catch((err) => {
-          console.warn(`[jira] activity fetch for webhook issue ${issue.key} failed:`, err)
-        })
-      }
-      saveJiraSyncMeta(this.db, { lastWebhookAt: new Date().toISOString() })
-      return { handled: true }
-    }
-
-    return { handled: false, message: `Unsupported event: ${event}` }
+export class JiraProvider extends JiraProviderCore {
+  constructor(db: Database, config: JiraProviderConfig, client?: JiraClient) {
+    initJiraCacheSchema(db)
+    super(new SqliteJiraCache(db), config, client)
   }
 }