@andypai/agent-kanban 0.5.1 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andypai/agent-kanban",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "Agent-friendly kanban board CLI. Manage tasks via bash commands, parse structured JSON output.",
   "homepage": "https://github.com/abpai/agent-kanban#readme",
   "repository": {

package/src/__tests__/jira-client.test.ts

@@ -1,7 +1,8 @@
 import { afterEach, describe, expect, test } from 'bun:test'
 import { Buffer } from 'node:buffer'
 import { ErrorCode, KanbanError } from '../errors'
-import { JiraClient } from '../providers/jira-client'
+import { JiraClient, decideJiraPagination } from '../providers/jira-client'
+import type { JiraIssue } from '../providers/jira-client'
 
 const origFetch = globalThis.fetch
 let lastRequest: { url: string; init?: RequestInit } | null = null
@@ -167,3 +168,99 @@ describe('JiraClient', () => {
     expect(sentBody).toContain('"transition":{"id":"11"}')
   })
 })
+
+describe('decideJiraPagination', () => {
+  const MAX = 100
+  // Only issues.length matters to the decision; build a right-sized stub array.
+  const issuesOfLength = (n: number): JiraIssue[] =>
+    Array.from({ length: n }, () => ({})) as unknown as JiraIssue[]
+
+  test('isLast=false with a fresh cursor advances', () => {
+    const d = decideJiraPagination(
+      { isLast: false, nextPageToken: 'p2', issues: issuesOfLength(MAX) },
+      new Set(),
+    )
+    expect(d).toEqual({ nextToken: 'p2', complete: false })
+  })
+
+  test('isLast=true is a definitive complete end even if a token is present', () => {
+    const d = decideJiraPagination(
+      { isLast: true, nextPageToken: 'p2', issues: issuesOfLength(MAX) },
+      new Set(),
+    )
+    expect(d).toEqual({ complete: true })
+  })
+
+  test('isLast=false with no cursor is incomplete (server claims more but gave no way to fetch)', () => {
+    const d = decideJiraPagination({ isLast: false, issues: issuesOfLength(MAX) }, new Set())
+    expect(d).toEqual({ complete: false })
+  })
+
+  test('isLast=false with a repeated cursor is incomplete (stalled, not a false complete)', () => {
+    const d = decideJiraPagination(
+      { isLast: false, nextPageToken: 'seen', issues: issuesOfLength(MAX) },
+      new Set(['seen']),
+    )
+    expect(d).toEqual({ complete: false })
+  })
+
+  test('isLast absent: a full page with a fresh cursor advances', () => {
+    const d = decideJiraPagination({ nextPageToken: 'p2', issues: issuesOfLength(MAX) }, new Set())
+    expect(d).toEqual({ nextToken: 'p2', complete: false })
+  })
+
+  // No completeness signal (no isLast, no total, no usable cursor): the scan is
+  // treated as incomplete REGARDLESS of page size. Guessing "complete" from a
+  // short/empty page would prune the entire cache on a full reconcile when a
+  // server returns a degraded response.
+  test('isLast absent: a full page with no cursor is incomplete (no completeness proof)', () => {
+    const d = decideJiraPagination({ issues: issuesOfLength(MAX) }, new Set())
+    expect(d).toEqual({ complete: false })
+  })
+
+  test('isLast absent: a short page with no cursor is incomplete (no completeness proof)', () => {
+    const d = decideJiraPagination({ issues: issuesOfLength(MAX - 1) }, new Set())
+    expect(d).toEqual({ complete: false })
+  })
+
+  test('isLast absent: an empty page is incomplete (a degraded {issues:[]} must not prune)', () => {
+    const d = decideJiraPagination({ issues: [] }, new Set())
+    expect(d).toEqual({ complete: false })
+  })
+
+  test('isLast absent: a repeated (stalled) cursor is incomplete', () => {
+    const d = decideJiraPagination(
+      { nextPageToken: 'seen', issues: issuesOfLength(1) },
+      new Set(['seen']),
+    )
+    expect(d).toEqual({ complete: false })
+  })
+
+  // Legacy total/startAt awareness: the live /search/jql endpoint omits `total`,
+  // but a non-standard or mock server may supply it without a cursor. When it
+  // does, completeness is proven by total/startAt rather than page size, so a
+  // full *last* page (the whole result set) is not misread as "more remain".
+  test('isLast absent: total present, full last page is complete', () => {
+    const d = decideJiraPagination(
+      { issues: issuesOfLength(MAX), total: MAX, startAt: 0 },
+      new Set(),
+    )
+    expect(d).toEqual({ complete: true })
+  })
+
+  test('isLast absent: total present, full non-last page is incomplete', () => {
+    const d = decideJiraPagination(
+      { issues: issuesOfLength(MAX), total: MAX * 3, startAt: 0 },
+      new Set(),
+    )
+    expect(d).toEqual({ complete: false })
+  })
+
+  test('isLast absent: total present, final offset page reaching total is complete', () => {
+    const d = decideJiraPagination(
+      { issues: issuesOfLength(MAX), total: MAX * 2, startAt: MAX },
+      new Set(),
+    )
+    expect(d).toEqual({ complete: true })
+  })
+})

