claude-code-kanban 7.4.0 → 7.6.0

package/plugin/plugins/claude-code-kanban/skills/show/references/explain.md

@@ -0,0 +1,98 @@
+# Explain card
+
+A markdown card that shows how code works: what calls what, what a function decides, where things live, or what a change moves. Post `kind: "markdown"`; the board renders the fences below.
+
+## Make one point
+
+Each card makes one point about the code under discussion. Write the point as a sentence or two, then the view that proves it. Pick the smallest view that makes the point clear; add a second view to the card only when it shows what the first cannot.
+
+| Showing | View | Fence |
+|---|---|---|
+| Runtime flow: who calls whom | Call stack | `callstack` |
+| What a function decides | Pseudocode | `text` |
+| UI structure, state and module boundaries | Component tree | `tsx` |
+| Which file owns what | File tree | `text` |
+| Messages between parts over time | Sequence | `mermaid` |
+| What a change adds, removes or moves | A diff of the view above | see [Diff](#diff) |
+
+Keep only the calls, files, props and states the point needs, with real names from the code. Give the card a `key` that names the topic; post a follow-up view, such as the diff after the fix, with the same key so it replaces the card.
+
+## Call stack
+
+The board draws the tree lines, links, focus and folds from this notation:
+
+```callstack
+ handleCheckout                  src/routes/checkout.ts:24
+   validateCart                  throws on an empty cart
+   placeOrder *                  src/orders/place.ts:40
+     chargeCard                  src/payments/charge.ts:31
+       ~ 2 SDK frames
+         PaymentsClient.charge   node_modules/pay-sdk/client.js:112
+         HttpClient.request      node_modules/pay-sdk/http.js:58
++    sendReceipt                 src/email/receipt.ts:9
+-    logOrder                    src/orders/log.ts:5
+ onPaymentWebhook                src/routes/webhooks.ts:58
+   markOrderPaid                 src/orders/status.ts:22
+```
+
+- The fence tag is `callstack`.
+- Caller on top. Indent each callee 2 spaces under its caller; the board turns the spaces into tree lines. Several roots are fine.
+- One frame per line: the function or method name as one identifier, spelled as in the code.
+- The note goes after 2 or more spaces: a `path:line` relative to the project root, which the board links, or a few words. Line the notes up in one column.
+- A `*` after the name, with one space, marks the frame to look at. One per stack.
+- `+` or `-` in the first column marks a frame the change adds or removes. In a stack with any `+` or `-`, every other line starts with one space.
+
+### Folds
+
+A `~ N <what> frames` line stands for frames the reader can skip, such as framework, library or runtime code. It sits where those frames sit: under the frame that calls them, or at the top for framework callers above a handler.
+
+- With frames indented under it, the line is a fold: the board shows it closed, and the reader clicks it to open.
+- A fold that holds the `*` frame or a `+` or `-` frame starts open, so the point stays on screen.
+- Folds nest: library frames that call runtime frames get a `~` each.
+- With nothing under it, the line is a note that frames were left out. Write the frames out only when the reader may need them.
+
+## Pseudocode
+
+```text
+placeOrder(cart)
+  if any item is out of stock
+    return "sold out"
+  charge the card
+  if the charge fails
+    release the stock
+  send the receipt
+```
+
+## Component tree
+
+```tsx
+<CheckoutPage>             (src/routes/checkout.tsx)
+  useCart()
+  <OrderSummary>
+    <PayButton>            (packages/ui)
+```
+
+## File tree
+
+The one view drawn with box characters:
+
+```text
+src/
+├── routes/       # HTTP handlers
+├── orders/       # owns order state
+└── payments/     # talks to the card provider
+```
+
+## Diff
+
+Draw a change in the shape of the view it changes: a component tree diff for a component change, a file tree diff for a move. Mark each line with `+`, `-` or a space in the first column. A call stack takes the marks inside its `callstack` fence; every other view goes in a `diff` fence:
+
+```diff
+ <CheckoutPage>
+   useCart()
+   <OrderSummary>
++    <PromoCodeInput />
+     <PayButton>
+```
+
+Show the whole block without marks when most of it is new, or when a diff would hide the order or the owner of each part.

package/plugin/plugins/claude-code-kanban/skills/show/references/mockup.md

@@ -0,0 +1,30 @@
+# Mockup card
+
+A wireframe in an HTML card: a screen, a dialog, a form or a component, to agree on layout and wording before code.
+
+## Content
+
+- Real labels and real copy from the task: "Delete 3 sessions?", not "Lorem ipsum" or "Button".
+- Plain boxes in place of logos, brand names and product chrome. A gray block (`--color-bg-subtle`) with a mono caption stands in for an image, chart or map.
+- One screen or one state per card. For a flow, post one card per step under one `key` prefix, or show 2 or 3 states side by side when they fit.
+- Mark open questions with numbered callouts: a small circle in `--color-accent` with a number, and the notes as a list under the sketch.
+
+## Building blocks
+
+The card already styles `button`, `button.primary`, `input`, `select`, `textarea`, `table` and headings from the tokens. Use them as they are.
+
+```html
+<style>
+  .m { border: 1px solid var(--color-border); border-radius: 8px; overflow: hidden; }
+  .m-bar { display: flex; gap: 8px; align-items: center; padding: 8px 12px; background: var(--color-bg-subtle); border-bottom: 1px solid var(--color-border); }
+  .m-body { padding: 12px; display: grid; gap: 8px; }
+  .m-img { background: var(--color-bg-subtle); border: 1px dashed var(--color-border); border-radius: 6px; min-height: 64px; display: grid; place-items: center; font: 11px var(--font-mono); color: var(--color-text-muted); }
+  .m-note { display: inline-grid; place-items: center; width: 18px; height: 18px; border-radius: 50%; background: var(--color-accent); color: #fff; font: 600 11px var(--font-sans); }
+</style>
+```
+
+## Fit the card
+
+- A sketch narrower than the card sits centered (`margin-inline: auto`).
+- A phone screen fits at real size, about 360 px. A desktop screen does not: sketch the part under discussion (one panel, the toolbar, the dialog), not the whole window.
+- Scripts may toggle a state (open a menu, switch a tab) to show the interaction. Keep it to a few lines; the card has no storage and no network.

package/plugin/plugins/claude-code-kanban/tests/doorbell.test.ts

@@ -0,0 +1,133 @@
+import type { On } from 'claude-code'
+import { expect, mock, test } from 'claude-code/testing'
+import { boardUrl, parseReply, RETRY_MS } from '../hooks/doorbell'
+
+test('the board URL comes from CCK_URL, else from server.json', async () => {
+  expect(boardUrl('http://127.0.0.1:4000/', '{"port":3541}')).toBe('http://127.0.0.1:4000')
+  expect(boardUrl(undefined, '{"port":3541}')).toBe('http://127.0.0.1:3541')
+  expect(boardUrl(undefined, '{"port":"3541"}')).toBe(undefined)
+  expect(boardUrl(undefined, 'not json')).toBe(undefined)
+  expect(boardUrl(undefined, undefined)).toBe(undefined)
+})
+
+type Reply = { status: number; events?: string[]; seqs?: number[]; board?: string }
+
+function engine(on: On, replies: (() => Reply)[], submit?: () => Promise<unknown>) {
+  const urls: string[] = []
+  const prompts: string[] = []
+  let sessionId = 'sid-1'
+  on('fs.read', (_$, e) => {
+    if (e.path.replaceAll('\\', '/') === 'C:/cfg/.cck/server.json') return { value: '{"port":3541}' }
+    throw new Error(`ENOENT: ${e.path}`)
+  })
+  on('env.get', (_$, e) => ({ value: { CLAUDE_CONFIG_DIR: 'C:/cfg' }[e.name] }))
+  on('session.id', () => ({ value: sessionId }))
+  on('session.start', (_$, e) => ({ cwd: e.cwd }))
+  on('http.fetch', async (_$, e) => {
+    urls.push(e.url)
+    const reply = replies.shift()
+    if (!reply) return new Promise(() => {})
+    const { status, events = [], seqs, board } = reply()
+    return { value: { status, ok: status < 300, headers: {}, text: JSON.stringify({ events, seqs, board }) } }
+  })
+  on('prompt.submit', async (_$, e) => {
+    prompts.push(e.text)
+    if (submit) await submit()
+    return { text: e.text }
+  })
+  return { urls, prompts, clear: () => (sessionId = 'sid-2') }
+}
+
+test('a -p run does not poll the board', async ($, on) => {
+  const clock = mock.clock(on)
+  const board = engine(on, [])
+  await $.session.start({ cwd: 'C:/proj', surface: null, isInteractive: false })
+  await clock.settle()
+  expect(board.urls).toEqual([])
+})
+
+test('polls the board, submits a burst as one prompt, and drops the backlog for a new session id', async ($, on) => {
+  const clock = mock.clock(on)
+  const replies = [
+    () => ({ status: 200, events: ['line one', 'line two'] }),
+    () => ({ status: 503 }),
+    () => {
+      board.clear()
+      return { status: 200 }
+    },
+    () => ({ status: 200, events: ['after clear'] }),
+  ]
+  const board = engine(on, replies)
+  await $.session.start({ cwd: 'C:/proj', surface: 'terminal', isInteractive: true })
+  await clock.settle()
+
+  const base = 'http://127.0.0.1:3541/api/sessions'
+  expect(board.prompts).toEqual(['line one\nline two'])
+  expect(board.urls).toEqual([
+    `${base}/sid-1/events?wait=25&board=&got=0&ack=0&first=1`,
+    `${base}/sid-1/events?wait=25&board=&got=0&ack=0`,
+  ])
+
+  await clock.advance(RETRY_MS)
+  expect(board.urls.slice(2)).toEqual([
+    `${base}/sid-1/events?wait=25&board=&got=0&ack=0`,
+    `${base}/sid-2/events?wait=25&board=&got=0&ack=0&first=1&prev=sid-1`,
+    `${base}/sid-2/events?wait=25&board=&got=0&ack=0`,
+  ])
+  expect(board.prompts).toEqual(['line one\nline two', 'after clear'])
+})
+
+test('keeps polling while a submit waits, sends what came in as one prompt, and acks only after the submit', async ($, on) => {
+  const clock = mock.clock(on)
+  let release = () => {}
+  const replies = [
+    () => ({ status: 200, events: ['move'], seqs: [1], board: 'b1' }),
+    () => ({ status: 200, events: ['review one'], seqs: [2], board: 'b1' }),
+    () => ({ status: 200, events: ['review two', 'review one'], seqs: [3, 2], board: 'b1' }),
+  ]
+  let held = true
+  const board = engine(on, replies, () => (held ? new Promise<void>(r => (release = () => ((held = false), r()))) : Promise.resolve()))
+  await $.session.start({ cwd: 'C:/proj', surface: 'terminal', isInteractive: true })
+  await clock.settle()
+
+  const base = 'http://127.0.0.1:3541/api/sessions/sid-1/events?wait=25'
+  expect(board.prompts).toEqual(['move'])
+  expect(board.urls).toEqual([
+    `${base}&board=&got=0&ack=0&first=1`,
+    `${base}&board=b1&got=1&ack=0`,
+    `${base}&board=b1&got=2&ack=0`,
+    `${base}&board=b1&got=3&ack=0`,
+  ])
+
+  release()
+  await clock.settle()
+  expect(board.prompts).toEqual(['move', 'review one\nreview two'])
+})
+
+test('acks a submitted line on the next poll', async ($, on) => {
+  const clock = mock.clock(on)
+  const replies = [() => ({ status: 200, events: ['review'], seqs: [4], board: 'b1' }), () => ({ status: 200, board: 'b1' })]
+  const board = engine(on, replies)
+  await $.session.start({ cwd: 'C:/proj', surface: 'terminal', isInteractive: true })
+  await clock.settle()
+  expect(board.urls.at(-1)).toContain('board=b1&got=4&ack=4')
+})
+
+test('starts the count again when the board restarts', async ($, on) => {
+  const clock = mock.clock(on)
+  const replies = [
+    () => ({ status: 200, events: ['old'], seqs: [9], board: 'b1' }),
+    () => ({ status: 200, board: 'b1' }),
+    () => ({ status: 200, events: ['new'], seqs: [1], board: 'b2' }),
+  ]
+  const board = engine(on, replies)
+  await $.session.start({ cwd: 'C:/proj', surface: 'terminal', isInteractive: true })
+  await clock.settle()
+  expect(board.prompts).toEqual(['old', 'new'])
+  expect(board.urls.at(-1)).toContain('board=b2&got=1&ack=1')
+})
+
+test('reads a reply from a board without acks', () => {
+  expect(parseReply('{"events":["a",3,"b"]}')).toEqual({ lines: [{ text: 'a', seq: undefined }, { text: 'b', seq: undefined }], board: '' })
+  expect(parseReply('{"events":["a"],"seqs":[5],"board":"b1"}')).toEqual({ lines: [{ text: 'a', seq: 5 }], board: 'b1' })
+})

package/plugin/plugins/claude-code-kanban/tests/show.test.ts

@@ -0,0 +1,137 @@
+import type { On, ToolCallArgs } from 'claude-code'
+import { expect, test } from 'claude-code/testing'
+import { boardPort, dropSkillLine, shownText, TOOL } from '../hooks/show'
+
+const CCK_URL = 'http://127.0.0.1:4100'
+const TERMINAL_ID = 'term-1'
+const TOKEN_FILE = 'C:/cfg/.cck/terminal-tokens/4100.json'
+const LISTING = [
+  'The following skills are available for use with the Skill tool:',
+  '',
+  '- claude-code-kanban:dispatch',
+  '- claude-code-kanban:show',
+  '- claude-code-kanban:kanban: Kanban board CLI',
+  '- meta:show-me: Help the user understand the current topic visually',
+].join('\n')
+
+type Reply = { status: number; body: unknown } | Error
+type Request = { url: string; method?: string; headers?: Record<string, string>; body?: unknown }
+
+function engine(on: On, env: Record<string, string>, reply?: Reply) {
+  const registered: string[] = []
+  const requests: Request[] = []
+  const files: Record<string, string> = { [TOKEN_FILE]: '{"token":"tok-abc"}' }
+  on('env.get', (_$, e) => ({ value: { CLAUDE_CONFIG_DIR: 'C:/cfg', ...env }[e.name] }))
+  on('fs.read', (_$, e) => {
+    const text = files[e.path.replaceAll('\\', '/')]
+    if (text === undefined) throw new Error(`ENOENT: ${e.path}`)
+    return { value: text }
+  })
+  on('session.id', () => ({ value: 'sid-1' }))
+  on('session.start', (_$, e) => ({ cwd: e.cwd }))
+  on('tool.register', (_$, e) => {
+    registered.push(e.name)
+    return { value: { tool: `mcp__claude-code-kanban__${e.name}` } }
+  })
+  on('prompt.attachment', (_$, e) => ({ text: e.text }))
+  on('http.fetch', (_$, e) => {
+    if (!e.url.includes('/show')) return new Promise(() => {})
+    const { method, headers, body } = (e.init ?? {}) as Omit<Request, 'url'>
+    requests.push({ url: e.url, method, headers, body: typeof body === 'string' ? JSON.parse(body) : body })
+    if (!reply) throw new Error('no reply')
+    if (reply instanceof Error) return { deny: reply.message }
+    return { value: { status: reply.status, ok: reply.status < 300, headers: {}, text: JSON.stringify(reply.body) } }
+  })
+  return { registered, requests, files }
+}
+
+const GATE = { CCK_URL, CCK_TERMINAL_ID: TERMINAL_ID }
+const listing = { type: 'skill_listing', text: LISTING, origin: { kind: 'engine' } } as const
+const call = (input: Record<string, unknown>) => ({ tool: TOOL, ...input }) as ToolCallArgs
+
+test('helpers: the port of CCK_URL, the answer line, the listing filter', async () => {
+  expect(boardPort('http://127.0.0.1:4100')).toBe('4100')
+  expect(boardPort('http://localhost:3541/')).toBe('3541')
+  expect(boardPort('http://localhost')).toBe(undefined)
+  expect(shownText({ title: 'Plan', key: 'plan', index: 3, count: 7 })).toBe('Shown "Plan" (plan, 3/7)')
+  expect(shownText({ title: 'Map', key: null, index: 1, count: 1 })).toBe('Shown "Map" (1/1)')
+  expect(shownText({ title: 'Plan', key: 'plan', index: 1, count: 1, path: 'C:/s/p1.md' }, true)).toBe(
+    'Card "Plan" (plan, 1/1) is ready. Write it to C:/s/p1.md; the card refreshes on each save.',
+  )
+  expect(dropSkillLine(LISTING)).toBe(LISTING.replace('- claude-code-kanban:show\n', ''))
+  expect(dropSkillLine('- claude-code-kanban:show: Show a diagram\n- x')).toBe('- x')
+})
+
+test('gate off: no tool, and the skill line is dropped', async ($, on) => {
+  const board = engine(on, { CCK_URL })
+  await $.session.start({ cwd: 'C:/proj', surface: 'terminal', isInteractive: true })
+  expect(board.registered).toEqual([])
+  const { text } = await $.prompt.attachment(listing)
+  expect(text).toBe(LISTING.replace('- claude-code-kanban:show\n', ''))
+})
+
+test('gate on: the tool is registered and the skill line stays', async ($, on) => {
+  const board = engine(on, GATE)
+  await $.session.start({ cwd: 'C:/proj', surface: 'terminal', isInteractive: true })
+  expect(board.registered).toEqual(['show'])
+  const { text } = await $.prompt.attachment(listing)
+  expect(text).toBe(LISTING)
+})
+
+test('a -p run gets no tool', async ($, on) => {
+  const board = engine(on, GATE)
+  await $.session.start({ cwd: 'C:/proj', surface: null, isInteractive: false })
+  expect(board.registered).toEqual([])
+})
+
+test('posts the body with the terminal token and answers with the position', async ($, on) => {
+  const board = engine(on, GATE, {
+    status: 200,
+    body: { id: 'p1', title: 'Plan', key: 'plan', index: 2, count: 3, replaced: false },
+  })
+  await $.session.start({ cwd: 'C:/proj', surface: 'terminal', isInteractive: true })
+  const res = await $.tool.call(call({ title: 'Plan', key: 'plan', kind: 'markdown', file: 'C:/proj/plan.md' }))
+  expect(res.result).toBe('Shown "Plan" (plan, 2/3)')
+  expect(board.requests).toEqual([
+    {
+      url: `${CCK_URL}/api/terminals/${TERMINAL_ID}/show`,
+      method: 'POST',
+      headers: { 'content-type': 'application/json', 'x-terminal-token': 'tok-abc' },
+      body: { sessionId: 'sid-1', title: 'Plan', key: 'plan', kind: 'markdown', file: 'C:/proj/plan.md' },
+    },
+  ])
+})
+
+test('a claim sends no file and answers with the file to write', async ($, on) => {
+  const path = 'C:/s/.cck/show/p1.md'
+  const board = engine(on, GATE, { status: 200, body: { id: 'p1', title: 'Plan', key: 'plan', index: 1, count: 1, path } })
+  await $.session.start({ cwd: 'C:/proj', surface: 'terminal', isInteractive: true })
+  const res = await $.tool.call(call({ title: 'Plan', key: 'plan' }))
+  expect(res.result).toBe(`Card "Plan" (plan, 1/1) is ready. Write it to ${path}; the card refreshes on each save.`)
+  expect(board.requests[0]?.body).toEqual({ sessionId: 'sid-1', title: 'Plan', key: 'plan' })
+})
+
+test('a 400 answer reaches the model as an error with the server text', async ($, on) => {
+  const error = 'file not found: C:/proj/gone.md'
+  engine(on, GATE, { status: 400, body: { error } })
+  await $.session.start({ cwd: 'C:/proj', surface: 'terminal', isInteractive: true })
+  const res = await $.tool.call(call({ title: 'Gone', file: 'C:/proj/gone.md' }))
+  expect(res.deny).toBe(error)
+})
+
+test('a network error reaches the model as an error', async ($, on) => {
+  engine(on, GATE, new Error('connect ECONNREFUSED 127.0.0.1:4100'))
+  await $.session.start({ cwd: 'C:/proj', surface: 'terminal', isInteractive: true })
+  const res = await $.tool.call(call({ title: 'Plan' }))
+  expect(res.deny).toContain(`Cannot reach cck at ${CCK_URL}`)
+  expect(res.deny).toContain('ECONNREFUSED')
+})
+
+test('no token file: no request, an error that names the board', async ($, on) => {
+  const board = engine(on, GATE)
+  delete board.files[TOKEN_FILE]
+  await $.session.start({ cwd: 'C:/proj', surface: 'terminal', isInteractive: true })
+  const res = await $.tool.call(call({ title: 'Plan' }))
+  expect(res.deny).toContain('No terminal token')
+  expect(board.requests).toEqual([])
+})