@andypai/agent-kanban 0.1.0

package/src/__tests__/metrics.test.ts

@@ -0,0 +1,64 @@
+import { describe, expect, test, beforeEach } from 'bun:test'
+import { Database } from 'bun:sqlite'
+import { initSchema, seedDefaultColumns, addTask } from '../db.ts'
+import { getBoardMetrics } from '../metrics.ts'
+
+let db: Database
+
+beforeEach(() => {
+  db = new Database(':memory:')
+  db.run('PRAGMA foreign_keys = ON')
+  initSchema(db)
+  seedDefaultColumns(db)
+})
+
+describe('getBoardMetrics', () => {
+  test('returns tasks per column', () => {
+    addTask(db, 'A', { column: 'recurring' })
+    addTask(db, 'B', { column: 'recurring' })
+    addTask(db, 'C', { column: 'backlog' })
+    const metrics = getBoardMetrics(db)
+    expect(metrics.tasksByColumn.find((c) => c.column_name === 'recurring')!.count).toBe(2)
+    expect(metrics.tasksByColumn.find((c) => c.column_name === 'backlog')!.count).toBe(1)
+    expect(metrics.tasksByColumn.find((c) => c.column_name === 'done')!.count).toBe(0)
+  })
+
+  test('returns tasks by priority', () => {
+    addTask(db, 'Urgent', { priority: 'urgent' })
+    addTask(db, 'High', { priority: 'high' })
+    addTask(db, 'Low', { priority: 'low' })
+    const metrics = getBoardMetrics(db)
+    expect(metrics.tasksByPriority.find((p) => p.priority === 'urgent')!.count).toBe(1)
+    expect(metrics.tasksByPriority.find((p) => p.priority === 'high')!.count).toBe(1)
+  })
+
+  test('returns total and completed counts', () => {
+    addTask(db, 'A', { column: 'recurring' })
+    addTask(db, 'B', { column: 'done' })
+    addTask(db, 'C', { column: 'done' })
+    const metrics = getBoardMetrics(db)
+    expect(metrics.totalTasks).toBe(3)
+    expect(metrics.completedTasks).toBe(2)
+  })
+
+  test('returns null avg completion when no data', () => {
+    const metrics = getBoardMetrics(db)
+    expect(metrics.avgCompletionHours).toBeNull()
+  })
+
+  test('returns recent activity', () => {
+    addTask(db, 'A')
+    addTask(db, 'B')
+    const metrics = getBoardMetrics(db)
+    expect(metrics.recentActivity.length).toBeGreaterThanOrEqual(2)
+    expect(metrics.recentActivity[0]!.action).toBe('created')
+  })
+
+  test('works with empty board', () => {
+    const metrics = getBoardMetrics(db)
+    expect(metrics.totalTasks).toBe(0)
+    expect(metrics.completedTasks).toBe(0)
+    expect(metrics.tasksByColumn).toHaveLength(5)
+    expect(metrics.tasksByPriority).toHaveLength(0)
+  })
+})

package/src/__tests__/output.test.ts

@@ -0,0 +1,39 @@
+import { describe, expect, test } from 'bun:test'
+import { success, error, formatOutput } from '../output.ts'
+
+describe('success', () => {
+  test('wraps data in ok envelope', () => {
+    const result = success({ id: '123' })
+    expect(result).toEqual({ ok: true, data: { id: '123' } })
+  })
+})
+
+describe('error', () => {
+  test('wraps error in envelope', () => {
+    const result = error('NOT_FOUND', 'Task not found')
+    expect(result).toEqual({
+      ok: false,
+      error: { code: 'NOT_FOUND', message: 'Task not found' },
+    })
+  })
+})
+
+describe('formatOutput', () => {
+  test('returns compact JSON when pretty=false', () => {
+    const result = success({ x: 1 })
+    const output = formatOutput(result, false)
+    expect(output).toBe('{"ok":true,"data":{"x":1}}')
+  })
+
+  test('returns error text when pretty=true', () => {
+    const result = error('CODE', 'Something failed')
+    const output = formatOutput(result, true)
+    expect(output).toBe('Error [CODE]: Something failed')
+  })
+
+  test('formats message data in pretty mode', () => {
+    const result = success({ message: 'Board initialized.' })
+    const output = formatOutput(result, true)
+    expect(output).toBe('Board initialized.')
+  })
+})

