npm - @andypai/agent-kanban - Versions diffs - 0.3.1 → 0.3.3 - Mend

@andypai/agent-kanban 0.3.1 → 0.3.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (9) hide show

package/README.md +10 -2
package/package.json +1 -1
package/src/__tests__/index.test.ts +47 -1
package/src/__tests__/jira-adf.test.ts +397 -4
package/src/__tests__/jira-provider-read.test.ts +47 -1
package/src/__tests__/output.test.ts +17 -0
package/src/index.ts +47 -0
package/src/output.ts +22 -1
package/src/providers/jira-adf.ts +187 -23

package/README.md CHANGED Viewed

@@ -127,8 +127,8 @@ surface.
 Unsupported operations return error code `UNSUPPORTED_OPERATION` with exit code 1.
-Task comments are currently exposed through the REST API and dashboard task
-detail flows rather than dedicated `kanban comment ...` CLI commands.
+Task comments are exposed through the CLI, REST API, MCP, and dashboard task
+detail flows.
 In Linear and Jira modes, webhooks update the cache immediately when configured,
 and the normal poll loop still runs as a fallback so missed deliveries and
@@ -192,6 +192,14 @@ Default columns: `recurring`, `backlog`, `in-progress`, `review`, `done`.
 | `--project <name>` | New project     |
 | `-m <json>`        | New metadata    |
+### comment
+| Command                                               | Description           |
+| ----------------------------------------------------- | --------------------- |
+| `kanban comment list <task-id>`                       | List task comments    |
+| `kanban comment add <task-id> <body>`                 | Create a task comment |
+| `kanban comment update <task-id> <comment-id> <body>` | Update a task comment |
 ### column
 | Command                                       | Description             |

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@andypai/agent-kanban",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "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__/index.test.ts CHANGED Viewed

@@ -4,7 +4,7 @@ import { mkdtempSync, rmSync } from 'node:fs'
 import { join } from 'node:path'
 import { tmpdir } from 'node:os'
 import { ErrorCode, KanbanError, type ErrorCodeValue } from '../errors'
-import type { Task } from '../types'
+import type { Task, TaskComment } from '../types'
 import { parseServeArgs, run } from '../index'
 async function withTempDb(runTest: (dbPath: string) => Promise<void>): Promise<void> {
@@ -234,6 +234,28 @@ describe('run', () => {
     })
   })
