@andypai/agent-kanban 0.1.0

package/src/providers/linear-client.ts

@@ -0,0 +1,329 @@
+import { ErrorCode } from '../errors.ts'
+import { providerUpstreamError } from './errors.ts'
+
+interface GraphQLResponse<T> {
+  data?: T
+  errors?: Array<{ message?: string; extensions?: { code?: string } }>
+}
+
+interface PageInfo {
+  hasNextPage: boolean
+  endCursor: string | null
+}
+
+export interface LinearTeamState {
+  id: string
+  name: string
+  position: number
+  color?: string | null
+  type?: string | null
+}
+
+export interface LinearIssue {
+  id: string
+  identifier: string
+  title: string
+  description?: string | null
+  priority?: number | null
+  url?: string | null
+  createdAt: string
+  updatedAt: string
+  assignee?: { id: string; name?: string | null; displayName?: string | null } | null
+  project?: { id: string; name: string; url?: string | null; state?: string | null } | null
+  state: { id: string; name: string; position: number }
+}
+
+interface LinearIssueNode {
+  id: string
+  identifier: string
+  title: string
+  description?: string | null
+  priority?: number | null
+  url?: string | null
+  createdAt: string
+  updatedAt: string
+  assignee?: { id: string; name?: string | null; displayName?: string | null } | null
+  project?: { id: string; name: string; url?: string | null; state?: string | null } | null
+  state: { id: string; name: string; position: number }
+}
+
+export class LinearClient {
+  private readonly endpoint = 'https://api.linear.app/graphql'
+
+  constructor(private readonly apiKey: string) {}
+
+  private async query<T>(query: string, variables: Record<string, unknown> = {}): Promise<T> {
+    const response = await fetch(this.endpoint, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: this.apiKey,
+      },
+      body: JSON.stringify({ query, variables }),
+    })
+
+    if (response.status === 401 || response.status === 403) {
+      providerUpstreamError('Linear authentication failed', ErrorCode.PROVIDER_AUTH_FAILED)
+    }
+
+    if (response.status === 429) {
+      providerUpstreamError('Linear API rate limit exceeded', ErrorCode.PROVIDER_RATE_LIMITED)
+    }
+
+    if (!response.ok) {
+      providerUpstreamError(`Linear API request failed with ${response.status}`)
+    }
+
+    const body = (await response.json()) as GraphQLResponse<T>
+    if (body.errors?.length) {
+      const first = body.errors[0]
+      if (first?.extensions?.code === 'RATELIMITED') {
+        providerUpstreamError('Linear API rate limit exceeded', ErrorCode.PROVIDER_RATE_LIMITED)
+      }
+      providerUpstreamError(first?.message ?? 'Linear API request failed')
+    }
+
+    if (!body.data) {
+      providerUpstreamError('Linear API returned no data')
+    }
+
+    return body.data
+  }
+
+  async getTeam(
+    teamId: string,
+  ): Promise<{ id: string; key: string; name: string; states: LinearTeamState[] }> {
+    const data = await this.query<{
+      team: {
+        id: string
+        key: string
+        name: string
+        states: { nodes: LinearTeamState[] }
+      } | null
+    }>(
+      `
+        query TeamSnapshot($teamId: String!) {
+          team(id: $teamId) {
+            id
+            key
+            name
+            states {
+              nodes {
+                id
+                name
+                position
+                color
+                type
+              }
+            }
+          }
+        }
+      `,
+      { teamId },
+    )
+    if (!data.team) {
+      providerUpstreamError(`Linear team '${teamId}' was not found`)
+    }
+    return {
+      id: data.team.id,
+      key: data.team.key,
+      name: data.team.name,
+      states: data.team.states.nodes,
+    }
+  }
+
+  async listUsers(): Promise<Array<{ id: string; name: string; active?: boolean }>> {
+    const data = await this.query<{
+      users: {
+        nodes: Array<{
+          id: string
+          name?: string | null
+          displayName?: string | null
+          active?: boolean | null
+        }>
+      }
+    }>(
+      `
+        query Users {
+          users {
+            nodes {
+              id
+              name
+              displayName
+              active
+            }
+          }
+        }
+      `,
+    )
+    return data.users.nodes.map((user) => ({
+      id: user.id,
+      name: user.displayName || user.name || user.id,
+      active: user.active ?? true,
+    }))
+  }
+
+  async listProjects(): Promise<
+    Array<{ id: string; name: string; url?: string | null; state?: string | null }>
+  > {
+    const data = await this.query<{
+      projects: {
+        nodes: Array<{ id: string; name: string; url?: string | null; state?: string | null }>
+      }
+    }>(
+      `
+        query Projects {
+          projects {
+            nodes {
+              id
+              name
+              url
+              state
+            }
+          }
+        }
+      `,
+    )
+    return data.projects.nodes
+  }
+
+  async listIssues(teamId: string, updatedAfter?: string): Promise<LinearIssue[]> {
+    let after: string | null = null
+    const issues: LinearIssue[] = []
+
+    do {
+      const data: {
+        issues: {
+          nodes: LinearIssueNode[]
+          pageInfo: PageInfo
+        }
+      } = await this.query(
+        `
+          query Issues($teamId: ID!, $after: String, $updatedAfter: DateTimeOrDuration) {
+            issues(
+              first: 100
+              after: $after
+              orderBy: updatedAt
+              filter: {
+                team: { id: { eq: $teamId } }
+                updatedAt: { gte: $updatedAfter }
+              }
+            ) {
+              nodes {
+                id
+                identifier
+                title
+                description
+                priority
+                url
+                createdAt
+                updatedAt
+                assignee {
+                  id
+                  name
+                  displayName
+                }
+                project {
+                  id
+                  name
+                  url
+                  state
+                }
+                state {
+                  id
+                  name
+                  position
+                }
+              }
+              pageInfo {
+                hasNextPage
+                endCursor
+              }
+            }
+          }
+        `,
+        { teamId, after, updatedAfter: updatedAfter ?? '1970-01-01T00:00:00.000Z' },
+      )
+      issues.push(
+        ...data.issues.nodes.map((issue: LinearIssueNode) => ({
+          ...issue,
+          assignee: issue.assignee
+            ? {
+                id: issue.assignee.id,
+                name: issue.assignee.displayName || issue.assignee.name,
+              }
+            : null,
+        })),
+      )
+      after = data.issues.pageInfo.hasNextPage ? data.issues.pageInfo.endCursor : null
+    } while (after)
+
+    return issues
+  }
+
+  async createIssue(input: {
+    teamId: string
+    stateId?: string
+    title: string
+    description?: string
+    priority?: number
+    assigneeId?: string
+    projectId?: string
+  }): Promise<{ success: boolean; issue: LinearIssue | null }> {
+    const data = await this.query<{
+      issueCreate: { success: boolean; issue: LinearIssue | null }
+    }>(
+      `
+        mutation CreateIssue($input: IssueCreateInput!) {
+          issueCreate(input: $input) {
+            success
+            issue {
+              id
+              identifier
+              title
+              description
+              priority
+              url
+              createdAt
+              updatedAt
+              assignee { id name displayName }
+              project { id name url state }
+              state { id name position }
+            }
+          }
+        }
+      `,
+      {
+        input: {
+          teamId: input.teamId,
+          stateId: input.stateId,
+          title: input.title,
+          description: input.description,
+          priority: input.priority,
+          assigneeId: input.assigneeId,
+          projectId: input.projectId,
+        },
+      },
+    )
+    return data.issueCreate
+  }
+
+  async updateIssue(
+    issueId: string,
+    input: Record<string, unknown>,
+  ): Promise<{ success: boolean }> {
+    const data = await this.query<{
+      issueUpdate: { success: boolean }
+    }>(
+      `
+        mutation UpdateIssue($id: String!, $input: IssueUpdateInput!) {
+          issueUpdate(id: $id, input: $input) {
+            success
+          }
+        }
+      `,
+      { id: issueId, input },
+    )
+    return data.issueUpdate
+  }
+}

