@andypai/agent-kanban 0.2.0 → 0.3.1

package/src/api.ts

@@ -1,11 +1,19 @@
-import { KanbanError, ErrorCode } from './errors.ts'
-import type { BoardConfig, CliOutput } from './types.ts'
-import type { CreateTaskInput, UpdateTaskInput, KanbanProvider } from './providers/types.ts'
+import { KanbanError, ErrorCode } from './errors'
+import type { BoardConfig, CliOutput, Task } from './types'
+import type { CreateTaskInput, UpdateTaskInput, KanbanProvider } from './providers/types'
+
+export type WsEvent =
+  | { type: 'task:upsert'; task: Task; columnName: string }
+  | { type: 'task:delete'; id: string }
 
 interface MoveTaskBody {
   column?: string
 }
 
+interface CommentBody {
+  body?: string
+}
+
 function json(data: unknown, status = 200): Response {
   return Response.json(data, { status })
 }
@@ -22,9 +30,15 @@ function missingArgument(field: string): Response {
 }
 
 function statusForCode(code: string): number {
-  if (code === ErrorCode.TASK_NOT_FOUND || code === ErrorCode.COLUMN_NOT_FOUND) return 404
+  if (
+    code === ErrorCode.TASK_NOT_FOUND ||
+    code === ErrorCode.COLUMN_NOT_FOUND ||
+    code === ErrorCode.COMMENT_NOT_FOUND
+  )
+    return 404
   if (code === ErrorCode.PROVIDER_AUTH_FAILED) return 401
   if (code === ErrorCode.PROVIDER_RATE_LIMITED) return 429
+  if (code === ErrorCode.CONFLICT) return 409
   if (code === ErrorCode.UNSUPPORTED_OPERATION) return 400
   if (code === ErrorCode.PROVIDER_NOT_CONFIGURED) return 500
   return 400
@@ -53,6 +67,20 @@ async function wrapHandler(fn: () => Promise<CliOutput> | CliOutput): Promise<Re
 export interface ApiResult {
   response: Response
   mutated: boolean
+  event?: WsEvent
+}
+
+async function resolveColumnName(
+  provider: KanbanProvider,
+  columnId: string,
+): Promise<string | null> {
+  const columns = await provider.listColumns()
+  return columns.find((column) => column.id === columnId)?.name ?? null
+}
+
+async function upsertEvent(provider: KanbanProvider, task: Task): Promise<WsEvent | undefined> {
+  const columnName = await resolveColumnName(provider, task.column_id)
+  return columnName ? { type: 'task:upsert', task, columnName } : undefined
 }
 
 export async function handleRequest(provider: KanbanProvider, req: Request): Promise<ApiResult> {
@@ -109,9 +137,9 @@ export async function handleRequest(provider: KanbanProvider, req: Request): Pro
   if (path === '/api/tasks' && method === 'POST') {
     const body = (await req.json()) as Partial<CreateTaskInput>
     if (!body.title) return { response: missingArgument('title'), mutated: false }
-    const response = await wrapHandler(async () => ({
-      ok: true,
-      data: await provider.createTask({
+    let created: Task | null = null
+    const response = await wrapHandler(async () => {
+      created = await provider.createTask({
         title: body.title!,
         description: body.description,
         column: body.column,
@@ -119,9 +147,11 @@ export async function handleRequest(provider: KanbanProvider, req: Request): Pro
         assignee: body.assignee,
         project: body.project,
         metadata: body.metadata,
-      }),
-    }))
-    return { response, mutated: response.ok }
+      })
+      return { ok: true, data: created }
+    })
+    const event = response.ok && created ? await upsertEvent(provider, created) : undefined
+    return { response, mutated: response.ok, event }
   }
 
   const taskMatch = path.match(/^\/api\/tasks\/([^/]+)$/)
@@ -137,11 +167,13 @@ export async function handleRequest(provider: KanbanProvider, req: Request): Pro
 
     if (method === 'PATCH') {
       const body = (await req.json()) as UpdateTaskInput
-      const response = await wrapHandler(async () => ({
-        ok: true,
-        data: await provider.updateTask(id, body),
-      }))
-      return { response, mutated: response.ok }
+      let updated: Task | null = null
+      const response = await wrapHandler(async () => {
+        updated = await provider.updateTask(id, body)
+        return { ok: true, data: updated }
+      })
+      const event = response.ok && updated ? await upsertEvent(provider, updated) : undefined
+      return { response, mutated: response.ok, event }
     }
 
     if (method === 'DELETE') {
@@ -149,7 +181,8 @@ export async function handleRequest(provider: KanbanProvider, req: Request): Pro
         ok: true,
         data: await provider.deleteTask(id),
       }))
