@andypai/agent-kanban 0.5.1 → 0.6.1

package/src/mcp/core.ts

@@ -1,5 +1,6 @@
 import type { KanbanProvider } from '../providers/types'
 import type { Task, TaskComment } from '../types'
+import * as useCases from '../use-cases'
 import { TrackerMcpError, toTrackerMcpError } from './errors'
 import type { TrackerMcpHooks, TrackerMcpPolicy } from './types'
 
@@ -122,7 +123,7 @@ export function createTrackerCore<TScope>(input: {
           ticketId,
           execute: async () => {
             await policy.canReadTicket(scope, ticketId)
-            return provider.getTask(ticketId)
+            return useCases.getTask(provider, ticketId)
           },
         })
       },
@@ -134,7 +135,7 @@ export function createTrackerCore<TScope>(input: {
           ticketId,
           execute: async () => {
             await policy.canReadTicket(scope, ticketId)
-            const comments = await provider.listComments(ticketId)
+            const comments = await useCases.listComments(provider, ticketId)
             return filterComments(scope, comments, policy)
           },
           resultMeta: (comments) => ({ commentCount: comments.length }),
@@ -145,7 +146,7 @@ export function createTrackerCore<TScope>(input: {
         return runTool({
           scope,
           tool: 'getBoard',
-          execute: async () => provider.getBoard(),
+          execute: async () => useCases.getBoard(provider),
         })
       },
 
@@ -156,7 +157,7 @@ export function createTrackerCore<TScope>(input: {
           ticketId,
           execute: async () => {
             await policy.canPostComment(scope, ticketId, body)
-            return provider.comment(ticketId, body)
+            return useCases.addComment(provider, ticketId, body)
           },
           resultMeta: (comment) => ({ commentId: comment.id }),
         })
@@ -168,9 +169,9 @@ export function createTrackerCore<TScope>(input: {
           tool: 'updateComment',
           ticketId,
           execute: async () => {
-            const existing = await provider.getComment(ticketId, commentId)
+            const existing = await useCases.getComment(provider, ticketId, commentId)
             await policy.canUpdateComment(scope, ticketId, existing, body)
-            return provider.updateComment(ticketId, commentId, body)
+            return useCases.updateComment(provider, ticketId, commentId, body)
           },
           resultMeta: (comment) => ({ commentId: comment.id }),
         })
@@ -183,7 +184,7 @@ export function createTrackerCore<TScope>(input: {
           ticketId,
           execute: async () => {
             await policy.canMoveTicket(scope, ticketId, column)
-            await provider.moveTask(ticketId, column)
+            await useCases.moveTask(provider, ticketId, column)
           },
           resultMeta: { movedTo: column },
         })

package/src/metrics.ts

@@ -1,5 +1,6 @@
 import { Database } from 'bun:sqlite'
 import type { ActivityEntry, BoardMetrics } from './types'
+import { selectDoneColumnIds, selectInProgressColumnIds } from './column-roles'
 
 function getDistinctTaskFieldValues(db: Database, field: 'assignee' | 'project'): string[] {
   return (
@@ -22,13 +23,28 @@ export function getDiscoveredProjects(db: Database): string[] {
 }
 
 export function getBoardMetrics(db: Database): BoardMetrics {
-  const tasksByColumn = db
+  const columnCounts = db
     .query(
-      `SELECT c.name as column_name, COUNT(t.id) as count
+      `SELECT c.id as id, c.name as column_name, c.position as position, COUNT(t.id) as count
        FROM columns c LEFT JOIN tasks t ON t.column_id = c.id
        GROUP BY c.id ORDER BY c.position`,
     )
-    .all() as { column_name: string; count: number }[]
+    .all() as { id: string; column_name: string; position: number; count: number }[]
+
+  const tasksByColumn = columnCounts.map((row) => ({
+    column_name: row.column_name,
+    count: row.count,
+  }))
+
+  // Classify columns by role (handles custom names / KANBAN_DEFAULT_COLUMNS)
+  // instead of matching the literal strings 'done' / 'in-progress'.
+  const columns = columnCounts.map((row) => ({
+    id: row.id,
+    name: row.column_name,
+    position: row.position,
+  }))
+  const doneColumnIds = new Set(selectDoneColumnIds(columns))
+  const inProgressColumnIds = new Set(selectInProgressColumnIds(columns))
 
   const tasksByPriority = db
     .query(
@@ -41,26 +57,37 @@ export function getBoardMetrics(db: Database): BoardMetrics {
 
   const totalTasks = getCount(db, 'SELECT COUNT(*) as count FROM tasks')
 
-  const completedTasks = getCount(
-    db,
-    `SELECT COUNT(*) as count FROM tasks t
-     JOIN columns c ON t.column_id = c.id WHERE LOWER(c.name) = 'done'`,
-  )
+  const completedTasks = columnCounts
+    .filter((row) => doneColumnIds.has(row.id))
+    .reduce((sum, row) => sum + row.count, 0)
 
-  const avgResult = db
-    .query(
-      `SELECT AVG(
-        (julianday(ct.exited_at) - julianday(first_enter.entered_at)) * 24
+  // Average completion time = first time a task was tracked (creation) until the
+  // first time it entered a Done column. Measuring the Done *entry* (not exit)
+  // means tasks that reach Done and stay there are counted; MIN() over Done rows
+  // handles tasks that re-enter Done. Kept in lockstep with the Postgres copy in
+  // postgres-local.ts:getMetrics — update both together.
+  const donePlaceholders = [...doneColumnIds].map(() => '?').join(', ')
+  const avgResult = (
+    doneColumnIds.size === 0
+      ? { avg_hours: null }
+      : (db
+          .query(
+            `SELECT AVG(
+        (julianday(done_enter.entered_at) - julianday(first_enter.entered_at)) * 24
        ) as avg_hours
-       FROM column_time_tracking ct
-       JOIN columns c ON ct.column_id = c.id
+       FROM (
+         SELECT ct.task_id, MIN(ct.entered_at) as entered_at
+         FROM column_time_tracking ct
+         WHERE ct.column_id IN (${donePlaceholders})
+         GROUP BY ct.task_id
+       ) done_enter
        JOIN (
          SELECT task_id, MIN(entered_at) as entered_at
          FROM column_time_tracking GROUP BY task_id
-       ) first_enter ON first_enter.task_id = ct.task_id
-       WHERE LOWER(c.name) = 'done' AND ct.exited_at IS NOT NULL`,
-    )
-    .get() as { avg_hours: number | null }
+       ) first_enter ON first_enter.task_id = done_enter.task_id`,
+          )
+          .get(...doneColumnIds) as { avg_hours: number | null })
+  ) as { avg_hours: number | null }
 
   const recentActivity = db
     .query('SELECT * FROM activity_log ORDER BY timestamp DESC, rowid DESC LIMIT 20')
@@ -71,11 +98,9 @@ export function getBoardMetrics(db: Database): BoardMetrics {
     "SELECT COUNT(*) as count FROM tasks WHERE created_at >= datetime('now', '-7 days')",
   )
 
-  const inProgressCount = getCount(
-    db,
-    `SELECT COUNT(*) as count FROM tasks t
-     JOIN columns c ON t.column_id = c.id WHERE LOWER(c.name) = 'in-progress'`,
-  )
+  const inProgressCount = columnCounts
+    .filter((row) => inProgressColumnIds.has(row.id))
+    .reduce((sum, row) => sum + row.count, 0)
 
   const completionPercent = totalTasks > 0 ? Math.round((completedTasks / totalTasks) * 100) : 0
 

package/src/provider-runtime.ts

@@ -22,7 +22,12 @@ export interface KanbanRuntime {
 }
 
 export async function openKanbanRuntime(
-  opts: { dbPath?: string; storage?: KanbanStorageConfig; tracker?: TrackerConfig } = {},
+  opts: {
+    dbPath?: string
+    storage?: KanbanStorageConfig
+    tracker?: TrackerConfig
+    seedLocalColumns?: boolean
+  } = {},
 ): Promise<KanbanRuntime> {
   const dbPath = opts.dbPath ?? getDbPath()
   const storage =
@@ -98,7 +103,9 @@ export async function openKanbanRuntime(
   const db = openDb(storage.sqlitePath)
   migrateSchema(db)
   return {
-    provider: createProvider(db, trackerConfig, storage.sqlitePath),
+    provider: createProvider(db, trackerConfig, storage.sqlitePath, {
+      seedLocalColumns: opts.seedLocalColumns,
+    }),
     dbPath: storage.sqlitePath,
     trackerConfig,
     sqliteDb: db,

package/src/providers/index.ts

@@ -10,6 +10,7 @@ export function createProvider(
   db: Database,
   config: TrackerConfig,
   dbPath = getDbPath(),
+  options: { seedLocalColumns?: boolean } = {},
 ): KanbanProvider {
   if (config.provider === 'linear') {
     return new LinearProvider(db, config.teamId, config.apiKey, config.syncIntervalMs)
@@ -28,6 +29,8 @@ export function createProvider(
   }
 
   initSchema(db)
-  seedDefaultColumns(db)
+  if (options.seedLocalColumns !== false) {
+    seedDefaultColumns(db, config.defaultColumns)
+  }
   return new LocalProvider(db, dbPath)
 }

package/src/providers/jira-cache.ts

@@ -297,12 +297,21 @@ export function replaceJiraColumns(
     statusIds: string[]
     source: 'board' | 'status'
   }>,
+  prune = true,
 ): void {
+  // prune=true (full reconcile / direct callers): replace the whole catalog.
+  // prune=false (delta sync): upsert the current rows and leave the rest, so a
+  // stale delta snapshot never deletes a row a fresher sync just added.
   const run = db.transaction(() => {
-    db.run('DELETE FROM jira_columns')
+    if (prune) db.run('DELETE FROM jira_columns')
     const stmt = db.prepare(
       `INSERT INTO jira_columns (id, name, position, status_ids, source)
-       VALUES ($id, $name, $position, $status_ids, $source)`,
+       VALUES ($id, $name, $position, $status_ids, $source)
+       ON CONFLICT(id) DO UPDATE SET
+         name = excluded.name,
+         position = excluded.position,
+         status_ids = excluded.status_ids,
+         source = excluded.source`,
     )
     for (const column of columns) {
       stmt.run({
@@ -341,10 +350,14 @@ export function upsertJiraUsers(
 export function replaceJiraPriorities(
   db: Database,
   priorities: Array<{ id: string; name: string }>,
+  prune = true,
 ): void {
   const run = db.transaction(() => {
-    db.run('DELETE FROM jira_priorities')
-    const stmt = db.prepare('INSERT INTO jira_priorities (id, name) VALUES ($id, $name)')
+    if (prune) db.run('DELETE FROM jira_priorities')
+    const stmt = db.prepare(
+      `INSERT INTO jira_priorities (id, name) VALUES ($id, $name)
+       ON CONFLICT(id) DO UPDATE SET name = excluded.name`,
+    )
     for (const priority of priorities) {
       stmt.run({ $id: priority.id, $name: priority.name })
     }
@@ -355,10 +368,14 @@ export function replaceJiraPriorities(
 export function replaceJiraIssueTypes(
   db: Database,
   types: Array<{ id: string; name: string }>,
+  prune = true,
 ): void {
   const run = db.transaction(() => {
-    db.run('DELETE FROM jira_issue_types')
-    const stmt = db.prepare('INSERT INTO jira_issue_types (id, name) VALUES ($id, $name)')
+    if (prune) db.run('DELETE FROM jira_issue_types')
+    const stmt = db.prepare(
+      `INSERT INTO jira_issue_types (id, name) VALUES ($id, $name)
+       ON CONFLICT(id) DO UPDATE SET name = excluded.name`,
+    )
     for (const type of types) {
       stmt.run({ $id: type.id, $name: type.name })
     }

package/src/providers/jira-client.ts

@@ -45,12 +45,73 @@ export interface JiraIssue {
 }
 
 export interface JiraSearchPage {
-  startAt: number
-  maxResults: number
-  total: number
+  // The legacy /rest/api/3/search endpoint returned startAt/maxResults/total.
+  // The current /rest/api/3/search/jql endpoint omits `total` and paginates by
+  // an opaque `nextPageToken` (with `isLast`), so these are optional now.
+  startAt?: number
+  maxResults?: number
+  total?: number
+  nextPageToken?: string
+  isLast?: boolean
   issues: JiraIssue[]
 }
 
+export interface JiraPaginationDecision {
+  // When set, advance the scan to this cursor. When absent, the scan is over and
+  // `complete` says whether it ended definitively (safe to prune against the
+  // accumulated issue set) or was cut short (must NOT prune — issues on unfetched
+  // pages would be wrongly deleted).
+  nextToken?: string
+  complete: boolean
+}
+
+// Decide how a `/rest/api/3/search/jql` cursor scan should proceed after a page.
+// The endpoint signals continuation with `isLast`/`nextPageToken`, but real and
+// degraded servers vary, so termination must be conservative: a scan is reported
+// `complete` (safe to prune against the accumulated issue set) ONLY when the
+// server proves the end, never from a page-size guess.
+//   - usable cursor (fresh `nextPageToken`, isLast !== true) → advance.
+//   - isLast === true                                        → definitive end (complete).
+//   - isLast === false                                       → more pages exist; if the
+//                                                              cursor is missing/stale we
+//                                                              cannot fetch them, so the
+//                                                              scan is incomplete.
+//   - isLast absent, `total` present                         → legacy total/startAt proof:
+//                                                              complete once startAt+count
+//                                                              reaches `total`.
+//   - isLast absent, no `total`, no usable cursor            → NO completeness proof. A
+//                                                              short/empty page must NOT be
+//                                                              read as "the end": a degraded
+//                                                              `{ issues: [] }` would then
+//                                                              prune the entire cache on a
+//                                                              full reconcile. Treat as
+//                                                              incomplete and retry instead.
+// A cursor already in `seenPageTokens` counts as not usable (a stalled cursor
+// that would otherwise loop forever).
+export function decideJiraPagination(
+  page: Pick<JiraSearchPage, 'isLast' | 'nextPageToken' | 'issues' | 'total' | 'startAt'>,
+  seenPageTokens: ReadonlySet<string>,
+): JiraPaginationDecision {
+  const token = page.nextPageToken
+  const canAdvance = !!token && page.isLast !== true && !seenPageTokens.has(token)
+  if (canAdvance) return { nextToken: token, complete: false }
+  if (page.isLast === true) return { complete: true }
+  if (page.isLast === false) return { complete: false }
+  // isLast absent below. Prefer the legacy total/startAt signal when a
+  // (non-standard) server supplies it: complete once we have fetched everything
+  // `total` promises. The live /search/jql endpoint omits `total` and ignores
+  // `startAt`, so the loop never advances by offset — a `total` promising more
+  // than this page is reported incomplete rather than fetched.
+  if (typeof page.total === 'number') {
+    const issueCount = page.issues?.length ?? 0
+    return { complete: (page.startAt ?? 0) + issueCount >= page.total }
+  }
+  // No completeness signal at all (no isLast, no total, no usable cursor). We
+  // cannot prove the scan reached the end, so never guess `complete` from page
+  // size — that would prune the whole cache on a degraded short/empty response.
+  return { complete: false }
+}
+
 export interface JiraCreatePayload {
   fields: Record<string, unknown>
 }
@@ -254,12 +315,17 @@ export class JiraClient {
     startAt: number
     maxResults: number
     fields?: string[]
+    nextPageToken?: string
   }): Promise<JiraSearchPage> {
     const query: QueryParams = {
       jql: params.jql,
-      startAt: params.startAt,
       maxResults: params.maxResults,
     }
+    // /rest/api/3/search/jql ignores startAt and paginates by nextPageToken.
+    // Send the cursor when we have one; only send startAt on the first page for
+    // back-compat with the legacy endpoint.
+    if (params.nextPageToken) query.nextPageToken = params.nextPageToken
+    else query.startAt = params.startAt
     if (params.fields && params.fields.length > 0) {
       query.fields = params.fields.join(',')
     }