@andypai/agent-kanban 0.4.0 → 0.5.1

package/src/labels.ts

@@ -0,0 +1,34 @@
+export function normalizeLabels(input: unknown): string[] {
+  const labels: string[] = []
+  const seen = new Set<string>()
+
+  collectLabels(input, labels, seen)
+
+  return labels
+}
+
+export function parseStoredLabels(raw: unknown): string[] {
+  if (typeof raw !== 'string') return normalizeLabels(raw)
+
+  try {
+    return normalizeLabels(JSON.parse(raw))
+  } catch {
+    return normalizeLabels(raw)
+  }
+}
+
+function collectLabels(input: unknown, labels: string[], seen: Set<string>): void {
+  if (Array.isArray(input)) {
+    for (const item of input) collectLabels(item, labels, seen)
+    return
+  }
+
+  if (typeof input !== 'string') return
+
+  for (const part of input.split(',')) {
+    const label = part.trim()
+    if (!label || seen.has(label)) continue
+    seen.add(label)
+    labels.push(label)
+  }
+}

package/src/providers/jira-cache.ts

@@ -1,8 +1,10 @@
 import type { Database } from 'bun:sqlite'
+import { ErrorCode, KanbanError } from '../errors'
 import type { BoardView, ProviderTeamInfo, Task } from '../types'
 
 // Column ids are prefixed to avoid collisions across sources:
-// - board-sourced columns: 'board:<boardId>:<columnName>'
+// - board-sourced columns: 'board:<boardId>:<columnName>' with an index suffix
+//   only when Jira returns duplicate board column names
 // - status-fallback columns: 'status:<statusId>'
 // The provider (T04) picks ONE source per sync, so mixed-source boards
 // do not occur in practice.
@@ -30,6 +32,67 @@ export interface JiraCacheConfig {
   issueTypes: Array<{ id: string; name: string }>
 }
 
+export interface JiraBoardColumnInput {
+  name: string
+  statuses: Array<{ id: string }>
+}
+
+export function jiraBoardColumnRows(
+  boardId: number,
+  columns: JiraBoardColumnInput[],
+): Array<{
+  id: string
+  name: string
+  position: number
+  statusIds: string[]
+  source: 'board'
+}> {
+  const seen = new Set<string>()
+  return columns.map((column, index) => {
+    const baseId = `board:${boardId}:${column.name}`
+    let id = baseId
+    if (seen.has(id)) {
+      id = `${baseId}:${index}`
+      let suffix = 2
+      while (seen.has(id)) {
+        id = `${baseId}:${index}:${suffix}`
+        suffix += 1
+      }
+    }
+    seen.add(id)
+    return {
+      id,
+      name: column.name,
+      position: index,
+      statusIds: column.statuses.map((status) => status.id),
+      source: 'board',
+    }
+  })
+}
+
+// Resolves a user-supplied column reference to a cached column id, trying
+// (1) exact id, (2) case-insensitive name, (3) raw status id containment.
+// A name that matches multiple columns (possible when Jira returns duplicate
+// board column names) is rejected as ambiguous so the caller picks an id.
+export function resolveJiraColumnId(columns: JiraColumnRow[], input: string): string {
+  const byId = columns.find((column) => column.id === input)
+  if (byId) return byId.id
+  const lower = input.toLowerCase()
+  const byName = columns.filter((column) => column.name.toLowerCase() === lower)
+  if (byName.length === 1) return byName[0]!.id
+  if (byName.length > 1) {
+    throw new KanbanError(
+      ErrorCode.COLUMN_NOT_FOUND,
+      `Jira column name '${input}' is ambiguous; use one of these column ids: ${byName
+        .map((column) => column.id)
+        .join(', ')}`,
+    )
+  }
+  const byStatus = columns.find((column) => decodeColumnStatusIds(column).includes(input))
+  if (byStatus) return byStatus.id
+  throw new KanbanError(ErrorCode.COLUMN_NOT_FOUND, `No Jira column matching '${input}'`)
+}
+
 interface JiraIssueRow {
   id: string
   key: string

package/src/providers/jira-client.ts

@@ -388,3 +388,7 @@ export class JiraClient {
     })
   }
 }