-      return { response, mutated: response.ok }
+      const event: WsEvent | undefined = response.ok ? { type: 'task:delete', id } : undefined
+      return { response, mutated: response.ok, event }
     }
   }
 
@@ -158,11 +191,53 @@ export async function handleRequest(provider: KanbanProvider, req: Request): Pro
     const id = decodeURIComponent(moveMatch[1]!)
     const body = (await req.json()) as MoveTaskBody
     if (!body.column) return { response: missingArgument('column'), mutated: false }
-    const response = await wrapHandler(async () => ({
-      ok: true,
-      data: await provider.moveTask(id, body.column!),
-    }))
-    return { response, mutated: response.ok }
+    let moved: Task | null = null
+    const response = await wrapHandler(async () => {
+      moved = await provider.moveTask(id, body.column!)
+      return { ok: true, data: moved }
+    })
+    const event = response.ok && moved ? await upsertEvent(provider, moved) : undefined
+    return { response, mutated: response.ok, event }
+  }
+
+  const commentsMatch = path.match(/^\/api\/tasks\/([^/]+)\/comments$/)
+  if (commentsMatch) {
+    const id = decodeURIComponent(commentsMatch[1]!)
+    if (method === 'GET') {
+      return {
+        response: await wrapHandler(async () => ({
+          ok: true,
+          data: await provider.listComments(id),
+        })),
+        mutated: false,
+      }
+    }
+
+    if (method === 'POST') {
+      const body = (await req.json()) as CommentBody
+      if (!body.body) return { response: missingArgument('body'), mutated: false }
+      const response = await wrapHandler(async () => ({
+        ok: true,
+        data: await provider.comment(id, body.body!),
+      }))
+      return { response, mutated: response.ok }
+    }
+  }
+
+  const commentMatch = path.match(/^\/api\/tasks\/([^/]+)\/comments\/([^/]+)$/)
+  if (commentMatch) {
+    const id = decodeURIComponent(commentMatch[1]!)
+    const commentId = decodeURIComponent(commentMatch[2]!)
+
+    if (method === 'PATCH') {
+      const body = (await req.json()) as CommentBody
+      if (!body.body) return { response: missingArgument('body'), mutated: false }
+      const response = await wrapHandler(async () => ({
+        ok: true,
+        data: await provider.updateComment(id, commentId, body.body!),
+      }))
+      return { response, mutated: response.ok }
+    }
   }
 
   if (path === '/api/activity' && method === 'GET') {
@@ -199,6 +274,66 @@ export async function handleRequest(provider: KanbanProvider, req: Request): Pro
     return { response, mutated: response.ok }
   }
 
