@andypai/agent-kanban 0.3.3 → 0.3.4

package/README.md

@@ -62,18 +62,19 @@ Running `kanban` with no arguments is equivalent to `kanban board view`.
 
 All operations route through a provider backend. Set `KANBAN_PROVIDER` to choose one.
 
-| Variable           | Default       | Description                                                              |
-| ------------------ | ------------- | ------------------------------------------------------------------------ |
-| `KANBAN_PROVIDER`  | `local`       | `local`, `linear`, or `jira`                                             |
-| `KANBAN_DB_PATH`   | auto-resolved | SQLite database path                                                     |
-| `LINEAR_API_KEY`   | —             | Required when `KANBAN_PROVIDER=linear`                                   |
-| `LINEAR_TEAM_ID`   | —             | Required when `KANBAN_PROVIDER=linear`                                   |
-| `JIRA_BASE_URL`    | —             | Required when `KANBAN_PROVIDER=jira` (e.g. `https://acme.atlassian.net`) |
-| `JIRA_EMAIL`       | —             | Required when `KANBAN_PROVIDER=jira` (Atlassian account email)           |
-| `JIRA_API_TOKEN`   | —             | Required when `KANBAN_PROVIDER=jira` (Atlassian API token)               |
-| `JIRA_PROJECT_KEY` | —             | Required when `KANBAN_PROVIDER=jira` (e.g. `ENG`)                        |
-| `JIRA_BOARD_ID`    | —             | Optional when `KANBAN_PROVIDER=jira` (Agile board id for column order)   |
-| `JIRA_ISSUE_TYPE`  | `Task`        | Optional when `KANBAN_PROVIDER=jira` (default issue type for new tasks)  |
+| Variable                  | Default       | Description                                                              |
+| ------------------------- | ------------- | ------------------------------------------------------------------------ |
+| `KANBAN_PROVIDER`         | `local`       | `local`, `linear`, or `jira`                                             |
+| `KANBAN_DB_PATH`          | auto-resolved | SQLite database path                                                     |
+| `KANBAN_SYNC_INTERVAL_MS` | `30000`       | Polling sync interval for remote providers; integer milliseconds >= 1000 |
+| `LINEAR_API_KEY`          | —             | Required when `KANBAN_PROVIDER=linear`                                   |
+| `LINEAR_TEAM_ID`          | —             | Required when `KANBAN_PROVIDER=linear`                                   |
+| `JIRA_BASE_URL`           | —             | Required when `KANBAN_PROVIDER=jira` (e.g. `https://acme.atlassian.net`) |
+| `JIRA_EMAIL`              | —             | Required when `KANBAN_PROVIDER=jira` (Atlassian account email)           |
+| `JIRA_API_TOKEN`          | —             | Required when `KANBAN_PROVIDER=jira` (Atlassian API token)               |
+| `JIRA_PROJECT_KEY`        | —             | Required when `KANBAN_PROVIDER=jira` (e.g. `ENG`)                        |
+| `JIRA_BOARD_ID`           | —             | Optional when `KANBAN_PROVIDER=jira` (Agile board id for column order)   |
+| `JIRA_ISSUE_TYPE`         | `Task`        | Optional when `KANBAN_PROVIDER=jira` (default issue type for new tasks)  |
 
 Without `KANBAN_DB_PATH`, the local provider resolves the database in this order:
 
@@ -301,8 +302,9 @@ Starts a Bun HTTP server with:
 - **Sync status** at `/api/sync-status` — reports background sync state plus provider sync metadata
 
 In `serve` mode, remote providers now warm once on startup and continue syncing
-in the background every 30 seconds. Full reconciliation is still handled by the
-provider-specific logic on top of that steady cadence.
+in the background every `KANBAN_SYNC_INTERVAL_MS` milliseconds. Full
+reconciliation is still handled by the provider-specific logic on top of that
+steady cadence.
 
 Comment routes:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andypai/agent-kanban",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "description": "Agent-friendly kanban board CLI. Manage tasks via bash commands, parse structured JSON output.",
   "homepage": "https://github.com/abpai/agent-kanban#readme",
   "repository": {

package/src/__tests__/jira-provider-read.test.ts

@@ -240,6 +240,28 @@ describe('JiraProvider read path', () => {
     }
   })
 
