@andypai/agent-kanban 0.3.3 → 0.3.5

package/README.md

@@ -62,20 +62,26 @@ 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)  |
-
-Without `KANBAN_DB_PATH`, the local provider resolves the database in this order:
+| Variable                     | Default       | Description                                                              |
+| ---------------------------- | ------------- | ------------------------------------------------------------------------ |
+| `KANBAN_PROVIDER`            | `local`       | `local`, `linear`, or `jira`                                             |
+| `KANBAN_STORAGE`             | `sqlite`      | `sqlite` or `postgres`                                                   |
+| `KANBAN_DATABASE_URL`        | —             | Required when `KANBAN_STORAGE=postgres`                                  |
+| `KANBAN_DB_PATH`             | auto-resolved | SQLite database path                                                     |
+| `KANBAN_DEFAULT_COLUMNS`     | —             | Optional bootstrap column names for local/Postgres caches                |
+| `KANBAN_DEFAULT_TASK_COLUMN` | —             | Optional created-task column override for local/Postgres caches          |
+| `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)  |
+
+When `KANBAN_STORAGE=sqlite` and `KANBAN_DB_PATH` is unset, the local provider
+resolves the database in this order:
 
 1. `./.kanban/board.db` if it exists in the current working directory
 2. `~/.kanban/board.db` if it exists
@@ -245,6 +251,7 @@ Default columns: `recurring`, `backlog`, `in-progress`, `review`, `done`.
 ```bash
 kanban serve            # default port 3000
 kanban serve --port 8080