package/src/activity.ts

@@ -0,0 +1,73 @@
+import { Database } from 'bun:sqlite'
+import { generateId } from './id.ts'
+import type { ActivityEntry, ActivityAction, ColumnTimeEntry } from './types.ts'
+
+export function logActivity(
+  db: Database,
+  taskId: string,
+  action: ActivityAction,
+  opts: { field?: string; old_value?: string | null; new_value?: string | null } = {},
+): void {
+  db.query(
+    `INSERT INTO activity_log (id, task_id, action, field_changed, old_value, new_value)
+     VALUES ($id, $task_id, $action, $field, $old, $new)`,
+  ).run({
+    $id: generateId('a'),
+    $task_id: taskId,
+    $action: action,
+    $field: opts.field ?? null,
+    $old: opts.old_value ?? null,
+    $new: opts.new_value ?? null,
+  })
+}
+
+export function listActivity(
+  db: Database,
+  opts: { limit?: number; taskId?: string } = {},
+): ActivityEntry[] {
+  const conditions: string[] = []
+  const params: Record<string, string | number> = {}
+
+  if (opts.taskId) {
+    conditions.push('task_id = $task_id')
+    params['$task_id'] = opts.taskId
+  }
+
+  const where = conditions.length ? `WHERE ${conditions.join(' AND ')}` : ''
+  const limit = opts.limit ? `LIMIT ${opts.limit}` : 'LIMIT 50'
+
+  return db
+    .query(`SELECT * FROM activity_log ${where} ORDER BY timestamp DESC, rowid DESC ${limit}`)
+    .all(params as Record<string, string>) as ActivityEntry[]
+}
+
+export function getTaskActivity(db: Database, taskId: string): ActivityEntry[] {
+  return listActivity(db, { taskId })
+}
+
+export function enterColumn(db: Database, taskId: string, columnId: string): void {
+  db.query(
+    `INSERT INTO column_time_tracking (id, task_id, column_id)
+     VALUES ($id, $task_id, $col)`,
+  ).run({
+    $id: generateId('ct'),
+    $task_id: taskId,
+    $col: columnId,
+  })
+}
+
+export function exitColumn(db: Database, taskId: string, columnId: string): void {
+  db.query(
+    `UPDATE column_time_tracking SET exited_at = datetime('now')
+     WHERE task_id = $task_id AND column_id = $col AND exited_at IS NULL`,
+  ).run({
+    $task_id: taskId,
+    $col: columnId,
+  })
+}
+
+export function getColumnTimeEntries(db: Database, taskId: string): ColumnTimeEntry[] {
+  return db
+    .query(`SELECT * FROM column_time_tracking WHERE task_id = $task_id ORDER BY entered_at`)
+    .all({ $task_id: taskId }) as ColumnTimeEntry[]
+}

package/src/api.ts