+  test('custom polling sync interval refreshes before the default 30 seconds', async () => {
+    const { fn, calls } = jiraFetchStub(standardRoutes({}))
+    globalThis.fetch = fn
+    const client = new JiraClient({
+      baseUrl: baseConfig.baseUrl,
+      email: baseConfig.email,
+      apiToken: baseConfig.apiToken,
+    })
+    const provider = new JiraProvider(db, { ...baseConfig, pollingSyncIntervalMs: 5_000 }, client)
+    saveJiraSyncMeta(db, {
+      projectKey: 'ENG',
+      lastSyncAt: '2026-01-01T00:00:00.000Z',
+      lastFullSyncAt: '2026-01-01T00:00:00.000Z',
+      lastIssueUpdatedAt: '2026-01-01T00:00:00.000Z',
+    })
+    Date.now = () => Date.parse('2026-01-01T00:00:06.000Z')
+
+    await provider.listTasks()
+
+    expect(calls.some((call) => call.url.includes('/rest/api/3/search/jql'))).toBe(true)
+  })
+
   test('sync delta JQL is exactly project = KEY AND updated >= "<ts>" ORDER BY updated ASC', async () => {
     const capturedJql: string[] = []
     // First sync: one issue returned so lastIssueUpdatedAt is set.

package/src/__tests__/linear-provider-sync.test.ts

@@ -485,4 +485,81 @@ describe('LinearProvider sync', () => {
 
     expect(issueQueries).toBe(1)
   })
+
+  test('custom polling sync interval refreshes before the default 30 seconds', async () => {
+    let issueQueries = 0
+
+    saveSyncMeta(db, {
+      team: { id: 'team-1', key: 'R2P', name: 'R2pi' },
+      lastSyncAt: '2026-01-01T00:00:00.000Z',
+      lastFullSyncAt: '2026-01-01T00:00:00.000Z',
+      lastIssueUpdatedAt: '2026-01-01T00:00:00.000Z',
+    })
+
+    globalThis.fetch = (async (_input: string | URL | Request, init?: RequestInit) => {
+      const body = JSON.parse(String(init?.body)) as {
+        query: string
+        variables: Record<string, unknown>
+      }
+
+      if (body.query.includes('query TeamSnapshot')) {
+        return new Response(
+          JSON.stringify({
+            data: {
+              team: {
+                id: 'team-1',
+                key: 'R2P',
+                name: 'R2pi',
+                states: { nodes: [{ id: 'state-1', name: 'Todo', position: 0 }] },
+              },
+            },
+          }),
+          { status: 200, headers: { 'content-type': 'application/json' } },
+        )
+      }
+
+      if (body.query.includes('query Users')) {
+        return new Response(JSON.stringify({ data: { users: { nodes: [] } } }), {
+          status: 200,
+          headers: { 'content-type': 'application/json' },
+        })
+      }
+
+      if (body.query.includes('query Projects')) {
+        return new Response(JSON.stringify({ data: { projects: { nodes: [] } } }), {
+          status: 200,
+          headers: { 'content-type': 'application/json' },
+        })
+      }
+
+      if (body.query.includes('query Issues')) {
+        issueQueries += 1
+        return new Response(
+          JSON.stringify({
+            data: {
+              issues: {
+                nodes: [],
+                pageInfo: { hasNextPage: false, endCursor: null },
+              },
+            },
+          }),
+          { status: 200, headers: { 'content-type': 'application/json' } },
+        )
+      }
+
+      return new Response(`Unexpected query: ${body.query}`, { status: 500 })
+    }) as unknown as typeof fetch
+
+    const originalDateNow = Date.now
+    Date.now = () => Date.parse('2026-01-01T00:00:06.000Z')
+
+    try {
+      const provider = new LinearProvider(db, 'R2P', 'lin_api_test', 5_000)
+      await provider.getBoard()
+    } finally {
+      Date.now = originalDateNow
+    }
+
+    expect(issueQueries).toBe(1)
+  })
 })