+  const webhookMatch = path.match(/^\/api\/webhooks\/([^/]+)$/)
+  if (webhookMatch && method === 'POST') {
+    const target = decodeURIComponent(webhookMatch[1]!)
+    if (target !== provider.type) {
+      return {
+        response: json(
+          {
+            ok: false,
+            error: {
+              code: 'UNSUPPORTED_OPERATION',
+              message: `Webhook target '${target}' does not match active provider '${provider.type}'`,
+            },
+          },
+          400,
+        ),
+        mutated: false,
+      }
+    }
+    if (!provider.handleWebhook) {
+      return {
+        response: json(
+          {
+            ok: false,
+            error: {
+              code: 'UNSUPPORTED_OPERATION',
+              message: `Provider '${provider.type}' does not accept webhooks`,
+            },
+          },
+          400,
+        ),
+        mutated: false,
+      }
+    }
+    const rawBody = await req.text()
+    const headers: Record<string, string> = {}
+    req.headers.forEach((value, key) => {
+      headers[key] = value
+    })
+    const result = await provider.handleWebhook({ headers, rawBody })
+    if (result.unauthorized) {
+      return {
+        response: json(
+          {
+            ok: false,
+            error: { code: 'PROVIDER_AUTH_FAILED', message: result.message ?? 'Unauthorized' },
+          },
+          401,
+        ),
+        mutated: false,
+      }
+    }
+    return {
+      response: json({
+        ok: true,
+        data: { handled: result.handled, message: result.message ?? null },
+      }),
+      mutated: result.handled,
+    }
+  }
+
   return {
     response: json(
       { ok: false, error: { code: 'NOT_FOUND', message: `No route: ${method} ${path}` } },

package/src/commands/board.ts

@@ -1,8 +1,8 @@
 import type { Database } from 'bun:sqlite'
-import { initSchema, seedDefaultColumns, isInitialized, getBoardView, resetBoard } from '../db.ts'
-import { ErrorCode, KanbanError } from '../errors.ts'
-import { success } from '../output.ts'
-import type { CliOutput } from '../types.ts'
+import { initSchema, seedDefaultColumns, isInitialized, resetBoard } from '../db'
+import { ErrorCode, KanbanError } from '../errors'
+import { success } from '../output'
+import type { CliOutput } from '../types'
 
 export function boardInit(db: Database): CliOutput {
   if (isInitialized(db)) {
@@ -13,16 +13,6 @@ export function boardInit(db: Database): CliOutput {
   return success({ message: 'Board initialized with default columns.' })
 }
 
-export function boardView(db: Database): CliOutput {
-  if (!isInitialized(db)) {
-    throw new KanbanError(
-      ErrorCode.BOARD_NOT_INITIALIZED,
-      'Board not initialized. Run: kanban board init',
-    )
-  }
-  return success(getBoardView(db))
-}
-
 export function boardReset(db: Database): CliOutput {
   resetBoard(db)
   return success({ message: 'Board reset. All data cleared and defaults restored.' })

package/src/commands/bulk.ts

@@ -1,8 +1,8 @@
 import type { Database } from 'bun:sqlite'
-import { bulkMoveAll, bulkClearDone } from '../db.ts'
-import { ErrorCode, KanbanError } from '../errors.ts'
-import { success } from '../output.ts'
-import type { CliOutput } from '../types.ts'
+import { bulkMoveAll, bulkClearDone } from '../db'
+import { ErrorCode, KanbanError } from '../errors'
+import { success } from '../output'
+import type { CliOutput } from '../types'
 
 export function bulkMoveAllCmd(db: Database, args: { from?: string; to?: string }): CliOutput {
   if (!args.from || !args.to) {

package/src/commands/column.ts

@@ -1,8 +1,8 @@
 import type { Database } from 'bun:sqlite'
-import { addColumn, listColumns, renameColumn, reorderColumn, deleteColumn } from '../db.ts'
-import { ErrorCode, KanbanError } from '../errors.ts'
-import { success } from '../output.ts'
-import type { CliOutput } from '../types.ts'
+import { addColumn, listColumns, renameColumn, reorderColumn, deleteColumn } from '../db'
+import { ErrorCode, KanbanError } from '../errors'
+import { success } from '../output'
+import type { CliOutput } from '../types'
 
 export function columnAdd(
   db: Database,

package/src/commands/mcp.ts

@@ -0,0 +1,87 @@
+import { Server } from '@modelcontextprotocol/sdk/server'
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+  type CallToolResult,
+} from '@modelcontextprotocol/sdk/types.js'
+import { AjvJsonSchemaValidator } from '@modelcontextprotocol/sdk/validation/ajv'
+import { createTrackerCore, defaultTools, TrackerMcpError } from '../mcp/index'
+import type { TrackerMcpPolicy, TrackerMcpTool } from '../mcp/index'
+import type { KanbanProvider } from '../providers/types'
+
+type LocalScope = Record<string, never>
+
+const allowAllPolicy: TrackerMcpPolicy<LocalScope> = {
+  canReadTicket() {},
+  canPostComment() {},
+  canUpdateComment() {},
+  canMoveTicket() {},
+}
+
+function toCallToolResult(result: unknown): CallToolResult {
+  const text = typeof result === 'string' ? result : JSON.stringify(result ?? null)
+  return {
+    content: [{ type: 'text', text }],
+    structuredContent: { result: result ?? null },
+  }
+}
+
+export async function startStdioMcpServer(provider: KanbanProvider): Promise<void> {
+  const core = createTrackerCore<LocalScope>({ provider, policy: allowAllPolicy })
+  const scope: LocalScope = {} as LocalScope
+  const tools = defaultTools(core)
+  const byName = new Map<string, TrackerMcpTool<LocalScope>>(tools.map((tool) => [tool.name, tool]))
+  const validators = new AjvJsonSchemaValidator()
+  const validateByName = new Map(
+    tools.map((tool) => [tool.name, validators.getValidator(tool.inputSchema)]),
+  )
+
+  const server = new Server(
+    { name: 'agent-kanban', version: '1.0.0' },
+    { capabilities: { tools: {} } },
+  )
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: tools.map((tool) => ({
+      name: tool.name,
+      description: tool.description,
+      inputSchema: tool.inputSchema,
+    })),
+  }))
+
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const tool = byName.get(request.params.name)
+    if (!tool) {
+      throw new TrackerMcpError({
+        code: 'validation_failed',
+        publicMessage: `Unknown tool '${request.params.name}'`,
+      })
+    }
+    const validated = validateByName.get(tool.name)!(request.params.arguments ?? {})
+    if (!validated.valid) {
+      throw new TrackerMcpError({
+        code: 'validation_failed',
+        publicMessage: validated.errorMessage ?? `Invalid arguments for '${tool.name}'`,
+      })
+    }
+    const result = await tool.handler({
+      scope,
+      args: validated.data as Record<string, unknown>,
+    })
+    return toCallToolResult(result)
+  })
+
+  const transport = new StdioServerTransport()
+  await server.connect(transport)
+
+  const shutdown = async (): Promise<void> => {
+    try {
+      await server.close()
+    } finally {
+      process.exit(0)
+    }
+  }
+  process.on('SIGINT', shutdown)
+  process.on('SIGTERM', shutdown)
+}

package/src/config.ts

@@ -1,6 +1,6 @@
 import { readFileSync, writeFileSync, renameSync } from 'node:fs'
 import { dirname, join } from 'node:path'
-import type { BoardConfig } from './types.ts'
+import type { BoardConfig } from './types'
 
 const DEFAULT_CONFIG: BoardConfig = { members: [], projects: [] }
 

package/src/db.ts

@@ -2,10 +2,10 @@ import { Database } from 'bun:sqlite'
 import { existsSync, mkdirSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { join } from 'node:path'
-import { generateId } from './id.ts'
-import { ErrorCode, KanbanError } from './errors.ts'
-import type { Column, Task, TaskWithColumn, Priority, BoardView } from './types.ts'
-import { logActivity, enterColumn, exitColumn } from './activity.ts'
+import { generateId } from './id'
+import { ErrorCode, KanbanError } from './errors'
+import type { BoardView, Column, Priority, Task, TaskComment, TaskWithColumn } from './types'
+import { logActivity, enterColumn, exitColumn } from './activity'
 
 const DEFAULT_COLUMNS = [
   { name: 'recurring', position: 0 },
@@ -64,6 +64,7 @@ export function initSchema(db: Database): void {
       assignee TEXT NOT NULL DEFAULT '',
       project TEXT NOT NULL DEFAULT '',
       metadata TEXT NOT NULL DEFAULT '{}',
+      revision INTEGER NOT NULL DEFAULT 0,
       created_at TEXT NOT NULL DEFAULT (datetime('now')),
       updated_at TEXT NOT NULL DEFAULT (datetime('now'))
     )
@@ -79,6 +80,16 @@ export function initSchema(db: Database): void {
       timestamp TEXT NOT NULL DEFAULT (datetime('now'))
     )
   `)
+  db.run(`
+    CREATE TABLE IF NOT EXISTS comments (
+      id TEXT PRIMARY KEY,
+      task_id TEXT NOT NULL REFERENCES tasks(id) ON DELETE CASCADE,
+      body TEXT NOT NULL,
+      author TEXT,
+      created_at TEXT NOT NULL DEFAULT (datetime('now')),
+      updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+    )
+  `)
   db.run(`
     CREATE TABLE IF NOT EXISTS column_time_tracking (
       id TEXT PRIMARY KEY,
@@ -97,6 +108,7 @@ export function initSchema(db: Database): void {
   db.run('CREATE INDEX IF NOT EXISTS idx_tasks_project ON tasks(project)')
   db.run('CREATE INDEX IF NOT EXISTS idx_activity_task_id ON activity_log(task_id)')
   db.run('CREATE INDEX IF NOT EXISTS idx_activity_timestamp ON activity_log(timestamp)')
+  db.run('CREATE INDEX IF NOT EXISTS idx_comments_task_id ON comments(task_id)')
   db.run('CREATE INDEX IF NOT EXISTS idx_column_time_task_id ON column_time_tracking(task_id)')
 }
 
@@ -112,6 +124,10 @@ export function migrateSchema(db: Database): void {
   if (!hasProject) {
     db.run("ALTER TABLE tasks ADD COLUMN project TEXT NOT NULL DEFAULT ''")
   }
+  const hasRevision = columns.some((c) => c.name === 'revision')
+  if (!hasRevision) {
+    db.run('ALTER TABLE tasks ADD COLUMN revision INTEGER NOT NULL DEFAULT 0')
+  }
   db.run('CREATE INDEX IF NOT EXISTS idx_tasks_project ON tasks(project)')
 }
 
@@ -399,7 +415,7 @@ export function updateTask(
     }
   }
 
-  const sets: string[] = ["updated_at = datetime('now')"]
+  const sets: string[] = ["updated_at = datetime('now')", 'revision = revision + 1']
   const params: Record<string, string> = { $id: id }
 
   if (updates.title !== undefined) {
@@ -477,6 +493,101 @@ export function deleteTask(db: Database, id: string): TaskWithColumn {
   return task
 }
 
+export function getComment(db: Database, taskId: string, commentId: string): TaskComment {
+  const row = db
+    .query(
+      `SELECT id, task_id, body, author, created_at, updated_at
+         FROM comments
+        WHERE id = $id AND task_id = $task_id`,
+    )
+    .get({
+      $id: commentId,
+      $task_id: taskId,
+    }) as TaskComment | null
+  if (!row) {
+    throw new KanbanError(
+      ErrorCode.COMMENT_NOT_FOUND,
+      `No comment '${commentId}' exists on task '${taskId}'`,
+    )
+  }
+  return row
+}
+
+export function listComments(db: Database, taskId: string): TaskComment[] {
+  getTask(db, taskId)
+  return db
+    .query(
+      `SELECT id, task_id, body, author, created_at, updated_at
+         FROM comments
+        WHERE task_id = $task_id
+        ORDER BY created_at ASC, rowid ASC`,
+    )
+    .all({ $task_id: taskId }) as TaskComment[]
+}
+
+export function countComments(db: Database, taskId: string): number {
+  const row = db
+    .query('SELECT COUNT(*) as count FROM comments WHERE task_id = $task_id')
+    .get({ $task_id: taskId }) as { count: number }
+  return row.count
+}
+
+export function countCommentsByTask(db: Database): Map<string, number> {
+  const rows = db
+    .query('SELECT task_id, COUNT(*) as count FROM comments GROUP BY task_id')
+    .all() as Array<{ task_id: string; count: number }>
+  return new Map(rows.map((row) => [row.task_id, row.count]))
+}
+
+export function addComment(
+  db: Database,
+  taskId: string,
+  body: string,
+  author: string | null = null,
+): TaskComment {
+  getTask(db, taskId)
+  const id = generateId('cm')
+  db.query(
+    `INSERT INTO comments (id, task_id, body, author)
+     VALUES ($id, $task_id, $body, $author)`,
+  ).run({
+    $id: id,
+    $task_id: taskId,
+    $body: body,
+    $author: author,
+  })
+  logActivity(db, taskId, 'updated', {
+    field: 'comment',
+    new_value: body,
+  })
+  return getComment(db, taskId, id)
+}
+
+export function updateComment(
+  db: Database,
+  taskId: string,
+  commentId: string,
+  body: string,
+): TaskComment {
+  const existing = getComment(db, taskId, commentId)
+  db.query(
+    `UPDATE comments
+        SET body = $body,
+            updated_at = datetime('now')
+      WHERE id = $id AND task_id = $task_id`,
+  ).run({
+    $id: commentId,
+    $task_id: taskId,
+    $body: body,
+  })
+  logActivity(db, taskId, 'updated', {
+    field: 'comment',
+    old_value: existing.body,
+    new_value: body,
+  })
+  return getComment(db, taskId, commentId)
+}
+
 export function moveTask(db: Database, id: string, columnIdOrName: string): TaskWithColumn {
   const task = getTask(db, id)
   const column = resolveColumn(db, columnIdOrName)
@@ -487,7 +598,7 @@ export function moveTask(db: Database, id: string, columnIdOrName: string): Task
 
   const oldColumnId = task.column_id
   db.query(
-    "UPDATE tasks SET column_id = $col, position = $pos, updated_at = datetime('now') WHERE id = $id",
+    "UPDATE tasks SET column_id = $col, position = $pos, updated_at = datetime('now'), revision = revision + 1 WHERE id = $id",
   ).run({ $col: column.id, $pos: maxPos.next, $id: id })
   renumberTasksInColumn(db, oldColumnId)
 
@@ -578,6 +689,7 @@ export function bulkClearDone(db: Database): { deleted: number } {
 }
 
 export function resetBoard(db: Database): void {
+  db.run('DROP TABLE IF EXISTS comments')
   db.run('DROP TABLE IF EXISTS column_time_tracking')
   db.run('DROP TABLE IF EXISTS activity_log')
   db.run('DROP TABLE IF EXISTS tasks')

package/src/errors.ts

@@ -2,12 +2,14 @@ export const ErrorCode = {
   BOARD_NOT_INITIALIZED: 'BOARD_NOT_INITIALIZED',
   BOARD_ALREADY_INITIALIZED: 'BOARD_ALREADY_INITIALIZED',
   TASK_NOT_FOUND: 'TASK_NOT_FOUND',
+  COMMENT_NOT_FOUND: 'COMMENT_NOT_FOUND',
   COLUMN_NOT_FOUND: 'COLUMN_NOT_FOUND',
   COLUMN_NOT_EMPTY: 'COLUMN_NOT_EMPTY',
   COLUMN_NAME_EXISTS: 'COLUMN_NAME_EXISTS',
   INVALID_PRIORITY: 'INVALID_PRIORITY',
   INVALID_METADATA: 'INVALID_METADATA',
   INVALID_POSITION: 'INVALID_POSITION',
+  CONFLICT: 'CONFLICT',
   MISSING_ARGUMENT: 'MISSING_ARGUMENT',
   UNKNOWN_COMMAND: 'UNKNOWN_COMMAND',
   UNSUPPORTED_OPERATION: 'UNSUPPORTED_OPERATION',

package/src/id.ts

@@ -1,4 +1,4 @@
-export function generateId(prefix: 't' | 'c' | 'a' | 'ct'): string {
+export function generateId(prefix: 't' | 'c' | 'a' | 'ct' | 'cm'): string {
   const bytes = new Uint8Array(5)
   crypto.getRandomValues(bytes)
   let num = 0n