@andypai/agent-kanban 0.3.4 → 0.3.5

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

@@ -0,0 +1,309 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test'
+import postgres from 'postgres'
+
+import { run } from '../index'
+import type { Task, TaskComment } from '../types'
+
+const databaseUrl = process.env['KANBAN_PG_TEST_URL'] ?? process.env['DATABASE_URL']
+const pgTest = databaseUrl ? test : test.skip
+
+type StubIssue = {
+  id: string
+  identifier: string
+  title: string
+  description: string
+  priority: number
+  url: string
+  createdAt: string
+  updatedAt: string
+  assignee: { id: string; name: string; displayName: string } | null
+  project: { id: string; name: string; url: string; state: string } | null
+  state: { id: string; name: string; position: number }
+  labels: { nodes: Array<{ id: string; name: string }> }
+  comments: { nodes: Array<{ id: string }>; pageInfo: { hasNextPage: boolean; endCursor: null } }
+}
+
+type StubComment = {
+  id: string
+  body: string
+  createdAt: string
+  updatedAt: string
+  user: { id: string; name: string; displayName: string }
+}
+
+function expectOk<T>(result: Awaited<ReturnType<typeof run>>): T {
+  expect(result.exitCode).toBe(0)
+  expect(result.output.ok).toBe(true)
+  if (!result.output.ok) throw new Error('expected successful CLI output')
+  return result.output.data as T
+}
+
+function makeIssue(overrides: Partial<StubIssue> = {}): StubIssue {
+  return {
+    id: overrides.id ?? 'lin-1',
+    identifier: overrides.identifier ?? 'GB-1',
+    title: overrides.title ?? 'Postgres cached Linear issue',
+    description: overrides.description ?? 'Cached in Postgres',
+    priority: overrides.priority ?? 2,
+    url: overrides.url ?? 'https://linear.app/issue/GB-1',
+    createdAt: overrides.createdAt ?? '2026-01-01T00:00:00.000Z',
+    updatedAt: overrides.updatedAt ?? '2026-01-02T00:00:00.000Z',
+    assignee: overrides.assignee ?? { id: 'user-1', name: 'Alice', displayName: 'Alice' },
+    project: overrides.project ?? {
+      id: 'proj-1',
+      name: 'Garage',
+      url: 'https://linear.app/project/garage',
+      state: 'started',
+    },
+    state: overrides.state ?? { id: 'state-todo', name: 'Todo', position: 0 },
+    labels: overrides.labels ?? { nodes: [{ id: 'label-1', name: 'garage' }] },
+    comments: overrides.comments ?? {
+      nodes: [],
+      pageInfo: { hasNextPage: false, endCursor: null },
+    },
+  }
+}
+
+function linearFetchStub(): typeof fetch {
+  const commentsByIssue = new Map<string, StubComment[]>()
+  const issues: StubIssue[] = [makeIssue()]
+  const states = [
+    { id: 'state-todo', name: 'Todo', position: 0, color: '#888', type: 'unstarted' },
+    { id: 'state-done', name: 'Done', position: 1, color: '#0a0', type: 'completed' },
+  ]
+  const team = { id: 'team-1', key: 'GB', name: 'Garage Band', states: { nodes: states } }
+  const users = {
+    nodes: [
+      { id: 'user-1', name: 'Alice', displayName: 'Alice', active: true },
+      { id: 'user-2', name: 'Bob', displayName: 'Bob', active: true },
+    ],
+  }
+  const projects = {
+    nodes: [
+      { id: 'proj-1', name: 'Garage', url: 'https://linear.app/project/garage', state: 'started' },
+    ],
+  }
+
+  return (async (_input: string | URL | Request, init?: RequestInit) => {
+    const body = JSON.parse(String(init?.body ?? '{}')) as {
+      query: string
+      variables?: Record<string, unknown>
+    }
+    const query = body.query
+    const variables = body.variables ?? {}
+
+    if (query.includes('query TeamSnapshot')) {
+      return Response.json({ data: { team } })
+    }
+    if (query.includes('query Users')) {
+      return Response.json({ data: { users } })
+    }
+    if (query.includes('query Projects')) {
+      return Response.json({ data: { projects } })
+    }
+    if (query.includes('query Issues')) {
+      return Response.json({
+        data: {
+          issues: {
+            nodes: issues,
+            pageInfo: { hasNextPage: false, endCursor: null },
+          },
+        },
+      })
+    }
+    if (query.includes('mutation CreateIssue')) {
+      const input = variables.input as {
+        title: string
+        description?: string
+        priority?: number
+        stateId?: string
+        assigneeId?: string
+        projectId?: string
+      }
+      const state = states.find((candidate) => candidate.id === input.stateId) ?? states[0]!
+      const issue = makeIssue({
+        id: 'lin-2',
+        identifier: 'GB-2',
+        title: input.title,
+        description: input.description ?? '',
+        priority: input.priority ?? 0,
+        state,
+        assignee: users.nodes.find((user) => user.id === input.assigneeId) ?? null,
+        project: projects.nodes.find((project) => project.id === input.projectId) ?? null,
+        updatedAt: '2026-01-03T00:00:00.000Z',
+      })
+      issues.push(issue)
+      return Response.json({ data: { issueCreate: { success: true, issue } } })
+    }
+    if (query.includes('mutation UpdateIssue')) {
+      const issue = issues.find((candidate) => candidate.id === variables.id)
+      const input = variables.input as { stateId?: string; title?: string }
+      if (issue) {
+        if (input.stateId) {
+          const state = states.find((candidate) => candidate.id === input.stateId)
+          if (state) issue.state = state
+        }
+        if (input.title) issue.title = input.title
+        issue.updatedAt = '2026-01-04T00:00:00.000Z'
+      }
+      return Response.json({ data: { issueUpdate: { success: true } } })
+    }
+    if (query.includes('query IssueComments')) {
+      const issueId = String(variables.issueId)
+      return Response.json({
+        data: {
+          issue: {
+            comments: {
+              nodes: commentsByIssue.get(issueId) ?? [],
+              pageInfo: { hasNextPage: false, endCursor: null },
+            },
+          },
+        },
+      })
+    }
+    if (query.includes('query Comment')) {
+      const comment = [...commentsByIssue.values()]
+        .flat()
+        .find((candidate) => candidate.id === variables.id)
+      return Response.json({ data: { comment: comment ?? null } })
+    }
+    if (query.includes('mutation CommentCreate')) {
+      const input = variables.input as { issueId: string; body: string }
+      const row: StubComment = {
+        id: `comment-${(commentsByIssue.get(input.issueId)?.length ?? 0) + 1}`,
+        body: input.body,
+        createdAt: '2026-01-05T00:00:00.000Z',
+        updatedAt: '2026-01-05T00:00:00.000Z',
+        user: { id: 'user-1', name: 'Alice', displayName: 'Alice' },
+      }
+      commentsByIssue.set(input.issueId, [...(commentsByIssue.get(input.issueId) ?? []), row])
+      return Response.json({ data: { commentCreate: { success: true, comment: row } } })
+    }
+    if (query.includes('mutation CommentUpdate')) {
+      const row = [...commentsByIssue.values()]
+        .flat()
+        .find((candidate) => candidate.id === variables.id)
+      if (row) {
+        row.body = (variables.input as { body: string }).body
+        row.updatedAt = '2026-01-06T00:00:00.000Z'
+      }
+      return Response.json({ data: { commentUpdate: { success: true, comment: row ?? null } } })
+    }
+    if (query.includes('query IssueHistory')) {
+      return Response.json({
+        data: {
+          issue: {
+            history: {
+              nodes: [],
+              pageInfo: { hasNextPage: false, endCursor: null },
+            },
+          },
+        },
+      })
+    }
+    if (query.includes('query IssueTeam')) {
+      return Response.json({ data: { issue: { team: { id: 'team-1', key: 'GB' } } } })
+    }
+
+    return Response.json({ errors: [{ message: 'unhandled Linear query' }] }, { status: 500 })
+  }) as typeof fetch
+}
+
+describe('postgres linear provider', () => {
+  let previousEnv: Record<string, string | undefined>
+  let previousFetch: typeof fetch
+  let sql: postgres.Sql | null = null
+
+  beforeEach(async () => {
+    previousFetch = globalThis.fetch
+    previousEnv = {
+      KANBAN_STORAGE: process.env['KANBAN_STORAGE'],
+      KANBAN_DATABASE_URL: process.env['KANBAN_DATABASE_URL'],
+      KANBAN_PROVIDER: process.env['KANBAN_PROVIDER'],
+      LINEAR_API_KEY: process.env['LINEAR_API_KEY'],
+      LINEAR_TEAM_ID: process.env['LINEAR_TEAM_ID'],
+    }
+    process.env['KANBAN_STORAGE'] = 'postgres'
+    process.env['KANBAN_DATABASE_URL'] = databaseUrl
+    process.env['KANBAN_PROVIDER'] = 'linear'
+    process.env['LINEAR_API_KEY'] = 'linear-key'
+    process.env['LINEAR_TEAM_ID'] = 'GB'
+
+    if (databaseUrl) {
+      sql = postgres(databaseUrl, { max: 1, onnotice: () => {} })
+      await sql`DROP TABLE IF EXISTS linear_activity`
+      await sql`DROP TABLE IF EXISTS linear_issues`
+      await sql`DROP TABLE IF EXISTS linear_projects`
+      await sql`DROP TABLE IF EXISTS linear_users`
+      await sql`DROP TABLE IF EXISTS linear_states`
+      await sql`DROP TABLE IF EXISTS linear_sync_meta`
+    }
+    globalThis.fetch = linearFetchStub()
+  })
+
+  afterEach(async () => {
+    globalThis.fetch = previousFetch
+    if (sql) {
+      await sql.end({ timeout: 1 })
+      sql = null
+    }
+    for (const [key, value] of Object.entries(previousEnv)) {
+      if (value === undefined) delete process.env[key]
+      else process.env[key] = value
+    }
+  })
+
+  pgTest('lists Linear tasks from a shared Postgres cache through the CLI path', async () => {
+    const tasks = expectOk<Task[]>(await run(['task', 'list', '-c', 'Todo']))
+
+    expect(tasks).toHaveLength(1)
+    expect(tasks[0]).toMatchObject({
+      id: 'linear:lin-1',
+      externalRef: 'GB-1',
+      title: 'Postgres cached Linear issue',
+      priority: 'high',
+      assignee: 'Alice',
+      project: 'Garage',
+    })
+  })
+
+  pgTest('creates, moves, and comments on Linear tasks through Postgres storage', async () => {
+    const created = expectOk<Task>(
+      await run([
+        'task',
+        'add',
+        'Created through Postgres Linear',
+        '-d',
+        'from the public CLI path',
+        '-p',
+        'medium',
+        '-a',
+        'Alice',
+        '--project',
+        'Garage',
+      ]),
+    )
+
+    expect(created).toMatchObject({
+      id: 'linear:lin-2',
+      externalRef: 'GB-2',
+      title: 'Created through Postgres Linear',
+      priority: 'medium',
+    })
+
+    const moved = expectOk<Task>(await run(['task', 'move', 'GB-2', 'Done']))
+    expect(moved.column_id).toBe('state-done')
+
+    const comment = expectOk<TaskComment>(
+      await run(['comment', 'add', 'GB-2', 'Garage projection comment']),
+    )
+    expect(comment).toMatchObject({
+      id: 'comment-1',
+      task_id: 'linear:lin-2',
+      body: 'Garage projection comment',
+    })
+
+    const comments = expectOk<TaskComment[]>(await run(['comment', 'list', 'GB-2']))
+    expect(comments).toHaveLength(1)
+  })
+})