package/src/__tests__/sync-config.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, test } from 'bun:test'
+import { ErrorCode, KanbanError } from '../errors'
+import {
+  DEFAULT_POLLING_SYNC_INTERVAL_MS,
+  MIN_POLLING_SYNC_INTERVAL_MS,
+  resolvePollingSyncIntervalMs,
+} from '../sync-config'
+
+describe('sync config', () => {
+  test('defaults when unset or blank', () => {
+    expect(resolvePollingSyncIntervalMs(undefined)).toBe(DEFAULT_POLLING_SYNC_INTERVAL_MS)
+    expect(resolvePollingSyncIntervalMs('   ')).toBe(DEFAULT_POLLING_SYNC_INTERVAL_MS)
+  })
+
+  test('accepts an integer millisecond interval', () => {
+    expect(resolvePollingSyncIntervalMs('5000')).toBe(5_000)
+  })
+
+  test('rejects invalid or too-aggressive intervals', () => {
+    for (const raw of ['999', '5s', '1000.5', '0']) {
+      let err: unknown
+      try {
+        resolvePollingSyncIntervalMs(raw)
+      } catch (caught) {
+        err = caught
+      }
+      expect(err).toBeInstanceOf(KanbanError)
+      expect((err as KanbanError).code).toBe(ErrorCode.INVALID_CONFIG)
+      expect((err as Error).message).toContain(String(MIN_POLLING_SYNC_INTERVAL_MS))
+    }
+  })
+})

package/src/errors.ts

@@ -9,6 +9,7 @@ export const ErrorCode = {
   INVALID_PRIORITY: 'INVALID_PRIORITY',
   INVALID_METADATA: 'INVALID_METADATA',
   INVALID_POSITION: 'INVALID_POSITION',
+  INVALID_CONFIG: 'INVALID_CONFIG',
   CONFLICT: 'CONFLICT',
   MISSING_ARGUMENT: 'MISSING_ARGUMENT',
   UNKNOWN_COMMAND: 'UNKNOWN_COMMAND',

package/src/mcp/errors.ts

@@ -39,6 +39,7 @@ function providerError(code: ErrorCodeValue): TrackerMcpErrorCode {
     case ErrorCode.INVALID_METADATA:
     case ErrorCode.INVALID_POSITION:
     case ErrorCode.INVALID_PRIORITY:
+    case ErrorCode.INVALID_CONFIG:
     case ErrorCode.MISSING_ARGUMENT:
     case ErrorCode.UNSUPPORTED_OPERATION:
     case ErrorCode.CONFLICT:

package/src/providers/index.ts

@@ -5,6 +5,7 @@ import { JiraProvider } from './jira'
 import { LinearProvider } from './linear'
 import { LocalProvider } from './local'
 import type { KanbanProvider } from './types'
+import { resolvePollingSyncIntervalMs } from '../sync-config'
 
 export function createProvider(db: Database, dbPath = getDbPath()): KanbanProvider {
   const providerType = (process.env['KANBAN_PROVIDER'] ?? 'local') as 'local' | 'linear' | 'jira'
@@ -17,7 +18,7 @@ export function createProvider(db: Database, dbPath = getDbPath()): KanbanProvid
         'LINEAR_API_KEY and LINEAR_TEAM_ID are required when KANBAN_PROVIDER=linear',
       )
     }
-    return new LinearProvider(db, teamId!, apiKey!)
+    return new LinearProvider(db, teamId!, apiKey!, resolvePollingSyncIntervalMs())
   }
 
   if (providerType === 'jira') {
@@ -45,6 +46,7 @@ export function createProvider(db: Database, dbPath = getDbPath()): KanbanProvid
       projectKey: projectKey!,
       boardId: Number.isFinite(boardId) ? boardId : undefined,
       defaultIssueType,
+      pollingSyncIntervalMs: resolvePollingSyncIntervalMs(),
     })
   }
 

package/src/providers/jira.ts

@@ -49,8 +49,8 @@ import type {
   TaskListFilters,
   UpdateTaskInput,
 } from './types'
+import { resolvePollingSyncIntervalMs } from '../sync-config'
 
