claude-code-kanban 4.29.0 → 4.31.0

package/lib/plugin-status.js

@@ -0,0 +1,38 @@
+const fs = require('node:fs');
+const path = require('node:path');
+const { isDefaultClaudeDir, displayPath } = require('./claude-dir');
+
+const PLUGIN_ID = 'claude-code-kanban@claude-code-kanban';
+const BUNDLED_MANIFEST = path.join(__dirname, '..', 'plugin', 'plugins', 'claude-code-kanban', '.claude-plugin', 'plugin.json');
+
+function readJson(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+// The claude CLI records installs in <config dir>/plugins/installed_plugins.json, one entry per scope.
+// A user-scope entry wins, because install.js installs at user scope.
+function pluginStatus(claudeDir, bundledManifest = BUNDLED_MANIFEST) {
+  const bundled = readJson(bundledManifest)?.version ?? null;
+  const installs = readJson(path.join(claudeDir, 'plugins', 'installed_plugins.json'))?.plugins?.[PLUGIN_ID];
+  const entries = Array.isArray(installs) ? installs : [];
+  const entry = entries.find((e) => e?.scope === 'user') ?? entries[0];
+  const installed = typeof entry?.version === 'string' ? entry.version : null;
+  const enabled = readJson(path.join(claudeDir, 'settings.json'))?.enabledPlugins?.[PLUGIN_ID] !== false;
+  let state = 'ok';
+  if (!installed) state = 'missing';
+  else if (!enabled) state = 'disabled';
+  else if (bundled && installed !== bundled) state = 'mismatch';
+  return { bundled, installed, state, configDir: displayPath(claudeDir), installCommand: installCommand(claudeDir) };
+}
+
+// --dir rather than CLAUDE_CONFIG_DIR=…, so the same line runs in bash, PowerShell and cmd.
+function installCommand(claudeDir) {
+  const base = 'claude-code-kanban --install --plugin-only';
+  return isDefaultClaudeDir(claudeDir) ? base : `${base} --dir "${claudeDir}"`;
+}
+
+module.exports = { pluginStatus, installCommand, PLUGIN_ID, BUNDLED_MANIFEST };

package/lib/session-cache.js

@@ -0,0 +1,34 @@
+const fs = require('node:fs');
+const { exportSessionCaches, importSessionCaches, sessionCachesDirty } = require('./parsers');
+const { exportParentVerdicts, importParentVerdicts, parentVerdictsDirty } = require('./parent-cache');
+const { exportTaskCounts, importTaskCounts, taskCountsDirty } = require('./task-counts');
+
+// Bump when an entry's shape or meaning changes: a file with another version is ignored.
+const VERSION = 2;
+// A cache this large is not one cck wrote for a normal set of transcripts. Rebuild it cold.
+const MAX_BYTES = 8 * 1024 * 1024;
+
+function loadSessionCache(file) {
+  try {
+    if (fs.statSync(file).size > MAX_BYTES) {
+      fs.rmSync(file, { force: true });
+      return false;
+    }
+    const data = JSON.parse(fs.readFileSync(file, 'utf8'));
+    if (data?.version !== VERSION) return false;
+    importSessionCaches(data);
+    importParentVerdicts(data.parents);
+    importTaskCounts(data.taskCounts);
+    return true;
+  } catch (_) {
+    return false;
+  }
+}
+
+// write(data) must replace the file atomically; server.js passes writeJsonAtomic.
+function saveSessionCache(write) {
+  if (!sessionCachesDirty() && !parentVerdictsDirty() && !taskCountsDirty()) return;
+  write({ version: VERSION, ...exportSessionCaches(), parents: exportParentVerdicts(), taskCounts: exportTaskCounts() });
+}
+
+module.exports = { loadSessionCache, saveSessionCache };

package/lib/session-events.js

@@ -25,6 +25,7 @@ const sessionEventBuckets = new Map();
 // One cap for the whole line rather than one per field, because the description comes
 // last: truncation eats its tail first and leaves the machine-readable head intact.
 function sanitizeEventLine(line) {
+  // biome-ignore lint/suspicious/noControlCharactersInRegex: strips control characters on purpose
   return line.replace(/[\x00-\x1f\x7f]/g, ' ').trim().slice(0, 1500);
 }
 
@@ -81,7 +82,7 @@ function handleSessionEvents(req, res) {
   // bucket is still evicted from the map.
   if (bucket && req.query.first === '1') drain(sessionId, bucket);
 
-  if (bucket && bucket.queue.length) return res.json({ events: drain(sessionId, bucket) });
+  if (bucket?.queue.length) return res.json({ events: drain(sessionId, bucket) });
   if (!wait) return res.json({ events: [] });
 
   const pending = bucket || { queue: [], waiters: new Set() };

package/lib/task-counts.js

@@ -0,0 +1,90 @@
+const fs = require('node:fs');
+const path = require('node:path');
+
+// A task file's status is reused while its size, mtime and inode are unchanged. An mtime can be
+// as coarse as 2 s (FAT), so a file read within that window of its last write could be written
+// again with the same stamp and size. Such a file is not stored and is read again next time.
+const RACY_MS = 3000;
+const SKIP = 'skip';
+const STATUSES = new Set(['completed', 'in_progress', 'pending', SKIP]);
+
+const dirs = new Map();
+let dirty = false;
+
+function readStatus(taskPath) {
+  const text = fs.readFileSync(taskPath, 'utf8');
+  let task;
+  try {
+    task = JSON.parse(text);
+  } catch (_) {
+    return SKIP;
+  }
+  if (task == null || task.metadata?._internal) return SKIP;
+  if (task.status === 'completed' || task.status === 'in_progress') return task.status;
+  return 'pending';
+}
+
+function countTaskDir(dir) {
+  const prev = dirs.get(dir);
+  const next = new Map();
+  const now = Date.now();
+  const tally = { completed: 0, in_progress: 0, pending: 0 };
+  let newestTaskMtime = null;
+
+  for (const file of fs.readdirSync(dir).filter((f) => f.endsWith('.json'))) {
+    const taskPath = path.join(dir, file);
+    let st;
+    try {
+      st = fs.statSync(taskPath);
+    } catch (_) {
+      continue;
+    }
+    const e = prev?.get(file);
+    let status;
+    if (e && e.size === st.size && e.mtimeMs === st.mtimeMs && e.ino === st.ino) {
+      status = e.status;
+      next.set(file, e);
+    } else {
+      try {
+        status = readStatus(taskPath);
+      } catch (_) {
+        continue;
+      }
+      if (now - st.mtimeMs >= RACY_MS) {
+        next.set(file, { size: st.size, mtimeMs: st.mtimeMs, ino: st.ino, status });
+        dirty = true;
+      }
+    }
+    if (status === SKIP) continue;
+    tally[status]++;
+    if (!newestTaskMtime || st.mtime > newestTaskMtime) newestTaskMtime = st.mtime;
+  }
+
+  if (prev && prev.size !== next.size) dirty = true;
+  dirs.set(dir, next);
+  return { completed: tally.completed, inProgress: tally.in_progress, pending: tally.pending, newestTaskMtime };
+}
+
+const taskCountsDirty = () => dirty;
+
+function exportTaskCounts() {
+  dirty = false;
+  return [...dirs].filter(([dir]) => fs.existsSync(dir)).map(([dir, files]) => [dir, [...files]]);
+}
+
+function importTaskCounts(entries) {
+  if (!Array.isArray(entries)) return;
+  const num = (x) => typeof x === 'number';
+  for (const pair of entries) {
+    if (typeof pair?.[0] !== 'string' || !Array.isArray(pair[1])) continue;
+    const files = new Map();
+    for (const item of pair[1]) {
+      const [file, e] = Array.isArray(item) ? item : [];
+      if (typeof file !== 'string' || !e || !num(e.size) || !num(e.mtimeMs) || !num(e.ino) || !STATUSES.has(e.status)) continue;
+      files.set(file, e);
+    }
+    dirs.set(pair[0], files);
+  }
+}
+
+module.exports = { countTaskDir, taskCountsDirty, exportTaskCounts, importTaskCounts };

package/lib/terminal.js

@@ -60,7 +60,7 @@ function readTerminalConfig({ argv = process.argv, env = process.env, getArgValu
   return {
     enabled: argv.includes('--enable-terminal') || cfg.enabled === true,
     shell:
-      (getArgValue && getArgValue('terminal-shell')) ||
+      getArgValue?.('terminal-shell') ||
       env.CCK_TERMINAL_SHELL ||
       (typeof cfg.shell === 'string' && cfg.shell) ||
       null,
@@ -151,6 +151,7 @@ function parseNewSpec(msg) {
   if (typeof worktree !== 'boolean' && !(typeof worktree === 'string' && WORKTREE_RE.test(worktree))) return 'worktree name';
   const model = msg.model || null;
   if (model && !MODELS.has(model)) return 'model';
+  // biome-ignore lint/suspicious/noControlCharactersInRegex: strips ESC so a prompt cannot carry terminal sequences
   const prompt = typeof msg.prompt === 'string' ? msg.prompt.replace(/\x1b/g, '').trim() : '';
   if (prompt.length > MAX_PROMPT) return 'prompt';
   return { cwd: msg.cwd, name: name || null, worktree, model, prompt: prompt || null };
@@ -179,11 +180,15 @@ 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.
-function ptyEnv({ claudeDir, isDefaultDir, noFlicker }) {
+// CCK_URL pins the CLI and the postman 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 };
   for (const k of STRIP_ENV) delete env[k];
   if (isDefaultDir) delete env.CLAUDE_CONFIG_DIR;
   else env.CLAUDE_CONFIG_DIR = claudeDir;
+  if (cckUrl) env.CCK_URL = cckUrl;
+  else delete env.CCK_URL;
   // xterm.js #5801: a clear inside a synchronized-output block jumps the viewport.
   if (noFlicker) env.CLAUDE_CODE_NO_FLICKER = '1';
   env.TERM = 'xterm-256color';
@@ -344,7 +349,7 @@ function createTerminalService(o) {
 
   function spawnSession(id, mode, cwdCandidate, cols, rows, spec, extraEnv) {
     const cwd = cwdCandidate && fs.existsSync(cwdCandidate) ? cwdCandidate : os.homedir();
-    const env = { ...ptyEnv({ claudeDir: o.claudeDir, isDefaultDir: o.isDefaultDir, noFlicker: config.noFlicker }), ...extraEnv };
+    const env = { ...ptyEnv({ claudeDir: o.claudeDir, isDefaultDir: o.isDefaultDir, noFlicker: config.noFlicker, cckUrl: o.serverUrl?.() }), ...extraEnv };
     // Git Bash's login profile cds to $HOME unless this is set.
     if (shellFamily(shell) === 'gitbash') env.CHERE_INVOKING = '1';
     const proc = pty.spawn(shell, shellArgs(shell, claudeArgsFor(mode, id, spec)), {
@@ -596,4 +601,4 @@ function createTerminalService(o) {
   return { token, handleUpgrade, clientConfig, list, isRunning, end, authorized, startNew, shutdown, unavailableReason };
 }
 
-module.exports = { createTerminalService, readTerminalConfig, shellArgs, resolveShell, claudeArgsFor, parseNewSpec, findPickProcess, tokenMatches };
+module.exports = { createTerminalService, readTerminalConfig, ptyEnv, shellArgs, resolveShell, claudeArgsFor, parseNewSpec, findPickProcess, tokenMatches };

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "claude-code-kanban",
-  "version": "4.29.0",
+  "version": "4.31.0",
   "description": "A web-based Kanban board for viewing Claude Code tasks with agent teams support",
   "main": "server.js",
+  "type": "commonjs",
   "bin": {
     "claude-code-kanban": "server.js"
   },

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

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-kanban",
-  "version": "2.14.0",
+  "version": "2.15.0",
   "description": "claude-code-kanban dashboard integration: agent activity tracking, context statusline, skills to drive the board from a session and to follow it",
   "experimental": {
     "monitors": "./monitors.json"

package/plugin/plugins/claude-code-kanban/scripts/postman.js

@@ -38,7 +38,10 @@ const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 // Re-read every cycle rather than caching: it is how we follow the board across a
 // restart onto a different port. A file left behind by a crashed server names a port
 // something else may now hold, so trust it only while its pid is alive.
+// CCK_URL comes from the board whose terminal started this session. That board owns the
+// session's queue, and server.json may name another board on the same config dir.
 function serverUrl() {
+  if (process.env.CCK_URL) return process.env.CCK_URL.replace(/\/+$/, '');
   const { port, pid } = JSON.parse(fs.readFileSync(SERVER_INFO, 'utf8'));
   if (pid) process.kill(pid, 0);
   return `http://127.0.0.1:${port}`;

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

@@ -9,58 +9,28 @@ disable-model-invocation: true
 
 This session id is `${CLAUDE_SESSION_ID}`, substituted when the skill loads.
 
-An argument names the section below that handles it; with no argument, open the current session. Prefer the bare `claude-code-kanban` binary, falling back to `npx claude-code-kanban` when it is off PATH or the user asks for npx.
+An argument names the command that handles it; with no argument, open the current session. Prefer the bare `claude-code-kanban` binary, falling back to `npx claude-code-kanban` when it is off PATH or the user asks for npx.
 
-To be driven *by* the board instead — card moves arriving as instructions — the user types `/claude-code-kanban:kanban-follow`.
-
-## `open` — the current session
-
-Pins the session and switches the board to the Active tab.
-
-```bash
-claude-code-kanban session open ${CLAUDE_SESSION_ID}
-```
-
-## `pin` — keep the session visible
-
-```bash
-claude-code-kanban session pin ${CLAUDE_SESSION_ID}            # pin
-claude-code-kanban session pin ${CLAUDE_SESSION_ID} --sticky   # always at the top
-claude-code-kanban session pin ${CLAUDE_SESSION_ID} --unpin    # clear
-claude-code-kanban session pins                                # list pinned; --sticky narrows
-```
-
-## `preview` — open a file in the modal
-
-Markdown or standalone HTML. HTML renders in a sandboxed iframe, so sibling assets like `./style.css` do not load. Relative paths are fine — the server resolves them.
-
-```bash
-claude-code-kanban preview-doc <file.md|.html> --session ${CLAUDE_SESSION_ID}
-```
-
-## `link` — attach a doc without the modal
-
-Adds the file to the session's linked docs in the sidebar. Any extension, and nothing pops up, so it is the safe choice while the user is working.
+The CLI help is the reference, and it always matches the installed binary. Read it before you run a command, instead of guessing flags:
 
 ```bash
-claude-code-kanban link-doc <path> --session ${CLAUDE_SESSION_ID}            # link
-claude-code-kanban link-doc <path> --session ${CLAUDE_SESSION_ID} --unlink   # remove
+claude-code-kanban help                        # every command
+claude-code-kanban help <command>              # its subcommands
+claude-code-kanban help <command> <subcommand> # flags and examples
 ```
 
-## `list` / `view` / `peek` — read-only
+| Argument | Command |
+|---|---|
+| `open` (or none) | `session open ${CLAUDE_SESSION_ID}` |
+| `pin` / `unpin` | `session pin ${CLAUDE_SESSION_ID}` (`--sticky`, `--unpin`) |
+| `preview` | `preview-doc <file> --session ${CLAUDE_SESSION_ID}` — opens a modal on the user's screen |
+| `link` | `link-doc <file\|url> --session ${CLAUDE_SESSION_ID}` — no modal, so it is the safe choice while the user is working. An http(s) URL (a PR, an artifact) opens in a new tab |
+| `list` / `search` | `session list`, `session search <text>` |
+| `view` / `peek` | `session view <id>`, `session peek <id>` |
+| tasks, projects | `task list`, `project list` |
 
-```bash
-claude-code-kanban session list --active                            # recent active sessions
-claude-code-kanban session list --project <name>                    # filter by project
-claude-code-kanban session list --days 0.5 --limit all              # touched in last 12h, uncapped
-claude-code-kanban session view ${CLAUDE_SESSION_ID}                # full stats for current session
-claude-code-kanban session peek ${CLAUDE_SESSION_ID} --limit 20     # last 20 messages (server caps at 50)
-```
-
-`session list` shows 10 rows and always includes pinned sessions, sticky first (`--no-pins` disables both). `--json` works on any list-style verb.
+To be driven *by* the board instead — card moves arriving as instructions — the user types `/claude-code-kanban:kanban-follow`.
 
 ## Troubleshooting
 
-`claude-code-kanban help <command>` prints the authoritative flags — read it instead of guessing.
-
-- **"Cannot reach cck server…"** → the error names the port it tried. Ask the user to start the server with `claude-code-kanban`. If they run it elsewhere, set `PORT=<n>` when invoking the CLI.
+- **"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 they run it elsewhere, set `PORT=<n>` or `CCK_URL=<url>` when invoking the CLI.