claude-code-kanban 7.6.1 → 7.8.0

package/hub-app.json

@@ -5,10 +5,10 @@
   "icon": "columns",
   "run": { "entry": "server.js", "defaultPort": 3541 },
   "publishes": ["session.changed"],
-  "keys": { "keeps": ["ctrl+alt+n", "ctrl+alt+r", "ctrl+alt+s"] },
+  "keys": { "keeps": ["ctrl+alt+n", "ctrl+alt+r", "ctrl+alt+s", "ctrl+shift+k", "ctrl+shift+p", "ctrl+shift+z"] },
   "plugin": {
-    "id": "claude-code-kanban@claude-code-kanban",
-    "path": "plugin/plugins/claude-code-kanban",
+    "marketplace": "plugin",
+    "name": "claude-code-kanban",
     "install": "claude-code-kanban --install --yes"
   },
   "provides": {

package/install.js

@@ -163,15 +163,7 @@ async function runInstall({ yes = false } = {}) {
     // on stdout — so a re-copied plugin keeps running from the old cached version
     // until `update` pulls the new one in. That is how a config dir ends up serving
     // a plugin older than the board it talks to.
-    if (alreadyInstalled) {
-      const upgrade = runCLI('claude plugin update claude-code-kanban', ['already at the latest']);
-      if (upgrade.ok) {
-        const line = (upgrade.output || '').split('\n').find(l => l.includes('updated from'));
-        console.log(`    ${green('✓')} ${line ? line.replace(/^[^A-Za-z]*/, '') : 'Already at the latest version'}`);
-      } else {
-        console.log(`    ${yellow('⚠')} Plugin update failed: ${upgrade.error}`);
-      }
-    }
+    if (alreadyInstalled) updatePlugin(PLUGIN_ID, 'Plugin');
   } else {
     console.log(`    ${dim('Skipped')}`);
   }
@@ -181,6 +173,16 @@ async function runInstall({ yes = false } = {}) {
   printSummary(failed);
 }
 
+function updatePlugin(id, label) {
+  const upgrade = runCLI(`claude plugin update ${id}`, ['already at the latest']);
+  if (upgrade.ok) {
+    const line = (upgrade.output || '').split('\n').find(l => l.includes('updated from'));
+    console.log(`    ${green('✓')} ${label}: ${line ? line.replace(/^[^A-Za-z]*/, '') : 'already at the latest version'}`);
+  } else {
+    console.log(`    ${yellow('⚠')} ${label} update failed: ${upgrade.error}`);
+  }
+}
+
 function printSummary(failed = false) {
   if (failed) {
     console.log(`\n  ${red('Setup incomplete — see the errors above.')}\n`);

package/kanbot/.claude-plugin/plugin.json

@@ -0,0 +1,5 @@
+{
+  "name": "cck-kanbot",
+  "version": "0.1.0",
+  "description": "The board's own assistant: one agent, loaded with --plugin-dir by the kanbot chat. Moves into claude-code-kanban once it settles."
+}

package/kanbot/agents/kanbot.md

@@ -0,0 +1,34 @@
+---
+name: kanbot
+description: Kanbot, the assistant built into the claude-code-kanban board. Answers questions, looks things up, drives the board through the claude-code-kanban CLI and hands project work to other sessions.
+color: orange
+memory: project
+---
+
+You are Kanbot, a general assistant built into the claude-code-kanban board (cck). The user talks to you in a popover on the board, often about 55 columns wide: answer in a few short lines or a short list, in plain words.
+
+You help with anything: questions, research, reading code and transcripts, and running the board. You are the user's front desk, not a worker on their projects.
+
+## Delegate the work
+
+Work that changes a project (code edits, fixes, features, refactors, long builds or test runs) belongs in its own session, where the user can watch and steer it. Do not do it yourself. Instead:
+
+- Suggest a session for it: name the project folder and write the task as a short, self-contained prompt.
+- When the user agrees, start it with the dispatch skill (`/claude-code-kanban:dispatch`) or `claude-code-kanban dispatch start`, or give the user the command to run.
+- For work already running in a session, point the user to that session or send the task there, not to you.
+
+Small things that change no project you may do yourself: answer, explain, search, read files, sketch a plan, write a scratch note.
+
+## Which session
+
+You cannot see which session the user has open on the board. When the user means one ("this session", "the siem one"), find it with `claude-code-kanban session search <text>` or `session list`, and ask when more than one fits. Keep using that session until the user names another.
+
+`session list` and `group list` show what the sidebar's Active view shows; add `--all` for every session. `group list --json` gives each member's title, branch, status and pin, so you need no `session list` to describe a group.
+
+Your own session is hidden from the board, so the CLI's default session is yours, not the user's. Pass `--session <id>` with the user's session to every command that takes `--session`.
+
+## Where to look
+
+- **A session**: `session view <id>` prints its project and transcript path. Read the transcript and task files.
+- **cck itself** (keys, themes, panes, settings, the terminal, the hub): read the docs at https://nikiforovall.blog/claude-code-kanban/ with WebFetch. Start from `reference/keyboard-shortcuts/`, `reference/configuration/` or the `guides/` page for the feature.
+- **The board CLI**: its top-level help and this board's URL are below. Read `claude-code-kanban help <command> <subcommand>` for the flags before you run a command.

package/lib/http-error.js

@@ -1,6 +1,7 @@
 // An error a route answers with `status`; `code` is the machine-readable reason, where one is set.
+// `expose` lets the API error handler send the message for a 5xx too, because it was written for the user.
 function httpError(status, message, code) {
-  return Object.assign(new Error(message), { status, code });
+  return Object.assign(new Error(message), { status, code, expose: true });
 }
 
 module.exports = { httpError };

package/lib/kanbot.js

@@ -0,0 +1,86 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { encodeProjectDirName } = require('./claude-dir');
+const { MODELS } = require('./terminal');
+const { topHelp } = require('../cli');
+
+const PLUGIN_DIR = path.join(__dirname, '..', 'kanbot');
+const AGENT = 'cck-kanbot:kanbot';
+const TRANSCRIPT_RE = /^([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\.jsonl$/i;
+
+function kanbotOn(cfg) {
+  return cfg?.kanbot?.enabled !== false;
+}
+
+function kanbotModel(cfg) {
+  const model = cfg?.kanbot?.model;
+  return MODELS.has(model) ? model : null;
+}
+
+function writeHelpPrompt(cwd, boardUrl) {
+  const file = path.join(cwd, 'cli-help.md');
+  const board = boardUrl ? `This board runs at ${boardUrl}; \`$CCK_URL\` holds the same URL, so the CLI talks to it.\n\n` : '';
+  fs.writeFileSync(file, `# claude-code-kanban CLI\n\n${board}\`claude-code-kanban help\` prints:\n\n\`\`\`\n${topHelp()}\n\`\`\`\n`);
+  return file;
+}
+
+function kanbotArgs(cwd, claudeDir, boardUrl) {
+  return ['--plugin-dir', PLUGIN_DIR, '--agent', AGENT, '--append-system-prompt-file', writeHelpPrompt(cwd, boardUrl), '--add-dir', claudeDir];
+}
+
+function createKanbot({ cckDir, projectsDir }) {
+  const cwd = path.join(cckDir, 'kanbot');
+  const projectDir = path.join(projectsDir, encodeProjectDirName(cwd));
+  const ownIds = new Set();
+  let sessionId = null;
+
+  function transcriptIds() {
+    try {
+      return fs.readdirSync(projectDir).map((f) => TRANSCRIPT_RE.exec(f)?.[1]).filter(Boolean);
+    } catch {
+      return [];
+    }
+  }
+
+  // The newest transcript is the chat to resume: /clear starts a new one in the same folder.
+  function newestTranscript() {
+    let best = null;
+    for (const id of transcriptIds()) {
+      const mtime = fs.statSync(path.join(projectDir, `${id}.jsonl`), { throwIfNoEntry: false })?.mtimeMs;
+      if (mtime && (!best || mtime > best.mtime)) best = { id, mtime };
+    }
+    return best?.id || null;
+  }
+
+  for (const id of transcriptIds()) ownIds.add(id);
+
+  return {
+    cwd,
+    ptyId: null,
+    isOwnPath: (p) => p === projectDir || p.startsWith(projectDir + path.sep),
+    isOwnProjectDirName: (name) => name === path.basename(projectDir),
+    isOwnSession: (id) => ownIds.has(id),
+    // A fresh start writes hook files under its id before claude writes a transcript.
+    own: (id) => ownIds.add(id),
+    onTranscript(filePath, event) {
+      const id = TRANSCRIPT_RE.exec(path.basename(filePath))?.[1];
+      if (event === 'unlink' || !id) return;
+      sessionId = id;
+      ownIds.add(id);
+    },
+    startSpec({ model = null, boardUrl = null } = {}) {
+      fs.mkdirSync(cwd, { recursive: true });
+      sessionId = newestTranscript();
+      const extraArgs = kanbotArgs(cwd, path.dirname(cckDir), boardUrl);
+      // Not restored on a cck restart: a restore would bring it back without the agent args.
+      return { cwd, name: 'kanbot', model, extraArgs, restore: false, ...(sessionId && { resume: sessionId }) };
+    },
+    get sessionId() {
+      return sessionId;
+    },
+  };
+}
+
+module.exports = { kanbotOn, kanbotModel, createKanbot, KANBOT_AGENT: AGENT, KANBOT_PLUGIN_DIR: PLUGIN_DIR };

package/lib/live-sessions.js

@@ -16,7 +16,7 @@ function readLiveSessions(sessionsDir) {
     try {
       const s = JSON.parse(fs.readFileSync(path.join(sessionsDir, file), 'utf8'));
       if (s?.sessionId && s.kind === 'interactive') {
-        sessions.push({ sessionId: s.sessionId, pid: s.pid || null, cwd: s.cwd || null, startedAt: s.startedAt || 0, status: s.status || null, name: s.name || null });
+        sessions.push({ sessionId: s.sessionId, pid: s.pid || null, cwd: s.cwd || null, startedAt: s.startedAt || 0, status: s.status || null, statusUpdatedAt: s.statusUpdatedAt || null, name: s.name || null });
       }
     } catch { /* skip invalid */ }
   }

package/lib/owner-routing.js

@@ -0,0 +1,53 @@
+// `dispatched` is the store from lib/retention.js; `listToSessions[listId]` is `{[sessionId]: …}`
+// from the plugin's task maps; `metadata` is a getter for session metadata.
+
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const linkKey = (list, owner) => `${list}\n${owner}`;
+
+// A list's candidates are the sessions the list's session dispatched (a session's own list)
+// and the sessions mapped to the list (a shared list). `owner` matches the live `agentName`,
+// which follows /rename the same way SendMessage does. A name two candidates share gets no link.
+function ownerLinks(listIds, { dispatched, listToSessions, metadata }) {
+  const candidates = new Map();
+  const add = (list, id) => {
+    if (!candidates.has(list)) candidates.set(list, new Set());
+    candidates.get(list).add(id);
+  };
+  for (const [id, e] of dispatched.entries()) if (listIds.has(e?.parent)) add(e.parent, id);
+  for (const list of listIds) for (const id of Object.keys(listToSessions[list] || {})) add(list, id);
+
+  const links = new Map();
+  if (candidates.size) {
+    const meta = metadata();
+    for (const [list, ids] of candidates) {
+      for (const id of ids) {
+        const name = meta[id]?.agentName;
+        if (!name) continue;
+        const key = linkKey(list, name);
+        links.set(key, links.has(key) ? null : id);
+      }
+    }
+  }
+  return (list, owner) => links.get(linkKey(list, owner)) || null;
+}
+
+// Who gets a board move on a shared list: the owner, else the one session that dispatched the
+// list's sessions, else no one, because a line to every worker makes them race for the task.
+// Null when the rule does not apply: a session's own list goes to that session, the orchestrator,
+// even for a child's card, and a list with no task map (a team board) keeps its old routing.
+function moveRecipients(listId, owner, inputs) {
+  const mapped = !UUID_RE.test(listId) && inputs.listToSessions[listId];
+  if (!mapped) return null;
+  const id = owner && ownerLinks(new Set([listId]), inputs)(listId, owner);
+  if (id) return [id];
+  const onList = Object.keys(mapped);
+  const on = new Set(onList);
+  const parentOf = (s) => inputs.dispatched.get(s)?.parent || null;
+  // A session on the list that dispatched others on it is the orchestrator; its own parent is
+  // outside the swarm and does not count.
+  const orchestrators = new Set(onList.map(parentOf).filter((p) => on.has(p)));
+  const parents = new Set(onList.filter((s) => !orchestrators.has(s)).map(parentOf).filter(Boolean));
+  return parents.size === 1 ? [...parents] : [];
+}
+
+module.exports = { ownerLinks, moveRecipients };

package/lib/preview-action.js

@@ -0,0 +1,55 @@
+const { oneLine } = require('./one-line');
+const { httpError } = require('./http-error');
+
+const ACTION_RE = /^[A-Za-z0-9._-]{1,64}$/;
+const KIND_RE = /^[a-z]{1,20}$/;
+const MAX_FIELDS = 50;
+const MAX_VALUES = 50;
+const MAX_CHARS = 4000;
+
+// The `source` of a review or an action: the view it came from. The caller resolves `path`.
+function parseReviewSource(source) {
+  if (!KIND_RE.test(source?.kind || '')) throw httpError(400, 'source.kind is required');
+  // The label is pasted into the terminal; an ESC could end bracketed paste and submit text.
+  const label = oneLine(source.label, 200);
+  if (!label) throw httpError(400, 'source.label is required');
+  return {
+    kind: source.kind,
+    label,
+    path: source.kind === 'file' ? source.path : null,
+    locate: oneLine(source.locate, 600) || null,
+  };
+}
+
+// The fields come from a form inside a sandboxed card, so the card's author picks the names and
+// values: they are capped here and printed as JSON, never as markdown.
+function parseActionBody(body) {
+  const { source, action, label, data } = body || {};
+  const src = parseReviewSource(source);
+  if (!ACTION_RE.test(action || '')) throw httpError(400, 'action must match [A-Za-z0-9._-]{1,64}');
+  const fields = {};
+  const entries = Object.entries(data && typeof data === 'object' && !Array.isArray(data) ? data : {});
+  if (entries.length > MAX_FIELDS) throw httpError(400, `data holds at most ${MAX_FIELDS} fields`);
+  for (const [k, v] of entries) {
+    const list = Array.isArray(v) ? v : [v];
+    if (list.length > MAX_VALUES || list.some((x) => typeof x !== 'string')) {
+      throw httpError(400, 'each field is a string or a list of strings');
+    }
+    const vals = list.map((x) => x.slice(0, MAX_CHARS));
+    fields[k.slice(0, 200)] = Array.isArray(v) ? vals : vals[0];
+  }
+  return { src, action, label: oneLine(label, 200) || action, fields };
+}
+
+function formatActionMarkdown({ src, action, label, fields }) {
+  const parts = [
+    `# Action "${action}" on ${src.path || src.label}`,
+    '',
+    `The user pressed "${label}" on the page in the board. Treat it as the user's answer.`,
+  ];
+  if (src.locate) parts.push('', src.locate);
+  if (Object.keys(fields).length) parts.push('', '```json', JSON.stringify(fields, null, 2), '```');
+  return `${parts.join('\n')}\n`;
+}
+
+module.exports = { parseReviewSource, parseActionBody, formatActionMarkdown };

package/lib/session-events.js

@@ -68,6 +68,10 @@ function formatReviewSubmitted(count, label, reviewFile) {
   return `${EVENT_PREFIX} Address ${comments} on ${label}: ${reviewFile}`;
 }
 
+function formatActionSubmitted(action, label, file) {
+  return `${EVENT_PREFIX} User submitted "${action}" on ${label}: ${file}`;
+}
+
 // Names this board run in every reply, so a mod drops `got` and `ack` counted against a run
 // that has since restarted.
 const BOARD_RUN = crypto.randomBytes(6).toString('hex');
@@ -260,6 +264,7 @@ module.exports = {
   formatTaskMoved,
   boardEventsOn,
   formatReviewSubmitted,
+  formatActionSubmitted,
   hasDoorbell,
   configureSessionEvents,
   enqueueSessionEvent,

package/lib/session-pins.js

@@ -0,0 +1,99 @@
+// Session pins: which sessions the sidebar pins, and which of those are sticky. The board, the CLI
+// and every board on the same config dir share them through `.cck/pins.json`, a flat
+// {sessionId: "pinned"|"sticky"} map. Each write changes only the sessions it names, so the last
+// write for a session wins.
+
+const { httpError } = require('./http-error');
+
+const MAX_PINS = 1000;
+const MAX_REF = 4096;
+const STATES = new Set(['pinned', 'sticky']);
+
+const fail = (status, message) => {
+  throw httpError(status, message);
+};
+
+const isRef = (s) => typeof s === 'string' && s.length > 0 && s.length <= MAX_REF;
+
+function readPins(obj) {
+  const out = {};
+  if (!obj || typeof obj !== 'object' || Array.isArray(obj)) return out;
+  let n = 0;
+  for (const [id, state] of Object.entries(obj)) {
+    if (n >= MAX_PINS) break;
+    if (isRef(id) && STATES.has(state)) {
+      out[id] = state;
+      n++;
+    }
+  }
+  return out;
+}
+
+/**
+ * @param {object} o
+ * @param {() => object|null|undefined} o.load `undefined` means keep what is in memory: the file has
+ *   not changed since the last load, or cannot be read
+ * @param {(data: object) => void} o.save throws when the pins must not or cannot be written
+ */
+function createSessionPinStore({ load, save }) {
+  let pins = {};
+
+  // Another board on the same config dir writes the same file. Returns the sessions whose state
+  // changed, as [{id, state}] with state 'none' for a removed pin.
+  function reload() {
+    const saved = load();
+    if (saved === undefined) return [];
+    const before = pins;
+    pins = readPins(saved);
+    return diff(before, pins);
+  }
+  reload();
+
+  const state = () => ({ pins });
+
+  function commit(next) {
+    save(next);
+    const changed = diff(pins, next);
+    pins = next;
+    return changed;
+  }
+
+  function set(ids, s) {
+    if (!Array.isArray(ids) || !ids.length || !ids.every(isRef)) fail(400, 'ids is required');
+    if (s !== 'none' && !STATES.has(s)) fail(400, 'state must be none|pinned|sticky');
+    const next = { ...pins };
+    for (const id of ids) {
+      if (s === 'none') delete next[id];
+      else next[id] = s;
+    }
+    if (Object.keys(next).length > MAX_PINS) fail(422, `at most ${MAX_PINS} pins`);
+    return commit(next);
+  }
+
+  // A browser's lists from before the server kept pins. Each origin sends its own once, so every
+  // import is merged; a session the server already holds keeps its state.
+  function importLocal({ pinned, sticky } = {}) {
+    const next = { ...pins };
+    const add = (list, s) => {
+      for (const id of Array.isArray(list) ? list : []) {
+        if (Object.keys(next).length >= MAX_PINS) return;
+        if (isRef(id) && !(id in next)) next[id] = s;
+      }
+    };
+    add(sticky, 'sticky');
+    add(pinned, 'pinned');
+    return commit(next);
+  }
+
+  return { state, reload, set, importLocal };
+}
+
+function diff(before, after) {
+  const out = [];
+  for (const id of new Set([...Object.keys(before), ...Object.keys(after)])) {
+    if (before[id] !== after[id]) out.push({ id, state: after[id] || 'none' });
+  }
+  return out;
+}
+
+module.exports = { createSessionPinStore };

package/lib/stamped-json-file.js

@@ -0,0 +1,49 @@
+const path = require('node:path');
+const { readFileSync, statSync } = require('node:fs');
+const { httpError } = require('./http-error');
+
+// A JSON file that the board keeps in memory and other boards on the same config dir also write.
+// `load` answers undefined while the file's mtime and size are the ones last read or written, and
+// null when there is no file. A file that cannot be read or parsed (a hand edit, a cut-off write,
+// EBUSY while another board renames over it) also answers undefined, so memory keeps the last good
+// state, and the next load tries again. While it cannot be read, `save` refuses with a 503, because
+// the write would replace the user's file. A failed write is a 503 too.
+function stampedJsonFile(file, writeJsonAtomic) {
+  const name = path.basename(file);
+  const stampOf = () => {
+    try {
+      const s = statSync(file);
+      return `${s.mtimeMs}:${s.size}`;
+    } catch {
+      return null;
+    }
+  };
+  let stamp;
+  let readError = null;
+  return {
+    load: () => {
+      const next = stampOf();
+      if (next === stamp && !readError) return undefined;
+      try {
+        const data = next === null ? null : JSON.parse(readFileSync(file, 'utf8'));
+        readError = null;
+        stamp = next;
+        return data;
+      } catch (e) {
+        readError = e;
+        return undefined;
+      }
+    },
+    save: (data) => {
+      if (readError) throw httpError(503, `${name} cannot be read (${readError.code || readError.message}); fix or delete it`);
+      try {
+        writeJsonAtomic(file, data);
+      } catch (e) {
+        throw httpError(503, `${name} not saved (${e.code || e.message})`);
+      }
+      stamp = stampOf();
+    },
+  };
+}
+
+module.exports = { stampedJsonFile };

package/lib/terminal-client.js

@@ -42,6 +42,7 @@ function createTerminalClient(o) {
   let hostReason = null;
   let ids = [];
   let terminalIds = [];
+  let awaitingTrust = [];
   let serverUrl = null;
   let restoreAsked = false;
   let stopped = false;
@@ -78,6 +79,7 @@ function createTerminalClient(o) {
       hostReason = msg.reason;
       ids = msg.ids;
       terminalIds = msg.terminalIds || [];
+      awaitingTrust = msg.awaitingTrust || [];
       settle(hostReason);
       o.onChange?.();
     } else if (msg.t === 'exit') o.onExit?.(msg.id);
@@ -121,6 +123,7 @@ function createTerminalClient(o) {
     const lost = ids;
     ids = [];
     terminalIds = [];
+    awaitingTrust = [];
     for (const id of lost) o.onExit?.(id);
     o.onChange?.();
     const now = Date.now();
@@ -228,6 +231,7 @@ function createTerminalClient(o) {
     token, handleUpgrade, clientConfig, unavailableReason, authorized, isRunning, hasTerminal, sessionOfTerminal, startNew, end, paste, restore,
     setServerUrl, sessions, stats, shutdown, started,
     ids: () => [...ids],
+    awaitingTrust: () => [...awaitingTrust],
   };
 }
 

package/lib/terminal-host.js

@@ -28,7 +28,13 @@ function ask(op, arg) {
 // The service reports every attach and detach too; cck needs only a change of ids or reason.
 function pushState() {
   const live = service.list();
-  const state = { t: 'state', reason: service.unavailableReason(), ids: live.map((s) => s.id), terminalIds: live.map((s) => s.terminalId) };
+  const state = {
+    t: 'state',
+    reason: service.unavailableReason(),
+    ids: live.map((s) => s.id),
+    terminalIds: live.map((s) => s.terminalId),
+    awaitingTrust: live.filter((s) => s.awaitingTrust).map((s) => s.id),
+  };
   const key = JSON.stringify(state);
   if (key === lastState) return;
   lastState = key;