+  test('runs comment commands through the real CLI path', async () => {
+    await withTempDb(async (dbPath) => {
+      const task = expectOk<Task>(await run(['--db', dbPath, 'task', 'add', 'Comment target']))
+      const created = expectOk<TaskComment>(
+        await run(['--db', dbPath, 'comment', 'add', task.id, 'hello', 'from', 'cli']),
+      )
+      expect(created.task_id).toBe(task.id)
+      expect(created.body).toBe('hello from cli')
+      const listed = expectOk<TaskComment[]>(
+        await run(['--db', dbPath, 'comment', 'list', task.id]),
+      )
+      expect(listed.map((comment) => comment.id)).toEqual([created.id])
+      const updated = expectOk<TaskComment>(
+        await run(['--db', dbPath, 'comment', 'update', task.id, created.id, 'edited', 'comment']),
+      )
+      expect(updated.body).toBe('edited comment')
+    })
+  })
   test('raises CLI errors for missing task arguments', async () => {
     await withTempDb(async (dbPath) => {
       const missingTitle = await expectKanbanError(
@@ -249,4 +271,28 @@ describe('run', () => {
       expect(missingId.message).toContain('Task ID is required')
     })
   })
+  test('raises CLI errors for missing comment arguments', async () => {
+    await withTempDb(async (dbPath) => {
+      const missingListId = await expectKanbanError(
+        run(['--db', dbPath, 'comment', 'list']),
+        ErrorCode.MISSING_ARGUMENT,
+      )
+      expect(missingListId.message).toContain('Task ID is required')
+      const missingAddBody = await expectKanbanError(
+        run(['--db', dbPath, 'comment', 'add', 't_1']),
+        ErrorCode.MISSING_ARGUMENT,
+      )
+      expect(missingAddBody.message).toContain('kanban comment add <task-id> <body>')
+      const missingUpdateBody = await expectKanbanError(
+        run(['--db', dbPath, 'comment', 'update', 't_1', 'c_1']),
+        ErrorCode.MISSING_ARGUMENT,
+      )
+      expect(missingUpdateBody.message).toContain(
+        'kanban comment update <task-id> <comment-id> <body>',
+      )
+    })
+  })
 })

package/src/__tests__/jira-adf.test.ts CHANGED Viewed

@@ -1,5 +1,32 @@
 import { describe, expect, test } from 'bun:test'
-import { adfToPlainText, plainTextToAdf, type AdfDocument } from '../providers/jira-adf'
+import {
+  adfToPlainText,
+  plainTextToAdf,
+  type AdfBulletListNode,
+  type AdfCodeBlockNode,
+  type AdfDocument,
+  type AdfExpandNode,
+  type AdfInlineNode,
+  type AdfParagraphNode,
+} from '../providers/jira-adf'
+function firstParagraphContent(doc: AdfDocument): AdfInlineNode[] {
+  const paragraph = doc.content[0] as AdfParagraphNode
+  expect(paragraph.type).toBe('paragraph')
+  return paragraph.content ?? []
+}
+function firstCodeBlock(doc: AdfDocument): AdfCodeBlockNode {
+  const code = doc.content[0] as AdfCodeBlockNode
+  expect(code.type).toBe('codeBlock')
+  return code
+}
+function firstBulletList(doc: AdfDocument): AdfBulletListNode {
+  const list = doc.content[0] as AdfBulletListNode
+  expect(list.type).toBe('bulletList')
+  return list
+}
 describe('plainTextToAdf / adfToPlainText', () => {
   test('empty doc round-trip', () => {
@@ -154,7 +181,7 @@ describe('plainTextToAdf / adfToPlainText', () => {
     expect(adfToPlainText(doc)).toBe('before\n\nafter')
   })
-  test('inline text marks are stripped on read', () => {
+  test('strong + link marks survive on read as markdown', () => {
     const doc: AdfDocument = {
       version: 1,
       type: 'doc',
@@ -163,12 +190,240 @@ describe('plainTextToAdf / adfToPlainText', () => {
           type: 'paragraph',
           content: [
             { type: 'text', text: 'bold', marks: [{ type: 'strong' }] },
-            { type: 'text', text: ' normal' },
+            { type: 'text', text: ' ' },
+            {
+              type: 'text',
+              text: 'click',
+              marks: [{ type: 'link', attrs: { href: 'https://example.com' } }],
+            },
+          ],
+        },
+      ],
+    }
+    expect(adfToPlainText(doc)).toBe('**bold** [click](https://example.com)')
+  })
+  test('write path emits **bold** as a strong mark', () => {
+    const input = 'hello **world**'
+    const doc = plainTextToAdf(input)
+    expect(firstParagraphContent(doc)).toEqual([
+      { type: 'text', text: 'hello ' },
+      { type: 'text', text: 'world', marks: [{ type: 'strong' }] },
+    ])
+    expect(adfToPlainText(doc)).toBe(input)
+  })
+  test('write path emits [label](https://...) as a link mark', () => {
+    const input = 'see [docs](https://example.com/x)'
+    const doc = plainTextToAdf(input)
+    expect(firstParagraphContent(doc)).toEqual([
+      { type: 'text', text: 'see ' },
+      {
+        type: 'text',
+        text: 'docs',
+        marks: [{ type: 'link', attrs: { href: 'https://example.com/x' } }],
+      },
+    ])
+    expect(adfToPlainText(doc)).toBe(input)
+  })
+  test('write path emits side-by-side bold and link as adjacent text nodes', () => {
+    const input = '**PR opened** — [repo#1](https://github.com/o/r/pull/1)'
+    const doc = plainTextToAdf(input)
+    expect(firstParagraphContent(doc)).toEqual([
+      { type: 'text', text: 'PR opened', marks: [{ type: 'strong' }] },
+      { type: 'text', text: ' — ' },
+      {
+        type: 'text',
+        text: 'repo#1',
+        marks: [{ type: 'link', attrs: { href: 'https://github.com/o/r/pull/1' } }],
+      },
+    ])
+    expect(adfToPlainText(doc)).toBe(input)
+  })
+  test('write path bolds bullet item field-name prefix', () => {
+    const input = '- **Marker:** drift:HUMAN REVIEW:516652'
+    const doc = plainTextToAdf(input)
+    const list = firstBulletList(doc)
+    const itemParagraph = list.content[0]!.content[0] as AdfParagraphNode
+    const itemContent = itemParagraph.content ?? []
+    expect(itemContent).toEqual([
+      { type: 'text', text: 'Marker:', marks: [{ type: 'strong' }] },
+      { type: 'text', text: ' drift:HUMAN REVIEW:516652' },
+    ])
+    expect(adfToPlainText(doc)).toBe(input)
+  })
+  test('inline tokenizer does NOT run inside fenced code blocks', () => {
+    const input = '```ts\nconst s = "**not bold** [x](https://e.com)"\n```'
+    const doc = plainTextToAdf(input)
+    const code = firstCodeBlock(doc)
+    const codeContent = code.content ?? []
+    expect(codeContent).toHaveLength(1)
+    expect(codeContent[0]?.text).toBe('const s = "**not bold** [x](https://e.com)"')
+    expect(codeContent[0]?.marks).toBeUndefined()
+    expect(adfToPlainText(doc)).toBe(input)
+  })
+  test('read: code block text marks stay literal', () => {
+    const doc: AdfDocument = {
+      version: 1,
+      type: 'doc',
+      content: [
+        {
+          type: 'codeBlock',
+          content: [
+            { type: 'text', text: '**not bold**', marks: [{ type: 'strong' }] },
+            {
+              type: 'text',
+              text: '\nhttps://example.com',
+              marks: [{ type: 'link', attrs: { href: 'https://example.com' } }],
+            },
+          ],
+        },
+      ],
+    }
+    expect(adfToPlainText(doc)).toBe('```\n**not bold**\nhttps://example.com\n```')
+  })
+  test('non-http link target is left as literal text (no link mark)', () => {
+    const input = 'see [docs](mailto:dev@example.com)'
+    const doc = plainTextToAdf(input)
+    expect(firstParagraphContent(doc)).toEqual([{ type: 'text', text: input }])
+  })
+  test('read: paragraph containing inlineCard emits the URL inline', () => {
+    const doc: AdfDocument = {
+      version: 1,
+      type: 'doc',
+      content: [
+        {
+          type: 'paragraph',
+          content: [
+            { type: 'text', text: 'Repo: ' },
+            { type: 'inlineCard', attrs: { url: 'https://github.com/abpai/garage-band' } },
+          ],
+        },
+      ],
+    }
+    expect(adfToPlainText(doc)).toBe('Repo: https://github.com/abpai/garage-band')
+  })
+  test('read: split strong field label keeps colon inside markdown', () => {
+    const doc: AdfDocument = {
+      version: 1,
+      type: 'doc',
+      content: [
+        {
+          type: 'paragraph',
+          content: [
+            { type: 'text', text: 'Repo', marks: [{ type: 'strong' }] },
+            { type: 'text', text: ': ' },
+            { type: 'inlineCard', attrs: { url: 'https://github.com/abpai/garage-band' } },
+          ],
+        },
+      ],
+    }
+    expect(adfToPlainText(doc)).toBe('**Repo:** https://github.com/abpai/garage-band')
+  })
+  test('read: blockCard renders as a standalone block with the URL', () => {
+    const doc: AdfDocument = {
+      version: 1,
+      type: 'doc',
+      content: [
+        { type: 'paragraph', content: [{ type: 'text', text: 'before' }] },
+        { type: 'blockCard', attrs: { url: 'https://github.com/abpai/garage-band' } },
+        { type: 'paragraph', content: [{ type: 'text', text: 'after' }] },
+      ],
+    }
+    expect(adfToPlainText(doc)).toBe('before\n\nhttps://github.com/abpai/garage-band\n\nafter')
+  })
+  test('read: embedCard also emits its URL', () => {
+    const doc: AdfDocument = {
+      version: 1,
+      type: 'doc',
+      content: [{ type: 'embedCard', attrs: { url: 'https://example.com/embed' } }],
+    }
+    expect(adfToPlainText(doc)).toBe('https://example.com/embed')
+  })
+  test('read: DXS-12-shaped description preserves smart-link Repo URL', () => {
+    // Captured shape from a real Jira description where a user pasted a URL
+    // and Jira auto-converted it to an inlineCard. Before the fix,
+    // adfToPlainText returned "Repo: " with the URL silently dropped.
+    const doc: AdfDocument = {
+      version: 1,
+      type: 'doc',
+      content: [
+        {
+          type: 'paragraph',
+          content: [
+            { type: 'text', text: 'Repo', marks: [{ type: 'strong' }] },
+            { type: 'text', text: ': ' },
+            { type: 'inlineCard', attrs: { url: 'https://github.com/abpai/garage-band' } },
+          ],
+        },
+        {
+          type: 'paragraph',
+          content: [{ type: 'text', text: 'Please make one minimal change.' }],
+        },
+        {
+          type: 'heading',
+          attrs: { level: 3 },
+          content: [{ type: 'text', text: 'Acceptance criteria:' }],
+        },
+        {
+          type: 'bulletList',
+          content: [
+            {
+              type: 'listItem',
+              content: [
+                {
+                  type: 'paragraph',
+                  content: [{ type: 'text', text: 'Change only SMOKE_TEST_TASK.md.' }],
+                },
+              ],
+            },
+            {
+              type: 'listItem',
+              content: [
+                {
+                  type: 'paragraph',
+                  content: [{ type: 'text', text: 'Increment current_count by exactly one.' }],
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    }
+    const out = adfToPlainText(doc)
+    expect(out).toContain('Repo:')
+    expect(out).toContain('https://github.com/abpai/garage-band')
+    // Repo line carries the URL — agents grepping for the URL recover it.
+    const repoLine = out.split('\n').find((l) => l.includes('Repo:'))
+    expect(repoLine).toBe('**Repo:** https://github.com/abpai/garage-band')
+  })
+  test('read: hardBreak between text runs emits newline', () => {
+    const doc: AdfDocument = {
+      version: 1,
+      type: 'doc',
+      content: [
+        {
+          type: 'paragraph',
+          content: [
+            { type: 'text', text: 'first line' },
+            { type: 'hardBreak' },
+            { type: 'text', text: 'second line' },
           ],
         },
       ],
     }
-    expect(adfToPlainText(doc)).toBe('bold normal')
+    expect(adfToPlainText(doc)).toBe('first line\nsecond line')
   })
   test('bullet item containing digits-dot substring is still a bullet', () => {
@@ -178,3 +433,141 @@ describe('plainTextToAdf / adfToPlainText', () => {
     expect(adfToPlainText(doc)).toBe(input)
   })
 })
+describe('jira-adf expand block', () => {
+  test('write: expand wrapping a fenced code block produces nested ADF', () => {
+    const input =
+      '::: expand title="garage-baton (machine-readable)"\n' +
+      '```garage-baton\n' +
+      '{"v":1}\n' +
+      '```\n' +
+      ':::'
+    const doc = plainTextToAdf(input)
+    expect(doc.content).toHaveLength(1)
+    const expand = doc.content[0] as AdfExpandNode
+    expect(expand.type).toBe('expand')
+    expect(expand.attrs?.title).toBe('garage-baton (machine-readable)')
+    expect(expand.content).toHaveLength(1)
+    const code = expand.content[0] as AdfCodeBlockNode
+    expect(code.type).toBe('codeBlock')
+    expect(code.attrs?.language).toBe('garage-baton')
+    expect(code.content?.[0]).toEqual({ type: 'text', text: '{"v":1}' })
+  })
+  test('read: ADF expand wrapping a codeBlock renders back to the wire format', () => {
+    const doc: AdfDocument = {
+      version: 1,
+      type: 'doc',
+      content: [
+        {
+          type: 'expand',
+          attrs: { title: 'garage-baton (machine-readable)' },
+          content: [
+            {
+              type: 'codeBlock',
+              attrs: { language: 'garage-baton' },
+              content: [{ type: 'text', text: '{"v":1}' }],
+            },
+          ],
+        },
+      ],
+    }
+    expect(adfToPlainText(doc)).toBe(
+      '::: expand title="garage-baton (machine-readable)"\n' +
+        '```garage-baton\n' +
+        '{"v":1}\n' +
+        '```\n' +
+        ':::',
+    )
+  })
+  test('write: bare ::: expand emits empty title', () => {
+    const input = '::: expand\nbody paragraph\n:::'
+    const doc = plainTextToAdf(input)
+    const expand = doc.content[0] as AdfExpandNode
+    expect(expand.type).toBe('expand')
+    expect(expand.attrs?.title).toBe('')
+    expect(expand.content[0]?.type).toBe('paragraph')
+  })
+  test('read: bare ::: expand renders without title attribute', () => {
+    const doc: AdfDocument = {
+      version: 1,
+      type: 'doc',
+      content: [
+        {
+          type: 'expand',
+          attrs: { title: '' },
+          content: [{ type: 'paragraph', content: [{ type: 'text', text: 'body' }] }],
+        },
+      ],
+    }
+    expect(adfToPlainText(doc)).toBe('::: expand\nbody\n:::')
+  })
+  test('read: expand without attrs renders as a bare expand block', () => {
+    const doc: AdfDocument = {
+      version: 1,
+      type: 'doc',
+      content: [
+        {
+          type: 'expand',
+          content: [{ type: 'paragraph', content: [{ type: 'text', text: 'body' }] }],
+        },
+      ],
+    }
+    expect(adfToPlainText(doc)).toBe('::: expand\nbody\n:::')
+  })
+  test('write: unterminated ::: expand falls through to paragraph', () => {
+    const input = '::: expand title="oops"\nstray text without close'
+    const doc = plainTextToAdf(input)
+    // Both lines collapse into a single paragraph; no expand node.
+    expect(doc.content.every((b) => b.type !== 'expand')).toBe(true)
+    expect(doc.content[0]?.type).toBe('paragraph')
+  })
+  test('round-trip: typed-comment-shaped string is byte-stable', () => {
+    const input =
+      'garage-triage: **Accepted** — abpai/garage-band\n' +
+      '\n' +
+      'Increment current_count by 1.\n' +
+      '\n' +
+      '**Next:** Handing off to planner.\n' +
+      '\n' +
+      '::: expand title="garage-baton (machine-readable)"\n' +
+      '```garage-baton\n' +
+      '{"v":1,"accepted":true}\n' +
+      '```\n' +
+      ':::'
+    expect(adfToPlainText(plainTextToAdf(input))).toBe(input)
+  })
+  test('round-trip: nested paragraph and bullet list inside expand survive', () => {
+    const input =
+      '::: expand title="details"\n' +
+      'first paragraph\n' +
+      '\n' +
+      '- bullet one\n' +
+      '- bullet two\n' +
+      ':::'
+    expect(adfToPlainText(plainTextToAdf(input))).toBe(input)
+  })
+  test('write: expand title preserves escaped quote', () => {
+    const input = '::: expand title="quoted \\"title\\""\nx\n:::'
+    const doc = plainTextToAdf(input)
+    const expand = doc.content[0] as AdfExpandNode
+    expect(expand.attrs?.title).toBe('quoted "title"')
+    // Round-trip emits the same escaping.
+    expect(adfToPlainText(doc)).toBe(input)
+  })
+  test('write: text followed by ::: expand on the next line is two blocks', () => {
+    const input = 'leading paragraph\n' + '::: expand title="x"\n' + 'inside\n' + ':::'
+    const doc = plainTextToAdf(input)
+    expect(doc.content).toHaveLength(2)
+    expect(doc.content[0]?.type).toBe('paragraph')
+    expect(doc.content[1]?.type).toBe('expand')
+  })
+})

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

@@ -67,13 +67,14 @@ function makeIssue(opts: {
   updated?: string
   summary?: string
   assignee?: { accountId: string; displayName: string } | null
+  description?: unknown
 }): Record<string, unknown> {
   return {
     id: opts.id,
     key: opts.key,
     fields: {
       summary: opts.summary ?? opts.key,
-      description: null,
+      description: opts.description ?? null,
       status: { id: opts.statusId, name: 'Status ' + opts.statusId },
       issuetype: { id: '10000', name: 'Bug' },
       priority: { id: '2', name: 'High' },
@@ -429,6 +430,51 @@ describe('JiraProvider read path', () => {
     expect(byPrefixed.externalRef).toBe('ENG-1')
   })
+  test('description ADF with an inlineCard smart-link preserves the URL through getTask', async () => {
+    // Regression for the DXS-12 shape: a user pastes
+    // `Repo: https://github.com/abpai/garage-band` in the description, Jira
+    // auto-converts the URL to an inlineCard, and the previous
+    // adfToPlainText silently dropped attrs.url.
+    const description = {
+      version: 1,
+      type: 'doc',
+      content: [
+        {
+          type: 'paragraph',
+          content: [
+            { type: 'text', text: 'Repo', marks: [{ type: 'strong' }] },
+            { type: 'text', text: ': ' },
+            { type: 'inlineCard', attrs: { url: 'https://github.com/abpai/garage-band' } },
+          ],
+        },
+        {
+          type: 'paragraph',
+          content: [{ type: 'text', text: 'Increment SMOKE_TEST_TASK.md by 1.' }],
+        },
+      ],
+    }
+    const searchHandler: StubHandler = () =>
+      jsonResponse({
+        startAt: 0,
+        maxResults: 100,
+        total: 1,
+        issues: [
+          makeIssue({
+            id: '20001',
+            key: 'ENG-12',
+            statusId: '10001',
+            description,
+          }),
+        ],
+      })
+    const { provider } = makeProvider(standardRoutes({ searchHandler }))
+    await provider.getBoard()
+    const task = await provider.getTask('ENG-12')
+    expect(task.description).toContain('Repo:')
+    expect(task.description).toContain('https://github.com/abpai/garage-band')
+    expect(task.description.split('\n')[0]).toBe('**Repo:** https://github.com/abpai/garage-band')
+  })
   test('getBootstrap returns provider=jira and the adapted BoardConfig', async () => {
     const { provider } = makeProvider(standardRoutes({}))
     const result = await provider.getBootstrap()

package/src/__tests__/output.test.ts CHANGED Viewed

@@ -36,4 +36,21 @@ describe('formatOutput', () => {
     const output = formatOutput(result, true)
     expect(output).toBe('Board initialized.')
   })
+  test('formats comments in pretty mode', () => {
+    const output = formatOutput(
+      success([
+        {
+          id: 'c_1',
+          task_id: 't_1',
+          body: 'hello from cli',
+          author: 'alice',
+          created_at: '2026-04-26T00:00:00.000Z',
+          updated_at: '2026-04-26T00:00:00.000Z',
+        },
+      ]),
+      true,
+    )
+    expect(output).toBe('  c_1 @alice  hello from cli')
+  })
 })

package/src/index.ts CHANGED Viewed

@@ -139,6 +139,45 @@ async function routeTask(
   }
 }
+async function routeComment(
+  provider: ReturnType<typeof createProvider>,
+  action: string | undefined,
+  positionals: string[],
+): Promise<CliOutput> {
+  switch (action) {
+    case 'list': {
+      const id = positionals[2]
+      if (!id) throw new KanbanError(ErrorCode.MISSING_ARGUMENT, 'Task ID is required')
+      return success(await provider.listComments(id))
+    }
+    case 'add': {
+      const id = positionals[2]
+      const body = positionals.slice(3).join(' ')
+      if (!id || !body) {
+        throw new KanbanError(
+          ErrorCode.MISSING_ARGUMENT,
+          'Usage: kanban comment add <task-id> <body>',
+        )
+      }
+      return success(await provider.comment(id, body))
+    }
+    case 'update': {
+      const id = positionals[2]
+      const commentId = positionals[3]
+      const body = positionals.slice(4).join(' ')
+      if (!id || !commentId || !body) {
+        throw new KanbanError(
+          ErrorCode.MISSING_ARGUMENT,
+          'Usage: kanban comment update <task-id> <comment-id> <body>',
+        )
+      }
+      return success(await provider.updateComment(id, commentId, body))
+    }
+    default:
+      throw new KanbanError(ErrorCode.UNKNOWN_COMMAND, `Unknown comment command '${action}'`)
+  }
+}
 function routeColumn(
   db: Database,
   providerType: string,
@@ -298,6 +337,9 @@ async function run(argv: string[]): Promise<{ output: CliOutput; exitCode: numbe
       case 'task':
         output = await routeTask(provider, action, positionals, values)
         break
+      case 'comment':
+        output = await routeComment(provider, action, positionals)
+        break
       case 'column':
         output = routeColumn(db, provider.type, action, positionals, values)
         break
@@ -335,6 +377,11 @@ Commands:
   task assign <id> <user>     Assign task
   task prioritize <id> <lvl>  Set priority
+  comment list <task-id>      List comments on a task
+  comment add <task-id> <body> Create a comment
+  comment update <task-id> <comment-id> <body>
+                              Update a comment
   column add <name>           Add column [--position n] [--color hex]
   column list                 List columns
   column rename <id> <name>   Rename column

package/src/output.ts CHANGED Viewed

@@ -1,4 +1,4 @@
-import type { CliOutput, BoardView, Task, TaskWithColumn, Column } from './types'
+import type { CliOutput, BoardView, Task, TaskWithColumn, TaskComment, Column } from './types'
 export function success<T>(data: T): CliOutput<T> {
   return { ok: true, data }
@@ -25,12 +25,16 @@ function formatPrettyData(data: unknown): string {
   if (Array.isArray(data)) {
     if (data.length === 0) return 'No items found.'
     if ('column_id' in data[0]) return data.map(formatTaskLine).join('\n')
+    if ('task_id' in data[0]) return data.map(formatCommentLine).join('\n')
     if ('position' in data[0]) return data.map(formatColumnLine).join('\n')
     return JSON.stringify(data, null, 2)
   }
   if (data && typeof data === 'object' && 'column_id' in data) {
     return formatTaskDetail(data as TaskWithColumn)
   }
+  if (data && typeof data === 'object' && 'task_id' in data) {
+    return formatCommentDetail(data as TaskComment)
+  }
   if (data && typeof data === 'object' && 'moved' in data) {
     return `Moved ${(data as { moved: number }).moved} task(s).`
   }
@@ -79,6 +83,23 @@ function formatTaskDetail(task: Task): string {
   return lines.join('\n')
 }
+function formatCommentLine(comment: TaskComment): string {
+  const author = comment.author ? ` @${comment.author}` : ''
+  return `  ${comment.id}${author}  ${comment.body}`
+}
+function formatCommentDetail(comment: TaskComment): string {
+  const lines = [
+    `Comment: ${comment.id}`,
+    `Task: ${comment.task_id}`,
+    ...(comment.author ? [`Author: ${comment.author}`] : []),
+    `Body: ${comment.body}`,
+    `Created: ${comment.created_at}`,
+    `Updated: ${comment.updated_at}`,
+  ]
+  return lines.join('\n')
+}
 function formatColumnLine(col: Column): string {
   const color = col.color ? ` (${col.color})` : ''
   return `  ${col.position}. ${col.name}${color}  [${col.id}]`

package/src/providers/jira-adf.ts CHANGED Viewed

@@ -2,14 +2,14 @@
 //
 // This module is intentionally dependency-free: no imports from the rest of the
 // provider stack, no bun:sqlite, no fetch. It models only the subset of ADF
-// that agent-kanban round-trips through plain text:
+// that agent-kanban writes, plus a few Jira nodes it must preserve on read:
 //
-//   doc > { paragraph | bulletList | orderedList | codeBlock | heading }
-//   paragraph / heading / codeBlock > text(inline)
+//   doc > { paragraph | bulletList | orderedList | codeBlock | heading | card }
+//   paragraph / heading / codeBlock > text(inline) | inlineCard | hardBreak
 //   bulletList / orderedList > listItem > paragraph > text
 //
-// Unknown node types are tolerated on the read path (skipped silently) and
-// never emitted on the write path.
+// Other unknown node types are tolerated on the read path (skipped silently)
+// and never emitted on the write path.
 export interface AdfDocument {
   version: 1
@@ -17,10 +17,15 @@ export interface AdfDocument {
   content: AdfBlockNode[]
 }
+export interface AdfMark {
+  type: string
+  attrs?: Record<string, unknown>
+}
 export interface AdfTextNode {
   type: 'text'
   text: string
-  marks?: unknown[]
+  marks?: AdfMark[]
 }
 export interface AdfUnknownInlineNode {
@@ -63,6 +68,12 @@ export interface AdfHeadingNode {
   content?: AdfInlineNode[]
 }
+export interface AdfExpandNode {
+  type: 'expand'
+  attrs?: { title?: string }
+  content: AdfBlockNode[]
+}
 export interface AdfUnknownBlockNode {
   type: string
   [key: string]: unknown
@@ -74,6 +85,7 @@ export type AdfBlockNode =
   | AdfOrderedListNode
   | AdfCodeBlockNode
   | AdfHeadingNode
+  | AdfExpandNode
   | AdfUnknownBlockNode
 // Public AdfNode union covers every node shape this module recognizes.
@@ -85,6 +97,18 @@ const ORDERED_MARKER = /^(\d+)\. (.*)$/
 // no whitespace before it. Fence must occupy the whole line.
 const FENCE_OPEN = /^```([^\s`]*)$/
 const FENCE_CLOSE = /^```$/
+// Expand wrapper: `::: expand` or `::: expand title="..."`. Quotes and
+// backslashes in the title are escaped with a leading `\`.
+const EXPAND_OPEN = /^::: expand(?: title="((?:\\.|[^"\\])*)")?$/
+const EXPAND_CLOSE = /^:::$/
+function unescapeTitle(raw: string): string {
+  return raw.replace(/\\(.)/g, '$1')
+}
+function escapeTitle(value: string): string {
+  return value.replace(/(["\\])/g, '\\$1')
+}
 function paragraphFromText(text: string): AdfParagraphNode {
   if (text.length === 0) {
@@ -92,7 +116,7 @@ function paragraphFromText(text: string): AdfParagraphNode {
   }
   return {
     type: 'paragraph',
-    content: [{ type: 'text', text }],
+    content: tokenizeInline(text),
   }
 }
@@ -103,17 +127,63 @@ function listItemFromText(text: string): AdfListItemNode {
   }
 }
+const INLINE_MARK = /\*\*([^*\n]+)\*\*|\[([^\]\n]+)\]\((https?:\/\/[^)\s]+)\)/g
+function tokenizeInline(text: string): AdfTextNode[] {
+  const out: AdfTextNode[] = []
+  INLINE_MARK.lastIndex = 0
+  let cursor = 0
+  for (const match of text.matchAll(INLINE_MARK)) {
+    const start = match.index ?? 0
+    if (start > cursor) {
+      out.push({ type: 'text', text: text.slice(cursor, start) })
+    }
+    const boldText = match[1]
+    if (boldText !== undefined) {
+      out.push({
+        type: 'text',
+        text: boldText,
+        marks: [{ type: 'strong' }],
+      })
+    } else {
+      out.push({
+        type: 'text',
+        text: match[2]!,
+        marks: [{ type: 'link', attrs: { href: match[3]! } }],
+      })
+    }
+    cursor = start + match[0].length
+  }
+  if (cursor < text.length) {
+    out.push({ type: 'text', text: text.slice(cursor) })
+  }
+  return out
+}
 export function plainTextToAdf(text: string): AdfDocument {
   if (text.length === 0) {
     return { version: 1, type: 'doc', content: [] }
   }
   const lines = text.split('\n')
-  const blocks: AdfBlockNode[] = []
+  const { blocks } = parseBlocks(lines, 0, () => false)
+  return { version: 1, type: 'doc', content: blocks }
+}
-  let i = 0
+interface ParseResult {
+  blocks: AdfBlockNode[]
+  // Index just past the last consumed line. When `stop` matches, this points
+  // at the stop line itself (the caller is responsible for stepping past it).
+  endIndex: number
+}
+function parseBlocks(lines: string[], start: number, stop: (line: string) => boolean): ParseResult {
+  const blocks: AdfBlockNode[] = []
+  let i = start
   while (i < lines.length) {
     const line = lines[i] ?? ''
+    if (stop(line)) {
+      return { blocks, endIndex: i }
+    }
     // Blank line separates blocks — consume and move on.
     if (line === '') {
@@ -121,6 +191,19 @@ export function plainTextToAdf(text: string): AdfDocument {
       continue
     }
+    // Expand wrapper.
+    const expandOpen = line.match(EXPAND_OPEN)
+    if (expandOpen) {
+      const title = unescapeTitle(expandOpen[1] ?? '')
+      const inner = parseBlocks(lines, i + 1, (l) => EXPAND_CLOSE.test(l))
+      if (inner.endIndex < lines.length) {
+        blocks.push({ type: 'expand', attrs: { title }, content: inner.blocks })
+        i = inner.endIndex + 1
+        continue
+      }
+      // Unterminated `::: expand` — fall through to paragraph.
+    }
     // Fenced code block.
     const fenceOpen = line.match(FENCE_OPEN)
     if (fenceOpen) {
@@ -189,16 +272,19 @@ export function plainTextToAdf(text: string): AdfDocument {
       continue
     }
-    // Paragraph: consume until blank line or a block-starting line.
+    // Paragraph: consume until blank line, stop predicate, or a
+    // block-starting line.
     const paragraphLines: string[] = [line]
     i += 1
     while (i < lines.length) {
       const current = lines[i] ?? ''
       if (
         current === '' ||
+        stop(current) ||
         BULLET_MARKER.test(current) ||
         ORDERED_MARKER.test(current) ||
-        FENCE_OPEN.test(current)
+        FENCE_OPEN.test(current) ||
+        EXPAND_OPEN.test(current)
       ) {
         break
       }
@@ -208,21 +294,82 @@ export function plainTextToAdf(text: string): AdfDocument {
     blocks.push(paragraphFromText(paragraphLines.join('\n')))
   }
-  return { version: 1, type: 'doc', content: blocks }
+  return { blocks, endIndex: i }
 }
-function inlineText(nodes: AdfInlineNode[] | undefined): string {
+function inlineText(
+  nodes: AdfInlineNode[] | undefined,
+  opts: { renderMarks?: boolean } = {},
+): string {
   if (!nodes) return ''
+  const renderMarks = opts.renderMarks ?? true
   let out = ''
-  for (const node of nodes) {
+  for (let i = 0; i < nodes.length; i += 1) {
+    const node = nodes[i]!
     if (node.type === 'text') {
-      out += (node as AdfTextNode).text
+      const textNode = node as AdfTextNode
+      if (!renderMarks) {
+        out += textNode.text
+        continue
+      }
+      const nextNode = nodes[i + 1]
+      const labelColon = readPlainTextLeadingColon(nextNode)
+      if (labelColon && hasMark(textNode, 'strong')) {
+        out += renderTextNode({ ...textNode, text: `${textNode.text}:` })
+        out += labelColon.remainder
+        i += 1
+        continue
+      }
+      out += renderTextNode(textNode)
+      continue
     }
-    // Unknown inline nodes (mentions, emoji, hardBreak, etc.) are skipped.
+    if (node.type === 'inlineCard') {
+      const url = readCardUrl(node)
+      if (url) out += url
+      continue
+    }
+    if (node.type === 'hardBreak') {
+      out += '\n'
+      continue
+    }
+    // Other unknown inline nodes (mentions, emoji, etc.) are skipped.
   }
   return out
 }
+function hasMark(node: AdfTextNode, type: string): boolean {
+  return node.marks?.some((m) => m.type === type) ?? false
+}
+function readPlainTextLeadingColon(node: AdfInlineNode | undefined): { remainder: string } | null {
+  if (!node || node.type !== 'text') return null
+  const textNode = node as AdfTextNode
+  if (textNode.marks && textNode.marks.length > 0) return null
+  if (!textNode.text.startsWith(':')) return null
+  return { remainder: textNode.text.slice(1) }
+}
+function renderTextNode(node: AdfTextNode): string {
+  if (!node.marks || node.marks.length === 0) return node.text
+  const link = node.marks.find((m) => m.type === 'link')
+  let out = node.text
+  if (link) {
+    const href = link.attrs?.['href']
+    if (typeof href === 'string' && href.length > 0) out = `[${out}](${href})`
+  }
+  if (hasMark(node, 'strong')) {
+    out = `**${out}**`
+  }
+  return out
+}
+function readCardUrl(node: AdfInlineNode | AdfBlockNode): string | null {
+  const attrs = (node as { attrs?: Record<string, unknown> }).attrs
+  if (!attrs) return null
+  const url = attrs['url']
+  return typeof url === 'string' && url.length > 0 ? url : null
+}
 function listItemInnerText(item: AdfListItemNode): string {
   // Each list item wraps a paragraph (or nested blocks). We flatten to the
   // first paragraph's inline text, which is all the write path produces.
@@ -252,24 +399,41 @@ function renderBlock(node: AdfBlockNode): string | null {
     case 'codeBlock': {
       const code = node as AdfCodeBlockNode
       const language = code.attrs?.language ?? ''
-      const body = inlineText(code.content)
+      const body = inlineText(code.content, { renderMarks: false })
       const fence = language.length > 0 ? `\`\`\`${language}` : '```'
       return `${fence}\n${body}\n\`\`\``
     }
     case 'heading':
       return inlineText((node as AdfHeadingNode).content)
+    case 'expand': {
+      const expand = node as AdfExpandNode
+      const title = expand.attrs?.title ?? ''
+      const open = title.length > 0 ? `::: expand title="${escapeTitle(title)}"` : '::: expand'
+      const inner = renderBlocks(expand.content)
+      const body = inner.length > 0 ? `${open}\n${inner}\n:::` : `${open}\n:::`
+      return body
+    }
+    case 'blockCard':
+    case 'embedCard': {
+      const url = readCardUrl(node)
+      return url ?? null
+    }
     default:
       // Unknown block node — skip entirely, never throw.
       return null
   }
 }
-export function adfToPlainText(doc: AdfDocument): string {
-  const rendered: string[] = []
-  for (const block of doc.content) {
+function renderBlocks(nodes: AdfBlockNode[]): string {
+  const out: string[] = []
+  for (const block of nodes) {
     const text = renderBlock(block)
     if (text === null) continue
-    rendered.push(text)
+    out.push(text)
   }
-  return rendered.join('\n\n')
+  return out.join('\n\n')
+}
+export function adfToPlainText(doc: AdfDocument): string {
+  return renderBlocks(doc.content)
 }