+kanban serve --sync-interval-ms 300000
 kanban serve --tunnel   # optional public URL for webhook testing
 ```
 
@@ -300,9 +307,11 @@ Starts a Bun HTTP server with:
 - **Readiness check** at `/api/ready` — reports whether the cache has warmed at least once
 - **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 `serve` mode, remote providers warm once on startup and continue syncing in
+the background on the runtime's configured polling cadence. Use
+`KANBAN_SYNC_INTERVAL_MS` or `kanban serve --sync-interval-ms` to tune it. 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.5",
   "description": "Agent-friendly kanban board CLI. Manage tasks via bash commands, parse structured JSON output.",
   "homepage": "https://github.com/abpai/agent-kanban#readme",
   "repository": {
@@ -55,7 +55,8 @@
     "prepack": "cd ui && bun install --frozen-lockfile && bun run build"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.29.0"
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "postgres": "^3.4.4"
   },
   "devDependencies": {
     "@eslint/js": "^9.39.1",

package/src/__tests__/api.test.ts

@@ -3,17 +3,17 @@ import { Database } from 'bun:sqlite'
 import { initSchema, seedDefaultColumns, addTask } from '../db'
 import { handleRequest } from '../api'
 import { createProvider } from '../providers/index'
+import type { KanbanProvider } from '../providers/types'
 
 let db: Database
-let provider: ReturnType<typeof createProvider>
+let provider: KanbanProvider
 
 beforeEach(() => {
-  process.env['KANBAN_PROVIDER'] = 'local'
   db = new Database(':memory:')
   db.run('PRAGMA foreign_keys = ON')
   initSchema(db)
   seedDefaultColumns(db)
-  provider = createProvider(db, ':memory:')
+  provider = createProvider(db, { provider: 'local' }, ':memory:')
 })
 
 describe('handleRequest', () => {

package/src/__tests__/index.test.ts

@@ -59,8 +59,28 @@ describe('parseServeArgs', () => {
   })
 
   test('--tunnel opts in; --port and --db override', () => {
-    const opts = parseServeArgs(['serve', '--tunnel', '--port', '5050', '--db', '/tmp/b.db'])
-    expect(opts).toEqual({ db: '/tmp/b.db', port: 5050, tunnel: true })
+    const opts = parseServeArgs([
+      'serve',
+      '--tunnel',
+      '--port',
+      '5050',
+      '--db',
+      '/tmp/b.db',
+      '--sync-interval-ms',
+      '600000',
+    ])
+    expect(opts).toEqual({
+      db: '/tmp/b.db',
+      port: 5050,
+      syncIntervalMs: 600_000,
+      tunnel: true,
+    })
+  })
+
+  test('--sync-interval-ms rejects invalid values', () => {
+    for (const raw of ['999', '0']) {
+      expect(() => parseServeArgs(['serve', '--sync-interval-ms', raw])).toThrow(KanbanError)
+    }
   })
 })
 

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__/jira-wiring.test.ts

@@ -6,6 +6,7 @@ import { join } from 'node:path'
 import { ErrorCode, KanbanError } from '../errors'
 import { run } from '../index'
 import { createProvider } from '../providers/index'
+import { trackerConfigFromEnv } from '../tracker-config'
 
 const ENV_KEYS = [
   'KANBAN_PROVIDER',
@@ -17,6 +18,7 @@ const ENV_KEYS = [
   'JIRA_ISSUE_TYPE',
   'LINEAR_API_KEY',
   'LINEAR_TEAM_ID',
+  'KANBAN_SYNC_INTERVAL_MS',
 ] as const
 
 const tempRoot = mkdtempSync(join(tmpdir(), 'jira-wiring-'))
@@ -75,17 +77,16 @@ describe('jira-wiring', () => {
     }
   })
 
-  test('createProvider throws PROVIDER_NOT_CONFIGURED listing missing JIRA_API_TOKEN', () => {
-    const { db, dbPath } = makeDb()
+  test('trackerConfigFromEnv throws PROVIDER_NOT_CONFIGURED listing missing JIRA_API_TOKEN', () => {
     process.env['KANBAN_PROVIDER'] = 'jira'
     process.env['JIRA_BASE_URL'] = 'https://example.atlassian.net'
     process.env['JIRA_EMAIL'] = 'a@example.com'
     delete process.env['JIRA_API_TOKEN']
     process.env['JIRA_PROJECT_KEY'] = 'ENG'
 
-    expect(() => createProvider(db, dbPath)).toThrow(KanbanError)
+    expect(() => trackerConfigFromEnv()).toThrow(KanbanError)
     try {
-      createProvider(db, dbPath)
+      trackerConfigFromEnv()
     } catch (err) {
       expect((err as KanbanError).code).toBe(ErrorCode.PROVIDER_NOT_CONFIGURED)
       expect((err as Error).message).toContain('JIRA_API_TOKEN')
@@ -93,8 +94,7 @@ describe('jira-wiring', () => {
     }
   })
 
-  test('createProvider throws PROVIDER_NOT_CONFIGURED listing multiple missing vars', () => {
-    const { db, dbPath } = makeDb()
+  test('trackerConfigFromEnv throws PROVIDER_NOT_CONFIGURED listing multiple missing vars', () => {
     process.env['KANBAN_PROVIDER'] = 'jira'
     process.env['JIRA_BASE_URL'] = 'https://example.atlassian.net'
     delete process.env['JIRA_EMAIL']
@@ -104,7 +104,7 @@ describe('jira-wiring', () => {
     let msg = ''
     let code: string | undefined
     try {
-      createProvider(db, dbPath)
+      trackerConfigFromEnv()
     } catch (err) {
       msg = (err as Error).message
       code = (err as KanbanError).code
@@ -118,17 +118,42 @@ describe('jira-wiring', () => {
 
   test('createProvider builds JiraProvider when all four required vars are set', () => {
     const { db, dbPath } = makeDb()
-    setJiraRequiredEnv()
-    const provider = createProvider(db, dbPath)
+    const provider = createProvider(
+      db,
+      {
+        provider: 'jira',
+        baseUrl: 'https://example.atlassian.net',
+        email: 'a@example.com',
+        apiToken: 'tok-test',
+        projectKey: 'ENG',
+      },
+      dbPath,
+    )
     expect(provider.type).toBe('jira')
   })
 
-  test('JIRA_BOARD_ID non-numeric falls back to undefined', () => {
-    const { db, dbPath } = makeDb()
+  test('JIRA_BOARD_ID non-numeric falls back to undefined in env loader', () => {
     setJiraRequiredEnv()
     process.env['JIRA_BOARD_ID'] = 'notanumber'
-    const provider = createProvider(db, dbPath)
-    expect(provider.type).toBe('jira')
+    const config = trackerConfigFromEnv()
+    expect(config.provider).toBe('jira')
+    expect(config).not.toHaveProperty('boardId')
+  })
+
+  test('trackerConfigFromEnv carries remote polling sync interval', () => {
+    setJiraRequiredEnv()
+    process.env['KANBAN_SYNC_INTERVAL_MS'] = '60000'
+
+    const jiraConfig = trackerConfigFromEnv()
+    expect(jiraConfig.provider).toBe('jira')
+    expect(jiraConfig.syncIntervalMs).toBe(60_000)
+
+    process.env['KANBAN_PROVIDER'] = 'linear'
+    process.env['LINEAR_API_KEY'] = 'lin_api_test'
+    process.env['LINEAR_TEAM_ID'] = 'team-test'
+    const linearConfig = trackerConfigFromEnv()
+    expect(linearConfig.provider).toBe('linear')
+    expect(linearConfig.syncIntervalMs).toBe(60_000)
   })
 
   test('kanban column add under KANBAN_PROVIDER=jira exits with UNSUPPORTED_OPERATION', async () => {
@@ -178,10 +203,15 @@ describe('jira-wiring', () => {
 
   test('KANBAN_PROVIDER=linear still builds LinearProvider (regression guard)', () => {
     const { db, dbPath } = makeDb()
-    process.env['KANBAN_PROVIDER'] = 'linear'
-    process.env['LINEAR_API_KEY'] = 'lin_api_test'
-    process.env['LINEAR_TEAM_ID'] = 'team-test'
-    const provider = createProvider(db, dbPath)
+    const provider = createProvider(
+      db,
+      {
+        provider: 'linear',
+        apiKey: 'lin_api_test',
+        teamId: 'team-test',
+      },
+      dbPath,
+    )
     expect(provider.type).toBe('linear')
   })
 })

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)
+  })
 })