@andypai/agent-kanban 0.2.0 → 0.3.1

package/README.md

@@ -2,17 +2,29 @@
 
 [![CI](https://github.com/abpai/agent-kanban/actions/workflows/ci.yml/badge.svg)](https://github.com/abpai/agent-kanban/actions/workflows/ci.yml)
 
-Agent-friendly kanban board CLI. Manage tasks via bash commands, parse structured JSON output.
+`agent-kanban` exists because browser-first project tools are a bad control
+plane for agents, shell scripts, and CI jobs. If automation has to click
+through a web app, scrape HTML, or learn a different integration for every
+tracker, the setup gets brittle fast.
 
-## Why
+This repo gives you one small contract across three modes: a local SQLite board,
+Linear, and Jira Cloud. The CLI stays the same. The JSON envelope stays the
+same. Humans still get an optional dashboard when they want a visual pass.
 
-Most project-management tools are built for humans clicking through UIs. `agent-kanban` is built for **CLI-first workflows** — AI agents and scripts get deterministic JSON they can parse, humans get a pretty-printed view and a web dashboard. Runs against a local SQLite file or a Linear backend.
+That buys you a few things that are easy to miss at first:
+
+- You can prototype an agent against a local board, then point the same workflow at Linear or Jira later.
+- Remote modes use webhooks plus polling fallback, so missed events are less painful than with one-shot scripts or browser automation.
+- Local mode needs no external database or service, which makes scratch boards, demos, and CI setups much easier to spin up.
+- The repo also includes a reusable MCP layer, so sibling tools can reuse the same tracker semantics instead of growing their own tracker adapter.
 
 ## Documentation
 
-- [`docs/README.md`](docs/README.md) for the documentation index
-- [`docs/WORKFLOW.md`](docs/WORKFLOW.md) for a common day-to-day workflow
+- [`docs/readme.md`](docs/readme.md) for the documentation index
+- [`docs/workflow.md`](docs/workflow.md) for a common day-to-day workflow
+- [`docs/mcp.md`](docs/mcp.md) for the reusable tracker MCP module
 - [`docs/providers/linear.md`](docs/providers/linear.md) for Linear provider details
+- [`docs/providers/jira.md`](docs/providers/jira.md) for Jira provider details
 - [`SKILL.md`](SKILL.md) for agent-specific repo usage instructions
 
 ## Install
@@ -50,12 +62,18 @@ 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` or `linear`                    |
-| `KANBAN_DB_PATH`  | auto-resolved | SQLite database path                   |
-| `LINEAR_API_KEY`  | —             | Required when `KANBAN_PROVIDER=linear` |
-| `LINEAR_TEAM_ID`  | —             | Required when `KANBAN_PROVIDER=linear` |
+| 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:
 
@@ -72,22 +90,50 @@ export LINEAR_TEAM_ID=<team-id>
 kanban board view
 ```
 
+### Jira quick start
+
+```bash
+export KANBAN_PROVIDER=jira
+export JIRA_BASE_URL=https://your-domain.atlassian.net
+export JIRA_EMAIL=you@example.com
+export JIRA_API_TOKEN=...
+export JIRA_PROJECT_KEY=ENG
+export JIRA_BOARD_ID=123  # optional
+kanban board view
+```
+
 ### Capability matrix
 
-| Capability              | Local | Linear |
-| ----------------------- | ----- | ------ |
-| task create/update/move | yes   | yes    |
-| task delete             | yes   | no     |
-| activity log            | yes   | no     |
-| metrics                 | yes   | no     |
-| column CRUD             | yes   | no     |
-| bulk operations         | yes   | no     |
-| config edit             | yes   | no     |
+| Capability                 | Local | Linear | Jira |
+| -------------------------- | ----- | ------ | ---- |
+| task create/update/move    | yes   | yes    | yes  |
+| task delete                | yes   | no     | no   |
+| comment read/create/update | yes   | yes    | yes  |
+| activity log               | yes   | no     | no   |
+| metrics                    | yes   | no     | no   |
+| column CRUD                | yes   | no     | no   |
+| bulk operations            | yes   | no     | no   |
+| config edit                | yes   | no     | no   |
+| webhooks                   | no    | yes    | yes  |
 
 Linear tasks carry an `externalRef` (e.g. `TEAM-123`) and a `url`. Commands accept either the internal ID or the external ref.
+Jira tasks can also be addressed by issue key (for example `ENG-123`).
+
+Local mode is still the only mode with built-in metrics, config mutation, bulk
+cleanup, and the dashboard/bootstrap activity feed. Linear and Jira do keep
+remote issue history and comment counts in their cache tables for sync and
+provider-backed flows, but those modes do not expose the same local analytics
+surface.
 
 Unsupported operations return error code `UNSUPPORTED_OPERATION` with exit code 1.
 
+Task comments are currently exposed through the REST API and dashboard task
+detail flows rather than dedicated `kanban comment ...` CLI commands.
+
+In Linear and Jira modes, webhooks update the cache immediately when configured,
+and the normal poll loop still runs as a fallback so missed deliveries and
+remote deletions are eventually reconciled.
+
 ## Commands
 
 ### board
@@ -191,8 +237,19 @@ Default columns: `recurring`, `backlog`, `in-progress`, `review`, `done`.
 ```bash
 kanban serve            # default port 3000
 kanban serve --port 8080
+kanban serve --tunnel   # optional public URL for webhook testing
 ```
 
+### mcp
+
+```bash
+kanban mcp
+kanban mcp --db /path/to/board.db
+```
+
+Runs the bundled MCP server over stdio for local MCP clients such as Claude
+Desktop. See [`docs/mcp.md`](docs/mcp.md) for the tool surface and caveats.
+
 ## Global flags
 
 | Flag               | Description                                                                                      |
@@ -228,10 +285,33 @@ In Linear mode the dashboard hides unsupported actions and shows Linear issue id
 
 Starts a Bun HTTP server with:
 
-- **REST API** at `/api/*` — same operations as the CLI (board, tasks, columns, activity, metrics, config)
-- **WebSocket** at `/ws` — push notifications on board mutations (clients receive `{"type":"refresh"}`)
+- **REST API** at `/api/*` — board, tasks, task comments, bootstrap/provider metadata, activity, metrics, config, and webhook endpoints
+- **WebSocket** at `/ws` — push notifications on board mutations (clients receive `task:upsert`, `task:delete`, or a fallback `refresh` event)
 - **Static UI** served from `ui/dist/` (build with `bun run build:ui` or `bun run ui:build`)
-- **Health check** at `/api/health`
+- **Health check** at `/api/health` — cheap process liveness only
+- **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.
+
+Comment routes:
+
+- `GET /api/tasks/:id/comments`
+- `POST /api/tasks/:id/comments`
+- `PATCH /api/tasks/:id/comments/:commentId`
+
+## Reusable MCP core
+
+The repo also includes a reusable tracker MCP implementation under `src/mcp/`.
+There are two ways to use it today:
+
+- run `kanban mcp` for a bundled stdio MCP server
+- import the helpers in `src/mcp/` from a sibling workspace or in-repo consumer
+
+See [`docs/mcp.md`](docs/mcp.md) for the current default tool set, the auth and
+policy model, and the caveats around source-level imports and `kanban serve`.
 
 ## Scripts
 
@@ -287,6 +367,22 @@ docker run -d \
   agent-kanban
 ```
 
+### Jira mode
+
+No volume needed — all state lives in Jira Cloud.
+
+```bash
+docker run -d \
+  -p 3000:3000 \
+  -e KANBAN_PROVIDER=jira \
+  -e JIRA_BASE_URL=https://your-domain.atlassian.net \
+  -e JIRA_EMAIL=you@example.com \
+  -e JIRA_API_TOKEN=... \
+  -e JIRA_PROJECT_KEY=ENG \
+  -e JIRA_BOARD_ID=123 \
+  agent-kanban
+```
+
 ### Dokploy
 
 Set the port via `PORT` env var (defaults to `3000`). Port resolution order: `--port` flag → `PORT` env → `3000`. Add provider env vars through Dokploy's environment configuration.
@@ -299,7 +395,7 @@ If you want to contribute or report an issue, start with these guides:
 - [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)
 - [SECURITY.md](SECURITY.md)
 
-Longer product and workflow docs live under [`docs/`](docs/README.md).
+Longer product and workflow docs live under [`docs/`](docs/readme.md).
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andypai/agent-kanban",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Agent-friendly kanban board CLI. Manage tasks via bash commands, parse structured JSON output.",
   "homepage": "https://github.com/abpai/agent-kanban#readme",
   "repository": {
@@ -54,7 +54,9 @@
     "prepare": "if [ \"${HUSKY:-1}\" != \"0\" ] && command -v husky >/dev/null 2>&1; then husky install; fi",
     "prepack": "cd ui && bun install --frozen-lockfile && bun run build"
   },
-  "dependencies": {},
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0"
+  },
   "devDependencies": {
     "@eslint/js": "^9.39.1",
     "@typescript-eslint/eslint-plugin": "^8.18.0",

package/src/__tests__/activity.test.ts

@@ -9,8 +9,8 @@ import {
   moveTask,
   bulkMoveAll,
   bulkClearDone,
-} from '../db.ts'
-import { listActivity, getTaskActivity, getColumnTimeEntries } from '../activity.ts'
+} from '../db'
+import { listActivity } from '../activity'
 
 let db: Database
 
@@ -21,10 +21,16 @@ beforeEach(() => {
   seedDefaultColumns(db)
 })
 
+function getColumnTimeEntries(taskId: string): { exited_at: string | null }[] {
+  return db
+    .query('SELECT * FROM column_time_tracking WHERE task_id = $id ORDER BY entered_at')
+    .all({ $id: taskId }) as { exited_at: string | null }[]
+}
+
 describe('activity logging', () => {
   test('addTask logs created activity', () => {
     const task = addTask(db, 'Test task')
-    const activities = getTaskActivity(db, task.id)
+    const activities = listActivity(db, { taskId: task.id })
     expect(activities).toHaveLength(1)
     expect(activities[0]!.action).toBe('created')
     expect(activities[0]!.new_value).toBe('Test task')
@@ -33,7 +39,7 @@ describe('activity logging', () => {
   test('updateTask logs field changes', () => {
     const task = addTask(db, 'Original')
     updateTask(db, task.id, { title: 'Updated', priority: 'high' })
-    const activities = getTaskActivity(db, task.id)
+    const activities = listActivity(db, { taskId: task.id })
     const actions = activities.map((a) => a.action)
     expect(actions).toContain('updated')
     expect(actions).toContain('prioritized')
@@ -42,7 +48,7 @@ describe('activity logging', () => {
   test('updateTask logs assignee change as assigned', () => {
     const task = addTask(db, 'Task')
     updateTask(db, task.id, { assignee: 'alice' })
-    const activities = getTaskActivity(db, task.id)
+    const activities = listActivity(db, { taskId: task.id })
     const assigned = activities.find((a) => a.action === 'assigned')
     expect(assigned).toBeDefined()
     expect(assigned!.new_value).toBe('alice')
@@ -51,7 +57,7 @@ describe('activity logging', () => {
   test('updateTask does not log when value unchanged', () => {
     const task = addTask(db, 'Task', { priority: 'high' })
     updateTask(db, task.id, { priority: 'high' })
-    const activities = getTaskActivity(db, task.id)
+    const activities = listActivity(db, { taskId: task.id })
     expect(activities.filter((a) => a.action === 'prioritized')).toHaveLength(0)
   })
 
@@ -68,7 +74,7 @@ describe('activity logging', () => {
   test('moveTask logs moved activity', () => {
     const task = addTask(db, 'Mobile', { column: 'recurring' })
     moveTask(db, task.id, 'in-progress')
-    const activities = getTaskActivity(db, task.id)
+    const activities = listActivity(db, { taskId: task.id })
     const moved = activities.find((a) => a.action === 'moved')
     expect(moved).toBeDefined()
     expect(moved!.old_value).toBe('recurring')
@@ -96,7 +102,7 @@ describe('activity logging', () => {
   test('listActivity returns most recent first', () => {
     const task = addTask(db, 'Task')
     updateTask(db, task.id, { title: 'Updated' })
-    const activities = getTaskActivity(db, task.id)
+    const activities = listActivity(db, { taskId: task.id })
     expect(activities[0]!.action).toBe('updated')
     expect(activities[1]!.action).toBe('created')
   })
@@ -113,7 +119,7 @@ describe('activity logging', () => {
 describe('column time tracking', () => {
   test('addTask creates enter record', () => {
     const task = addTask(db, 'Task', { column: 'recurring' })
-    const entries = getColumnTimeEntries(db, task.id)
+    const entries = getColumnTimeEntries(task.id)
     expect(entries).toHaveLength(1)
     expect(entries[0]!.exited_at).toBeNull()
   })
@@ -121,7 +127,7 @@ describe('column time tracking', () => {
   test('moveTask creates exit and enter records', () => {
     const task = addTask(db, 'Task', { column: 'recurring' })
     moveTask(db, task.id, 'in-progress')
-    const entries = getColumnTimeEntries(db, task.id)
+    const entries = getColumnTimeEntries(task.id)
     expect(entries).toHaveLength(2)
     expect(entries[0]!.exited_at).not.toBeNull()
     expect(entries[1]!.exited_at).toBeNull()

package/src/__tests__/api.test.ts

@@ -1,8 +1,8 @@
 import { beforeEach, describe, expect, test } from 'bun:test'
 import { Database } from 'bun:sqlite'
-import { initSchema, seedDefaultColumns, addTask } from '../db.ts'
-import { handleRequest } from '../api.ts'
-import { createProvider } from '../providers/index.ts'
+import { initSchema, seedDefaultColumns, addTask } from '../db'
+import { handleRequest } from '../api'
+import { createProvider } from '../providers/index'
 
 let db: Database
 let provider: ReturnType<typeof createProvider>
@@ -58,6 +58,102 @@ describe('handleRequest', () => {
     expect(result.mutated).toBe(true)
   })
 
+  test('marks successful comment creation as mutated', async () => {
+    const task = addTask(db, 'Comment me')
+    const req = new Request(`http://localhost/api/tasks/${task.id}/comments`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ body: 'hello from api' }),
+    })
+    const result = await handleRequest(provider, req)
+    const body = (await result.response.json()) as {
+      ok: boolean
+      data: { id: string; body: string }
+    }
+
+    expect(result.response.status).toBe(200)
+    expect(result.mutated).toBe(true)
+    expect(body.ok).toBe(true)
+    expect(body.data.body).toBe('hello from api')
+  })
+
+  test('lists comments without marking the request as mutated', async () => {
+    const task = addTask(db, 'Comment me')
+    await provider.comment(task.id, 'hello from api')
+    await provider.comment(task.id, 'second api comment')
+
+    const req = new Request(`http://localhost/api/tasks/${task.id}/comments`, {
+      method: 'GET',
+    })
+    const result = await handleRequest(provider, req)
+    const body = (await result.response.json()) as {
+      ok: boolean
+      data: Array<{ id: string; body: string }>
+    }
+
+    expect(result.response.status).toBe(200)
+    expect(result.mutated).toBe(false)
+    expect(body.ok).toBe(true)
+    expect(body.data.map((comment) => comment.body)).toEqual([
+      'hello from api',
+      'second api comment',
+    ])
+  })
+
+  test('marks successful comment update as mutated', async () => {
+    const task = addTask(db, 'Comment me')
+    const created = await provider.comment(task.id, 'hello from api')
+
+    const updateReq = new Request(`http://localhost/api/tasks/${task.id}/comments/${created.id}`, {
+      method: 'PATCH',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ body: 'edited via api' }),
+    })
+    const updated = await handleRequest(provider, updateReq)
+    expect(updated.response.status).toBe(200)
+    expect(updated.mutated).toBe(true)
+  })
+
+  test('emits task:upsert event on create', async () => {
+    const req = new Request('http://localhost/api/tasks', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ title: 'Optimistic', column: 'backlog' }),
+    })
+    const result = await handleRequest(provider, req)
+
+    expect(result.mutated).toBe(true)
+    expect(result.event?.type).toBe('task:upsert')
+    if (result.event?.type !== 'task:upsert') throw new Error('unreachable')
+    expect(result.event.task.title).toBe('Optimistic')
+    expect(result.event.columnName.toLowerCase()).toBe('backlog')
+  })
+
+  test('emits task:upsert event on move across columns', async () => {
+    const task = addTask(db, 'Movable')
+    const req = new Request(`http://localhost/api/tasks/${task.id}/move`, {
+      method: 'PATCH',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ column: 'in-progress' }),
+    })
+    const result = await handleRequest(provider, req)
+
+    expect(result.mutated).toBe(true)
+    expect(result.event?.type).toBe('task:upsert')
+    if (result.event?.type !== 'task:upsert') throw new Error('unreachable')
+    expect(result.event.task.id).toBe(task.id)
+    expect(result.event.columnName.toLowerCase()).toBe('in-progress')
+  })
+
+  test('emits task:delete event on delete', async () => {
+    const task = addTask(db, 'Goodbye')
+    const req = new Request(`http://localhost/api/tasks/${task.id}`, { method: 'DELETE' })
+    const result = await handleRequest(provider, req)
+
+    expect(result.mutated).toBe(true)
+    expect(result.event).toEqual({ type: 'task:delete', id: task.id })
+  })
+
   test('returns bootstrap payload', async () => {
     const req = new Request('http://localhost/api/bootstrap', { method: 'GET' })
     const result = await handleRequest(provider, req)

package/src/__tests__/board-utils.test.ts

@@ -0,0 +1,100 @@
+import { describe, expect, test } from 'bun:test'
+import { replaceTask, upsertTaskInColumn } from '../../ui/src/components/boardUtils'
+import type { BoardView, Task } from '../../ui/src/types'
+
+function makeTask(
+  overrides: Partial<Task> & Pick<Task, 'id' | 'title' | 'column_id' | 'position'>,
+): Task {
+  const { id, title, column_id, position, ...rest } = overrides
+  return {
+    id,
+    providerId: id,
+    externalRef: id,
+    url: null,
+    title,
+    description: '',
+    column_id,
+    position,
+    priority: 'medium',
+    assignee: '',
+    assignees: [],
+    labels: [],
+    comment_count: 0,
+    project: '',
+    metadata: '{}',
+    created_at: '2026-01-01T00:00:00.000Z',
+    updated_at: '2026-01-01T00:00:00.000Z',
+    version: '0',
+    source_updated_at: null,
+    ...rest,
+  }
+}
+
+function makeBoard(): BoardView {
+  return {
+    columns: [
+      {
+        id: 'c-backlog',
+        name: 'backlog',
+        position: 0,
+        color: null,
+        created_at: '',
+        updated_at: '',
+        tasks: [
+          makeTask({ id: 't-1', title: 'First', column_id: 'c-backlog', position: 0 }),
+          makeTask({ id: 'tmp-1', title: 'Temp', column_id: 'c-backlog', position: 1 }),
+          makeTask({ id: 't-2', title: 'Second', column_id: 'c-backlog', position: 2 }),
+        ],
+      },
+      {
+        id: 'c-done',
+        name: 'done',
+        position: 1,
+        color: null,
+        created_at: '',
+        updated_at: '',
+        tasks: [],
+      },
+    ],
+  }
+}
+
+describe('boardUtils', () => {
+  test('replaceTask removes duplicate real task ids when resolving an optimistic create', () => {
+    const board = makeBoard()
+    const withWsInsertedReal: BoardView = {
+      columns: board.columns.map((column) =>
+        column.id === 'c-backlog'
+          ? {
+              ...column,
+              tasks: [
+                ...column.tasks,
+                makeTask({ id: 't-real', title: 'Created', column_id: 'c-backlog', position: 1 }),
+              ],
+            }
+          : column,
+      ),
+    }
+
+    const nextBoard = replaceTask(
+      withWsInsertedReal,
+      'tmp-1',
+      makeTask({ id: 't-real', title: 'Created', column_id: 'c-backlog', position: 1 }),
+    )
+
+    expect(nextBoard.columns[0]!.tasks.map((task) => task.id)).toEqual(['t-1', 't-real', 't-2'])
+  })
+
+  test('upsertTaskInColumn preserves same-column ordering for in-place edits', () => {
+    const board = makeBoard()
+
+    const nextBoard = upsertTaskInColumn(
+      board,
+      makeTask({ id: 't-1', title: 'First edited', column_id: 'c-backlog', position: 0 }),
+      'backlog',
+    )
+
+    expect(nextBoard.columns[0]!.tasks.map((task) => task.id)).toEqual(['t-1', 'tmp-1', 't-2'])
+    expect(nextBoard.columns[0]!.tasks[0]!.title).toBe('First edited')
+  })
+})

package/src/__tests__/commands/board.test.ts

@@ -1,8 +1,8 @@
 import { describe, expect, test, beforeEach } from 'bun:test'
 import { Database } from 'bun:sqlite'
-import { initSchema, seedDefaultColumns } from '../../db.ts'
-import { boardInit, boardView, boardReset } from '../../commands/board.ts'
-import { KanbanError } from '../../errors.ts'
+import { getBoardView, initSchema, seedDefaultColumns } from '../../db'
+import { boardInit, boardReset } from '../../commands/board'
+import { KanbanError } from '../../errors'
 
 let db: Database
 
@@ -24,20 +24,12 @@ describe('boardInit', () => {
   })
 })
 