@@ -0,0 +1,209 @@
+import { KanbanError, ErrorCode } from './errors.ts'
+import type { BoardConfig, CliOutput } from './types.ts'
+import type { CreateTaskInput, UpdateTaskInput, KanbanProvider } from './providers/types.ts'
+
+interface MoveTaskBody {
+  column?: string
+}
+
+function json(data: unknown, status = 200): Response {
+  return Response.json(data, { status })
+}
+
+function parseOptionalInt(value: string | null): number | undefined {
+  return value ? parseInt(value, 10) : undefined
+}
+
+function missingArgument(field: string): Response {
+  return json(
+    { ok: false, error: { code: 'MISSING_ARGUMENT', message: `${field} is required` } },
+    400,
+  )
+}
+
+function statusForCode(code: string): number {
+  if (code === ErrorCode.TASK_NOT_FOUND || code === ErrorCode.COLUMN_NOT_FOUND) return 404
+  if (code === ErrorCode.PROVIDER_AUTH_FAILED) return 401
+  if (code === ErrorCode.PROVIDER_RATE_LIMITED) return 429
+  if (code === ErrorCode.UNSUPPORTED_OPERATION) return 400
+  if (code === ErrorCode.PROVIDER_NOT_CONFIGURED) return 500
+  return 400
+}
+
+function toResponse(result: CliOutput): Response {
+  if (result.ok) return json(result)
+  return json(result, statusForCode(result.error.code))
+}
+
+async function wrapHandler(fn: () => Promise<CliOutput> | CliOutput): Promise<Response> {
+  try {
+    return toResponse(await fn())
+  } catch (err) {
+    if (err instanceof KanbanError) {
+      return json(
+        { ok: false, error: { code: err.code, message: err.message } },
+        statusForCode(err.code),
+      )
+    }
+    const msg = err instanceof Error ? err.message : String(err)
+    return json({ ok: false, error: { code: 'INTERNAL_ERROR', message: msg } }, 500)
+  }
+}
+
+export interface ApiResult {
+  response: Response
+  mutated: boolean
+}
+
+export async function handleRequest(provider: KanbanProvider, req: Request): Promise<ApiResult> {
+  const url = new URL(req.url)
+  const path = url.pathname
+  const method = req.method
+
+  if (path === '/api/bootstrap' && method === 'GET') {
+    return {
+      response: await wrapHandler(async () => ({ ok: true, data: await provider.getBootstrap() })),
+      mutated: false,
+    }
+  }
+
+  if (path === '/api/provider' && method === 'GET') {
+    return {
+      response: await wrapHandler(async () => ({ ok: true, data: await provider.getContext() })),
+      mutated: false,
+    }
+  }
+
+  if (path === '/api/board' && method === 'GET') {
+    return {
+      response: await wrapHandler(async () => ({ ok: true, data: await provider.getBoard() })),
+      mutated: false,
+    }
+  }
+
+  if (path === '/api/columns' && method === 'GET') {
+    return {
+      response: await wrapHandler(async () => ({ ok: true, data: await provider.listColumns() })),
+      mutated: false,
+    }
+  }
+
+  if (path === '/api/tasks' && method === 'GET') {
+    return {
+      response: await wrapHandler(async () => {
+        const column = url.searchParams.get('column') ?? undefined
+        const priority = url.searchParams.get('priority') ?? undefined
+        const assignee = url.searchParams.get('assignee') ?? undefined
+        const project = url.searchParams.get('project') ?? undefined
+        const sort = url.searchParams.get('sort') ?? undefined
+        const limit = parseOptionalInt(url.searchParams.get('limit'))
+        return {
+          ok: true,
+          data: await provider.listTasks({ column, priority, assignee, project, sort, limit }),
+        }
+      }),
+      mutated: false,
+    }
+  }
+
+  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({
+        title: body.title!,
+        description: body.description,
+        column: body.column,
+        priority: body.priority,
+        assignee: body.assignee,
+        project: body.project,
+        metadata: body.metadata,
+      }),
+    }))
+    return { response, mutated: response.ok }
+  }
+
+  const taskMatch = path.match(/^\/api\/tasks\/([^/]+)$/)
+  if (taskMatch) {
+    const id = decodeURIComponent(taskMatch[1]!)
+
+    if (method === 'GET') {
+      return {
+        response: await wrapHandler(async () => ({ ok: true, data: await provider.getTask(id) })),
+        mutated: false,
+      }
+    }
+
+    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 }
+    }
+
+    if (method === 'DELETE') {
+      const response = await wrapHandler(async () => ({
+        ok: true,
+        data: await provider.deleteTask(id),
+      }))
+      return { response, mutated: response.ok }
+    }
+  }
+
+  const moveMatch = path.match(/^\/api\/tasks\/([^/]+)\/move$/)
+  if (moveMatch && method === 'PATCH') {
+    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 }
+  }
+
+  if (path === '/api/activity' && method === 'GET') {
+    return {
+      response: await wrapHandler(async () => {
+        const taskId = url.searchParams.get('taskId') ?? undefined
+        const limit = parseOptionalInt(url.searchParams.get('limit'))
+        return { ok: true, data: await provider.getActivity(limit, taskId) }
+      }),
+      mutated: false,
+    }
+  }
+
+  if (path === '/api/metrics' && method === 'GET') {
+    return {
+      response: await wrapHandler(async () => ({ ok: true, data: await provider.getMetrics() })),
+      mutated: false,
+    }
+  }
+
+  if (path === '/api/config' && method === 'GET') {
+    return {
+      response: await wrapHandler(async () => ({ ok: true, data: await provider.getConfig() })),
+      mutated: false,
+    }
+  }
+
+  if (path === '/api/config' && method === 'PATCH') {
+    const body = (await req.json()) as Partial<BoardConfig>
+    const response = await wrapHandler(async () => ({
+      ok: true,
+      data: await provider.patchConfig(body),
+    }))
+    return { response, mutated: response.ok }
+  }
+
+  return {
+    response: json(
+      { ok: false, error: { code: 'NOT_FOUND', message: `No route: ${method} ${path}` } },
+      404,
+    ),
+    mutated: false,
+  }
+}

