@andypai/agent-kanban 0.5.1 → 0.6.1

package/src/__tests__/webhooks.test.ts

@@ -27,6 +27,18 @@ function hmac(secret: string, body: string): string {
   return createHmac('sha256', secret).update(body).digest('hex')
 }
 
+const JIRA_TEST_SECRET = 'topsecret'
+const LINEAR_TEST_SECRET = 'hushhush'
+
+// Sign for both providers; each handler only reads its own header, so this works
+// regardless of which provider the test exercises.
+function signedHeaders(body: string): Record<string, string> {
+  return {
+    'x-hub-signature': `sha256=${hmac(JIRA_TEST_SECRET, body)}`,
+    'linear-signature': hmac(LINEAR_TEST_SECRET, body),
+  }
+}
+
 function jsonResponse(body: unknown, status = 200): Response {
   return new Response(JSON.stringify(body), {
     status,
@@ -108,7 +120,7 @@ describe('Jira webhook', () => {
   test('issue_created upserts the task', async () => {
     const db = new Database(':memory:')
     seedJira(db)
-    delete process.env['JIRA_WEBHOOK_SECRET']
+    process.env['JIRA_WEBHOOK_SECRET'] = JIRA_TEST_SECRET
     const client = new JiraClient({
       baseUrl: jiraConfig.baseUrl,
       email: jiraConfig.email,
@@ -133,7 +145,7 @@ describe('Jira webhook', () => {
         },
       },
     })
-    const result = await provider.handleWebhook({ headers: {}, rawBody: body })
+    const result = await provider.handleWebhook({ headers: signedHeaders(body), rawBody: body })
     expect(result.handled).toBe(true)
     const tasks = getCachedJiraTasks(db)
     expect(tasks.find((t) => t.externalRef === 'ENG-100')?.title).toBe('New issue')
@@ -142,7 +154,7 @@ describe('Jira webhook', () => {
   test('issue_created accepts Jira webhook string descriptions', async () => {
     const db = new Database(':memory:')
     seedJira(db)
-    delete process.env['JIRA_WEBHOOK_SECRET']
+    process.env['JIRA_WEBHOOK_SECRET'] = JIRA_TEST_SECRET
     const client = new JiraClient({
       baseUrl: jiraConfig.baseUrl,
       email: jiraConfig.email,
@@ -170,7 +182,7 @@ describe('Jira webhook', () => {
       },
     })
 
-    const result = await provider.handleWebhook({ headers: {}, rawBody: body })
+    const result = await provider.handleWebhook({ headers: signedHeaders(body), rawBody: body })
 
     expect(result.handled).toBe(true)
     expect(getCachedJiraTasks(db).find((t) => t.externalRef === 'ENG-101')?.description).toBe(
@@ -193,7 +205,7 @@ describe('Jira webhook', () => {
         updatedAt: '2025-02-01',
       },
     ])
-    delete process.env['JIRA_WEBHOOK_SECRET']
+    process.env['JIRA_WEBHOOK_SECRET'] = JIRA_TEST_SECRET
     const client = new JiraClient({
       baseUrl: jiraConfig.baseUrl,
       email: jiraConfig.email,
@@ -214,7 +226,7 @@ describe('Jira webhook', () => {
         },
       },
     })
-    const result = await provider.handleWebhook({ headers: {}, rawBody: body })
+    const result = await provider.handleWebhook({ headers: signedHeaders(body), rawBody: body })
     expect(result.handled).toBe(true)
     expect(getCachedJiraTasks(db).find((t) => t.externalRef === 'ENG-200')).toBeUndefined()
   })
@@ -298,7 +310,7 @@ describe('Jira webhook', () => {
   test('ignores issue updates from other projects', async () => {
     const db = new Database(':memory:')
     seedJira(db)
-    delete process.env['JIRA_WEBHOOK_SECRET']
+    process.env['JIRA_WEBHOOK_SECRET'] = JIRA_TEST_SECRET
     const client = new JiraClient({
       baseUrl: jiraConfig.baseUrl,
       email: jiraConfig.email,
@@ -323,7 +335,7 @@ describe('Jira webhook', () => {
       },
     })
 
-    const result = await provider.handleWebhook({ headers: {}, rawBody: body })
+    const result = await provider.handleWebhook({ headers: signedHeaders(body), rawBody: body })
 
     expect(result.handled).toBe(false)
     expect(result.message).toContain('Ignoring issue from project')
@@ -333,7 +345,7 @@ describe('Jira webhook', () => {
   test('issue_updated backfills activity immediately', async () => {
     const db = new Database(':memory:')
     seedJira(db)
-    delete process.env['JIRA_WEBHOOK_SECRET']
+    process.env['JIRA_WEBHOOK_SECRET'] = JIRA_TEST_SECRET
     const originalFetch = globalThis.fetch
     globalThis.fetch = (async (input) => {
       const url =
@@ -381,7 +393,7 @@ describe('Jira webhook', () => {
         },
       })
 
-      const result = await provider.handleWebhook({ headers: {}, rawBody: body })
+      const result = await provider.handleWebhook({ headers: signedHeaders(body), rawBody: body })
 
       expect(result.handled).toBe(true)
       expect(getCachedJiraTasks(db).find((task) => task.externalRef === 'ENG-600')?.column_id).toBe(
@@ -434,7 +446,7 @@ describe('Linear webhook', () => {
   test('Issue.create upserts the task', async () => {
     const db = new Database(':memory:')
     seedLinear(db)
-    delete process.env['LINEAR_WEBHOOK_SECRET']
+    process.env['LINEAR_WEBHOOK_SECRET'] = LINEAR_TEST_SECRET
     const provider = new LinearProvider(db, 'tid', 'key')
     const body = JSON.stringify({
       action: 'create',
@@ -454,7 +466,7 @@ describe('Linear webhook', () => {
         commentCount: 1,
       },
     })
-    const result = await provider.handleWebhook({ headers: {}, rawBody: body })
+    const result = await provider.handleWebhook({ headers: signedHeaders(body), rawBody: body })
     expect(result.handled).toBe(true)
     const tasks = getCachedLinearTasks(db)
     const issue = tasks.find((t) => t.externalRef === 'DX-1')
@@ -479,14 +491,14 @@ describe('Linear webhook', () => {
         updatedAt: '2025-01',
       },
     ])
-    delete process.env['LINEAR_WEBHOOK_SECRET']
+    process.env['LINEAR_WEBHOOK_SECRET'] = LINEAR_TEST_SECRET
     const provider = new LinearProvider(db, 'tid', 'key')
     const body = JSON.stringify({
       action: 'remove',
       type: 'Issue',
       data: { id: 'ix', identifier: 'DX-9' },
     })
-    const result = await provider.handleWebhook({ headers: {}, rawBody: body })
+    const result = await provider.handleWebhook({ headers: signedHeaders(body), rawBody: body })
     expect(result.handled).toBe(true)
     expect(getCachedLinearTasks(db).find((t) => t.externalRef === 'DX-9')).toBeUndefined()
   })
@@ -494,7 +506,7 @@ describe('Linear webhook', () => {
   test('ignores create/update events from another team', async () => {
     const db = new Database(':memory:')
     seedLinear(db)
-    delete process.env['LINEAR_WEBHOOK_SECRET']
+    process.env['LINEAR_WEBHOOK_SECRET'] = LINEAR_TEST_SECRET
     const provider = new LinearProvider(db, 'tid', 'key')
     const body = JSON.stringify({
       action: 'update',
@@ -510,7 +522,7 @@ describe('Linear webhook', () => {
       },
     })
 
-    const result = await provider.handleWebhook({ headers: {}, rawBody: body })
+    const result = await provider.handleWebhook({ headers: signedHeaders(body), rawBody: body })
 
     expect(result.handled).toBe(false)
     expect(result.message).toContain("Ignoring issue from team 'other-team'")
@@ -520,7 +532,7 @@ describe('Linear webhook', () => {
   test('falls back to issue-team lookup when the webhook payload omits team info', async () => {
     const db = new Database(':memory:')
     seedLinear(db)
-    delete process.env['LINEAR_WEBHOOK_SECRET']
+    process.env['LINEAR_WEBHOOK_SECRET'] = LINEAR_TEST_SECRET
     globalThis.fetch = (async (_input: string | URL | Request, init?: RequestInit) => {
       const body = JSON.parse(String(init?.body)) as {
         query: string
@@ -559,7 +571,7 @@ describe('Linear webhook', () => {
       },
     })
 
-    const result = await provider.handleWebhook({ headers: {}, rawBody: body })
+    const result = await provider.handleWebhook({ headers: signedHeaders(body), rawBody: body })
 
     expect(result.handled).toBe(false)
     expect(result.message).toContain("Ignoring issue from team 'OPS'")
@@ -583,7 +595,7 @@ describe('Linear webhook', () => {
         updatedAt: '2025-02-01T00:00:00.000Z',
       },
     ])
-    delete process.env['LINEAR_WEBHOOK_SECRET']
+    process.env['LINEAR_WEBHOOK_SECRET'] = LINEAR_TEST_SECRET
     const provider = new LinearProvider(db, 'tid', 'key')
     const body = JSON.stringify({
       action: 'update',
@@ -599,7 +611,7 @@ describe('Linear webhook', () => {
       },
     })
 
-    const result = await provider.handleWebhook({ headers: {}, rawBody: body })
+    const result = await provider.handleWebhook({ headers: signedHeaders(body), rawBody: body })
 
     expect(result.handled).toBe(true)
     expect(
@@ -610,7 +622,7 @@ describe('Linear webhook', () => {
   test('create event stamps lastWebhookAt without clobbering team/lastSyncAt', async () => {
     const db = new Database(':memory:')
     seedLinear(db)
-    delete process.env['LINEAR_WEBHOOK_SECRET']
+    process.env['LINEAR_WEBHOOK_SECRET'] = LINEAR_TEST_SECRET
     const provider = new LinearProvider(db, 'tid', 'key')
     const body = JSON.stringify({
       action: 'create',
@@ -626,7 +638,7 @@ describe('Linear webhook', () => {
       },
     })
     const before = Date.now()
-    await provider.handleWebhook({ headers: {}, rawBody: body })
+    await provider.handleWebhook({ headers: signedHeaders(body), rawBody: body })
     const meta = loadSyncMeta(db)
     expect(meta.lastWebhookAt).not.toBeNull()
     expect(new Date(meta.lastWebhookAt!).getTime()).toBeGreaterThanOrEqual(before)
@@ -677,3 +689,44 @@ describe('Linear webhook', () => {
     expect(result.unauthorized).toBe(true)
   })
 })
+
+describe('webhook fail-closed when secret is unset', () => {
+  test('Jira rejects unauthenticated webhooks when JIRA_WEBHOOK_SECRET is unset', async () => {
+    const prev = process.env['JIRA_WEBHOOK_SECRET']
+    delete process.env['JIRA_WEBHOOK_SECRET']
+    try {
+      const db = new Database(':memory:')
+      seedJira(db)
+      const client = new JiraClient({
+        baseUrl: jiraConfig.baseUrl,
+        email: jiraConfig.email,
+        apiToken: jiraConfig.apiToken,
+      })
+      const provider = new JiraProvider(db, jiraConfig, client)
+      const body = JSON.stringify({ webhookEvent: 'jira:issue_created', issue: { id: '1' } })
+      const result = await provider.handleWebhook({ headers: {}, rawBody: body })
+      expect(result.handled).toBe(false)
+      expect(result.unauthorized).toBe(true)
+    } finally {
+      if (prev === undefined) delete process.env['JIRA_WEBHOOK_SECRET']
+      else process.env['JIRA_WEBHOOK_SECRET'] = prev
+    }
+  })
+
+  test('Linear rejects unauthenticated webhooks when LINEAR_WEBHOOK_SECRET is unset', async () => {
+    const prev = process.env['LINEAR_WEBHOOK_SECRET']
+    delete process.env['LINEAR_WEBHOOK_SECRET']
+    try {
+      const db = new Database(':memory:')
+      seedLinear(db)
+      const provider = new LinearProvider(db, 'tid', 'key')
+      const body = JSON.stringify({ action: 'create', type: 'Issue', data: { id: 'i1' } })
+      const result = await provider.handleWebhook({ headers: {}, rawBody: body })
+      expect(result.handled).toBe(false)
+      expect(result.unauthorized).toBe(true)
+    } finally {
+      if (prev === undefined) delete process.env['LINEAR_WEBHOOK_SECRET']
+      else process.env['LINEAR_WEBHOOK_SECRET'] = prev
+    }
+  })
+})

package/src/api.ts

@@ -1,11 +1,13 @@
 import { KanbanError, ErrorCode } from './errors'
 import type { BoardConfig, CliOutput, Task } from './types'
 import type { CreateTaskInput, UpdateTaskInput, KanbanProvider } from './providers/types'
-import { normalizeLabels } from './labels'
+import * as useCases from './use-cases'
 
 export type WsEvent =
-  | { type: 'task:upsert'; task: Task; columnName: string }
+  | { type: 'task:upsert'; task: Task; columnId: string }
   | { type: 'task:delete'; id: string }
+  // Fallback when a mutation has no precise event; the UI does a full refresh.
+  | { type: 'refresh' }
 
 interface MoveTaskBody {
   column?: string
@@ -34,7 +36,8 @@ function statusForCode(code: string): number {
   if (
     code === ErrorCode.TASK_NOT_FOUND ||
     code === ErrorCode.COLUMN_NOT_FOUND ||
-    code === ErrorCode.COMMENT_NOT_FOUND
+    code === ErrorCode.COMMENT_NOT_FOUND ||
+    code === ErrorCode.NOT_FOUND
   )
     return 404
   if (code === ErrorCode.PROVIDER_AUTH_FAILED) return 401
@@ -71,17 +74,8 @@ export interface ApiResult {
   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
+function upsertEvent(task: Task): WsEvent {
+  return { type: 'task:upsert', task, columnId: task.column_id }
 }
 
 export async function handleRequest(provider: KanbanProvider, req: Request): Promise<ApiResult> {
@@ -91,28 +85,40 @@ export async function handleRequest(provider: KanbanProvider, req: Request): Pro
 
   if (path === '/api/bootstrap' && method === 'GET') {
     return {
-      response: await wrapHandler(async () => ({ ok: true, data: await provider.getBootstrap() })),
+      response: await wrapHandler(async () => ({
+        ok: true,
+        data: await useCases.getBootstrap(provider),
+      })),
       mutated: false,
     }
   }
 
   if (path === '/api/provider' && method === 'GET') {
     return {
-      response: await wrapHandler(async () => ({ ok: true, data: await provider.getContext() })),
+      response: await wrapHandler(async () => ({
+        ok: true,
+        data: await useCases.getContext(provider),
+      })),
       mutated: false,
     }
   }
 
   if (path === '/api/board' && method === 'GET') {
     return {
-      response: await wrapHandler(async () => ({ ok: true, data: await provider.getBoard() })),
+      response: await wrapHandler(async () => ({
+        ok: true,
+        data: await useCases.getBoard(provider),
+      })),
       mutated: false,
     }
   }
 
   if (path === '/api/columns' && method === 'GET') {
     return {
-      response: await wrapHandler(async () => ({ ok: true, data: await provider.listColumns() })),
+      response: await wrapHandler(async () => ({
+        ok: true,
+        data: await useCases.listColumns(provider),
+      })),
       mutated: false,
     }
   }
@@ -128,7 +134,14 @@ export async function handleRequest(provider: KanbanProvider, req: Request): Pro
         const limit = parseOptionalInt(url.searchParams.get('limit'))
         return {
           ok: true,
-          data: await provider.listTasks({ column, priority, assignee, project, sort, limit }),
+          data: await useCases.listTasks(provider, {
+            column,
+            priority,
+            assignee,
+            project,
+            sort,
+            limit,
+          }),
         }
       }),
       mutated: false,
@@ -140,19 +153,19 @@ export async function handleRequest(provider: KanbanProvider, req: Request): Pro
     if (!body.title) return { response: missingArgument('title'), mutated: false }
     let created: Task | null = null
     const response = await wrapHandler(async () => {
-      created = await provider.createTask({
+      created = await useCases.createTask(provider, {
         title: body.title!,
         description: body.description,
         column: body.column,
         priority: body.priority,
         assignee: body.assignee,
         project: body.project,
-        labels: normalizeLabels(body.labels),
+        labels: body.labels,
         metadata: body.metadata,
       })
       return { ok: true, data: created }
     })
-    const event = response.ok && created ? await upsertEvent(provider, created) : undefined
+    const event = response.ok && created ? upsertEvent(created) : undefined
     return { response, mutated: response.ok, event }
   }
 
@@ -162,7 +175,10 @@ export async function handleRequest(provider: KanbanProvider, req: Request): Pro
 
     if (method === 'GET') {
       return {
-        response: await wrapHandler(async () => ({ ok: true, data: await provider.getTask(id) })),
+        response: await wrapHandler(async () => ({
+          ok: true,
+          data: await useCases.getTask(provider, id),
+        })),
         mutated: false,
       }
     }
@@ -171,17 +187,17 @@ export async function handleRequest(provider: KanbanProvider, req: Request): Pro
       const body = (await req.json()) as UpdateTaskInput
       let updated: Task | null = null
       const response = await wrapHandler(async () => {
-        updated = await provider.updateTask(id, body)
+        updated = await useCases.updateTask(provider, id, body)
         return { ok: true, data: updated }
       })
-      const event = response.ok && updated ? await upsertEvent(provider, updated) : undefined
+      const event = response.ok && updated ? upsertEvent(updated) : undefined
       return { response, mutated: response.ok, event }
     }
 
     if (method === 'DELETE') {
       const response = await wrapHandler(async () => ({
         ok: true,
-        data: await provider.deleteTask(id),
+        data: await useCases.deleteTask(provider, id),
       }))
       const event: WsEvent | undefined = response.ok ? { type: 'task:delete', id } : undefined
       return { response, mutated: response.ok, event }
@@ -195,10 +211,10 @@ export async function handleRequest(provider: KanbanProvider, req: Request): Pro
     if (!body.column) return { response: missingArgument('column'), mutated: false }
     let moved: Task | null = null
     const response = await wrapHandler(async () => {
-      moved = await provider.moveTask(id, body.column!)
+      moved = await useCases.moveTask(provider, id, body.column!)
       return { ok: true, data: moved }
     })
-    const event = response.ok && moved ? await upsertEvent(provider, moved) : undefined
+    const event = response.ok && moved ? upsertEvent(moved) : undefined
     return { response, mutated: response.ok, event }
   }
 
@@ -209,7 +225,7 @@ export async function handleRequest(provider: KanbanProvider, req: Request): Pro
       return {
         response: await wrapHandler(async () => ({
           ok: true,
-          data: await provider.listComments(id),
+          data: await useCases.listComments(provider, id),
         })),
         mutated: false,
       }
@@ -220,7 +236,7 @@ export async function handleRequest(provider: KanbanProvider, req: Request): Pro
       if (!body.body) return { response: missingArgument('body'), mutated: false }
       const response = await wrapHandler(async () => ({
         ok: true,
-        data: await provider.comment(id, body.body!),
+        data: await useCases.addComment(provider, id, body.body!),
       }))
       return { response, mutated: response.ok }
     }
@@ -236,7 +252,7 @@ export async function handleRequest(provider: KanbanProvider, req: Request): Pro
       if (!body.body) return { response: missingArgument('body'), mutated: false }
       const response = await wrapHandler(async () => ({
         ok: true,
-        data: await provider.updateComment(id, commentId, body.body!),
+        data: await useCases.updateComment(provider, id, commentId, body.body!),
       }))
       return { response, mutated: response.ok }
     }
@@ -247,7 +263,7 @@ export async function handleRequest(provider: KanbanProvider, req: Request): Pro
       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) }
+        return { ok: true, data: await useCases.getActivity(provider, limit, taskId) }
       }),
       mutated: false,
     }
@@ -255,14 +271,20 @@ export async function handleRequest(provider: KanbanProvider, req: Request): Pro
 
   if (path === '/api/metrics' && method === 'GET') {
     return {
-      response: await wrapHandler(async () => ({ ok: true, data: await provider.getMetrics() })),
+      response: await wrapHandler(async () => ({
+        ok: true,
+        data: await useCases.getMetrics(provider),
+      })),
       mutated: false,
     }
   }
 
   if (path === '/api/config' && method === 'GET') {
     return {
-      response: await wrapHandler(async () => ({ ok: true, data: await provider.getConfig() })),
+      response: await wrapHandler(async () => ({
+        ok: true,
+        data: await useCases.getConfig(provider),
+      })),
       mutated: false,
     }
   }
@@ -271,7 +293,7 @@ export async function handleRequest(provider: KanbanProvider, req: Request): Pro
     const body = (await req.json()) as Partial<BoardConfig>
     const response = await wrapHandler(async () => ({
       ok: true,
-      data: await provider.patchConfig(body),
+      data: await useCases.patchConfig(provider, body),
     }))
     return { response, mutated: response.ok }
   }
@@ -338,7 +360,7 @@ export async function handleRequest(provider: KanbanProvider, req: Request): Pro
 
   return {
     response: json(
-      { ok: false, error: { code: 'NOT_FOUND', message: `No route: ${method} ${path}` } },
+      { ok: false, error: { code: ErrorCode.NOT_FOUND, message: `No route: ${method} ${path}` } },
       404,
     ),
     mutated: false,

package/src/column-roles.ts

@@ -0,0 +1,52 @@
+// Board metrics need to know which columns mean "done" and "in progress", but
+// columns are just (name, position) with no role metadata. Names vary across
+// boards (custom local columns, Jira/Linear statuses, KANBAN_DEFAULT_COLUMNS),
+// so we classify by a normalized name plus a small synonym set rather than an
+// exact 'done' / 'in-progress' string match.
+
+export interface ClassifiableColumn {
+  id: string
+  name: string
+  position: number
+}
+
+const DONE_NAMES = new Set([
+  'done',
+  'complete',
+  'completed',
+  'closed',
+  'resolved',
+  'shipped',
+  'merged',
+])
+
+const IN_PROGRESS_NAMES = new Set([
+  'inprogress',
+  'doing',
+  'wip',
+  'started',
+  'indevelopment',
+  'inreview',
+])
+
+// Lowercase and drop separators so 'In Progress', 'in-progress', and
+// 'in_progress' all normalize to the same token.
+function normalizeColumnName(name: string): string {
+  return name.toLowerCase().replace(/[^a-z0-9]/g, '')
+}
+
+export function selectDoneColumnIds(columns: ClassifiableColumn[]): string[] {
+  const matched = columns.filter((c) => DONE_NAMES.has(normalizeColumnName(c.name)))
+  if (matched.length > 0) return matched.map((c) => c.id)
+  // No recognizable "done" name: fall back to the terminal column (the kanban
+  // convention) so completion metrics aren't silently zero under custom names.
+  const terminal = columns.reduce<ClassifiableColumn | null>(
+    (best, c) => (best === null || c.position > best.position ? c : best),
+    null,
+  )
+  return terminal ? [terminal.id] : []
+}
+
+export function selectInProgressColumnIds(columns: ClassifiableColumn[]): string[] {
+  return columns.filter((c) => IN_PROGRESS_NAMES.has(normalizeColumnName(c.name))).map((c) => c.id)
+}

package/src/commands/board.ts

@@ -4,16 +4,16 @@ import { ErrorCode, KanbanError } from '../errors'
 import { success } from '../output'
 import type { CliOutput } from '../types'
 
-export function boardInit(db: Database): CliOutput {
+export function boardInit(db: Database, columnNames?: string[]): CliOutput {
   if (isInitialized(db)) {
     throw new KanbanError(ErrorCode.BOARD_ALREADY_INITIALIZED, 'Board is already initialized')
   }
   initSchema(db)
-  seedDefaultColumns(db)
+  seedDefaultColumns(db, columnNames)
   return success({ message: 'Board initialized with default columns.' })
 }
 
-export function boardReset(db: Database): CliOutput {
-  resetBoard(db)
+export function boardReset(db: Database, columnNames?: string[]): CliOutput {
+  resetBoard(db, columnNames)
   return success({ message: 'Board reset. All data cleared and defaults restored.' })
 }