-describe('boardView', () => {
+describe('getBoardView', () => {
   test('returns board view after init', () => {
     initSchema(db)
     seedDefaultColumns(db)
-    const result = boardView(db)
-    expect(result.ok).toBe(true)
-    if (result.ok) {
-      const data = result.data as { columns: unknown[] }
-      expect(data.columns).toHaveLength(5)
-    }
-  })
-
-  test('throws if not initialized', () => {
-    expect(() => boardView(db)).toThrow(KanbanError)
+    const data = getBoardView(db)
+    expect(data.columns).toHaveLength(5)
   })
 })
 
@@ -47,5 +39,6 @@ describe('boardReset', () => {
     seedDefaultColumns(db)
     const result = boardReset(db)
     expect(result.ok).toBe(true)
+    expect(getBoardView(db).columns).toHaveLength(5)
   })
 })

package/src/__tests__/commands/bulk.test.ts

@@ -1,8 +1,8 @@
 import { describe, expect, test, beforeEach } from 'bun:test'
 import { Database } from 'bun:sqlite'
-import { initSchema, seedDefaultColumns, addTask, listTasks } from '../../db.ts'
-import { bulkMoveAllCmd, bulkClearDoneCmd } from '../../commands/bulk.ts'
-import { KanbanError } from '../../errors.ts'
+import { initSchema, seedDefaultColumns, addTask, listTasks } from '../../db'
+import { bulkMoveAllCmd, bulkClearDoneCmd } from '../../commands/bulk'
+import { KanbanError } from '../../errors'
 
 let db: Database
 

