claude-code-kanban 4.14.0 → 4.16.0

package/cli.js

@@ -2,14 +2,23 @@ const path = require('path');
 
 // Help is auto-generated from this table — keep flags/usage in sync with `run` behavior.
 const COMMANDS = {
-  preview: {
-    summary: 'Open a markdown file in the preview modal on connected browser tabs',
-    usage: 'claude-code-kanban preview <file.md> [--session <id>]',
+  'preview-doc': {
+    summary: 'Open a markdown or HTML file in the preview modal on connected browser tabs',
+    usage: 'claude-code-kanban preview-doc <file.md|file.html> [--session <id>]',
     flags: {
       '--session <id>': 'Switch focused session in the browser (does not link the file)',
     },
     run: runPreviewCli,
   },
+  'link-doc': {
+    summary: 'Link a file to a session in the sidebar without opening the preview modal',
+    usage: 'claude-code-kanban link-doc <file> --session <id> [--unlink]',
+    flags: {
+      '--session <id>': 'Session to link the file to (required unless $PREVIEW_SESSION is set)',
+      '--unlink': 'Remove the link instead of adding it',
+    },
+    run: runLinkDocCli,
+  },
   session: {
     summary: 'List or open Claude Code sessions',
     verbs: {
@@ -148,7 +157,8 @@ function printTopHelp() {
   console.log('  --port <n>            Port to listen on (default 3541)');
   console.log('  --dir <path>          Override Claude config dir (default ~/.claude)');
   console.log('  --open                Open browser on start');
-  console.log('  --install, --uninstall    Install or remove the agent-spy hook');
+  console.log('  --install, --uninstall    Install or remove the plugin, context spy, and statusline');
+  console.log('  --plugin-only         With --install: refresh only the plugin, skip context spy and statusline');
 }
 
 function printNounHelp(noun) {
@@ -201,6 +211,19 @@ async function cliFetch(urlPath, init) {
   }
 }
 
+// Every write verb posts JSON and reports failure the same way; `label` names the verb
+// in the error line. Returns false when the server refused, so callers just return 1.
+async function cliPostJson(urlPath, body, label) {
+  const res = await cliFetch(urlPath, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(body)
+  });
+  if (res.ok) return true;
+  console.error(`${label} failed (${res.status}): ${await res.text()}`);
+  return false;
+}
+
 function reportCliError(e) {
   console.error(e.code === 'unreachable' ? e.message : (e.message || String(e)));
 }
@@ -208,26 +231,41 @@ function reportCliError(e) {
 async function runPreviewCli(args) {
   const filePathArg = args.find(a => !a.startsWith('--'));
   if (!filePathArg) {
-    printLeafHelp('preview', COMMANDS.preview);
+    printLeafHelp('preview-doc', COMMANDS['preview-doc']);
     return 1;
   }
   const sessionId = getArgValue(args, 'session') || process.env.PREVIEW_SESSION || null;
   const abs = path.resolve(filePathArg);
   try {
-    const res = await cliFetch('/api/preview', {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ path: abs, sessionId })
-    });
-    if (!res.ok) {
-      console.error(`Preview failed (${res.status}): ${await res.text()}`);
-      return 1;
-    }
+    if (!await cliPostJson('/api/preview', { path: abs, sessionId }, 'Preview')) return 1;
     console.log(`Preview opened: ${abs}${sessionId ? ` (session ${sessionId})` : ''}`);
     return 0;
   } catch (e) { reportCliError(e); return 1; }
 }
 
+async function runLinkDocCli(args) {
+  const filePathArg = args.find(a => !a.startsWith('--'));
+  const sessionArg = getArgValue(args, 'session') || process.env.PREVIEW_SESSION || null;
+  if (!filePathArg) {
+    printLeafHelp('link-doc', COMMANDS['link-doc']);
+    return 1;
+  }
+  if (!sessionArg) {
+    console.error('--session is required: linked docs are stored per session.');
+    return 1;
+  }
+  const unlink = args.includes('--unlink');
+  // Resolved here because the browser keys linked docs by full id, so a prefix won't match.
+  const resolved = await resolveSessionByIdOrPrefix(sessionArg);
+  if (!resolved) return 1;
+  const abs = path.resolve(filePathArg);
+  try {
+    if (!await cliPostJson('/api/document/link', { path: abs, sessionId: resolved.id, unlink }, 'Link')) return 1;
+    console.log(`Document ${unlink ? 'unlinked from' : 'linked to'} session ${resolved.id.slice(0, 8)}: ${abs}`);
+    return 0;
+  } catch (e) { reportCliError(e); return 1; }
+}
+
 // Mirror of `isSessionActive` in public/app.js — keep in sync (different runtimes, no shared module).
 function isSessionActive(s) {
   return s.hasRecentLog || s.inProgress > 0 || s.hasActiveAgents || s.hasWaitingForUser;
@@ -390,15 +428,7 @@ async function runSessionOpenCli(args) {
   const resolved = await resolveSessionByIdOrPrefix(idArg);
   if (!resolved) return 1;
   try {
-    const res = await cliFetch('/api/session/open', {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ id: resolved.id })
-    });
-    if (!res.ok) {
-      console.error(`Open failed (${res.status}): ${await res.text()}`);
-      return 1;
-    }
+    if (!await cliPostJson('/api/session/open', { id: resolved.id }, 'Open')) return 1;
     console.log(`Session opened: ${resolved.id}${resolved.customTitle ? ` (${resolved.customTitle})` : ''}`);
     return 0;
   } catch (e) { reportCliError(e); return 1; }
@@ -414,15 +444,7 @@ async function runSessionPinCli(args) {
   const resolved = await resolveSessionByIdOrPrefix(idArg);
   if (!resolved) return 1;
   try {
-    const res = await cliFetch('/api/session/pin', {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ id: resolved.id, state })
-    });
-    if (!res.ok) {
-      console.error(`Pin failed (${res.status}): ${await res.text()}`);
-      return 1;
-    }
+    if (!await cliPostJson('/api/session/pin', { id: resolved.id, state }, 'Pin')) return 1;
     const label = state === 'none' ? 'unpinned' : state;
     console.log(`Session ${label}: ${resolved.id}${resolved.customTitle ? ` (${resolved.customTitle})` : ''}`);
     return 0;

package/install.js

@@ -49,6 +49,19 @@ function copyScript(src, dest) {
   try { fs.chmodSync(dest, 0o755); } catch {}
 }
 
+// Deletes files but never directories: on Windows the running Claude Code process holds
+// handles on the registered marketplace dirs, so removing one fails EPERM mid-clean and
+// leaves the install gutted. Clearing files alone still drops anything stale, and the
+// leftover empty dirs are harmless — copyDirSync writes straight back into them.
+function clearFilesRecursive(dir) {
+  if (!fs.existsSync(dir)) return;
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const target = path.join(dir, entry.name);
+    if (entry.isDirectory()) clearFilesRecursive(target);
+    else fs.rmSync(target, { force: true });
+  }
+}
+
 function copyDirSync(src, dest) {
   fs.mkdirSync(dest, { recursive: true });
   for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
@@ -63,8 +76,9 @@ function copyDirSync(src, dest) {
   }
 }
 
-async function runInstall() {
-  console.log(`\n  ${bold('claude-code-kanban')} — Plugin & StatusLine installer\n`);
+async function runInstall({ pluginOnly = false } = {}) {
+  console.log(`\n  ${bold('claude-code-kanban')} — ${pluginOnly ? 'Plugin installer' : 'Plugin & StatusLine installer'}\n`);
+  let failed = false;
 
   // 1. Check prerequisites
   process.stdout.write('  Checking claude CLI... ');
@@ -87,14 +101,15 @@ async function runInstall() {
 
   // 2. Copy plugin to stable location & register marketplace
   console.log(`\n  Plugin: ${dim(PLUGIN_DEST)}`);
-  if (await prompt(`    Install claude-code-kanban plugin? [Y/n] `)) {
+  if (pluginOnly || await prompt(`    Install claude-code-kanban plugin? [Y/n] `)) {
     process.stdout.write('    Copying plugin to ~/.claude/.cck/plugin... ');
     try {
-      if (fs.existsSync(PLUGIN_DEST)) fs.rmSync(PLUGIN_DEST, { recursive: true, force: true });
+      clearFilesRecursive(PLUGIN_DEST);
       copyDirSync(PLUGIN_SRC, PLUGIN_DEST);
       console.log(green('✓'));
     } catch (e) {
       console.log(red(`✗ ${e.message}`));
+      failed = true;
     }
 
     process.stdout.write('    Registering marketplace... ');
@@ -105,16 +120,27 @@ async function runInstall() {
       console.log(yellow(`⚠ ${mkt.error}`));
     }
 
+    // Claude caches the marketplace manifest, so a re-copied plugin stays invisible until refreshed
+    const upd = runCLI('claude plugin marketplace update claude-code-kanban');
+    if (!upd.ok) console.log(`    ${yellow('⚠')} Marketplace refresh failed: ${upd.error}`);
+
     const inst = runCLI('claude plugin install claude-code-kanban@claude-code-kanban', ['already installed', 'already exists']);
     if (inst.ok) {
       console.log(`    ${green('✓')} ${inst.idempotent ? 'Already installed' : 'Plugin installed'}`);
     } else {
       console.log(`    ${red('✗')} Plugin install failed: ${inst.error}`);
+      failed = true;
     }
   } else {
     console.log(`    ${dim('Skipped')}`);
   }
 
+  if (pluginOnly) {
+    console.log(`\n  ${dim('Context spy and statusline skipped (--plugin-only).')}`);
+    printSummary(failed);
+    return;
+  }
+
   // 3. StatusLine setup (context-status.sh must be copied globally since statusLine is not plugin-scoped)
   console.log(`\n  Context spy: ${dim(CTX_SCRIPT_DEST)}`);
   let ctxInstalled = false;
@@ -148,7 +174,7 @@ async function runInstall() {
         : {};
     } catch {
       console.log(`    ${red('✗')} Malformed JSON in settings.json — skipping statusline config`);
-      printSummary();
+      printSummary(true);
       return;
     }
 
@@ -179,10 +205,14 @@ async function runInstall() {
     }
   }
 
-  printSummary();
+  printSummary(failed);
 }
 
-function printSummary() {
+function printSummary(failed = false) {
+  if (failed) {
+    console.log(`\n  ${red('Setup incomplete — see the errors above.')}\n`);
+    return;
+  }
   console.log(`\n  ${green('Setup complete. Agent activity will appear in the Kanban dashboard.')}\n`);
 }
 

package/lib/parsers.js

@@ -1291,33 +1291,31 @@ function findTerminatedTeammates(jsonlPath) {
 
 function extractPromptFromTranscript(jsonlPath) {
   const { openSync, readSync, closeSync } = fs;
-  const MAX_READ = 65536;
-  const CHUNK = 4096;
+  // statSync (outside try) throws on a missing path — callers rely on that.
+  const stat = statSync(jsonlPath);
+  // Workflow-spawned subagent prompts embed full task context and routinely
+  // exceed 64 KB, so read the whole first line up to a generous cap. One buffered
+  // read (vs. per-chunk decode) also avoids corrupting multi-byte chars at chunk
+  // boundaries for large prompts.
+  const readSize = Math.min(2097152, stat.size);
   const fd = openSync(jsonlPath, 'r');
   try {
-    let accumulated = '';
-    const buf = Buffer.alloc(CHUNK);
-    while (accumulated.length < MAX_READ) {
-      const bytesRead = readSync(fd, buf, 0, CHUNK, null);
-      if (bytesRead === 0) break;
-      accumulated += buf.toString('utf8', 0, bytesRead);
-      const nlIdx = accumulated.indexOf('\n');
-      if (nlIdx === -1) continue;
-      const firstLine = accumulated.slice(0, nlIdx);
-      try {
-        const obj = JSON.parse(firstLine);
-        if (obj.type === 'user') {
-          const content = obj.message?.content;
-          if (typeof content === 'string') return content;
-          if (Array.isArray(content)) {
-            for (const b of content) {
-              if (b.type === 'text' && b.text) return b.text;
-            }
-          }
+    const buf = Buffer.alloc(readSize);
+    readSync(fd, buf, 0, readSize, 0);
+    // Decode only the first line, not the whole (possibly large) read window.
+    const nlByte = buf.indexOf(0x0a);
+    const firstLine = (nlByte === -1 ? buf : buf.subarray(0, nlByte)).toString('utf8');
+    const obj = JSON.parse(firstLine);
+    if (obj.type === 'user') {
+      const content = obj.message?.content;
+      if (typeof content === 'string') return content;
+      if (Array.isArray(content)) {
+        for (const b of content) {
+          if (b.type === 'text' && b.text) return b.text;
         }
-      } catch (_) {}
-      break;
+      }
     }
+  } catch (_) {
   } finally {
     closeSync(fd);
   }
@@ -1354,6 +1352,82 @@ function extractModelFromTranscript(jsonlPath) {
   return null;
 }
 
+// Full-file scan of a subagent transcript for roster stats: model, summed
+// output tokens, and first/last timestamps (for duration). COLD PATH ONLY —
+// used by the workflow run view on demand, never from the session-scan hot
+// path (a full read per agent would blow the /api/sessions budget).
+function extractTranscriptStats(jsonlPath) {
+  let content;
+  try { content = readFileSync(jsonlPath, 'utf8'); } catch (_) { return null; }
+  let model = null;
+  let outputTokens = 0;
+  let firstTs = null;
+  let lastTs = null;
+  for (const line of content.split('\n')) {
+    if (!line.trim()) continue;
+    let obj;
+    try { obj = JSON.parse(line); } catch (_) { continue; }
+    if (obj.timestamp) {
+      if (!firstTs) firstTs = obj.timestamp;
+      lastTs = obj.timestamp;
+    }
+    const msg = obj.message;
+    if (msg && typeof msg === 'object') {
+      if (!model && msg.model) model = msg.model;
+      const out = msg.usage?.output_tokens;
+      if (typeof out === 'number') outputTokens += out;
+    }
+  }
+  return { model, outputTokens, firstTs, lastTs };
+}
+
+// Render a StructuredOutput tool input (arbitrary schema object) as markdown:
+// one section per field, prose kept verbatim, structured values as JSON blocks.
+function formatStructuredResult(input) {
+  const parts = [];
+  for (const [key, value] of Object.entries(input)) {
+    if (value == null || value === '') continue;
+    parts.push('### ' + key);
+    parts.push(typeof value === 'string' ? value : '```json\n' + JSON.stringify(value, null, 2) + '\n```');
+  }
+  return parts.length ? parts.join('\n\n') : null;
+}
+
+// Workflow-spawned subagents given a schema end their run on a forced
+// StructuredOutput tool call and never emit a text response — so their
+// lastMessage is empty. Tail-read the transcript, take the LAST StructuredOutput
+// tool_use, and format its input as the agent's result. Returns null when absent.
+function extractStructuredResultFromTranscript(jsonlPath) {
+  const { openSync, readSync, closeSync } = fs;
+  const stat = statSync(jsonlPath);
+  const readSize = Math.min(1048576, stat.size);
+  const start = stat.size - readSize;
+  const fd = openSync(jsonlPath, 'r');
+  try {
+    const buf = Buffer.alloc(readSize);
+    readSync(fd, buf, 0, readSize, start);
+    const text = buf.toString('utf8');
+    // Drop the leading partial line unless we read from the very start.
+    const clean = start > 0 ? text.slice(text.indexOf('\n') + 1) : text;
+    if (!clean.includes('"StructuredOutput"')) return null;
+    // Scan from the end for the last StructuredOutput tool call.
+    const lines = clean.split('\n');
+    for (let i = lines.length - 1; i >= 0; i--) {
+      if (!lines[i].includes('"StructuredOutput"')) continue;
+      let obj;
+      try { obj = JSON.parse(lines[i]); } catch (_) { continue; }
+      const content = obj?.message?.content;
+      if (!Array.isArray(content)) continue;
+      const block = content.find(b => b?.type === 'tool_use' && b.name === 'StructuredOutput' && b.input && typeof b.input === 'object');
+      if (block) return formatStructuredResult(block.input);
+    }
+  } catch (_) {
+  } finally {
+    closeSync(fd);
+  }
+  return null;
+}
+
 // Incremental loop-tool scanner. JSONL is append-only, so we keep per-path
 // state and on each call read ONLY the bytes appended since scannedOffset.
 // Avoids the only full-file read that ran inside the /api/sessions hot path.
@@ -1492,5 +1566,7 @@ module.exports = {
   readCompactSummaries,
   findTerminatedTeammates,
   extractPromptFromTranscript,
-  extractModelFromTranscript
+  extractModelFromTranscript,
+  extractStructuredResultFromTranscript,
+  extractTranscriptStats
 };

package/package.json

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

package/plugin/.claude-plugin/marketplace.json

@@ -7,7 +7,7 @@
     {
       "name": "claude-code-kanban",
       "source": "./plugins/claude-code-kanban",
-      "description": "Agent activity tracking for claude-code-kanban dashboard"
+      "description": "claude-code-kanban dashboard integration: agent activity tracking, context statusline, and a skill to drive the board from a session"
     }
   ]
 }

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

@@ -1,5 +1,5 @@
 {
   "name": "claude-code-kanban",
-  "version": "2.2.1",
-  "description": "Agent activity tracking for claude-code-kanban dashboard"
+  "version": "2.3.3",
+  "description": "claude-code-kanban dashboard integration: agent activity tracking, context statusline, and a skill to drive the board from a session"
 }

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

@@ -1,30 +1,28 @@
 ---
 name: kanban
-description: Drive the claude-code-kanban browser dashboard from this Claude session. Use this skill when the user mentions "kanban" together with "session" — e.g. "open this session in kanban", "show kanban", "focus current session in kanban", "pin/unpin a session in kanban", "preview this file in kanban", or asks to peek/view a kanban session.
-compatibility: Requires the `claude-code-kanban` CLI on PATH and the server running locally (default port 3541).
+description: Drive the claude-code-kanban dashboard from this session — focus the current session in the browser, pin/unpin it in the sidebar, preview a markdown or HTML file, link a document to the session, or inspect session stats and messages. Use when the user mentions kanban or cck.
+argument-hint: '[open|pin|unpin|preview|link] [target]'
 ---
 
 # Kanban Skill
 
-Drive the kanban from this Claude session. Every command corresponds to something the user could do in the kanban dashboard.
+The current Claude session id is `${CLAUDE_SESSION_ID}` (substituted when this skill loads), so the user never needs to look it up.
 
-The current Claude session id is available as `${CLAUDE_SESSION_ID}` (substituted when this skill loads), so the user never needs to look it up.
+When the user passes arguments, map them to the matching command below (`open` → `session open`, `pin`/`unpin`/`pins` → `session pin`/`--unpin`/`session pins`, `preview` → `preview-doc`, `link` → `link-doc`, `list`/`view`/`peek` → the read-only verbs); with no arguments, open the current session.
 
-NOTE, sometimes user prefers `npx claude-code-kanban` to `claude-code-kanban` — both work, as long as the CLI is available. Use npx as fallback or when user instructed explicitly.
+Prefer the bare `claude-code-kanban` binary; fall back to `npx claude-code-kanban` when it is not on PATH, or when the user asks for npx explicitly.
 
 ## Open the current session in kanban
 
-Primary use case. Pins the active Claude session in the kanban sidebar and switches to the Active tab.
+Primary use case. Pins the active session in the sidebar and switches to the Active tab.
 
 ```bash
 claude-code-kanban session open ${CLAUDE_SESSION_ID}
 ```
 
-Trigger phrases: "show this session in kanban", "focus current session", "open in kanban".
+## Pin the current session
 
-## Pin the current session in kanban
-
-Pins the active Claude session in the sidebar so it stays visible regardless of filters. Three states: `pinned` (default), `sticky` (always at the top), or cleared via `--unpin`.
+Pins the session so it stays visible regardless of filters. Three states: `pinned` (default), `sticky` (always at the top), or cleared with `--unpin`.
 
 ```bash
 claude-code-kanban session pin ${CLAUDE_SESSION_ID}            # pin
@@ -32,43 +30,46 @@ claude-code-kanban session pin ${CLAUDE_SESSION_ID} --sticky   # sticky at top
 claude-code-kanban session pin ${CLAUDE_SESSION_ID} --unpin    # clear
 ```
 
-Trigger phrases: "pin this session", "pin in kanban", "make this session sticky", "unpin session".
-
 ## List pinned sessions
 
 ```bash
-claude-code-kanban session pins              # all pinned/sticky sessions
+claude-code-kanban session pins              # all pinned/sticky
 claude-code-kanban session pins --sticky     # sticky only
-claude-code-kanban session pins --json       # JSON output
 ```
 
-Trigger phrases: "show pinned sessions", "what's pinned", "list pins".
-
 ## Preview a file in kanban
 
-Opens a markdown file in the preview modal:
+Opens a markdown or standalone HTML file in the preview modal (HTML renders live in a sandboxed iframe, so sibling assets like `./style.css` do not load). Relative paths are fine — the server resolves to absolute.
 
 ```bash
-claude-code-kanban preview <path-to-file.md> --session ${CLAUDE_SESSION_ID}   # prefer this one
+claude-code-kanban preview-doc <path-to-file.md|.html> --session ${CLAUDE_SESSION_ID}
 ```
 
-Relative paths are fine — the server resolves to absolute.
+## Link a document to the session (no modal)
 
-## Inspect sessions (read-only)
+Same idea as `preview-doc`, but it only attaches the file to the session's linked docs in the sidebar — nothing pops up, so it is the safe choice while the user is working. Any extension is linkable.
+
+```bash
+claude-code-kanban link-doc <path-to-file> --session ${CLAUDE_SESSION_ID}            # link
+claude-code-kanban link-doc <path-to-file> --session ${CLAUDE_SESSION_ID} --unlink   # remove
+```
 
-When the user asks "what's going on in kanban?" or wants stats:
+## Inspect sessions (read-only)
 
 ```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
+claude-code-kanban session peek ${CLAUDE_SESSION_ID} --limit 20     # last 20 messages (server caps at 50)
 ```
 
+`session list` shows 10 rows by default and always includes pinned sessions, sticky first — `--no-pins` disables both.
+
 Add `--json` to any list-style verb for machine-readable output.
 
 ## Troubleshooting
 
-- **"Cannot reach cck server on port 3541"** → ask the user to start it: `claude-code-kanban` (or `npm start` in the cck repo).
-- **Different port** → set `PORT=<n>` env var when invoking the CLI.
-- **Ambiguous session prefix (HTTP 409)** → use the full id. With `${CLAUDE_SESSION_ID}` this won't happen.
+`claude-code-kanban help <command>` prints the authoritative flags for any command — 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.