claude-code-kanban 4.27.0 → 4.28.0

package/lib/dispatch.js

@@ -0,0 +1,171 @@
+// Dispatch: one Claude Code session started by another through cck, and the report it
+// settles with. In memory on purpose: the PTYs die with the server, so nothing a
+// restart drops could still settle.
+//
+// The child holds a per-dispatch capability, never the terminal token, so it can
+// report its own outcome and nothing else. A stale or duplicate child is refused
+// because a record settles once.
+
+const crypto = require('node:crypto');
+const { tokenMatches } = require('./terminal');
+const { clampWait } = require('./session-events');
+
+const OUTCOMES = new Set(['succeeded', 'failed']);
+const MAX_SUMMARY = 4000;
+// Settled records outlive their session long enough for a parent to collect them.
+const KEEP_SETTLED_MS = 24 * 60 * 60 * 1000;
+const ID_RE = /^d_[0-9a-f]{12}$/;
+// The peer name lands verbatim in the started session's prompt.
+const PEER_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+
+const isPeerName = (v) => typeof v === 'string' && PEER_RE.test(v);
+
+// With neither --report nor --peer the started session gets the task alone, like one the user typed.
+function formatPreamble(record, cli = 'claude-code-kanban') {
+  if (!record.report && !record.peer) return record.spec;
+  const lines = [`[cck dispatch ${record.id}] Another Claude Code session started you through claude-code-kanban to do the task below.`];
+  if (record.peer) {
+    lines.push(
+      `That session is the peer "${record.peer}". Ask it, not the user: when you need a decision, or find something that changes the task, send a short message with the SendMessage tool to "${record.peer}".`,
+      'Keep working on what does not depend on the answer. The reply arrives as a new message.',
+    );
+  }
+  if (record.report) {
+    lines.push(
+      'When the task is done, or you cannot finish it, report exactly once with this command, then stop:',
+      `${cli} dispatch done ${record.id} --cap ${record.cap} --outcome succeeded --summary "<what changed, what you found, what remains>"`,
+      record.peer
+        ? 'Use --outcome failed when the task cannot be finished. If the command refuses because the dispatch already ended, send the summary to the peer instead.'
+        : 'Use --outcome failed when the task is not done. Do not ask the user questions the other session must answer; report failed with the question instead.',
+    );
+  }
+  lines.push('', 'Task:', record.spec);
+  return lines.join('\n');
+}
+
+// The line reaches the parent through the postman at hook trust level; the summary is
+// last so no summary text can pose as a further field.
+function formatDispatchLine(r) {
+  const head = `cck:1 dispatch.${r.status} ${r.id} session=${r.session}`;
+  return r.summary ? `${head} summary=${r.summary}` : head;
+}
+
+function publicView(r) {
+  const { cap: _cap, ...rest } = r;
+  return rest;
+}
+
+function createDispatchRegistry({ onSettle, now = Date.now } = {}) {
+  const records = new Map();
+  const waiters = new Set();
+
+  function prune() {
+    const cutoff = now() - KEEP_SETTLED_MS;
+    for (const [id, r] of records) if (r.settledAt && r.settledAt < cutoff) records.delete(id);
+  }
+
+  function create({ parent, spec, name, report, peer, group, worktree }) {
+    prune();
+    const r = {
+      id: `d_${crypto.randomBytes(6).toString('hex')}`,
+      cap: crypto.randomBytes(16).toString('hex'),
+      parent: parent || null,
+      session: null,
+      cwd: null,
+      name: name || null,
+      report: !!report,
+      peer: peer || null,
+      group: group || null,
+      worktree: worktree || null,
+      spec,
+      status: 'running',
+      summary: null,
+      startedAt: now(),
+      settledAt: null,
+    };
+    records.set(r.id, r);
+    return r;
+  }
+
+  // The preamble carries the id, so the record exists before its session does.
+  function attach(id, { session, cwd }) {
+    const r = records.get(id);
+    if (r) Object.assign(r, { session, cwd });
+  }
+
+  function discard(id) {
+    records.delete(id);
+  }
+
+  function finish(r, status, summary) {
+    r.status = status;
+    r.summary = summary;
+    r.settledAt = now();
+    onSettle?.(r);
+    for (const wake of [...waiters]) wake();
+  }
+
+  // Returns null when settled, or {status, error} naming the refusal.
+  function settle(id, cap, outcome, summary) {
+    const r = typeof id === 'string' && ID_RE.test(id) ? records.get(id) : null;
+    if (!r) return { status: 404, error: 'no such dispatch' };
+    if (!tokenMatches(r.cap, cap)) return { status: 403, error: 'wrong capability' };
+    if (r.status !== 'running') return { status: 409, error: `already ${r.status}` };
+    if (!OUTCOMES.has(outcome)) return { status: 400, error: 'outcome must be succeeded or failed' };
+    const text = typeof summary === 'string' ? summary.replace(/[\x00-\x1f\x7f]/g, ' ').trim().slice(0, MAX_SUMMARY) : '';
+    finish(r, outcome, text || null);
+    return null;
+  }
+
+  // The PTY ended with no report: the parent must not wait on it forever.
+  function sessionExited(sessionId) {
+    for (const r of records.values()) if (r.session === sessionId && r.status === 'running') finish(r, 'exited', null);
+  }
+
+  function select({ ids, parent } = {}) {
+    prune();
+    let out = [...records.values()];
+    if (ids?.length) out = out.filter((r) => ids.includes(r.id));
+    else if (parent) out = out.filter((r) => r.parent === parent);
+    return out;
+  }
+
+  function list(filter) {
+    return select(filter).map(publicView);
+  }
+
+  // Resolves once any selected record is settled, or after `waitSec`. Stateless for the
+  // caller: it passes the ids still running on the next call. `onClose(stop)` returns an
+  // unsubscribe, called once the wait ends.
+  function wait(filter, waitSec, onClose) {
+    const sec = clampWait(waitSec);
+    const snapshot = () => {
+      const rows = select(filter);
+      return {
+        settled: rows.filter((r) => r.status !== 'running').map(publicView),
+        running: rows.filter((r) => r.status === 'running').map(publicView),
+      };
+    };
+    const first = snapshot();
+    if (first.settled.length || !first.running.length || !sec) return Promise.resolve({ ...first, timeout: false });
+    return new Promise((resolve) => {
+      let unsubscribe;
+      const done = (timeout) => {
+        if (!waiters.delete(wake)) return;
+        clearTimeout(timer);
+        unsubscribe?.();
+        resolve({ ...snapshot(), timeout });
+      };
+      const wake = () => {
+        if (select(filter).some((r) => r.status !== 'running')) done(false);
+      };
+      const timer = setTimeout(() => done(true), sec * 1000);
+      waiters.add(wake);
+      unsubscribe = onClose?.(() => done(true));
+    });
+  }
+
+  return { create, attach, discard, settle, sessionExited, list, wait };
+}
+
+module.exports = { createDispatchRegistry, formatPreamble, formatDispatchLine, isPeerName };

