@andypai/agent-kanban 0.6.2 → 0.6.3

package/src/mcp/types.ts

@@ -1,6 +1,6 @@
 import type { ToolAnnotations } from '@modelcontextprotocol/sdk/types.js'
 import type { JsonSchemaType } from '@modelcontextprotocol/sdk/validation'
-import type { TaskComment } from '../types'
+import type { Task, TaskComment } from '../types'
 import type { TrackerMcpError, TrackerMcpErrorCode } from './errors'
 
 export type TrackerMcpAuthResolver<TScope> = (ctx: {
@@ -20,6 +20,17 @@ export interface TrackerMcpPolicy<TScope> {
   ): Promise<void> | void
   canMoveTicket(scope: TScope, ticketId: string, destinationColumn: string): Promise<void> | void
   filterComment?(scope: TScope, comment: TaskComment): Promise<boolean> | boolean
+  /**
+   * Gate the aggregate board read. Throw to deny access to the whole board.
+   * Omit to allow board reads (individual tickets can still be hidden via `filterTask`).
+   */
+  canReadBoard?(scope: TScope): Promise<void> | void
+  /**
+   * Decide whether a single board task is visible to this scope. Return `false`
+   * to drop it from `getBoard`. Without this, the board exposes every ticket,
+   * bypassing per-ticket `canReadTicket` gates.
+   */
+  filterTask?(scope: TScope, task: Task): Promise<boolean> | boolean
 }
 
 export interface TrackerMcpHooks<TScope> {

package/src/metrics-spec.ts

@@ -0,0 +1,87 @@
+import type { ActivityEntry, BoardMetrics } from './types'
+import {
+  type ClassifiableColumn,
+  selectDoneColumnIds,
+  selectInProgressColumnIds,
+} from './column-roles'
+
+// One source of truth for how raw board aggregates become BoardMetrics. The
+// SQLite (metrics.ts) and Postgres (postgres-local.ts) backends each gather the
+// primitive rows with their own dialect, then feed them through this assembler
+// so the derived fields — done/in-progress classification, completion math, and
+// priority ordering — can never drift between backends.
+
+const PRIORITY_RANK: Record<string, number> = { urgent: 0, high: 1, medium: 2, low: 3 }
+
+/** A column plus how many tasks currently sit in it. */
+export interface MetricsColumnCount extends ClassifiableColumn {
+  count: number
+}
+
+export interface MetricsInputs {
+  /** Every column with its live task count, in display (position) order. */
+  columnCounts: MetricsColumnCount[]
+  /** Raw per-priority counts; ordering is normalized here. */
+  priorityCounts: Array<{ priority: string; count: number }>
+  totalTasks: number
+  tasksCreatedThisWeek: number
+  /** Average creation→Done hours, or null when no Done column / no completions. */
+  avgCompletionHours: number | null
+  recentActivity: ActivityEntry[]
+  assignees: string[]
+  projects: string[]
+}
+
+/**
+ * Classify a board's columns into done / in-progress roles. Backends call this
+ * to scope their average-completion SQL (which needs the done column ids before
+ * querying column_time_tracking); assembleBoardMetrics() reclassifies from the
+ * same column set so the two never disagree.
+ */
+export function classifyColumnRoles(columns: ClassifiableColumn[]): {
+  doneColumnIds: string[]
+  inProgressColumnIds: string[]
+} {
+  return {
+    doneColumnIds: selectDoneColumnIds(columns),
+    inProgressColumnIds: selectInProgressColumnIds(columns),
+  }
+}
+
+export function assembleBoardMetrics(inputs: MetricsInputs): BoardMetrics {
+  const { doneColumnIds, inProgressColumnIds } = classifyColumnRoles(inputs.columnCounts)
+  const done = new Set(doneColumnIds)
+  const inProgress = new Set(inProgressColumnIds)
+
+  const tasksByColumn = inputs.columnCounts.map((column) => ({
+    column_name: column.name,
+    count: column.count,
+  }))
+  const completedTasks = inputs.columnCounts
+    .filter((column) => done.has(column.id))
+    .reduce((sum, column) => sum + column.count, 0)
+  const inProgressCount = inputs.columnCounts
+    .filter((column) => inProgress.has(column.id))
+    .reduce((sum, column) => sum + column.count, 0)
+
+  const tasksByPriority = [...inputs.priorityCounts].sort(
+    (a, b) => (PRIORITY_RANK[a.priority] ?? 99) - (PRIORITY_RANK[b.priority] ?? 99),
+  )
+
+  const completionPercent =
+    inputs.totalTasks > 0 ? Math.round((completedTasks / inputs.totalTasks) * 100) : 0
+
+  return {
+    tasksByColumn,
+    tasksByPriority,
+    totalTasks: inputs.totalTasks,
+    completedTasks,
+    avgCompletionHours: inputs.avgCompletionHours,
+    recentActivity: inputs.recentActivity,
+    tasksCreatedThisWeek: inputs.tasksCreatedThisWeek,
+    inProgressCount,
+    completionPercent,
+    assignees: inputs.assignees,
+    projects: inputs.projects,
+  }
+}

package/src/metrics.ts

@@ -1,6 +1,6 @@
 import { Database } from 'bun:sqlite'
 import type { ActivityEntry, BoardMetrics } from './types'
-import { selectDoneColumnIds, selectInProgressColumnIds } from './column-roles'
+import { assembleBoardMetrics, classifyColumnRoles } from './metrics-spec'
 
 function getDistinctTaskFieldValues(db: Database, field: 'assignee' | 'project'): string[] {
   return (
@@ -23,52 +23,34 @@ export function getDiscoveredProjects(db: Database): string[] {
 }
 
 export function getBoardMetrics(db: Database): BoardMetrics {
-  const columnCounts = db
-    .query(
-      `SELECT c.id as id, c.name as column_name, c.position as position, COUNT(t.id) as count
-       FROM columns c LEFT JOIN tasks t ON t.column_id = c.id
-       GROUP BY c.id ORDER BY c.position`,
-    )
-    .all() as { id: string; column_name: string; position: number; count: number }[]
-
-  const tasksByColumn = columnCounts.map((row) => ({
-    column_name: row.column_name,
-    count: row.count,
-  }))
-
-  // Classify columns by role (handles custom names / KANBAN_DEFAULT_COLUMNS)
-  // instead of matching the literal strings 'done' / 'in-progress'.
-  const columns = columnCounts.map((row) => ({
-    id: row.id,
-    name: row.column_name,
-    position: row.position,
-  }))
-  const doneColumnIds = new Set(selectDoneColumnIds(columns))
-  const inProgressColumnIds = new Set(selectInProgressColumnIds(columns))
-
-  const tasksByPriority = db
-    .query(
-      `SELECT priority, COUNT(*) as count FROM tasks
-       GROUP BY priority ORDER BY CASE priority
-         WHEN 'urgent' THEN 0 WHEN 'high' THEN 1
-         WHEN 'medium' THEN 2 WHEN 'low' THEN 3 END`,
-    )
+  const columnCounts = (
+    db
+      .query(
+        `SELECT c.id as id, c.name as name, c.position as position, COUNT(t.id) as count
+         FROM columns c LEFT JOIN tasks t ON t.column_id = c.id
+         GROUP BY c.id ORDER BY c.position`,
+      )
+      .all() as { id: string; name: string; position: number; count: number }[]
+  ).map((row) => ({ id: row.id, name: row.name, position: row.position, count: row.count }))
+
+  // Done/in-progress classification and all derived fields live in metrics-spec;
+  // here we only gather the raw aggregates this backend's SQL produces. The done
+  // ids are needed up front to scope the average-completion query.
+  const { doneColumnIds } = classifyColumnRoles(columnCounts)
+
+  const priorityCounts = db
+    .query(`SELECT priority, COUNT(*) as count FROM tasks GROUP BY priority`)
     .all() as { priority: string; count: number }[]
 
   const totalTasks = getCount(db, 'SELECT COUNT(*) as count FROM tasks')
 
-  const completedTasks = columnCounts
-    .filter((row) => doneColumnIds.has(row.id))
-    .reduce((sum, row) => sum + row.count, 0)
-
   // Average completion time = first time a task was tracked (creation) until the
   // first time it entered a Done column. Measuring the Done *entry* (not exit)
   // means tasks that reach Done and stay there are counted; MIN() over Done rows
-  // handles tasks that re-enter Done. Kept in lockstep with the Postgres copy in
-  // postgres-local.ts:getMetrics — update both together.
-  const donePlaceholders = [...doneColumnIds].map(() => '?').join(', ')
-  const avgResult = (
-    doneColumnIds.size === 0
+  // handles tasks that re-enter Done.
+  const donePlaceholders = doneColumnIds.map(() => '?').join(', ')
+  const avgResult =
+    doneColumnIds.length === 0
       ? { avg_hours: null }
       : (db
           .query(
@@ -87,7 +69,6 @@ export function getBoardMetrics(db: Database): BoardMetrics {
        ) first_enter ON first_enter.task_id = done_enter.task_id`,
           )
           .get(...doneColumnIds) as { avg_hours: number | null })
-  ) as { avg_hours: number | null }
 
   const recentActivity = db
     .query('SELECT * FROM activity_log ORDER BY timestamp DESC, rowid DESC LIMIT 20')
@@ -98,26 +79,14 @@ export function getBoardMetrics(db: Database): BoardMetrics {
     "SELECT COUNT(*) as count FROM tasks WHERE created_at >= datetime('now', '-7 days')",
   )
 
-  const inProgressCount = columnCounts
-    .filter((row) => inProgressColumnIds.has(row.id))
-    .reduce((sum, row) => sum + row.count, 0)
-
-  const completionPercent = totalTasks > 0 ? Math.round((completedTasks / totalTasks) * 100) : 0
-
-  const assignees = getDiscoveredAssignees(db)
-  const projects = getDiscoveredProjects(db)
-
-  return {
-    tasksByColumn,
-    tasksByPriority,
+  return assembleBoardMetrics({
+    columnCounts,
+    priorityCounts,
     totalTasks,
-    completedTasks,
+    tasksCreatedThisWeek,
     avgCompletionHours: avgResult.avg_hours,
     recentActivity,
-    tasksCreatedThisWeek,
-    inProgressCount,
-    completionPercent,
-    assignees,
-    projects,
-  }
+    assignees: getDiscoveredAssignees(db),
+    projects: getDiscoveredProjects(db),
+  })
 }

package/src/providers/capabilities.ts

@@ -25,6 +25,18 @@ export const LOCAL_CAPABILITIES: ProviderCapabilities = capabilities({
   configEdit: true,
 })
 
+// Postgres-local shares most local capabilities, but board administration
+// (column CRUD, bulk ops) and config editing have no Postgres provider path —
+// the CLI implements column/bulk against a raw SQLite Database and blocks them
+// under KANBAN_STORAGE=postgres. Advertise that honestly so clients don't offer
+// operations the provider can't perform.
+export const POSTGRES_LOCAL_CAPABILITIES: ProviderCapabilities = {
+  ...LOCAL_CAPABILITIES,
+  columnCrud: false,
+  bulk: false,
+  configEdit: false,
+}
+
 export const LINEAR_CAPABILITIES: ProviderCapabilities = capabilities()
 
 export const JIRA_CAPABILITIES: ProviderCapabilities = capabilities()

package/src/providers/linear-client.ts

@@ -33,6 +33,7 @@ export interface LinearIssue {
   state: { id: string; name: string; position: number }
   labels?: string[]
   commentCount?: number
+  teamId?: string | null
 }
 
 export interface LinearComment {
@@ -65,6 +66,7 @@ interface LinearIssueNode {
     nodes: Array<{ id: string }>
     pageInfo?: { hasNextPage: boolean; endCursor: string | null }
   } | null
+  team?: { id: string } | null
 }
 
 interface LinearCommentNode {
@@ -86,6 +88,7 @@ function toLinearIssue(node: LinearIssueNode): LinearIssue {
       : null,
     labels: node.labels?.nodes.map((label) => label.name) ?? [],
     commentCount: node.comments?.nodes?.length ?? undefined,
+    teamId: node.team?.id ?? null,
   }
 }
 
@@ -97,6 +100,30 @@ const COMMENT_FIELDS = `
   user { id name displayName }
 `
 
+// Shared selection set for an issue node, used by listIssues, createIssue, and
+// getIssue so a single-issue hydrate returns exactly the same shape the bulk
+// sync caches. The inline comments page is id-only and capped; callers that
+// need an accurate count follow up via countIssueComments when hasNextPage.
+const ISSUE_NODE_FIELDS = `
+  id
+  identifier
+  title
+  description
+  priority
+  url
+  createdAt
+  updatedAt
+  assignee { id name displayName }
+  project { id name url state }
+  state { id name position }
+  labels { nodes { id name } }
+  comments(first: 250) {
+    nodes { id }
+    pageInfo { hasNextPage endCursor }
+  }
+  team { id }
+`
+
 export class LinearClient {
   private readonly endpoint = 'https://api.linear.app/graphql'
 
@@ -183,58 +210,80 @@ export class LinearClient {
   }
 
   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
+    type UserNode = {
+      id: string
+      name?: string | null
+      displayName?: string | null
+      active?: boolean | null
+    }
+    let after: string | null = null
+    const users: Array<{ id: string; name: string; active?: boolean }> = []
+
+    do {
+      const data: { users: { nodes: UserNode[]; pageInfo: PageInfo } } = await this.query(
+        `
+          query Users($after: String) {
+            users(first: 100, after: $after) {
+              nodes {
+                id
+                name
+                displayName
+                active
+              }
+              pageInfo {
+                hasNextPage
+                endCursor
+              }
             }
           }
-        }
-      `,
-    )
-    return data.users.nodes.map((user) => ({
-      id: user.id,
-      name: user.displayName || user.name || user.id,
-      active: user.active ?? true,
-    }))
+        `,
+        { after },
+      )
+      for (const user of data.users.nodes) {
+        users.push({
+          id: user.id,
+          name: user.displayName || user.name || user.id,
+          active: user.active ?? true,
+        })
+      }
+      after = data.users.pageInfo.hasNextPage ? data.users.pageInfo.endCursor : null
+    } while (after)
+
+    return users
   }
 
   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
+    type ProjectNode = { id: string; name: string; url?: string | null; state?: string | null }
+    let after: string | null = null
+    const projects: ProjectNode[] = []
+
+    do {
+      const data: { projects: { nodes: ProjectNode[]; pageInfo: PageInfo } } = await this.query(
+        `
+          query Projects($after: String) {
+            projects(first: 100, after: $after) {
+              nodes {
+                id
+                name
+                url
+                state
+              }
+              pageInfo {
+                hasNextPage
+                endCursor
+              }
             }
           }
-        }
-      `,
-    )
-    return data.projects.nodes
+        `,
+        { after },
+      )
+      projects.push(...data.projects.nodes)
+      after = data.projects.pageInfo.hasNextPage ? data.projects.pageInfo.endCursor : null
+    } while (after)
+
+    return projects
   }
 
   async listIssueLabels(): Promise<LinearIssueLabel[]> {
@@ -293,39 +342,7 @@ export class LinearClient {
                 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
-                }
-                labels {
-                  nodes { id name }
-                }
-                comments(first: 250) {
-                  nodes { id }
-                  pageInfo { hasNextPage endCursor }
-                }
-              }
+              nodes { ${ISSUE_NODE_FIELDS} }
               pageInfo {
                 hasNextPage
                 endCursor
@@ -335,13 +352,90 @@ export class LinearClient {
         `,
         { teamId, after, updatedAfter: updatedAfter ?? '1970-01-01T00:00:00.000Z' },
       )
-      issues.push(...data.issues.nodes.map(toLinearIssue))
+      const pageIssues = data.issues.nodes.map(toLinearIssue)
+      // Linear connections expose no totalCount, and the inline comments page is
+      // capped at 250. When an issue has more, the loaded length undercounts, so
+      // continue paging the (id-only) comment cursor to get an accurate count
+      // instead of advertising a partial page length as the total.
+      await Promise.all(
+        data.issues.nodes.map(async (node, index) => {
+          const info = node.comments?.pageInfo
+          if (info?.hasNextPage && info.endCursor) {
+            pageIssues[index]!.commentCount = await this.countIssueComments(
+              node.id,
+              info.endCursor,
+              node.comments?.nodes?.length ?? 0,
+            )
+          }
+        }),
+      )
+      issues.push(...pageIssues)
       after = data.issues.pageInfo.hasNextPage ? data.issues.pageInfo.endCursor : null
     } while (after)
 
     return issues
   }
 
+  // Continue paging an issue's comment cursor (id-only) to count comments beyond
+  // the inline first page. Only invoked when the first page reported hasNextPage.
+  private async countIssueComments(
+    issueId: string,
+    startCursor: string,
+    loaded: number,
+  ): Promise<number> {
+    let count = loaded
+    let after: string | null = startCursor
+
+    while (after) {
+      const data: {
+        issue: { comments: { nodes: Array<{ id: string }>; pageInfo: PageInfo } } | null
+      } = await this.query(
+        `
+          query IssueCommentCount($id: String!, $after: String) {
+            issue(id: $id) {
+              comments(first: 250, after: $after) {
+                nodes { id }
+                pageInfo { hasNextPage endCursor }
+              }
+            }
+          }
+        `,
+        { id: issueId, after },
+      )
+      const comments = data.issue?.comments
+      if (!comments) break
+      count += comments.nodes.length
+      after = comments.pageInfo.hasNextPage ? comments.pageInfo.endCursor : null
+    }
+
+    return count
+  }
+
+  // Fetch a single issue with the same selection set as the bulk sync so a
+  // read-after-write hydrate can refresh one cache row without a full team
+  // reconcile. Returns null when the issue no longer exists.
+  async getIssue(issueId: string): Promise<LinearIssue | null> {
+    const data = await this.query<{ issue: LinearIssueNode | null }>(
+      `
+        query IssueById($id: String!) {
+          issue(id: $id) { ${ISSUE_NODE_FIELDS} }
+        }
+      `,
+      { id: issueId },
+    )
+    if (!data.issue) return null
+    const issue = toLinearIssue(data.issue)
+    const info = data.issue.comments?.pageInfo
+    if (info?.hasNextPage && info.endCursor) {
+      issue.commentCount = await this.countIssueComments(
+        data.issue.id,
+        info.endCursor,
+        data.issue.comments?.nodes?.length ?? 0,
+      )
+    }
+    return issue
+  }
+
   async createIssue(input: {
     teamId: string
     stateId?: string
@@ -359,24 +453,7 @@ export class LinearClient {
         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 }
-              labels { nodes { id name } }
-              comments(first: 250) {
-                nodes { id }
-                pageInfo { hasNextPage endCursor }
-              }
-            }
+            issue { ${ISSUE_NODE_FIELDS} }
           }
         }
       `,