package/src/__tests__/postgres-local-provider.test.ts

@@ -0,0 +1,129 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test'
+import postgres from 'postgres'
+
+import { run } from '../index'
+import type { Task, TaskComment, TaskWithColumn } from '../types'
+
+const databaseUrl = process.env['KANBAN_PG_TEST_URL'] ?? process.env['DATABASE_URL']
+const pgTest = databaseUrl ? test : test.skip
+
+function expectOk<T>(result: Awaited<ReturnType<typeof run>>): T {
+  expect(result.exitCode).toBe(0)
+  expect(result.output.ok).toBe(true)
+  if (!result.output.ok) throw new Error('expected successful CLI output')
+  return result.output.data as T
+}
+
+describe('postgres local provider', () => {
+  let previousStorage: string | undefined
+  let previousDatabaseUrl: string | undefined
+  let previousProvider: string | undefined
+  let previousDbPath: string | undefined
+  let previousDefaultColumns: string | undefined
+  let sql: postgres.Sql | null = null
+
+  beforeEach(async () => {
+    previousStorage = process.env['KANBAN_STORAGE']
+    previousDatabaseUrl = process.env['KANBAN_DATABASE_URL']
+    previousProvider = process.env['KANBAN_PROVIDER']
+    previousDbPath = process.env['KANBAN_DB_PATH']
+    previousDefaultColumns = process.env['KANBAN_DEFAULT_COLUMNS']
+
+    process.env['KANBAN_STORAGE'] = 'postgres'
+    process.env['KANBAN_DATABASE_URL'] = databaseUrl
+    process.env['KANBAN_PROVIDER'] = 'local'
+    delete process.env['KANBAN_DB_PATH']
+
+    if (databaseUrl) {
+      sql = postgres(databaseUrl, { max: 1, onnotice: () => {} })
+      await sql`DROP TABLE IF EXISTS comments`
+      await sql`DROP TABLE IF EXISTS column_time_tracking`
+      await sql`DROP TABLE IF EXISTS activity_log`
+      await sql`DROP TABLE IF EXISTS tasks`
+      await sql`DROP TABLE IF EXISTS columns`
+    }
+  })
+
+  afterEach(async () => {
+    if (sql) {
+      await sql.end({ timeout: 1 })
+      sql = null
+    }
+
+    if (previousStorage === undefined) delete process.env['KANBAN_STORAGE']
+    else process.env['KANBAN_STORAGE'] = previousStorage
+    if (previousDatabaseUrl === undefined) delete process.env['KANBAN_DATABASE_URL']
+    else process.env['KANBAN_DATABASE_URL'] = previousDatabaseUrl
+    if (previousProvider === undefined) delete process.env['KANBAN_PROVIDER']
+    else process.env['KANBAN_PROVIDER'] = previousProvider
+    if (previousDbPath === undefined) delete process.env['KANBAN_DB_PATH']
+    else process.env['KANBAN_DB_PATH'] = previousDbPath
+    if (previousDefaultColumns === undefined) delete process.env['KANBAN_DEFAULT_COLUMNS']
+    else process.env['KANBAN_DEFAULT_COLUMNS'] = previousDefaultColumns
+  })
+
+  pgTest('runs task and comment commands through Postgres storage', async () => {
+    const created = expectOk<TaskWithColumn>(
+      await run([
+        'task',
+        'add',
+        'Postgres-backed task',
+        '-d',
+        'Stored in Postgres',
+        '-c',
+        'recurring',
+        '-p',
+        'high',
+        '-a',
+        'garage',
+        '--project',
+        'Dispatch',
+        '-m',
+        '{"storage":"postgres"}',
+      ]),
+    )
+
+    expect(created.title).toBe('Postgres-backed task')
+    expect(created.column_name).toBe('recurring')
+    expect(created.version).toBe('0')
+
+    const listed = expectOk<Task[]>(await run(['task', 'list', '-c', 'recurring']))
+    expect(listed.map((task) => task.id)).toContain(created.id)
+
+    const updated = expectOk<Task>(
+      await run(['task', 'update', created.id, '--title', 'Updated from Postgres', '-p', 'urgent']),
+    )
+    expect(updated.title).toBe('Updated from Postgres')
+    expect(updated.priority).toBe('urgent')
+    expect(updated.version).toBe('1')
+
+    const comment = expectOk<TaskComment>(
+      await run(['comment', 'add', created.id, 'Projection comment stored in Postgres']),
+    )
+    expect(comment.task_id).toBe(created.id)
+
+    const comments = expectOk<TaskComment[]>(await run(['comment', 'list', created.id]))
+    expect(comments).toHaveLength(1)
+    expect(comments[0]!.body).toBe('Projection comment stored in Postgres')
+  })
+
+  pgTest('seeds custom default columns for Garage local compose', async () => {
+    process.env['KANBAN_DEFAULT_COLUMNS'] = 'Todo,In Progress,Human Review,Merging,Done'
+
+    const created = expectOk<TaskWithColumn>(
+      await run(['task', 'add', 'Garage column task', '-c', 'Todo']),
+    )
+
+    expect(created.column_name).toBe('Todo')
+  })
+
+  pgTest('defaults new tasks to the first configured column when backlog is absent', async () => {
+    process.env['KANBAN_DEFAULT_COLUMNS'] = 'Todo,In Progress,Human Review,Merging,Done'
+
+    const created = expectOk<TaskWithColumn>(
+      await run(['task', 'add', 'Garage default column task']),
+    )
+
+    expect(created.column_name).toBe('Todo')
+  })
+})

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