+
+export function normalizeJiraLabels(labels: string[] | undefined): string[] {
+  return (labels ?? []).map((label) => label.trim()).filter(Boolean)
+}

package/src/providers/jira.ts

@@ -20,7 +20,7 @@ import {
 import { adfToPlainText, plainTextToAdf, type AdfDocument } from './jira-adf'
 import { JIRA_CAPABILITIES } from './capabilities'
 import { providerUpstreamError, unsupportedOperation } from './errors'
-import { JiraClient, type JiraComment, type JiraIssue } from './jira-client'
+import { JiraClient, normalizeJiraLabels, type JiraComment, type JiraIssue } from './jira-client'
 import {
   adjustJiraIssueCommentCount,
   decodeColumnStatusIds,
@@ -32,6 +32,8 @@ import {
   getCachedTask,
   getCachedTasks,
   initJiraCacheSchema,
+  jiraBoardColumnRows,
+  resolveJiraColumnId,
   loadJiraSyncMeta,
   loadTeamInfo,
   pruneJiraIssuesMissingUpstream,
@@ -122,13 +124,7 @@ export class JiraProvider implements KanbanProvider {
     if (this.config.boardId !== undefined) {
       const boardCfg = await this.client.getBoardColumns(this.config.boardId)
       const boardId = this.config.boardId
-      const rows = boardCfg.columnConfig.columns.map((col, i) => ({
-        id: `board:${boardId}:${col.name}`,
-        name: col.name,
-        position: i,
-        statusIds: col.statuses.map((s) => s.id),
-        source: 'board' as const,
-      }))
+      const rows = jiraBoardColumnRows(boardId, boardCfg.columnConfig.columns)
       replaceJiraColumns(this.db, rows)
     } else {
       const statusCats = await this.client.getProjectStatuses(project.key)
@@ -275,18 +271,7 @@ export class JiraProvider implements KanbanProvider {
   }
 
   private resolveColumnId(input: string): string {
-    const columns = getCachedColumns(this.db)
-    // Priority 1: exact id.
-    const byId = columns.find((c) => c.id === input)
-    if (byId) return byId.id
-    // Priority 2: case-insensitive name.
-    const lower = input.toLowerCase()
-    const byName = columns.find((c) => c.name.toLowerCase() === lower)
-    if (byName) return byName.id
-    // Priority 3: status_ids containment (raw status id).
-    const byStatus = columns.find((c) => decodeColumnStatusIds(c).includes(input))
-    if (byStatus) return byStatus.id
-    throw new KanbanError(ErrorCode.COLUMN_NOT_FOUND, `No Jira column matching '${input}'`)
+    return resolveJiraColumnId(getCachedColumns(this.db), input)
   }
 
   private async buildBoardConfig(): Promise<BoardConfig> {
@@ -488,6 +473,8 @@ export class JiraProvider implements KanbanProvider {
         accountId: this.resolveAssigneeAccountId(input.assignee),
       }
     }
+    const labels = normalizeJiraLabels(input.labels)
+    if (labels.length > 0) fields['labels'] = labels
     // Column at create-time is intentionally unsupported in Jira mode: new
     // issues land in the project workflow's default start state. Use
     // `moveTask` after create to change status.

package/src/providers/linear-client.ts

@@ -43,6 +43,11 @@ export interface LinearComment {
   user?: { id: string; name?: string | null; displayName?: string | null } | null
 }
 
+export interface LinearIssueLabel {
+  id: string
+  name: string
+}
+
 interface LinearIssueNode {
   id: string
   identifier: string
@@ -232,6 +237,40 @@ export class LinearClient {
     return data.projects.nodes
   }
 
+  async listIssueLabels(): Promise<LinearIssueLabel[]> {
+    let after: string | null = null
+    const labels: LinearIssueLabel[] = []
+
+    do {
+      const data: {
+        issueLabels: {
+          nodes: LinearIssueLabel[]
+          pageInfo: PageInfo
+        }
+      } = await this.query(
+        `
+          query IssueLabels($after: String) {
+            issueLabels(first: 100, after: $after) {
+              nodes {
+                id
+                name
+              }
+              pageInfo {
+                hasNextPage
+                endCursor
+              }
+            }
+          }
+        `,
+        { after },
+      )
+      labels.push(...data.issueLabels.nodes)
+      after = data.issueLabels.pageInfo.hasNextPage ? data.issueLabels.pageInfo.endCursor : null
+    } while (after)
+
+    return labels
+  }
+
   async listIssues(teamId: string, updatedAfter?: string): Promise<LinearIssue[]> {
     let after: string | null = null
     const issues: LinearIssue[] = []
@@ -311,6 +350,7 @@ export class LinearClient {
     priority?: number
     assigneeId?: string
     projectId?: string
+    labelIds?: string[]
   }): Promise<{ success: boolean; issue: LinearIssue | null }> {
     const data = await this.query<{
       issueCreate: { success: boolean; issue: LinearIssueNode | null }
@@ -349,6 +389,7 @@ export class LinearClient {
           priority: input.priority,
           assigneeId: input.assigneeId,
           projectId: input.projectId,
+          labelIds: input.labelIds,
         },
       },
     )
@@ -567,3 +608,57 @@ export class LinearClient {
     }
   }
 }
+
+export async function resolveLabelIdsForCreate(
+  client: LinearClient,
+  inputLabels: string[] | undefined,
+): Promise<string[] | undefined> {
+  if (!inputLabels?.some((label) => label.trim())) return undefined
+  return resolveLinearLabelIds(inputLabels, await client.listIssueLabels())
+}
+
+export function resolveLinearLabelIds(
+  inputLabels: string[] | undefined,
+  availableLabels: LinearIssueLabel[],
+): string[] | undefined {
+  const requested = dedupeLabelQueries(inputLabels)
+  if (requested.length === 0) return undefined
+
+  const byName = new Map(
+    availableLabels.map((label) => [label.name.trim().toLowerCase(), label.id]),
+  )
+  const knownIds = new Set(availableLabels.map((label) => label.id))
+  const ids: string[] = []
+  const missing: string[] = []
+
+  for (const label of requested) {
+    const id = byName.get(label.toLowerCase()) ?? (knownIds.has(label) ? label : undefined)
+    if (!id) {
+      missing.push(label)
+      continue
+    }
+    if (!ids.includes(id)) ids.push(id)
+  }
+
+  if (missing.length > 0) {
+    providerUpstreamError(
+      `Linear label${missing.length === 1 ? '' : 's'} not found: ${missing.join(', ')}`,
+    )
+  }
+
+  return ids.length > 0 ? ids : undefined
+}
+
+function dedupeLabelQueries(labels: string[] | undefined): string[] {
+  const out: string[] = []
+  const seen = new Set<string>()
+  for (const label of labels ?? []) {
+    const trimmed = label.trim()
+    if (!trimmed) continue
+    const key = trimmed.toLowerCase()
+    if (seen.has(key)) continue
+    seen.add(key)
+    out.push(trimmed)
+  }
+  return out
+}

package/src/providers/linear.ts

@@ -31,7 +31,7 @@ import {
   upsertUsers,
   type LinearActivityRow,
 } from './linear-cache'
-import { LinearClient, type LinearComment } from './linear-client'
+import { LinearClient, resolveLabelIdsForCreate, type LinearComment } from './linear-client'
 import { unsupportedOperation } from './errors'
 import type {
   CreateTaskInput,
@@ -349,6 +349,7 @@ export class LinearProvider implements KanbanProvider {
   async createTask(input: CreateTaskInput) {
     await this.sync()
     const state = input.column ? this.resolveState(input.column) : undefined
+    const labelIds = await resolveLabelIdsForCreate(this.client, input.labels)
     const result = await this.client.createIssue({
       teamId: this.resolvedTeamId(),
       stateId: state?.id,
@@ -357,6 +358,7 @@ export class LinearProvider implements KanbanProvider {
       priority: toLinearPriority(input.priority),
       assigneeId: this.resolveAssigneeId(input.assignee),
       projectId: this.resolveProjectId(input.project),
+      labelIds,
     })
     if (!result.success || !result.issue) {
       throw new KanbanError(ErrorCode.PROVIDER_UPSTREAM_ERROR, 'Linear issue creation failed')

package/src/providers/local.ts

@@ -56,13 +56,14 @@ export class LocalProvider implements KanbanProvider {
   private enrichTask(task: Task, commentCount?: number): Task {
     const revision = task.revision ?? 0
     const assignees = task.assignee ? [task.assignee] : []
+    const labels = Array.isArray(task.labels) ? task.labels : []
     return {
       ...task,
       providerId: task.id,
       externalRef: task.id,
       url: null,
       assignees,
-      labels: [],
+      labels,
       comment_count: commentCount ?? countComments(this.db, task.id),
       version: String(revision),
       source_updated_at: null,

package/src/providers/postgres-jira.ts

@@ -14,9 +14,15 @@ import type {
   TaskComment,
 } from '../types'
 import { JIRA_CAPABILITIES } from './capabilities'
-import { decodeColumnStatusIds, type JiraActivityRow, type JiraColumnRow } from './jira-cache'
+import {
+  decodeColumnStatusIds,
+  jiraBoardColumnRows,
+  resolveJiraColumnId,
+  type JiraActivityRow,
+  type JiraColumnRow,
+} from './jira-cache'
 import { adfToPlainText, plainTextToAdf, type AdfDocument } from './jira-adf'
-import { JiraClient, type JiraComment, type JiraIssue } from './jira-client'
+import { JiraClient, normalizeJiraLabels, type JiraComment, type JiraIssue } from './jira-client'
 import type { JiraProviderConfig } from './jira'
 import { providerUpstreamError, unsupportedOperation } from './errors'
 import type {
@@ -605,15 +611,7 @@ export class PostgresJiraProvider implements KanbanProvider {
     if (this.config.boardId !== undefined) {
       const boardCfg = await this.client.getBoardColumns(this.config.boardId)
       const boardId = this.config.boardId
-      await this.replaceColumns(
-        boardCfg.columnConfig.columns.map((column, index) => ({
-          id: `board:${boardId}:${column.name}`,
-          name: column.name,
-          position: index,
-          statusIds: column.statuses.map((status) => status.id),
-          source: 'board' as const,
-        })),
-      )
+      await this.replaceColumns(jiraBoardColumnRows(boardId, boardCfg.columnConfig.columns))
     } else {
       const statusCats = await this.client.getProjectStatuses(project.key)
       const seen = new Set<string>()
@@ -741,15 +739,7 @@ export class PostgresJiraProvider implements KanbanProvider {
   }
 
   private async resolveColumnId(input: string): Promise<string> {
-    const columns = await this.getColumns()
-    const byId = columns.find((column) => column.id === input)
-    if (byId) return byId.id
-    const lower = input.toLowerCase()
-    const byName = columns.find((column) => column.name.toLowerCase() === lower)
-    if (byName) return byName.id
-    const byStatus = columns.find((column) => decodeColumnStatusIds(column).includes(input))
-    if (byStatus) return byStatus.id
-    throw new KanbanError(ErrorCode.COLUMN_NOT_FOUND, `No Jira column matching '${input}'`)
+    return resolveJiraColumnId(await this.getColumns(), input)
   }
 
   private async buildBoardConfig(): Promise<BoardConfig> {
@@ -948,6 +938,8 @@ export class PostgresJiraProvider implements KanbanProvider {
     if (input.assignee) {
       fields['assignee'] = { accountId: await this.resolveAssigneeAccountId(input.assignee) }
     }
+    const labels = normalizeJiraLabels(input.labels)
+    if (labels.length > 0) fields['labels'] = labels
     const created = await this.client.createIssue({ fields })
     await this.sync(true)
     const fresh = await this.getCachedTask(created.key)

package/src/providers/postgres-linear.ts

@@ -22,7 +22,7 @@ import {
 } from '../webhook-events'
 import { LINEAR_CAPABILITIES } from './capabilities'
 import { unsupportedOperation } from './errors'
-import { LinearClient, type LinearComment } from './linear-client'
+import { LinearClient, resolveLabelIdsForCreate, type LinearComment } from './linear-client'
 import type {
   CreateTaskInput,
   KanbanProvider,
@@ -822,6 +822,7 @@ export class PostgresLinearProvider implements KanbanProvider {
   async createTask(input: CreateTaskInput): Promise<Task> {
     await this.sync()
     const state = input.column ? await this.resolveState(input.column) : undefined
+    const labelIds = await resolveLabelIdsForCreate(this.client, input.labels)
     const result = await this.client.createIssue({
       teamId: await this.resolvedTeamId(),
       stateId: state?.id,
@@ -830,6 +831,7 @@ export class PostgresLinearProvider implements KanbanProvider {
       priority: toLinearPriority(input.priority),
       assigneeId: await this.resolveAssigneeId(input.assignee),
       projectId: await this.resolveProjectId(input.project),
+      labelIds,
     })
     if (!result.success || !result.issue) {
       throw new KanbanError(ErrorCode.PROVIDER_UPSTREAM_ERROR, 'Linear issue creation failed')

package/src/providers/postgres-local.ts

@@ -24,6 +24,7 @@ import type {
   UpdateTaskInput,
 } from './types'
 import type { LocalTrackerConfig } from '../tracker-config'
+import { normalizeLabels, parseStoredLabels } from '../labels'
 
 const DEFAULT_COLUMNS = [
   { name: 'recurring', position: 0 },
@@ -43,6 +44,7 @@ interface TaskRow {
   priority: Priority
   assignee: string
   project: string
+  labels: string
   metadata: string
   revision: number
   created_at: string
@@ -126,6 +128,7 @@ export class PostgresLocalProvider implements KanbanProvider {
         priority TEXT NOT NULL DEFAULT 'medium',
         assignee TEXT NOT NULL DEFAULT '',
         project TEXT NOT NULL DEFAULT '',
+        labels TEXT NOT NULL DEFAULT '[]',
         metadata TEXT NOT NULL DEFAULT '{}',
         revision INTEGER NOT NULL DEFAULT 0,
         created_at TEXT NOT NULL,
@@ -162,6 +165,7 @@ export class PostgresLocalProvider implements KanbanProvider {
         exited_at TEXT
       )
     `
+    await this.sql`ALTER TABLE tasks ADD COLUMN IF NOT EXISTS labels TEXT NOT NULL DEFAULT '[]'`
     await this.sql`CREATE INDEX IF NOT EXISTS idx_tasks_column_id ON tasks(column_id)`
     await this.sql`CREATE INDEX IF NOT EXISTS idx_tasks_priority ON tasks(priority)`
     await this.sql`CREATE INDEX IF NOT EXISTS idx_tasks_assignee ON tasks(assignee)`
@@ -194,7 +198,7 @@ export class PostgresLocalProvider implements KanbanProvider {
       externalRef: row.id,
       url: null,
       assignees: row.assignee ? [row.assignee] : [],
-      labels: [],
+      labels: parseStoredLabels(row.labels),
       comment_count: commentCount,
       version: String(row.revision ?? 0),
       source_updated_at: null,
@@ -352,6 +356,7 @@ export class PostgresLocalProvider implements KanbanProvider {
     const priority = input.priority ?? 'medium'
     assertPriority(priority)
     const metadata = parseMetadata(input.metadata)
+    const labels = normalizeLabels(input.labels)
     const column = input.column
       ? await this.resolveColumn(input.column)
       : await this.resolveDefaultTaskColumn()
@@ -362,12 +367,12 @@ export class PostgresLocalProvider implements KanbanProvider {
     const timestamp = nowIso()
     await this.sql`
       INSERT INTO tasks (
-        id, title, description, column_id, position, priority, assignee, project, metadata,
+        id, title, description, column_id, position, priority, assignee, project, labels, metadata,
         revision, created_at, updated_at
       )
       VALUES (
         ${id}, ${input.title}, ${input.description ?? ''}, ${column.id}, ${Number(positionRow?.next ?? 0)},
-        ${priority}, ${input.assignee ?? ''}, ${input.project ?? ''}, ${metadata},
+        ${priority}, ${input.assignee ?? ''}, ${input.project ?? ''}, ${JSON.stringify(labels)}, ${metadata},
         0, ${timestamp}, ${timestamp}
       )
     `

package/src/providers/types.ts

@@ -29,6 +29,7 @@ export interface CreateTaskInput {
   priority?: Priority
   assignee?: string
   project?: string
+  labels?: string[]
   metadata?: string
 }