package/src/providers/linear.ts

@@ -0,0 +1,305 @@
+import type { Database } from 'bun:sqlite'
+import { ErrorCode, KanbanError } from '../errors.ts'
+import type {
+  ActivityEntry,
+  BoardBootstrap,
+  BoardConfig,
+  BoardMetrics,
+  Column,
+  Task,
+} from '../types.ts'
+import { LINEAR_CAPABILITIES } from './capabilities.ts'
+import {
+  getCachedBoard,
+  getCachedColumns,
+  getCachedConfig,
+  getCachedTask,
+  getCachedTasks,
+  initLinearCacheSchema,
+  loadSyncMeta,
+  replaceStates,
+  saveSyncMeta,
+  upsertIssues,
+  upsertProjects,
+  upsertUsers,
+} from './linear-cache.ts'
+import { LinearClient } from './linear-client.ts'
+import { unsupportedOperation } from './errors.ts'
+import type {
+  CreateTaskInput,
+  KanbanProvider,
+  ProviderContext,
+  TaskListFilters,
+  UpdateTaskInput,
+} from './types.ts'
+
+const SYNC_INTERVAL_MS = 30_000
+
+function toLinearPriority(priority: Task['priority'] | undefined): number | undefined {
+  switch (priority) {
+    case 'urgent':
+      return 1
+    case 'high':
+      return 2
+    case 'medium':
+      return 3
+    case 'low':
+      return 4
+    default:
+      return undefined
+  }
+}
+
+export class LinearProvider implements KanbanProvider {
+  readonly type = 'linear' as const
+  private readonly client: LinearClient
+
+  constructor(
+    private readonly db: Database,
+    private readonly teamId: string,
+    apiKey: string,
+  ) {
+    initLinearCacheSchema(db)
+    this.client = new LinearClient(apiKey)
+  }
+
+  private async sync(force = false): Promise<void> {
+    const meta = loadSyncMeta(this.db)
+    const lastSyncAtMs = meta.lastSyncAt ? Date.parse(meta.lastSyncAt) : 0
+    if (!force && lastSyncAtMs && Date.now() - lastSyncAtMs < SYNC_INTERVAL_MS) return
+
+    const [team, users, projects, issues] = await Promise.all([
+      this.client.getTeam(this.teamId),
+      this.client.listUsers(),
+      this.client.listProjects(),
+      this.client.listIssues(
+        this.teamId,
+        force ? undefined : (meta.lastIssueUpdatedAt ?? undefined),
+      ),
+    ])
+
+    replaceStates(this.db, team.states)
+    upsertUsers(this.db, users)
+    upsertProjects(this.db, projects)
+    upsertIssues(
+      this.db,
+      issues.map((issue) => ({
+        id: issue.id,
+        identifier: issue.identifier,
+        title: issue.title,
+        description: issue.description ?? '',
+        priority: issue.priority ?? 0,
+        assigneeId: issue.assignee?.id ?? null,
+        assigneeName: issue.assignee?.name ?? null,
+        projectId: issue.project?.id ?? null,
+        projectName: issue.project?.name ?? null,
+        stateId: issue.state.id,
+        stateName: issue.state.name,
+        statePosition: issue.state.position,
+        url: issue.url ?? null,
+        createdAt: issue.createdAt,
+        updatedAt: issue.updatedAt,
+      })),
+    )
+
+    const newestIssueTimestamp =
+      issues.length > 0
+        ? issues.reduce(
+            (latest, issue) => (issue.updatedAt > latest ? issue.updatedAt : latest),
+            issues[0]!.updatedAt,
+          )
+        : meta.lastIssueUpdatedAt
+
+    saveSyncMeta(this.db, {
+      team: { id: team.id, key: team.key, name: team.name },
+      lastSyncAt: new Date().toISOString(),
+      lastIssueUpdatedAt: newestIssueTimestamp ?? new Date().toISOString(),
+    })
+  }
+
+  private resolveTask(idOrRef: string): Task {
+    const task = getCachedTask(this.db, idOrRef)
+    if (!task) {
+      throw new KanbanError(ErrorCode.TASK_NOT_FOUND, `No task with id '${idOrRef}'`)
+    }
+    return task
+  }
+
+  private resolveState(column: string): Column {
+    const states = getCachedColumns(this.db)
+    const match = states.find(
+      (state) => state.id === column || state.name.toLowerCase() === column.toLowerCase(),
+    )
+    if (!match) {
+      throw new KanbanError(
+        ErrorCode.COLUMN_NOT_FOUND,
+        `No Linear workflow state matching '${column}'`,
+      )
+    }
+    return match
+  }
+
+  private resolveAssigneeId(name?: string): string | undefined {
+    if (!name) return undefined
+    const row = this.db
+      .query('SELECT id FROM linear_users WHERE LOWER(name) = LOWER($name) LIMIT 1')
+      .get({ $name: name }) as { id: string } | null
+    return row?.id
+  }
+
+  private resolveProjectId(name?: string): string | undefined {
+    if (!name) return undefined
+    const row = this.db
+      .query('SELECT id FROM linear_projects WHERE LOWER(name) = LOWER($name) LIMIT 1')
+      .get({ $name: name }) as { id: string } | null
+    return row?.id
+  }
+
+  async getContext(): Promise<ProviderContext> {
+    await this.sync()
+    const meta = loadSyncMeta(this.db)
+    return {
+      provider: 'linear',
+      capabilities: LINEAR_CAPABILITIES,
+      team: meta.team,
+    }
+  }
+
+  async getBootstrap(): Promise<BoardBootstrap> {
+    await this.sync()
+    return {
+      provider: 'linear',
+      capabilities: LINEAR_CAPABILITIES,
+      board: getCachedBoard(this.db),
+      config: getCachedConfig(this.db),
+      metrics: null,
+      activity: [],
+      team: loadSyncMeta(this.db).team,
+    }
+  }
+
+  async getBoard() {
+    await this.sync()
+    return getCachedBoard(this.db)
+  }
+
+  async listColumns() {
+    await this.sync()
+    return getCachedColumns(this.db)
+  }
+
+  async listTasks(filters: TaskListFilters = {}) {
+    await this.sync()
+    let tasks = getCachedTasks(this.db)
+    if (filters.column) {
+      const column = this.resolveState(filters.column)
+      tasks = tasks.filter((task) => task.column_id === column.id)
+    }
+    if (filters.priority) tasks = tasks.filter((task) => task.priority === filters.priority)
+    if (filters.assignee) tasks = tasks.filter((task) => task.assignee === filters.assignee)
+    if (filters.project) tasks = tasks.filter((task) => task.project === filters.project)
+    if (filters.sort === 'title') tasks = [...tasks].sort((a, b) => a.title.localeCompare(b.title))
+    if (filters.sort === 'updated')
+      tasks = [...tasks].sort((a, b) => b.updated_at.localeCompare(a.updated_at))
+    if (filters.limit) tasks = tasks.slice(0, filters.limit)
+    return tasks
+  }
+
+  async getTask(idOrRef: string) {
+    await this.sync()
+    return this.resolveTask(idOrRef)
+  }
+
+  async createTask(input: CreateTaskInput) {
+    await this.sync()
+    const state = input.column ? this.resolveState(input.column) : undefined
+    const result = await this.client.createIssue({
+      teamId: this.teamId,
+      stateId: state?.id,
+      title: input.title,
+      description: input.description,
+      priority: toLinearPriority(input.priority),
+      assigneeId: this.resolveAssigneeId(input.assignee),
+      projectId: this.resolveProjectId(input.project),
+    })
+    if (!result.success || !result.issue) {
+      throw new KanbanError(ErrorCode.PROVIDER_UPSTREAM_ERROR, 'Linear issue creation failed')
+    }
+    const issue = result.issue
+    upsertIssues(this.db, [
+      {
+        id: issue.id,
+        identifier: issue.identifier,
+        title: issue.title,
+        description: issue.description ?? '',
+        priority: issue.priority ?? 0,
+        assigneeId: issue.assignee?.id ?? null,
+        assigneeName: issue.assignee?.name ?? issue.assignee?.displayName ?? '',
+        projectId: issue.project?.id ?? null,
+        projectName: issue.project?.name ?? '',
+        stateId: issue.state.id,
+        stateName: issue.state.name,
+        statePosition: issue.state.position,
+        url: issue.url ?? null,
+        createdAt: issue.createdAt,
+        updatedAt: issue.updatedAt,
+      },
+    ])
+    return this.resolveTask(issue.id)
+  }
+
+  async updateTask(idOrRef: string, input: UpdateTaskInput) {
+    await this.sync()
+    const task = this.resolveTask(idOrRef)
+    const updateInput: Record<string, unknown> = {}
+    if (input.title !== undefined) updateInput['title'] = input.title
+    if (input.description !== undefined) updateInput['description'] = input.description
+    if (input.priority !== undefined) updateInput['priority'] = toLinearPriority(input.priority)
+    if (input.assignee !== undefined)
+      updateInput['assigneeId'] = this.resolveAssigneeId(input.assignee) ?? null
+    if (input.project !== undefined)
+      updateInput['projectId'] = this.resolveProjectId(input.project) ?? null
+    if (input.metadata !== undefined) {
+      unsupportedOperation('Linear mode does not support metadata updates')
+    }
+    const result = await this.client.updateIssue(task.providerId || task.id, updateInput)
+    if (!result.success) {
+      throw new KanbanError(ErrorCode.PROVIDER_UPSTREAM_ERROR, 'Linear issue update failed')
+    }
+    await this.sync(true)
+    return this.resolveTask(task.providerId || task.id)
+  }
+
+  async moveTask(idOrRef: string, column: string) {
+    await this.sync()
+    const task = this.resolveTask(idOrRef)
+    const state = this.resolveState(column)
+    const result = await this.client.updateIssue(task.providerId || task.id, { stateId: state.id })
+    if (!result.success) {
+      throw new KanbanError(ErrorCode.PROVIDER_UPSTREAM_ERROR, 'Linear issue move failed')
+    }
+    await this.sync(true)
+    return this.resolveTask(task.providerId || task.id)
+  }
+
+  async deleteTask(_idOrRef: string): Promise<Task> {
+    unsupportedOperation('Task deletion is not supported in Linear mode')
+  }
+
+  async getActivity(_limit?: number, _taskId?: string): Promise<ActivityEntry[]> {
+    unsupportedOperation('Activity is not available in Linear mode')
+  }
+
+  async getMetrics(): Promise<BoardMetrics> {
+    unsupportedOperation('Metrics are not available in Linear mode')
+  }
+
+  async getConfig(): Promise<BoardConfig> {
+    await this.sync()
+    return getCachedConfig(this.db)
+  }
+
+  async patchConfig(_input: Partial<BoardConfig>): Promise<BoardConfig> {
+    unsupportedOperation('Config mutation is not supported in Linear mode')
+  }
+}