claude-code-kanban 7.4.0 → 7.5.0

package/lib/terminal.js

@@ -251,7 +251,7 @@ function screenText(term) {
 
 // Claude Code keeps .claude.json beside ~/.claude when CLAUDE_CONFIG_DIR is unset but
 // inside the dir when set, so the default dir must stay unset, not be spelled out.
-// CCK_URL pins the CLI and the postman to this board: two boards on one config dir share
+// CCK_URL pins the CLI and the doorbell mod to this board: two boards on one config dir share
 // one server.json, and the last one started owns it.
 function ptyEnv({ claudeDir, isDefaultDir, noFlicker, cckUrl }) {
   const env = { ...process.env };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-kanban",
-  "version": "7.4.0",
+  "version": "7.5.0",
   "description": "A web-based Kanban board for viewing Claude Code tasks with agent teams support",
   "main": "server.js",
   "type": "commonjs",

package/plugin/plugins/claude-code-kanban/.claude-plugin/plugin.json

@@ -1,8 +1,5 @@
 {
   "name": "claude-code-kanban",
-  "version": "2.25.2",
-  "description": "claude-code-kanban dashboard integration: agent activity tracking, context and cost tracking, skills to drive the board from a session and to follow it",
-  "experimental": {
-    "monitors": "./monitors.json"
-  }
+  "version": "3.0.1",
+  "description": "claude-code-kanban dashboard integration: agent activity tracking, context and cost tracking, board moves and reviews delivered to the session, and skills to drive the board from a session"
 }

package/plugin/plugins/claude-code-kanban/hooks/doorbell.ts

@@ -0,0 +1,80 @@
+import type { EngineInterface, Register } from 'claude-code'
+import { cckRoot } from './context'
+
+// $.http.fetch gives up on a request after 30 s, so the poll asks the board to answer sooner.
+export const WAIT_SEC = 25
+export const RETRY_MS = 10_000
+
+export function boardUrl(cckUrl: string | undefined, serverJson: string | undefined) {
+  if (cckUrl) return cckUrl.replace(/\/+$/, '')
+  try {
+    const { port } = JSON.parse(serverJson ?? '')
+    return Number.isInteger(port) ? `http://127.0.0.1:${port}` : undefined
+  } catch {
+    return undefined
+  }
+}
+
+let cck: Promise<string> | undefined
+
+// The engine does not follow $ into an imported function, so only the path rule is shared.
+function cckDir($: EngineInterface) {
+  cck ??= Promise.all([$.env.get('CLAUDE_CONFIG_DIR'), $.env.get('HOME'), $.env.get('USERPROFILE')]).then(
+    ([configDir, home, userProfile]) => cckRoot(configDir, home, userProfile),
+  )
+  return cck
+}
+
+// Read on every poll, so the mod follows a board that restarted on another port. CCK_URL comes
+// from the board whose terminal started this session, which owns the session's queue.
+async function findBoard($: EngineInterface) {
+  const cckUrl = await $.env.get('CCK_URL')
+  if (cckUrl) return boardUrl(cckUrl, undefined)
+  try {
+    return boardUrl(undefined, await $.fs.read(`${await cckDir($)}/server.json`))
+  } catch {
+    return undefined
+  }
+}
+
+async function poll($: EngineInterface, url: string, sessionId: string, first: boolean) {
+  const query = `wait=${WAIT_SEC}${first ? '&first=1' : ''}`
+  const r = await $.http.fetch(`${url}/api/sessions/${encodeURIComponent(sessionId)}/events?${query}`)
+  if (!r.ok) throw new Error(`HTTP ${r.status}`)
+  const { events } = JSON.parse(r.text) as { events?: unknown }
+  return Array.isArray(events) ? events.filter((e): e is string => typeof e === 'string') : []
+}
+
+// The session id changes on /clear, so it is read for every poll. The first poll for an id drops
+// what the board queued before this session listened: a move from hours ago is not an instruction.
+async function listen($: EngineInterface) {
+  let attached: string | undefined
+  for (;;) {
+    const [url, sessionId] = await Promise.all([findBoard($), $.session.id()])
+    let events: string[] | undefined
+    try {
+      if (url) events = await poll($, url, sessionId, attached !== sessionId)
+    } catch {}
+    if (!events) {
+      await $.clock.sleep(RETRY_MS)
+      continue
+    }
+    attached = sessionId
+    // A submit waits until the session is idle, and one prompt keeps a burst of moves in one turn.
+    if (events.length) await $.prompt.submit({ text: events.join('\n') }).catch(() => {})
+  }
+}
+
+let listening = false
+
+// Only a session with a person at the prompt listens: a -p run ends on its own and must not wait on an open poll.
+export const register: Register = on => {
+  on('session.start', { isInteractive: true }, async ($, e, next) => {
+    const result = await next(e)
+    if (!listening) {
+      listening = true
+      void listen($)
+    }
+    return result
+  })
+}

package/plugin/plugins/claude-code-kanban/hooks/index.ts

@@ -1,8 +1,10 @@
 import type { Register } from 'claude-code'
 import { register as activity } from './activity'
 import { register as context } from './context'
+import { register as doorbell } from './doorbell'
 
 export const register: Register = (on, options) => {
   context(on, options)
   activity(on, options)
+  doorbell(on, options)
 }

package/plugin/plugins/claude-code-kanban/skills/kanban/SKILL.md

@@ -19,7 +19,7 @@ This session id is `${CLAUDE_SESSION_ID}`. `--session` defaults to it through `$
 | `session` | `list` · `search <text>` · `open <id>` focuses it · `view <id>` stats and transcript path · `plan <id>` · `agents <id>` · `pin <id>` |
 | `task` | `list` for a session, a project or the whole board |
 | `project` | `list` |
-| `dispatch` | `start`, `list` — run `/claude-code-kanban:dispatch` instead |
+| `dispatch` | `start`, `list`, `end` — run `/claude-code-kanban:dispatch` instead |
 
 ## Run a command
 
@@ -38,8 +38,6 @@ To show the user a page, a prototype or a collage of screenshots, write it as HT
 
 Read its transcript. `session view <id>` and `session search <text> --json` print the path.
 
-To have card moves arrive in this session as instructions, the user types `/claude-code-kanban:follow`.
-
 ## Troubleshooting
 
 - **"Cannot reach cck server…"** → the error names the config dir and the port it tried. Ask the user to start the server with `claude-code-kanban`. If it runs elsewhere, set `PORT=<n>` or `CCK_URL=<url>` when invoking the CLI.

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

@@ -0,0 +1,74 @@
+import type { On } from 'claude-code'
+import { expect, mock, test } from 'claude-code/testing'
+import { boardUrl, 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)
+})
+
+function engine(on: On, replies: (() => { status: number; events?: string[] })[]) {
+  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 = [] } = reply()
+    return { value: { status, ok: status < 300, headers: {}, text: JSON.stringify({ events }) } }
+  })
+  on('prompt.submit', (_$, e) => {
+    prompts.push(e.text)
+    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()
+
+  expect(board.prompts).toEqual(['line one\nline two'])
+  expect(board.urls).toEqual([
+    'http://127.0.0.1:3541/api/sessions/sid-1/events?wait=25&first=1',
+    'http://127.0.0.1:3541/api/sessions/sid-1/events?wait=25',
+  ])
+
+  await clock.advance(RETRY_MS)
+  expect(board.urls.slice(2)).toEqual([
+    'http://127.0.0.1:3541/api/sessions/sid-1/events?wait=25',
+    'http://127.0.0.1:3541/api/sessions/sid-2/events?wait=25&first=1',
+    'http://127.0.0.1:3541/api/sessions/sid-2/events?wait=25',
+  ])
+  expect(board.prompts).toEqual(['line one\nline two', 'after clear'])
+})