package/src/commands/board.ts

@@ -0,0 +1,29 @@
+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'
+
+export function boardInit(db: Database): CliOutput {
+  if (isInitialized(db)) {
+    throw new KanbanError(ErrorCode.BOARD_ALREADY_INITIALIZED, 'Board is already initialized')
+  }
+  initSchema(db)
+  seedDefaultColumns(db)
+  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

@@ -0,0 +1,19 @@
+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'
+
+export function bulkMoveAllCmd(db: Database, args: { from?: string; to?: string }): CliOutput {
+  if (!args.from || !args.to) {
+    throw new KanbanError(
+      ErrorCode.MISSING_ARGUMENT,
+      'Usage: kanban bulk move-all <from-col> <to-col>',
+    )
+  }
+  return success(bulkMoveAll(db, args.from, args.to))
+}
+
+export function bulkClearDoneCmd(db: Database): CliOutput {
+  return success(bulkClearDone(db))
+}

package/src/commands/column.ts

@@ -0,0 +1,60 @@
+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'
+
+export function columnAdd(
+  db: Database,
+  args: { name?: string; position?: string; color?: string },
+): CliOutput {
+  if (!args.name) {
+    throw new KanbanError(ErrorCode.MISSING_ARGUMENT, 'Column name is required')
+  }
+  const pos = args.position !== undefined ? parseInt(args.position, 10) : undefined
+  if (pos !== undefined && isNaN(pos)) {
+    throw new KanbanError(ErrorCode.INVALID_POSITION, 'Position must be a number')
+  }
+  return success(addColumn(db, args.name, { position: pos, color: args.color }))
+}
+
+export function columnList(db: Database): CliOutput {
+  return success(listColumns(db))
+}
+
+export function columnRename(
+  db: Database,
+  args: { idOrName?: string; newName?: string },
+): CliOutput {
+  if (!args.idOrName || !args.newName) {
+    throw new KanbanError(
+      ErrorCode.MISSING_ARGUMENT,
+      'Usage: kanban column rename <id|name> <new-name>',
+    )
+  }
+  return success(renameColumn(db, args.idOrName, args.newName))
+}
+
+export function columnReorder(
+  db: Database,
+  args: { idOrName?: string; position?: string },
+): CliOutput {
+  if (!args.idOrName || args.position === undefined) {
+    throw new KanbanError(
+      ErrorCode.MISSING_ARGUMENT,
+      'Usage: kanban column reorder <id|name> <position>',
+    )
+  }
+  const pos = parseInt(args.position, 10)
+  if (isNaN(pos)) {
+    throw new KanbanError(ErrorCode.INVALID_POSITION, 'Position must be a number')
+  }
+  return success(reorderColumn(db, args.idOrName, pos))
+}
+
+export function columnDelete(db: Database, args: { idOrName?: string }): CliOutput {
+  if (!args.idOrName) {
+    throw new KanbanError(ErrorCode.MISSING_ARGUMENT, 'Usage: kanban column delete <id|name>')
+  }
+  return success(deleteColumn(db, args.idOrName))
+}

package/src/commands/task.ts

@@ -0,0 +1,117 @@
+import type { Database } from 'bun:sqlite'
+import { addTask, getTask, listTasks, updateTask, deleteTask, moveTask } from '../db.ts'
+import { ErrorCode, KanbanError } from '../errors.ts'
+import { success } from '../output.ts'
+import type { CliOutput, Priority } from '../types.ts'
+
+export function taskAdd(
+  db: Database,
+  args: {
+    title?: string
+    description?: string
+    column?: string
+    priority?: string
+    assignee?: string
+    project?: string
+    metadata?: string
+  },
+): CliOutput {
+  if (!args.title) {
+    throw new KanbanError(ErrorCode.MISSING_ARGUMENT, 'Task title is required')
+  }
+  return success(
+    addTask(db, args.title, {
+      description: args.description,
+      column: args.column,
+      priority: args.priority as Priority | undefined,
+      assignee: args.assignee,
+      project: args.project,
+      metadata: args.metadata,
+    }),
+  )
+}
+
+export function taskList(
+  db: Database,
+  opts: {
+    column?: string
+    priority?: string
+    assignee?: string
+    project?: string
+    limit?: string
+    sort?: string
+  },
+): CliOutput {
+  return success(
+    listTasks(db, {
+      column: opts.column,
+      priority: opts.priority,
+      assignee: opts.assignee,
+      project: opts.project,
+      limit: opts.limit ? parseInt(opts.limit, 10) : undefined,
+      sort: opts.sort,
+    }),
+  )
+}
+
+export function taskView(db: Database, args: { id?: string }): CliOutput {
+  if (!args.id) {
+    throw new KanbanError(ErrorCode.MISSING_ARGUMENT, 'Task ID is required')
+  }
+  return success(getTask(db, args.id))
+}
+
+export function taskUpdate(
+  db: Database,
+  args: {
+    id?: string
+    title?: string
+    description?: string
+    priority?: string
+    assignee?: string
+    project?: string
+    metadata?: string
+  },
+): CliOutput {
+  if (!args.id) {
+    throw new KanbanError(ErrorCode.MISSING_ARGUMENT, 'Task ID is required')
+  }
+  return success(
+    updateTask(db, args.id, {
+      title: args.title,
+      description: args.description,
+      priority: args.priority as Priority | undefined,
+      assignee: args.assignee,
+      project: args.project,
+      metadata: args.metadata,
+    }),
+  )
+}
+
+export function taskDelete(db: Database, args: { id?: string }): CliOutput {
+  if (!args.id) {
+    throw new KanbanError(ErrorCode.MISSING_ARGUMENT, 'Task ID is required')
+  }
+  return success(deleteTask(db, args.id))
+}
+
+export function taskMove(db: Database, args: { id?: string; column?: string }): CliOutput {
+  if (!args.id || !args.column) {
+    throw new KanbanError(ErrorCode.MISSING_ARGUMENT, 'Usage: kanban task move <id> <column>')
+  }
+  return success(moveTask(db, args.id, args.column))
+}
+
+export function taskAssign(db: Database, args: { id?: string; assignee?: string }): CliOutput {
+  if (!args.id || !args.assignee) {
+    throw new KanbanError(ErrorCode.MISSING_ARGUMENT, 'Usage: kanban task assign <id> <assignee>')
+  }
+  return success(updateTask(db, args.id, { assignee: args.assignee }))
+}
+
+export function taskPrioritize(db: Database, args: { id?: string; priority?: string }): CliOutput {
+  if (!args.id || !args.priority) {
+    throw new KanbanError(ErrorCode.MISSING_ARGUMENT, 'Usage: kanban task prioritize <id> <level>')
+  }
+  return success(updateTask(db, args.id, { priority: args.priority as Priority }))
+}

package/src/config.ts

@@ -0,0 +1,29 @@
+import { readFileSync, writeFileSync, renameSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import type { BoardConfig } from './types.ts'
+
+const DEFAULT_CONFIG: BoardConfig = { members: [], projects: [] }
+
+export function getConfigPath(dbPath: string): string {
+  return join(dirname(dbPath), 'config.json')
+}
+
+export function loadConfig(dbPath: string): BoardConfig {
+  const configPath = getConfigPath(dbPath)
+  try {
+    const raw = readFileSync(configPath, 'utf-8')
+    const parsed = JSON.parse(raw) as Partial<BoardConfig>
+    return {
+      members: Array.isArray(parsed.members) ? parsed.members : [],
+      projects: Array.isArray(parsed.projects) ? parsed.projects : [],
+    }
+  } catch {
+    return { ...DEFAULT_CONFIG, members: [], projects: [] }
+  }
+}
+
+export function saveConfig(configPath: string, config: BoardConfig): void {
+  const tmp = configPath + '.tmp'
+  writeFileSync(tmp, JSON.stringify(config, null, 2) + '\n')
+  renameSync(tmp, configPath)
+}