@andypai/agent-kanban 0.6.3 → 0.6.5

package/src/providers/postgres-local.ts

@@ -1,11 +1,10 @@
-import type { Sql, TransactionSql } from 'postgres'
+import type { Sql } from 'postgres'
 
 import { ErrorCode, KanbanError } from '../errors'
 import { generateId } from '../id'
 import { assembleBoardMetrics, classifyColumnRoles } from '../metrics-spec'
 import type {
   ActivityEntry,
-  BoardBootstrap,
   BoardConfig,
   BoardMetrics,
   BoardView,
@@ -17,20 +16,11 @@ import type {
 } from '../types'
 import { POSTGRES_LOCAL_CAPABILITIES } from './capabilities'
 import { unsupportedOperation } from './errors'
-import type {
-  CreateTaskInput,
-  KanbanProvider,
-  ProviderContext,
-  ProviderSyncStatus,
-  TaskListFilters,
-  UpdateTaskInput,
-} from './types'
+import { LocalProviderCore, type LocalStorePort } from './local-core'
+import type { CreateTaskInput, TaskListFilters, UpdateTaskInput } from './types'
 import type { LocalTrackerConfig } from '../tracker-config'
 import { normalizeLabels, parseStoredLabels } from '../labels'
-
-// Accepts either the root connection or a scoped transaction handle so the
-// mutation helpers can run inside or outside a `sql.begin(...)` block.
-type Exec = Sql | TransactionSql
+import type { Exec } from './postgres-batch'
 
 const DEFAULT_COLUMNS = [
   { name: 'recurring', position: 0 },
@@ -98,8 +88,8 @@ function parseMetadata(metadata: string | undefined): string {
   }
 }
 
-export class PostgresLocalProvider implements KanbanProvider {
-  readonly type = 'local' as const
+class PostgresLocalStore implements LocalStorePort {
+  readonly capabilities = POSTGRES_LOCAL_CAPABILITIES
   private readonly ready: Promise<void>
 
   constructor(
@@ -294,25 +284,6 @@ export class PostgresLocalProvider implements KanbanProvider {
     `
   }
 
-  async getContext(): Promise<ProviderContext> {
-    await this.ready
-    return { provider: this.type, capabilities: POSTGRES_LOCAL_CAPABILITIES, team: null }
-  }
-
-  async getBootstrap(): Promise<BoardBootstrap> {
-    await this.ready
-    const metrics = await this.getMetrics()
-    return {
-      provider: this.type,
-      capabilities: POSTGRES_LOCAL_CAPABILITIES,
-      board: await this.getBoard(),
-      config: await this.getConfig(),
-      metrics,
-      activity: await this.getActivity(50),
-      team: null,
-    }
-  }
-
   async getBoard(): Promise<BoardView> {
     await this.ready
     const columns = await this.listColumns()
@@ -386,6 +357,11 @@ export class PostgresLocalProvider implements KanbanProvider {
     return this.enrichTask(row, counts.get(row.id) ?? 0)
   }
 
+  async getTaskVersion(idOrRef: string): Promise<string> {
+    const row = await this.requireTask(idOrRef)
+    return String(row.revision ?? 0)
+  }
+
   async createTask(input: CreateTaskInput): Promise<Task> {
     await this.ready
     const priority = input.priority ?? 'medium'
@@ -418,18 +394,12 @@ export class PostgresLocalProvider implements KanbanProvider {
     return this.getTask(id)
   }
 
-  async updateTask(idOrRef: string, input: UpdateTaskInput): Promise<Task> {
+  async updateTask(
+    idOrRef: string,
+    input: Omit<UpdateTaskInput, 'expectedVersion'>,
+  ): Promise<Task> {
     await this.ready
     const current = await this.requireTask(idOrRef)
-    if (
-      input.expectedVersion !== undefined &&
-      String(current.revision ?? 0) !== input.expectedVersion
-    ) {
-      throw new KanbanError(
-        ErrorCode.CONFLICT,
-        `Task ${idOrRef} was modified since you loaded it (expected version ${input.expectedVersion}, current ${current.revision ?? 0})`,
-      )
-    }
 
     if (input.priority !== undefined) assertPriority(input.priority)
     const metadata = input.metadata === undefined ? undefined : parseMetadata(input.metadata)
@@ -763,8 +733,13 @@ export class PostgresLocalProvider implements KanbanProvider {
     // and fail loudly so the HTTP API and CLI agree.
     unsupportedOperation('Editing board config is not supported with KANBAN_STORAGE=postgres')
   }
+}
 
-  async getSyncStatus(): Promise<ProviderSyncStatus | null> {
-    return null
+export class PostgresLocalProvider extends LocalProviderCore {
+  constructor(
+    sql: Sql,
+    config: Pick<LocalTrackerConfig, 'defaultColumns' | 'defaultTaskColumn'> = {},
+  ) {
+    super(new PostgresLocalStore(sql, config))
   }
 }

package/src/providers/sqlite-local-store.ts

@@ -0,0 +1,121 @@
+import type { Database } from 'bun:sqlite'
+
+import { listActivity } from '../activity'
+import { getConfigPath, loadConfig, saveConfig } from '../config'
+import {
+  addComment,
+  countComments,
+  countCommentsByTask,
+  addTask,
+  deleteTask,
+  getBoardView,
+  getComment as getTaskComment,
+  getTask,
+  listComments as listTaskComments,
+  listColumns,
+  listTasks,
+  moveTask,
+  updateComment as updateTaskComment,
+  updateTask,
+} from '../db'
+import { getBoardMetrics, getDiscoveredAssignees, getDiscoveredProjects } from '../metrics'
+import type { BoardConfig, BoardMetrics, TaskComment } from '../types'
+import { LOCAL_CAPABILITIES } from './capabilities'
+import type { CreateTaskInput, TaskListFilters, UpdateTaskInput } from './types'
+import type { LocalStorePort } from './local-core'
+
+export class SqliteLocalStore implements LocalStorePort {
+  readonly capabilities = LOCAL_CAPABILITIES
+
+  constructor(
+    private readonly db: Database,
+    private readonly dbPath: string,
+  ) {}
+
+  getBoard() {
+    return getBoardView(this.db)
+  }
+
+  listColumns() {
+    return listColumns(this.db)
+  }
+
+  listTasks(filters: TaskListFilters = {}) {
+    return listTasks(this.db, filters)
+  }
+
+  getTask(idOrRef: string) {
+    return getTask(this.db, idOrRef)
+  }
+
+  getTaskVersion(idOrRef: string): string {
+    return String(getTask(this.db, idOrRef).revision ?? 0)
+  }
+
+  createTask(input: CreateTaskInput) {
+    return addTask(this.db, input.title, input)
+  }
+
+  updateTask(idOrRef: string, input: Omit<UpdateTaskInput, 'expectedVersion'>) {
+    return updateTask(this.db, idOrRef, input)
+  }
+
+  moveTask(idOrRef: string, column: string) {
+    return moveTask(this.db, idOrRef, column)
+  }
+
+  deleteTask(idOrRef: string) {
+    return deleteTask(this.db, idOrRef)
+  }
+
+  listComments(idOrRef: string): TaskComment[] {
+    return listTaskComments(this.db, idOrRef)
+  }
+
+  getComment(idOrRef: string, commentId: string): TaskComment {
+    return getTaskComment(this.db, idOrRef, commentId)
+  }
+
+  comment(idOrRef: string, body: string): TaskComment {
+    return addComment(this.db, idOrRef, body)
+  }
+
+  updateComment(idOrRef: string, commentId: string, body: string): TaskComment {
+    return updateTaskComment(this.db, idOrRef, commentId, body)
+  }
+
+  getActivity(limit?: number, taskId?: string) {
+    return listActivity(this.db, { limit, taskId })
+  }
+
+  getMetrics() {
+    return getBoardMetrics(this.db)
+  }
+
+  getConfig(context: { metrics?: BoardMetrics } = {}): BoardConfig {
+    const discoveredAssignees = context.metrics?.assignees ?? getDiscoveredAssignees(this.db)
+    const discoveredProjects = context.metrics?.projects ?? getDiscoveredProjects(this.db)
+    return {
+      ...loadConfig(this.dbPath),
+      provider: 'local',
+      discoveredAssignees,
+      discoveredProjects,
+    }
+  }
+
+  patchConfig(input: Partial<BoardConfig>): BoardConfig {
+    const config = loadConfig(this.dbPath)
+    if (input.members) config.members = input.members
+    if (input.projects) config.projects = input.projects
+    saveConfig(getConfigPath(this.dbPath), config)
+    return this.getConfig()
+  }
+
+  countComments(taskId: string): number {
+    return countComments(this.db, taskId)
+  }
+
+  countCommentsByTask(): Map<string, number> {
+    return countCommentsByTask(this.db)
+  }
+}

package/src/providers/sync-core.ts

@@ -0,0 +1,91 @@
+import type { Task } from '../types'
+import type { ProviderSyncStatus, TaskListFilters } from './types'
+
+export function parseSyncTimestamp(value: string | null | undefined): number {
+  if (!value) return 0
+  const parsed = Date.parse(value)
+  return Number.isFinite(parsed) ? parsed : 0
+}
+
+export function maxSyncTimestamp(
+  a: string | null | undefined,
+  b: string | null | undefined,
+): string | null {
+  const aMs = parseSyncTimestamp(a)
+  const bMs = parseSyncTimestamp(b)
+  if (!aMs && !bMs) return null
+  return aMs >= bMs ? (a ?? null) : (b ?? null)
+}
+
+export class SyncGate {
+  private backgroundManaged = false
+
+  constructor(private readonly pollingSyncIntervalMs: number) {}
+
+  shouldSkip(params: {
+    force: boolean
+    viaWarmer: boolean
+    lastSyncAt: string | null | undefined
+    now?: number
+  }): boolean {
+    const lastSyncAtMs = parseSyncTimestamp(params.lastSyncAt)
+    if (this.backgroundManaged && !params.force && !params.viaWarmer && lastSyncAtMs > 0) {
+      return true
+    }
+    const now = params.now ?? Date.now()
+    return !params.force && lastSyncAtMs > 0 && now - lastSyncAtMs < this.pollingSyncIntervalMs
+  }
+
+  setBackgroundManaged(managed: boolean): void {
+    this.backgroundManaged = managed
+  }
+}
+
+export function syncStatusFromMeta(meta: {
+  lastSyncAt: string | null
+  lastFullSyncAt: string | null
+  lastWebhookAt: string | null
+}): ProviderSyncStatus {
+  return {
+    lastSyncAt: meta.lastSyncAt,
+    lastFullSyncAt: meta.lastFullSyncAt,
+    lastWebhookAt: meta.lastWebhookAt,
+  }
+}
+
+export function applyTaskFilters(tasks: Task[], filters: TaskListFilters = {}): Task[] {
+  let result = tasks
+  if (filters.priority) result = result.filter((task) => task.priority === filters.priority)
+  if (filters.assignee) result = result.filter((task) => task.assignee === filters.assignee)
+  if (filters.project) result = result.filter((task) => task.project === filters.project)
+  if (filters.sort === 'title') {
+    result = [...result].sort((a, b) => a.title.localeCompare(b.title))
+  }
+  if (filters.sort === 'updated') {
+    result = [...result].sort((a, b) => b.updated_at.localeCompare(a.updated_at))
+  }
+  if (filters.limit) result = result.slice(0, filters.limit)
+  return result
+}
+
+export async function mapWithConcurrency<T, R>(
+  items: T[],
+  concurrency: number,
+  mapper: (item: T, index: number) => Promise<R>,
+): Promise<R[]> {
+  if (concurrency < 1) throw new RangeError('concurrency must be at least 1')
+  const results: R[] = []
+  for (let i = 0; i < items.length; i += concurrency) {
+    const batch = items.slice(i, i + concurrency)
+    results.push(...(await Promise.all(batch.map((item, offset) => mapper(item, i + offset)))))
+  }
+  return results
+}
+
+export async function forEachWithConcurrency<T>(
+  items: T[],
+  concurrency: number,
+  worker: (item: T, index: number) => Promise<void>,
+): Promise<void> {
+  await mapWithConcurrency(items, concurrency, worker)
+}

package/src/providers/team-info.ts

@@ -0,0 +1,24 @@
+import type { ProviderTeamInfo } from '../types'
+
+export function parseProviderTeamInfo(raw: string | null): ProviderTeamInfo | null {
+  if (raw === null) return null
+  try {
+    const parsed = JSON.parse(raw) as unknown
+    if (
+      parsed &&
+      typeof parsed === 'object' &&
+      'id' in parsed &&
+      'key' in parsed &&
+      'name' in parsed &&
+      typeof (parsed as { id: unknown }).id === 'string' &&
+      typeof (parsed as { key: unknown }).key === 'string' &&
+      typeof (parsed as { name: unknown }).name === 'string'
+    ) {
+      const team = parsed as { id: string; key: string; name: string }
+      return { id: team.id, key: team.key, name: team.name }
+    }
+  } catch {
+    // Corrupt persisted provider metadata should not prevent cache bootstrap.
+  }
+  return null
+}

package/src/providers/warn-once.ts

@@ -0,0 +1,15 @@
+const warnedKeys = new Set<string>()
+
+// Emit an informational warning at most once per process for a given key, so
+// repeated hot paths (e.g. inbound webhooks) don't flood the dev console.
+export function warnOnce(key: string, message: string): void {
+  if (warnedKeys.has(key)) return
+  warnedKeys.add(key)
+  console.warn(message)
+}
+
+// Test-only: clear the process-wide dedup set so tests can assert warnings
+// independently of which test ran first.
+export function resetWarnOnce(): void {
+  warnedKeys.clear()
+}

package/src/use-cases.ts

@@ -1,139 +1,15 @@
 import { normalizeLabels } from './labels'
-import type {
-  CreateTaskInput,
-  KanbanProvider,
-  ProviderContext,
-  TaskListFilters,
-  UpdateTaskInput,
-} from './providers/types'
-import type {
-  ActivityEntry,
-  BoardBootstrap,
-  BoardConfig,
-  BoardMetrics,
-  BoardView,
-  Column,
-  Task,
-  TaskComment,
-} from './types'
+import type { CreateTaskInput } from './providers/types'
 
 /**
- * Typed use-case layer shared by every transport (CLI, HTTP, MCP).
- *
- * Each function is the single, typed seam between a transport and the
- * provider: transports own their own concerns — argument parsing and
- * transport-specific error messages, HTTP routing and WebSocket events, MCP
- * authorization policy and hooks — then delegate the actual provider call
- * here. Keeping that call in one place means cross-cutting concerns (label
- * normalization today; future auditing/validation) have a single insertion
- * point instead of being re-derived in three transports.
- *
- * These functions intentionally do NOT perform required-argument validation:
- * the transports raise their own (differently worded) errors before calling
- * in, so the contract each surface already advertises is preserved.
- */
-
-/**
- * Create-task input as a transport supplies it. Identical to CreateTaskInput
- * except `labels` is accepted in any raw form (CLI flag arrays, a JSON array,
- * a comma-separated string) and normalized here so no transport re-implements
- * the normalization.
+ * Create-task input as a transport supplies it. It accepts `labels` in raw
+ * transport forms (CLI flag arrays, JSON arrays, comma-separated strings), then
+ * normalizes them before the provider call. Other provider operations are direct
+ * enough for transports to call the provider without a use-case wrapper.
  */
 export type CreateTaskCommand = Omit<CreateTaskInput, 'labels'> & { labels?: unknown }
 
-export function createTask(provider: KanbanProvider, input: CreateTaskCommand): Promise<Task> {
+export function normalizeCreateTaskInput(input: CreateTaskCommand): CreateTaskInput {
   const { labels, ...rest } = input
-  return provider.createTask({ ...rest, labels: normalizeLabels(labels) })
-}
-
-export function listTasks(provider: KanbanProvider, filters?: TaskListFilters): Promise<Task[]> {
-  return provider.listTasks(filters)
-}
-
-export function getTask(provider: KanbanProvider, idOrRef: string): Promise<Task> {
-  return provider.getTask(idOrRef)
-}
-
-export function updateTask(
-  provider: KanbanProvider,
-  idOrRef: string,
-  input: UpdateTaskInput,
-): Promise<Task> {
-  return provider.updateTask(idOrRef, input)
-}
-
-export function moveTask(provider: KanbanProvider, idOrRef: string, column: string): Promise<Task> {
-  return provider.moveTask(idOrRef, column)
-}
-
-export function deleteTask(provider: KanbanProvider, idOrRef: string): Promise<Task> {
-  return provider.deleteTask(idOrRef)
-}
-
-export function listComments(provider: KanbanProvider, idOrRef: string): Promise<TaskComment[]> {
-  return provider.listComments(idOrRef)
-}
-
-export function getComment(
-  provider: KanbanProvider,
-  idOrRef: string,
-  commentId: string,
-): Promise<TaskComment> {
-  return provider.getComment(idOrRef, commentId)
-}
-
-export function addComment(
-  provider: KanbanProvider,
-  idOrRef: string,
-  body: string,
-): Promise<TaskComment> {
-  return provider.comment(idOrRef, body)
-}
-
-export function updateComment(
-  provider: KanbanProvider,
-  idOrRef: string,
-  commentId: string,
-  body: string,
-): Promise<TaskComment> {
-  return provider.updateComment(idOrRef, commentId, body)
-}
-
-export function getBoard(provider: KanbanProvider): Promise<BoardView> {
-  return provider.getBoard()
-}
-
-export function getBootstrap(provider: KanbanProvider): Promise<BoardBootstrap> {
-  return provider.getBootstrap()
-}
-
-export function getContext(provider: KanbanProvider): Promise<ProviderContext> {
-  return provider.getContext()
-}
-
-export function listColumns(provider: KanbanProvider): Promise<Column[]> {
-  return provider.listColumns()
-}
-
-export function getActivity(
-  provider: KanbanProvider,
-  limit?: number,
-  taskId?: string,
-): Promise<ActivityEntry[]> {
-  return provider.getActivity(limit, taskId)
-}
-
-export function getMetrics(provider: KanbanProvider): Promise<BoardMetrics> {
-  return provider.getMetrics()
-}
-
-export function getConfig(provider: KanbanProvider): Promise<BoardConfig> {
-  return provider.getConfig()
-}
-
-export function patchConfig(
-  provider: KanbanProvider,
-  input: Partial<BoardConfig>,
-): Promise<BoardConfig> {
-  return provider.patchConfig(input)
+  return { ...rest, labels: normalizeLabels(labels) }
 }

package/src/webhook-events.ts

@@ -25,7 +25,7 @@
 import type { JSONValue, Sql } from 'postgres'
 
 import type { TrackerProvider } from './tracker-config'
-import type { WebhookResult } from './webhooks'
+import type { WebhookRequest, WebhookResult } from './webhooks'
 
 export type WebhookEventStatus = 'accepted' | 'skipped' | 'error'
 
@@ -70,6 +70,34 @@ export function webhookEventStatus(result: WebhookResult): WebhookEventStatus {
   return result.handled ? 'accepted' : 'skipped'
 }
 
+/** Run a webhook dispatch and record its outcome (accepted/skipped/error) fire-and-forget. */
+export async function withWebhookRecording(
+  sql: Sql,
+  provider: TrackerProvider,
+  payload: WebhookRequest,
+  dispatch: () => Promise<WebhookResult>,
+): Promise<WebhookResult> {
+  const meta = extractWebhookMeta(provider, payload.rawBody)
+  let result: WebhookResult
+  try {
+    result = await dispatch()
+  } catch (err) {
+    void recordWebhookEvent(sql, {
+      provider,
+      ...meta,
+      status: 'error',
+      detail: { error: err instanceof Error ? err.message : String(err) },
+    })
+    throw err
+  }
+  void recordWebhookEvent(sql, {
+    provider,
+    ...meta,
+    status: webhookEventStatus(result),
+  })
+  return result
+}
+
 /** Append a receipt. Swallows every error — a logging miss must never fail the webhook. */
 export async function recordWebhookEvent(sql: Sql, record: WebhookEventRecord): Promise<void> {
   if (!webhookEventsEnabled()) return