@@ -0,0 +1,39 @@
+import { describe, expect, test } from 'bun:test'
+
+import { resolveKanbanStorageConfig } from '../storage-config'
+
+describe('resolveKanbanStorageConfig', () => {
+  test('defaults to sqlite using the resolved board path', () => {
+    const config = resolveKanbanStorageConfig(
+      { HOME: '/tmp/kanban-home' },
+      { defaultSqlitePath: '/tmp/board.db' },
+    )
+
+    expect(config).toEqual({ mode: 'sqlite', sqlitePath: '/tmp/board.db' })
+  })
+
+  test('accepts uppercase postgres mode and requires a database URL', () => {
+    expect(() =>
+      resolveKanbanStorageConfig({ KANBAN_STORAGE: 'POSTGRES' }, { defaultSqlitePath: 'ignored' }),
+    ).toThrow('KANBAN_DATABASE_URL is required when KANBAN_STORAGE=postgres')
+
+    expect(
+      resolveKanbanStorageConfig(
+        {
+          KANBAN_STORAGE: 'POSTGRES',
+          KANBAN_DATABASE_URL: 'postgres://garage:garage@localhost:5432/garage',
+        },
+        { defaultSqlitePath: 'ignored' },
+      ),
+    ).toEqual({
+      mode: 'postgres',
+      databaseUrl: 'postgres://garage:garage@localhost:5432/garage',
+    })
+  })
+
+  test('rejects unknown storage modes', () => {
+    expect(() =>
+      resolveKanbanStorageConfig({ KANBAN_STORAGE: 'mysql' }, { defaultSqlitePath: 'ignored' }),
+    ).toThrow("Unsupported KANBAN_STORAGE 'mysql'")
+  })
+})