-const SYNC_INTERVAL_MS = 30_000
 const FULL_RECONCILE_INTERVAL_MS = 5 * 60_000
 
 function shouldRunFullReconcile(lastFullSyncAt: string | null, now: number): boolean {
@@ -78,11 +78,13 @@ export interface JiraProviderConfig {
   projectKey: string
   boardId?: number
   defaultIssueType?: string
+  pollingSyncIntervalMs?: number
 }
 
 export class JiraProvider implements KanbanProvider {
   readonly type = 'jira' as const
   private readonly client: JiraClient
+  private readonly pollingSyncIntervalMs: number
 
   constructor(
     private readonly db: Database,
@@ -90,6 +92,7 @@ export class JiraProvider implements KanbanProvider {
     client?: JiraClient,
   ) {
     initJiraCacheSchema(db)
+    this.pollingSyncIntervalMs = config.pollingSyncIntervalMs ?? resolvePollingSyncIntervalMs()
     this.client =
       client ??
       new JiraClient({
@@ -103,7 +106,7 @@ export class JiraProvider implements KanbanProvider {
     const meta = loadJiraSyncMeta(this.db)
     const lastSyncAtMs = meta.lastSyncAt ? Date.parse(meta.lastSyncAt) : 0
     const now = Date.now()
-    if (!force && lastSyncAtMs && now - lastSyncAtMs < SYNC_INTERVAL_MS) return
+    if (!force && lastSyncAtMs && now - lastSyncAtMs < this.pollingSyncIntervalMs) return
     const fullReconcile = force || shouldRunFullReconcile(meta.lastFullSyncAt, now)
 
     // 1. Resolve project.

package/src/providers/linear.ts

@@ -41,8 +41,8 @@ import type {
   TaskListFilters,
   UpdateTaskInput,
 } from './types'
+import { resolvePollingSyncIntervalMs } from '../sync-config'
 
-const SYNC_INTERVAL_MS = 30_000
 const FULL_RECONCILIATION_INTERVAL_MS = 5 * 60_000
 
 function parseTimestamp(value: string | null | undefined): number {
@@ -81,6 +81,7 @@ export class LinearProvider implements KanbanProvider {
     private readonly db: Database,
     private readonly teamId: string,
     apiKey: string,
+    private readonly pollingSyncIntervalMs = resolvePollingSyncIntervalMs(),
   ) {
     initLinearCacheSchema(db)
     this.client = new LinearClient(apiKey)
@@ -105,7 +106,7 @@ export class LinearProvider implements KanbanProvider {
     const lastSyncAtMs = parseTimestamp(meta.lastSyncAt)
     const lastFullSyncAtMs = parseTimestamp(meta.lastFullSyncAt)
     const now = Date.now()
-    if (!force && lastSyncAtMs && now - lastSyncAtMs < SYNC_INTERVAL_MS) return
+    if (!force && lastSyncAtMs && now - lastSyncAtMs < this.pollingSyncIntervalMs) return
 
     const shouldFullSync =
       force ||

package/src/server.ts

@@ -3,6 +3,7 @@ import { join } from 'node:path'
 import { handleRequest } from './api'
 import type { ServerWebSocket } from 'bun'
 import type { KanbanProvider } from './providers/types'
+import { resolvePollingSyncIntervalMs } from './sync-config'
 
 const wsClients = new Set<ServerWebSocket<unknown>>()
 const CORS_HEADERS = {
@@ -10,8 +11,6 @@ const CORS_HEADERS = {
   'Access-Control-Allow-Methods': 'GET, POST, PATCH, DELETE, OPTIONS',
   'Access-Control-Allow-Headers': 'Content-Type',
 }
-const DEFAULT_BACKGROUND_SYNC_INTERVAL_MS = 30_000
-
 interface BackgroundSyncState {
   enabled: boolean
   inFlight: boolean
@@ -64,7 +63,7 @@ export function startServer(
 ): StartedServer {
   const distDir = join(import.meta.dir, '..', 'ui', 'dist')
   const hasStatic = existsSync(distDir)
-  const syncIntervalMs = opts.syncIntervalMs ?? DEFAULT_BACKGROUND_SYNC_INTERVAL_MS
+  const syncIntervalMs = opts.syncIntervalMs ?? resolvePollingSyncIntervalMs()
   const syncCache = provider.syncCache?.bind(provider)
   const getSyncStatus = provider.getSyncStatus?.bind(provider)
   const backgroundSync: BackgroundSyncState = {

package/src/sync-config.ts

@@ -0,0 +1,18 @@
+import { ErrorCode, KanbanError } from './errors'
+
+export const DEFAULT_POLLING_SYNC_INTERVAL_MS = 30_000
+export const MIN_POLLING_SYNC_INTERVAL_MS = 1_000
+
+export function resolvePollingSyncIntervalMs(raw = process.env['KANBAN_SYNC_INTERVAL_MS']): number {
+  const value = raw?.trim()
+  if (!value) return DEFAULT_POLLING_SYNC_INTERVAL_MS
+
+  const parsed = Number(value)
+  if (!Number.isInteger(parsed) || parsed < MIN_POLLING_SYNC_INTERVAL_MS) {
+    throw new KanbanError(
+      ErrorCode.INVALID_CONFIG,
+      `KANBAN_SYNC_INTERVAL_MS must be an integer >= ${MIN_POLLING_SYNC_INTERVAL_MS}`,
+    )
+  }
+  return parsed
+}