package/lib/folder-dialog.js

@@ -0,0 +1,91 @@
+'use strict';
+
+// Opens the OS folder picker on the machine running cck. The page cannot do this: a
+// browser's directory input hands over file contents, never the folder's path.
+
+const { spawn } = require('node:child_process');
+const { statSync } = require('node:fs');
+const path = require('node:path');
+
+const PROMPT = 'Choose a folder for the new session';
+
+// The owner form keeps the dialog above the browser; without it the dialog opens behind.
+// The start folder arrives in an env var, never spliced into the script.
+const WIN_SCRIPT = [
+  'Add-Type -AssemblyName System.Windows.Forms',
+  '[Console]::OutputEncoding = [Text.Encoding]::UTF8',
+  '$owner = New-Object System.Windows.Forms.Form -Property @{ TopMost = $true }',
+  '$d = New-Object System.Windows.Forms.FolderBrowserDialog',
+  `$d.Description = "${PROMPT}"`,
+  '$d.ShowNewFolderButton = $true',
+  'if ($env:CCK_PICK_START) { $d.SelectedPath = $env:CCK_PICK_START }',
+  'if ($d.ShowDialog($owner) -eq "OK") { [Console]::Out.Write($d.SelectedPath) }',
+].join('; ');
+
+// argv, not string interpolation, so a quote in the path cannot end the AppleScript literal.
+const MAC_SCRIPT = [
+  'on run argv',
+  'if (count of argv) > 0 then',
+  `return POSIX path of (choose folder with prompt "${PROMPT}" default location (POSIX file (item 1 of argv)))`,
+  'end if',
+  `return POSIX path of (choose folder with prompt "${PROMPT}")`,
+  'end run',
+];
+
+function candidates(platform, start) {
+  // No `.exe`: whichSync appends PATHEXT itself, so `powershell.exe` is never found.
+  // pwsh first: on .NET Core the same FolderBrowserDialog is the Explorer-style picker, while
+  // Windows PowerShell (.NET Framework) shows the old tree view.
+  if (platform === 'win32') {
+    const args = ['-NoProfile', '-STA', '-Command', WIN_SCRIPT];
+    return [['pwsh', args], ['powershell', args]];
+  }
+  if (platform === 'darwin') return [['osascript', [...MAC_SCRIPT.flatMap((l) => ['-e', l]), ...(start ? [start] : [])]]];
+  return [
+    ['zenity', ['--file-selection', '--directory', `--title=${PROMPT}`, ...(start ? [`--filename=${start}${path.sep}`] : [])]],
+    ['kdialog', ['--getexistingdirectory', start || '.', '--title', PROMPT]],
+  ];
+}
+
+// The page sends any text the user typed; only an existing absolute folder is worth opening at.
+function startFolder(dir) {
+  if (typeof dir !== 'string' || !path.isAbsolute(dir)) return null;
+  try {
+    return statSync(dir).isDirectory() ? dir : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @param {(cmd: string) => string|null} which
+ * @param {{ start?: string }} [opts] folder the dialog opens at, ignored unless it exists
+ * @returns {Promise<string|null>} the chosen folder, or null when the user cancels
+ * @throws when this machine has no folder dialog
+ */
+function pickFolder(which, opts = {}, platform = process.platform, env = process.env) {
+  if (platform === 'linux' && !env.DISPLAY && !env.WAYLAND_DISPLAY) {
+    return Promise.reject(new Error('no display for a folder dialog'));
+  }
+  const start = startFolder(opts.start);
+  const found = candidates(platform, start).find(([cmd]) => which(cmd));
+  if (!found) return Promise.reject(new Error('no folder dialog on this machine (install zenity or kdialog)'));
+  const [cmd, args] = found;
+  return new Promise((resolve, reject) => {
+    const child = spawn(which(cmd), args, {
+      stdio: ['ignore', 'pipe', 'ignore'],
+      windowsHide: true,
+      env: start ? { ...env, CCK_PICK_START: start } : env,
+    });
+    let out = '';
+    child.stdout.on('data', (d) => { out += d; });
+    child.on('error', reject);
+    // Every picker exits non-zero on cancel and prints nothing.
+    child.on('close', () => {
+      const dir = out.trim();
+      resolve(dir ? dir.replace(/(.)[/\\]$/, '$1') : null);
+    });
+  });
+}
+
+module.exports = { pickFolder, candidates, startFolder };

package/lib/net-guard.js

@@ -181,6 +181,16 @@ function createNetGuard(config = {}) {
     return next();
   }
 
+  // For a WebSocket upgrade, which originGuard must not judge: the handshake is a
+  // GET, and WebSocket has no CORS, so any page can open one. Browsers always send
+  // Origin on the handshake, so a missing or `null` one is refused, not trusted.
+  // Returns null when allowed, or the reason it was refused.
+  function upgradeVerdict(req) {
+    if (!hostAllowed(parseHostHeader(req.headers.host))) return 'unrecognized Host header';
+    if (originVerdict(req.headers.origin) !== true) return 'cross-origin or missing Origin';
+    return null;
+  }
+
   // Constant for the life of the process, and frameGuard runs ahead of
   // express.static — so this is built once rather than per asset fetch.
   //
@@ -229,12 +239,19 @@ function createNetGuard(config = {}) {
    * @param {any} app express app (or any http request handler)
    * @param {number} port 0 selects a free port
    * @param {(port: number) => void} [onReady]
-   * @param {{maxHeaderSize?: number}} [opts]
+   * `onUpgrade` is attached to both servers; a caller that attached it to the
+   * returned one alone would drop every WebSocket that arrives over the other family.
+   *
+   * @param {{maxHeaderSize?: number, onUpgrade?: (req: any, socket: any, head: Buffer) => void}} [opts]
    */
   function listenLoopback(app, port, onReady, opts = {}) {
     const http = require('http');
     const serverOpts = opts.maxHeaderSize ? { maxHeaderSize: opts.maxHeaderSize } : {};
-    const makeServer = (handler) => http.createServer(serverOpts, handler);
+    const makeServer = (handler) => {
+      const s = http.createServer(serverOpts, handler);
+      if (opts.onUpgrade) s.on('upgrade', opts.onUpgrade);
+      return s;
+    };
     const server = makeServer(app);
     let secondary = null;
 
@@ -261,7 +278,7 @@ function createNetGuard(config = {}) {
     return `WARNING: listening on ${BIND_HOST} - reachable from your network, with no authentication.`;
   }
 
-  return { BIND_HOST, ALLOWED_HOSTS, hostGuard, originGuard, frameGuard, listenLoopback, exposureWarning };
+  return { BIND_HOST, ALLOWED_HOSTS, EXPOSED, hostGuard, originGuard, upgradeVerdict, frameGuard, listenLoopback, exposureWarning };
 }
 
 module.exports = { createNetGuard, parseHostHeader, isLoopbackAddress };

package/lib/session-events.js

@@ -51,11 +51,28 @@ function enqueueSessionEvent(sessionId, line) {
   for (const wake of [...bucket.waiters]) wake();
 }
 
+const MAX_WAIT_SEC = 120;
+const TOPIC_RE = /^[a-z]+$/;
+
+function clampWait(sec) {
+  return Math.min(Math.max(Number(sec) || 0, 0), MAX_WAIT_SEC);
+}
+
+// Each topic rides its own bucket, so the kanban-dispatch postman never prints task moves
+// the user did not grant with kanban-follow. No topic is the task-move bucket.
+function topicKey(topic, sessionId) {
+  return topic ? `${topic}:${sessionId}` : sessionId;
+}
+
 // Long-poll drained by the postman monitor. Routing stays in server.js; this is the handler.
 function handleSessionEvents(req, res) {
-  const { sessionId } = req.params;
+  const topic = req.query.topic;
+  if (topic !== undefined && !(typeof topic === 'string' && TOPIC_RE.test(topic))) {
+    return res.status(400).json({ error: 'invalid topic' });
+  }
+  const sessionId = topicKey(topic, req.params.sessionId);
   const bucket = sessionEventBuckets.get(sessionId);
-  const wait = Math.min(Math.max(Number(req.query.wait) || 0, 0), 120);
+  const wait = clampWait(req.query.wait);
 
   // A postman is armed by a skill invocation, so it can attach long after the board moved
   // something. Those lines are read as instructions, and an hours-old instruction is worse
@@ -96,4 +113,7 @@ module.exports = {
   formatTaskMoved,
   enqueueSessionEvent,
   handleSessionEvents,
+  topicKey,
+  clampWait,
+  MAX_WAIT_SEC,
 };