package/src/index.ts

@@ -4,14 +4,17 @@ import { parseArgs } from 'node:util'
 import { Database } from 'bun:sqlite'
 import { KanbanError, ErrorCode } from './errors'
 import { formatOutput, error, success } from './output'
-import { openDb, getDbPath, initSchema, migrateSchema, seedDefaultColumns } from './db'
+import { getDbPath, initSchema, seedDefaultColumns } from './db'
 import { boardInit, boardReset } from './commands/board'
 import { columnAdd, columnDelete, columnList, columnRename, columnReorder } from './commands/column'
 import { bulkClearDoneCmd, bulkMoveAllCmd } from './commands/bulk'
 import { getConfigPath, loadConfig, saveConfig } from './config'
 import type { CliOutput, Priority } from './types'
-import { createProvider } from './providers/index'
 import { unsupportedOperation } from './providers/errors'
+import { openKanbanRuntime } from './provider-runtime'
+import { trackerConfigFromEnv } from './tracker-config'
+import type { KanbanProvider } from './providers/types'
+import { resolvePollingSyncIntervalMs } from './sync-config'
 
 interface ParsedArgs {
   values: Record<string, unknown>
@@ -48,7 +51,7 @@ function requireLocalProvider(providerType: string, feature: string): void {
 }
 
 async function routeTask(
-  provider: ReturnType<typeof createProvider>,
+  provider: KanbanProvider,
   action: string | undefined,
   positionals: string[],
   values: Record<string, unknown>,
@@ -140,7 +143,7 @@ async function routeTask(
 }
 
 async function routeComment(
-  provider: ReturnType<typeof createProvider>,
+  provider: KanbanProvider,
   action: string | undefined,
   positionals: string[],
 ): Promise<CliOutput> {
@@ -224,7 +227,7 @@ function routeBulk(
 }
 
 async function routeConfig(
-  provider: ReturnType<typeof createProvider>,
+  provider: KanbanProvider,
   dbPath: string,
   action: string | undefined,
   positionals: string[],
@@ -288,7 +291,7 @@ async function routeConfig(
 
 async function routeBoard(
   db: Database,
-  provider: ReturnType<typeof createProvider>,
+  provider: KanbanProvider,
   action: string | undefined,
 ): Promise<CliOutput> {
   switch (action) {
@@ -316,23 +319,29 @@ async function run(argv: string[]): Promise<{ output: CliOutput; exitCode: numbe
     return { output: { ok: true, data: { message: HELP_TEXT } }, exitCode: 0 }
   }
 
-  const dbPath = (values.db as string | undefined) ?? getDbPath()
-  const db = openDb(dbPath)
-  migrateSchema(db)
+  const runtime = await openKanbanRuntime({
+    dbPath: (values.db as string | undefined) ?? getDbPath(),
+  })
 
   try {
-    const provider = createProvider(db, dbPath)
+    const { provider, sqliteDb, dbPath } = runtime
     const group = positionals[0]
     const action = positionals[1]
 
     if (!group) {
-      return { output: await routeBoard(db, provider, undefined), exitCode: 0 }
+      if (sqliteDb) return { output: await routeBoard(sqliteDb, provider, undefined), exitCode: 0 }
+      return { output: success(await provider.getBoard()), exitCode: 0 }
     }
 
     let output: CliOutput
     switch (group) {
       case 'board':
-        output = await routeBoard(db, provider, action)
+        if (sqliteDb) {
+          output = await routeBoard(sqliteDb, provider, action)
+        } else {
+          if (action === 'view' || action === undefined) output = success(await provider.getBoard())
+          else unsupportedOperation(`board ${action} is not available with KANBAN_STORAGE=postgres`)
+        }
         break
       case 'task':
         output = await routeTask(provider, action, positionals, values)
@@ -341,13 +350,24 @@ async function run(argv: string[]): Promise<{ output: CliOutput; exitCode: numbe
         output = await routeComment(provider, action, positionals)
         break
       case 'column':
-        output = routeColumn(db, provider.type, action, positionals, values)
+        if (!sqliteDb)
+          unsupportedOperation('Column commands are not available with KANBAN_STORAGE=postgres')
+        output = routeColumn(sqliteDb, provider.type, action, positionals, values)
         break
       case 'bulk':
-        output = routeBulk(db, provider.type, action, positionals)
+        if (!sqliteDb)
+          unsupportedOperation('Bulk commands are not available with KANBAN_STORAGE=postgres')
+        output = routeBulk(sqliteDb, provider.type, action, positionals)
         break
       case 'config':
-        output = await routeConfig(provider, dbPath, action, positionals, values)
+        if (sqliteDb) {
+          output = await routeConfig(provider, dbPath, action, positionals, values)
+        } else {
+          if (action === 'show' || action === undefined)
+            output = success(await provider.getConfig())
+          else
+            unsupportedOperation(`config ${action} is not available with KANBAN_STORAGE=postgres`)
+        }
         break
       default:
         throw new KanbanError(ErrorCode.UNKNOWN_COMMAND, `Unknown command group '${group}'`)
@@ -355,7 +375,7 @@ async function run(argv: string[]): Promise<{ output: CliOutput; exitCode: numbe
 
     return { output, exitCode: 0 }
   } finally {
-    db.close()
+    await runtime.close()
   }
 }
 
@@ -397,18 +417,19 @@ Commands:
   config add-project <name>   Add project
   config remove-project <name> Remove project
 
-  serve                       Start web dashboard [--port 3000]
+  serve                       Start web dashboard [--port 3000] [--sync-interval-ms ms]
   mcp                         Run as an MCP server over stdio (for Claude Desktop, etc.)
 
 Options:
   --pretty      Human-readable output (default: JSON)
-  --db <path>   Database path (default: local ./.kanban if present, else ~/.kanban if present, else create ./.kanban)
+  --db <path>   SQLite database path (default: local ./.kanban if present, else ~/.kanban if present, else create ./.kanban)
   --project <n> Filter/set project
   -h, --help    Show this help`
 
 export interface ServeOptions {
   db?: string
   port: number
+  syncIntervalMs?: number
   tunnel: boolean
 }
 
@@ -418,6 +439,7 @@ export function parseServeArgs(argv: string[]): ServeOptions {
     options: {
       db: { type: 'string' },
       port: { type: 'string' },
+      'sync-interval-ms': { type: 'string' },
       tunnel: { type: 'boolean', default: false },
     },
     strict: false,
@@ -429,10 +451,17 @@ export function parseServeArgs(argv: string[]): ServeOptions {
   return {
     db: values.db as string | undefined,
     port,
+    ...(values['sync-interval-ms']
+      ? { syncIntervalMs: parseSyncIntervalMs(values['sync-interval-ms'] as string) }
+      : {}),
     tunnel: Boolean(values.tunnel),
   }
 }
 
+function parseSyncIntervalMs(raw: string): number {
+  return resolvePollingSyncIntervalMs(raw, { label: '--sync-interval-ms' })
+}
+
 export interface McpOptions {
   db?: string
 }
@@ -452,21 +481,29 @@ if (import.meta.main) {
 
   if (argv[0] === 'mcp') {
     const opts = parseMcpArgs(argv)
-    const dbPath = opts.db ?? getDbPath()
-    const db = openDb(dbPath)
-    migrateSchema(db)
-    const provider = createProvider(db, dbPath)
+    const runtime = await openKanbanRuntime({ dbPath: opts.db ?? getDbPath() })
     const { startStdioMcpServer } = await import('./commands/mcp')
-    await startStdioMcpServer(provider)
+    try {
+      await startStdioMcpServer(runtime.provider)
+    } finally {
+      await runtime.close()
+    }
   } else if (argv[0] === 'serve') {
     const opts = parseServeArgs(argv)
 
-    const dbPath = opts.db ?? getDbPath()
-    const db = openDb(dbPath)
-    migrateSchema(db)
-    const provider = createProvider(db, dbPath)
+    const runtime = await openKanbanRuntime({
+      dbPath: opts.db ?? getDbPath(),
+      ...(opts.syncIntervalMs !== undefined
+        ? {
+            tracker: {
+              ...trackerConfigFromEnv(process.env),
+              syncIntervalMs: opts.syncIntervalMs,
+            },
+          }
+        : {}),
+    })
     const { startServer } = await import('./server')
-    startServer(provider, opts.port)
+    startServer(runtime.provider, opts.port, { syncIntervalMs: runtime.syncIntervalMs })
 
     if (opts.tunnel) {
       const { startCloudflareTunnel } = await import('./tunnel')