package/src/__tests__/commands/column.test.ts

@@ -1,15 +1,15 @@
 import { describe, expect, test, beforeEach } from 'bun:test'
 import { Database } from 'bun:sqlite'
-import { initSchema, seedDefaultColumns, addTask } from '../../db.ts'
+import { initSchema, seedDefaultColumns, addTask } from '../../db'
 import {
   columnAdd,
   columnList,
   columnRename,
   columnReorder,
   columnDelete,
-} from '../../commands/column.ts'
-import { KanbanError } from '../../errors.ts'
-import type { Column } from '../../types.ts'
+} from '../../commands/column'
+import { KanbanError } from '../../errors'
+import type { Column } from '../../types'
 
 let db: Database
 

package/src/__tests__/conflict.test.ts

@@ -0,0 +1,64 @@
+import { beforeEach, describe, expect, test } from 'bun:test'
+import { Database } from 'bun:sqlite'
+import { initSchema, seedDefaultColumns } from '../db'
+import { LocalProvider } from '../providers/local'
+import { ErrorCode, KanbanError } from '../errors'
+
+let db: Database
+let provider: LocalProvider
+
+beforeEach(() => {
+  db = new Database(':memory:')
+  initSchema(db)
+  seedDefaultColumns(db)
+  provider = new LocalProvider(db, ':memory:')
+})
+
+describe('local provider conflict detection', () => {
+  test('update without expectedVersion succeeds', async () => {
+    const created = await provider.createTask({ title: 'T1' })
+    const updated = await provider.updateTask(created.id, { title: 'T1-a' })
+    expect(updated.title).toBe('T1-a')
+  })
+
+  test('update with matching expectedVersion succeeds', async () => {
+    const created = await provider.createTask({ title: 'T1' })
+    const updated = await provider.updateTask(created.id, {
+      title: 'T1-a',
+      expectedVersion: created.version ?? undefined,
+    })
+    expect(updated.title).toBe('T1-a')
+    expect(updated.version).not.toBe(created.version)
+  })
+
+  test('update with stale expectedVersion throws CONFLICT', async () => {
+    const created = await provider.createTask({ title: 'T1' })
+    await provider.updateTask(created.id, { title: 'bumped' })
+    let err: unknown
+    try {
+      await provider.updateTask(created.id, {
+        title: 'stale',
+        expectedVersion: created.version ?? undefined,
+      })
+    } catch (e) {
+      err = e
+    }
+    expect(err).toBeInstanceOf(KanbanError)
+    expect((err as KanbanError).code).toBe(ErrorCode.CONFLICT)
+  })
+
+  test('task exposes version and source_updated_at', async () => {
+    const created = await provider.createTask({ title: 'T1' })
+    expect(created.version).toBe('0')
+    expect(created.source_updated_at).toBeNull()
+  })
+
+  test('version bumps on each update', async () => {
+    const created = await provider.createTask({ title: 'T1' })
+    expect(created.version).toBe('0')
+    const v1 = await provider.updateTask(created.id, { title: 'a' })
+    expect(v1.version).toBe('1')
+    const v2 = await provider.updateTask(created.id, { title: 'b' })
+    expect(v2.version).toBe('2')
+  })
+})