package/src/__tests__/jira-provider-mutations.test.ts

@@ -194,6 +194,19 @@ function standardSyncRoutes(opts: SyncRoutesOpts): StubRoute[] {
       match: (u) => u.includes('/rest/api/3/issuetype/project'),
       handler: () => jsonResponse(opts.issueTypes ?? []),
     },
+    {
+      // GET /rest/api/3/issue/{key} backs hydrateIssueByKey's read-after-write.
+      // Serves the post-mutation issue from the same pool as /search so tests
+      // that push a created/updated issue into `opts.issues` see it here too.
+      match: (u, init) =>
+        /\/rest\/api\/3\/issue\/[A-Z]+-\d+$/.test(new URL(u).pathname) &&
+        (init?.method ?? 'GET') === 'GET',
+      handler: (u) => {
+        const key = new URL(u).pathname.split('/').pop()!
+        const found = (opts.issues ?? []).find((iss) => (iss as { key?: string }).key === key)
+        return found ? jsonResponse(found) : jsonResponse({ errorMessages: ['not found'] }, 404)
+      },
+    },
     {
       match: (u) => u.includes('/rest/api/3/search/jql'),
       handler: () =>
@@ -298,16 +311,16 @@ function fullSyncRoutes(extraIssues: Record<string, unknown>[] = []): StubRoute[
 describe('JiraProvider mutations', () => {
   test('createTask happy path: plainTextToAdf invoked, priority mapped, assignee and issueType resolved', async () => {
     fullSeed(db)
-    // Shared state so the POST /issue handler appends the created issue, which
-    // the subsequent sync(true)'s /search handler then returns so getCachedTask
-    // finds it after the post-mutation sync.
-    const createdIssues: Record<string, unknown>[] = []
+    // Shared issue pool: the POST /issue handler appends the created issue, which
+    // hydrateIssueByKey then reads back through the GET /issue/{key} route so the
+    // returned task reflects the create.
     const createdIssue = makeJiraIssueFixture({
       id: '600',
       key: 'ENG-10',
       statusId: '20000',
       summary: 'Fix',
     })
+    const issues: Record<string, unknown>[] = [makeJiraIssueFixture(seedIssues[0]!)]
     const syncRoutes: StubRoute[] = standardSyncRoutes({
       projectKey: 'ENG',
       columns: [
@@ -317,28 +330,12 @@ describe('JiraProvider mutations', () => {
       users: seedUsers,
       priorities: seedPriorities,
       issueTypes: seedIssueTypes,
-      issues: [makeJiraIssueFixture(seedIssues[0]!)],
+      issues,
     })
-    // Replace the /search route to include createdIssues dynamically.
-    const searchRouteIndex = syncRoutes.findIndex((r) =>
-      r.match('https://example.atlassian.net/rest/api/3/search/jql'),
-    )
-    syncRoutes[searchRouteIndex] = {
-      match: (u) => u.includes('/rest/api/3/search/jql'),
-      handler: () => {
-        const all = [makeJiraIssueFixture(seedIssues[0]!), ...createdIssues]
-        return jsonResponse({
-          startAt: 0,
-          maxResults: 100,
-          total: all.length,
-          issues: all,
-        })
-      },
-    }
     const mutationRoute: StubRoute = {
       match: (u, init) => u.endsWith('/rest/api/3/issue') && (init?.method ?? 'GET') === 'POST',
       handler: () => {
-        createdIssues.push(createdIssue)
+        issues.push(createdIssue)
         return jsonResponse({
           id: '600',
           key: 'ENG-10',
@@ -483,6 +480,62 @@ describe('JiraProvider mutations', () => {
     expect(body.transition.id).toBe('21')
   })
 
+  test('moveTask ingests the moved issue changelog via hydration (activity recorded immediately)', async () => {
+    // seedCache sets a recent lastSyncAt, so moveTask's pre-move sync() is
+    // throttled and fetches no changelog. The only changelog call must therefore
+    // come from hydrateIssueByKey's read-after-write — proving the transition
+    // lands in jira_activity immediately rather than waiting for a later sync.
+    seedCache(db, {
+      priorities: seedPriorities,
+      users: seedUsers,
+      issueTypes: seedIssueTypes,
+      columns: seedColumns,
+      issues: [{ id: '501', key: 'ENG-1', statusId: '20000' }],
+      projectKey: 'ENG',
+    })
+    const syncRoutes = fullSyncRoutes()
+    let changelogCalls = 0
+    const changelogRoute: StubRoute = {
+      match: (u) => /\/rest\/api\/3\/issue\/501\/changelog/.test(new URL(u).pathname),
+      handler: () => {
+        changelogCalls += 1
+        return jsonResponse({
+          values: [
+            {
+              id: 'h1',
+              created: '2026-01-06T00:00:00Z',
+              items: [{ field: 'status', from: '20000', to: '10001' }],
+            },
+          ],
+        })
+      },
+    }
+    const transitionsRoute: StubRoute = {
+      match: (u, init) =>
+        u.endsWith('/rest/api/3/issue/ENG-1/transitions') && (init?.method ?? 'GET') === 'GET',
+      handler: () =>
+        jsonResponse({
+          transitions: [{ id: '21', name: 'Done', to: { id: '10001', name: 'Done' } }],
+        }),
+    }
+    const postTransitionRoute: StubRoute = {
+      match: (u, init) =>
+        u.endsWith('/rest/api/3/issue/ENG-1/transitions') && (init?.method ?? 'GET') === 'POST',
+      handler: () => emptyResponse(204),
+    }
+    const { provider } = makeProvider(db, [
+      changelogRoute,
+      transitionsRoute,
+      postTransitionRoute,
+      ...syncRoutes,
+    ])
+    await provider.moveTask('ENG-1', 'Done')
+
+    expect(changelogCalls).toBe(1)
+    const activity = await provider.getActivity(50, 'jira:501')
+    expect(activity.length).toBeGreaterThan(0)
+  })
+
   test('moveTask no-match failure: error message names target and lists available transitions', async () => {
     seedCache(db, {
       priorities: seedPriorities,
@@ -492,7 +545,9 @@ describe('JiraProvider mutations', () => {
       issues: [{ id: '501', key: 'ENG-1', statusId: '20000' }],
       projectKey: 'ENG',
     })
-    // No standard sync routes — the mutation throws before sync(true).
+    // No standard sync/hydrate routes needed: the move resolves against the
+    // seeded cache and throws at transition resolution (no transition reaches the
+    // target status) before any read-after-write hydration runs.
     const transitionsRoute: StubRoute = {
       match: (u, init) =>
         u.endsWith('/rest/api/3/issue/ENG-1/transitions') && (init?.method ?? 'GET') === 'GET',
@@ -652,13 +707,13 @@ describe('JiraProvider mutations', () => {
 
   test('createTask project field omitted is accepted', async () => {
     fullSeed(db)
-    const createdIssues: Record<string, unknown>[] = []
     const createdIssue = makeJiraIssueFixture({
       id: '600',
       key: 'ENG-10',
       statusId: '20000',
       summary: 'x',
     })
+    const issues: Record<string, unknown>[] = [makeJiraIssueFixture(seedIssues[0]!)]
     const syncRoutes = standardSyncRoutes({
       projectKey: 'ENG',
       columns: [
@@ -668,27 +723,12 @@ describe('JiraProvider mutations', () => {
       users: seedUsers,
       priorities: seedPriorities,
       issueTypes: seedIssueTypes,
-      issues: [makeJiraIssueFixture(seedIssues[0]!)],
+      issues,
     })
-    const searchIdx = syncRoutes.findIndex((r) =>
-      r.match('https://example.atlassian.net/rest/api/3/search/jql'),
-    )
-    syncRoutes[searchIdx] = {
-      match: (u) => u.includes('/rest/api/3/search/jql'),
-      handler: () => {
-        const all = [makeJiraIssueFixture(seedIssues[0]!), ...createdIssues]
-        return jsonResponse({
-          startAt: 0,
-          maxResults: 100,
-          total: all.length,
-          issues: all,
-        })
-      },
-    }
     const mutationRoute: StubRoute = {
       match: (u, init) => u.endsWith('/rest/api/3/issue') && (init?.method ?? 'GET') === 'POST',
       handler: () => {
-        createdIssues.push(createdIssue)
+        issues.push(createdIssue)
         return jsonResponse({ id: '600', key: 'ENG-10', self: 'x' })
       },
     }
@@ -706,13 +746,13 @@ describe('JiraProvider mutations', () => {
 
   test('createTask project field matching configured projectKey is accepted', async () => {
     fullSeed(db)
-    const createdIssues: Record<string, unknown>[] = []
     const createdIssue = makeJiraIssueFixture({
       id: '601',
       key: 'ENG-11',
       statusId: '20000',
       summary: 'x',
     })
+    const issues: Record<string, unknown>[] = [makeJiraIssueFixture(seedIssues[0]!)]
     const syncRoutes = standardSyncRoutes({
       projectKey: 'ENG',
       columns: [
@@ -722,27 +762,12 @@ describe('JiraProvider mutations', () => {
       users: seedUsers,
       priorities: seedPriorities,
       issueTypes: seedIssueTypes,
-      issues: [makeJiraIssueFixture(seedIssues[0]!)],
+      issues,
     })
-    const searchIdx = syncRoutes.findIndex((r) =>
-      r.match('https://example.atlassian.net/rest/api/3/search/jql'),
-    )
-    syncRoutes[searchIdx] = {
-      match: (u) => u.includes('/rest/api/3/search/jql'),
-      handler: () => {
-        const all = [makeJiraIssueFixture(seedIssues[0]!), ...createdIssues]
-        return jsonResponse({
-          startAt: 0,
-          maxResults: 100,
-          total: all.length,
-          issues: all,
-        })
-      },
-    }
     const mutationRoute: StubRoute = {
       match: (u, init) => u.endsWith('/rest/api/3/issue') && (init?.method ?? 'GET') === 'POST',
       handler: () => {
-        createdIssues.push(createdIssue)
+        issues.push(createdIssue)
         return jsonResponse({ id: '601', key: 'ENG-11', self: 'x' })
       },
     }

package/src/__tests__/jira-provider-read.test.ts

@@ -331,6 +331,85 @@ describe('JiraProvider read path', () => {
     )
   })
 
+  test('sync follows the nextPageToken cursor across pages when total is omitted', async () => {
+    // /rest/api/3/search/jql omits `total` and paginates by an opaque
+    // nextPageToken. The previous offset/total loop stopped after page 1 once
+    // `total` came back undefined, so every issue beyond the first 100 (by
+    // updated ASC) — including newly-created tickets — was silently dropped.
+    const requestedTokens: Array<string | null> = []
+    const searchHandler: StubHandler = (url) => {
+      const token = new URL(url).searchParams.get('nextPageToken')
+      requestedTokens.push(token)
+      if (token === null) {
+        return jsonResponse({
+          nextPageToken: 'page-2',
+          isLast: false,
+          issues: [makeIssue({ id: '1', key: 'ENG-1', statusId: '10001' })],
+        })
+      }
+      if (token === 'page-2') {
+        return jsonResponse({
+          isLast: true,
+          issues: [makeIssue({ id: '2', key: 'ENG-2', statusId: '10002' })],
+        })
+      }
+      return jsonResponse({ isLast: true, issues: [] })
+    }
+    const { provider } = makeProviderWithBoard(standardRoutes({ searchHandler }), 3)
+    await provider.getBoard()
+
+    // Both pages land in the cache, not just page 1.
+    expect(
+      getCachedTasks(db)
+        .map((task) => task.externalRef)
+        .sort(),
+    ).toEqual(['ENG-1', 'ENG-2'])
+    // Page 1 sends no cursor; page 2 follows the returned token; then it stops.
+    expect(requestedTokens).toEqual([null, 'page-2'])
+  })
+
+  test('sync does not drop a page when an intermediate page is empty but carries a token', async () => {
+    // A non-last page may legitimately return zero issues alongside a cursor;
+    // the loop must follow the token rather than treat the empty page as the end.
+    const searchHandler: StubHandler = (url) => {
+      const token = new URL(url).searchParams.get('nextPageToken')
+      if (token === null) {
+        return jsonResponse({ nextPageToken: 'page-2', isLast: false, issues: [] })
+      }
+      return jsonResponse({
+        isLast: true,
+        issues: [makeIssue({ id: '2', key: 'ENG-2', statusId: '10002' })],
+      })
+    }
+    const { provider } = makeProviderWithBoard(standardRoutes({ searchHandler }), 3)
+    await provider.getBoard()
+    expect(getCachedTasks(db).map((task) => task.externalRef)).toEqual(['ENG-2'])
+  })
+
+  test('sync terminates instead of spinning when the server repeats a cursor token', async () => {
+    // A misbehaving server that keeps handing back the same non-last token would
+    // otherwise loop forever and hang the poll cycle; the seen-token guard stops
+    // after the cursor fails to advance, without dropping the page it did return.
+    let call = 0
+    const searchHandler: StubHandler = () => {
+      call += 1
+      return jsonResponse({
+        nextPageToken: 'stuck',
+        isLast: false,
+        issues: [makeIssue({ id: String(call), key: `ENG-${call}`, statusId: '10001' })],
+      })
+    }
+    const { provider } = makeProviderWithBoard(standardRoutes({ searchHandler }), 3)
+    await provider.getBoard()
+    // Two fetches: the first records token 'stuck', the second sees it repeat and breaks.
+    expect(call).toBe(2)
+    expect(
+      getCachedTasks(db)
+        .map((task) => task.externalRef)
+        .sort(),
+    ).toEqual(['ENG-1', 'ENG-2'])
+  })
+
   test('periodic full reconciliation prunes cached issues missing upstream', async () => {
     const capturedJql: string[] = []
     let searchCalls = 0
@@ -400,6 +479,91 @@ describe('JiraProvider read path', () => {
     expect(getCachedTasks(db).map((task) => task.externalRef)).toEqual(['ENG-1'])
   })
 
+  test('full reconcile with a stalled cursor does not prune issues from the unfetched pages', async () => {
+    // If the cursor stalls (a repeated non-last token) mid-scan, seenIssueIds is
+    // only partial. Pruning against it would delete issues that exist upstream on
+    // pages we never fetched, so an incomplete scan must not prune.
+    let stalled = false
+    const searchHandler: StubHandler = () => {
+      if (!stalled) {
+        // First full reconcile: a clean single terminal page with both issues.
+        return jsonResponse({
+          isLast: true,
+          issues: [
+            makeIssue({ id: '1', key: 'ENG-1', statusId: '10001' }),
+            makeIssue({ id: '2', key: 'ENG-2', statusId: '10001' }),
+          ],
+        })
+      }
+      // Later full reconcile: the cursor stalls after returning only ENG-1, so
+      // ENG-2's page is never reached.
+      return jsonResponse({
+        nextPageToken: 'stuck',
+        isLast: false,
+        issues: [makeIssue({ id: '1', key: 'ENG-1', statusId: '10001' })],
+      })
+    }
+    const { provider } = makeProviderWithBoard(standardRoutes({ searchHandler }), 3)
+    const baseNow = originalDateNow()
+
+    Date.now = () => baseNow
+    await provider.getBoard()
+    expect(
+      getCachedTasks(db)
+        .map((task) => task.externalRef)
+        .sort(),
+    ).toEqual(['ENG-1', 'ENG-2'])
+
+    // Next full reconcile (past the interval) hits the stalled cursor.
+    stalled = true
+    Date.now = () => baseNow + 5 * 60_000 + 31_000
+    await provider.getBoard()
+
+    // ENG-2 must survive: the incomplete scan is not authoritative for pruning.
+    expect(
+      getCachedTasks(db)
+        .map((task) => task.externalRef)
+        .sort(),
+    ).toEqual(['ENG-1', 'ENG-2'])
+  })
+
+  test('full reconcile does not prune when the server reports isLast=false but omits a cursor', async () => {
+    // A server can contradict itself: claim more pages (isLast=false) while giving
+    // no nextPageToken. That must be treated as an incomplete scan, not a complete
+    // one, so a partial result never prunes issues that still exist upstream.
+    let degraded = false
+    const searchHandler: StubHandler = () => {
+      if (!degraded) {
+        return jsonResponse({
+          isLast: true,
+          issues: [
+            makeIssue({ id: '1', key: 'ENG-1', statusId: '10001' }),
+            makeIssue({ id: '2', key: 'ENG-2', statusId: '10001' }),
+          ],
+        })
+      }
+      return jsonResponse({
+        isLast: false,
+        issues: [makeIssue({ id: '1', key: 'ENG-1', statusId: '10001' })],
+      })
+    }
+    const { provider } = makeProviderWithBoard(standardRoutes({ searchHandler }), 3)
+    const baseNow = originalDateNow()
+
+    Date.now = () => baseNow
+    await provider.getBoard()
+
+    degraded = true
+    Date.now = () => baseNow + 5 * 60_000 + 31_000
+    await provider.getBoard()
+
+    expect(
+      getCachedTasks(db)
+        .map((task) => task.externalRef)
+        .sort(),
+    ).toEqual(['ENG-1', 'ENG-2'])
+  })
+
   test('listTasks filters by columnId with many-to-one mapping', async () => {
     const { provider } = makeProvider(standardRoutes({}))
     // Sync first (populates statuses-based columns)
@@ -628,7 +792,7 @@ describe('JiraProvider read path', () => {
   })
 
   test('sync paginates listIssues across multiple pages', async () => {
-    const searchCalls: Array<{ startAt: number }> = []
+    const searchCalls: Array<{ token: string | null }> = []
     const page1Issues = Array.from({ length: 100 }, (_, i) =>
       makeIssue({
         id: String(i + 1),
@@ -645,38 +809,31 @@ describe('JiraProvider read path', () => {
         updated: '2026-01-02T00:00:00Z',
       }),
     )
+    // /rest/api/3/search/jql paginates by an opaque nextPageToken (no `total`);
+    // the loop follows the cursor until `isLast`.
     const searchHandler: StubHandler = (url) => {
-      const parsed = new URL(url)
-      const startAt = Number(parsed.searchParams.get('startAt') ?? '0')
-      searchCalls.push({ startAt })
-      if (startAt === 0) {
+      const token = new URL(url).searchParams.get('nextPageToken')
+      searchCalls.push({ token })
+      if (token === null) {
         return jsonResponse({
-          startAt: 0,
-          maxResults: 100,
-          total: 150,
+          nextPageToken: 'page-2',
+          isLast: false,
           issues: page1Issues,
         })
       }
-      if (startAt === 100) {
+      if (token === 'page-2') {
         return jsonResponse({
-          startAt: 100,
-          maxResults: 100,
-          total: 150,
+          isLast: true,
           issues: page2Issues,
         })
       }
-      return jsonResponse({
-        startAt,
-        maxResults: 100,
-        total: 150,
-        issues: [],
-      })
+      return jsonResponse({ isLast: true, issues: [] })
     }
     const { provider } = makeProviderWithBoard(standardRoutes({ searchHandler }), 3)
     await provider.getBoard()
     expect(searchCalls).toHaveLength(2)
-    expect(searchCalls[0]!.startAt).toBe(0)
-    expect(searchCalls[1]!.startAt).toBe(100)
+    expect(searchCalls[0]!.token).toBeNull()
+    expect(searchCalls[1]!.token).toBe('page-2')
     expect(getCachedTasks(db)).toHaveLength(150)
   })