claude-code-kanban 6.1.2 → 7.0.1

package/server.js

@@ -15,6 +15,8 @@ const { createNetGuard } = require('./lib/net-guard');
 const { isContained } = require('./lib/contain');
 const { resolveScratchSubdir, listScratchDir } = require('./lib/scratch-files');
 const { fileUrlToPath } = require('./lib/file-url');
+const { httpError: previewError } = require('./lib/http-error');
+const { oneLine } = require('./lib/one-line');
 const { pluginStatus } = require('./lib/plugin-status');
 const { getAutoCompact } = require('./lib/auto-compact');
 
@@ -42,7 +44,7 @@ const {
 } = require('./lib/parsers');
 const { inlineHtmlAssets, MIME_BY_EXT } = require('./lib/inline-assets');
 const { buildDecision, decisionFileName, isDecisionFile, approvalsFrom, boardRefusal } = require('./lib/approvals');
-const { getClaudeDir, getArgValue, storageNamespace, isDefaultClaudeDir, encodeProjectDirName } = require('./lib/claude-dir');
+const { getClaudeDir, getArgValue, storageNamespace, isDefaultClaudeDir } = require('./lib/claude-dir');
 const { readTerminalConfig } = require('./lib/terminal');
 const { createTerminalClient } = require('./lib/terminal-client');
 const { readLiveSessions, isPidAlive, isSessionLive } = require('./lib/live-sessions');
@@ -52,8 +54,11 @@ const { createGroupStore, isGroupName, suggestGroupName } = require('./lib/dispa
 const { createDispatchedStore, scanTranscripts, pruneSessionDirs, pruneContextStatus, retentionMs } = require('./lib/retention');
 const { freshRateLimits } = require('./lib/rate-limits');
 const { createWorktreeStore } = require('./lib/worktrees');
+const { createScratchpadDirResolver } = require('./lib/scratchpad-dir');
 const { readGitBranch, sessionGitBranch } = require('./lib/git-branch');
 const { createLinkedDocStore, linkUrl } = require('./lib/linked-docs');
+const { createPaneStore, isOwnOrigin } = require('./lib/panes');
+const { probeFraming, parseOrigin } = require('./lib/frame-policy');
 const { pickFolder } = require('./lib/folder-dialog');
 const { loadSessionCache, saveSessionCache } = require('./lib/session-cache');
 const { countTaskDir } = require('./lib/task-counts');
@@ -105,6 +110,7 @@ const DISPATCH_GROUPS_FILE = path.join(CCK_DIR, 'dispatch-groups.json');
 const DISPATCHED_FILE = path.join(CCK_DIR, 'dispatched.json');
 const WORKTREES_FILE = path.join(CCK_DIR, 'worktrees.json');
 const LINKED_DOCS_FILE = path.join(CCK_DIR, 'linked-docs.json');
+const PANES_FILE = path.join(CCK_DIR, 'panes.json');
 const SERVER_INFO_FILE = path.join(CCK_DIR, 'server.json');
 const TERMINAL_TOKENS_DIR = path.join(CCK_DIR, 'terminal-tokens');
 const SESSION_CACHE_FILE = path.join(CCK_DIR, 'session-cache.json');
@@ -1122,25 +1128,10 @@ function getSessionDisplayName(_sessionId, meta) {
   return null;
 }
 
-// Derived by convention, not looked up: the harness creates the dir lazily, so a
-// stat here would report "missing" for every session that has not written a temp
-// file yet — and it would put IO on the session-list hot path. Pure string join.
-function getScratchpadDir(id, meta) {
-  if (!meta.jsonlPath) return null;
-  const byProject = path.join(SCRATCHPAD_ROOT, path.basename(path.dirname(meta.jsonlPath)), id, 'scratchpad');
-
-  // A session launched with `claude -w` starts in the main checkout and enters the
-  // worktree afterwards, so the harness keys its scratchpad on the repo while the
-  // transcript ends up filed under the worktree. Neither the project nor any `cwd`
-  // in the log records that, so the two candidates are told apart by which one the
-  // harness actually created. Probed only for worktree sessions, and only until one
-  // of them exists — before that there is nothing to disambiguate and `byProject`,
-  // right for a session started inside the worktree, stands.
-  const wt = worktrees.resolve(meta.project);
-  if (!wt || existsSync(byProject)) return byProject;
-  const byRepo = path.join(SCRATCHPAD_ROOT, encodeProjectDirName(wt.repo), id, 'scratchpad');
-  return existsSync(byRepo) ? byRepo : byProject;
-}
+const getScratchpadDir = createScratchpadDirResolver({
+  root: SCRATCHPAD_ROOT,
+  resolveWorktree: worktrees.resolve,
+});
 
 function buildSessionObject(id, meta, overrides = {}) {
   const logStat = overrides._logStat || getSessionLogStat(meta);
@@ -3688,25 +3679,19 @@ const PREVIEW_MAX_BYTES = 8 * 1024 * 1024;
 // Source in a modal is for reading, not for scrolling a generated bundle.
 const PREVIEW_TEXT_MAX_BYTES = 2 * 1024 * 1024;
 
-function previewError(status, message) {
-  const err = new Error(message);
-  err.status = status;
-  return err;
-}
-
 // Existence + kind of a file target, with the HTTP status codes both the preview and
 // the link-a-file endpoints report. `kind` is null for anything the previewer can't
 // render — the caller decides whether that disqualifies the path.
 async function statFileTarget(absPath) {
   try {
     const stats = await fs.stat(absPath);
-    if (!stats.isFile()) throw previewError(400, 'Not a file');
+    if (!stats.isFile()) throw previewError(400, 'Not a file', 'not_a_file');
     const kind = previewKindFor(absPath);
     return { size: stats.size, kind: kind === 'image' ? kind : await confirmKind(absPath, kind) };
   } catch (e) {
     if (e.status) throw e;
-    if (e.code === 'ENOENT') throw previewError(404, 'File not found');
-    if (e.code === 'EISDIR') throw previewError(400, 'Not a file');
+    if (e.code === 'ENOENT') throw previewError(404, 'File not found', 'file_not_found');
+    if (e.code === 'EISDIR') throw previewError(400, 'Not a file', 'not_a_file');
     throw e;
   }
 }
@@ -3714,7 +3699,7 @@ async function statFileTarget(absPath) {
 function enforcePreviewSize(kind, size) {
   const max = kind === 'text' ? PREVIEW_TEXT_MAX_BYTES : PREVIEW_MAX_BYTES;
   if (size > max) {
-    throw previewError(400, `Preview too large (${Math.round(size / 1048576)}MB, max ${max / 1048576}MB)`);
+    throw previewError(400, `Preview too large (${Math.round(size / 1048576)}MB, max ${max / 1048576}MB)`, 'too_large');
   }
 }
 
@@ -3722,7 +3707,7 @@ function enforcePreviewSize(kind, size) {
 // validation (and its status codes) but never the content.
 async function validatePreviewFile(absPath) {
   const { kind, size } = await statFileTarget(absPath);
-  if (!kind) throw previewError(400, 'Not a previewable text, markdown, HTML or image file');
+  if (!kind) throw previewError(400, 'Not a previewable text, markdown, HTML or image file', 'not_previewable');
   enforcePreviewSize(kind, size);
   return { kind, size };
 }
@@ -3804,7 +3789,7 @@ app.post('/api/preview', async (req, res) => {
 // API: Link a file to a session's sidebar docs without opening the preview modal.
 // Not extension-restricted, matching /api/file/resolve — an unpreviewable link just
 // opens in the editor. Unlinking skips the stat so a deleted file can still be removed.
-// An http(s) URL is linked as it is. `open` comes from `preview-doc <url>`: a tab cannot
+// An http(s) URL is linked as it is. `open` comes from `doc preview <url>`: a tab cannot
 // open a URL without a click, so the tab on screen offers an Open button.
 app.post('/api/document/link', async (req, res) => {
   try {
@@ -3959,6 +3944,116 @@ app.get('/api/file/resolve', async (req, res) => {
 
 // #endregion
 
+// #region PANES
+// Tabs next to Board in a session view. Each change broadcasts the whole layout with its rev,
+// so a tab replaces its copy when the rev is newer instead of applying a diff. Another board
+// on the same config dir writes the same file; the watcher broadcasts its changes here.
+const panesFileStamp = () => {
+  try {
+    const s = statSync(PANES_FILE);
+    return `${s.mtimeMs}:${s.size}`;
+  } catch {
+    return null;
+  }
+};
+let panesStamp;
+const panes = createPaneStore({
+  load: () => {
+    const stamp = panesFileStamp();
+    if (stamp === panesStamp) return undefined;
+    panesStamp = stamp;
+    try { return JSON.parse(readFileSync(PANES_FILE, 'utf8')); } catch { return null; }
+  },
+  save: (data) => {
+    writeJsonAtomic(PANES_FILE, data);
+    panesStamp = panesFileStamp();
+  },
+  onChange: (sessionId, layout) => broadcast({ type: 'pane:changed', sessionId, layout }),
+});
+chokidar.watch(PANES_FILE, { ignoreInitial: true }).on('all', (event) => {
+  if (event === 'add' || event === 'change') panes.reload();
+});
+
+let boardPort = null;
+const boardHosts = [...net.ALLOWED_HOSTS.split(','), net.EXPOSED ? net.BIND_HOST : '']
+  .map((h) => h.trim().toLowerCase())
+  .filter(Boolean);
+
+function paneRouteError(res, error, what) {
+  if (!error.status) console.error(`Error in ${what}:`, error);
+  const code = error.status ? error.code : 'internal';
+  res.status(error.status || 500).json({ error: error.message || `${what} failed`, code });
+}
+
+async function resolvePaneTarget(target, base) {
+  const url = linkUrl(target);
+  if (url) {
+    if (isOwnOrigin(url, { boardPort, boardHosts, hubUrl: process.env.HUB_URL })) {
+      throw previewError(400, 'A pane cannot show the board or the hub itself', 'own_origin');
+    }
+    return { kind: 'url', target: url };
+  }
+  const hasBase = typeof base === 'string' && path.isAbsolute(base);
+  if (!hasBase && !path.isAbsolute(fileUrlToPath(target))) {
+    throw previewError(400, 'target must be an http(s) URL, an absolute file path, or a relative path with an absolute base', 'bad_target');
+  }
+  const abs = resolvePreviewPath(target, base);
+  const { kind } = await validatePreviewFile(abs);
+  return { kind, target: await fs.realpath(abs) };
+}
+
+app.get('/api/panes/:sessionId', (req, res) => {
+  res.setHeader('Cache-Control', 'no-store');
+  res.json(panes.get(req.params.sessionId));
+});
+
+app.post('/api/panes/:sessionId', async (req, res) => {
+  try {
+    const { target, base, title } = req.body || {};
+    if (typeof target !== 'string' || !target) throw previewError(400, 'target is required', 'bad_target');
+    res.json(panes.add(req.params.sessionId, { ...(await resolvePaneTarget(target, base)), title }));
+  } catch (error) {
+    paneRouteError(res, error, 'POST /api/panes');
+  }
+});
+
+app.patch('/api/panes/:sessionId', (req, res) => {
+  try {
+    res.json({ layout: panes.reorder(req.params.sessionId, req.body?.order) });
+  } catch (error) {
+    paneRouteError(res, error, 'PATCH /api/panes');
+  }
+});
+
+// Probes only a pane's own target, so the route cannot fetch an arbitrary URL. `ancestors` is
+// the comma-separated origins above the frame: the board's page origin, then the hub's. The CLI
+// has no page, so without it the board's own origin and HUB_URL stand in; under the hub the page
+// is on the proxy port, which agrees for 'self', 'none' and policies that name neither.
+app.get('/api/panes/:sessionId/:paneId/framing', async (req, res) => {
+  try {
+    const { sessionId, paneId } = req.params;
+    const pane = panes.get(sessionId).panes.find((p) => p.id === paneId && p.kind === 'url');
+    if (!pane) throw previewError(404, `No URL pane ${paneId} in session ${sessionId}`, 'no_pane');
+    const fallback = [`http://localhost:${boardPort}`, process.env.HUB_URL].filter(Boolean).join(',');
+    const ancestors = String(req.query.ancestors || fallback)
+      .split(',')
+      .slice(0, 5)
+      .filter((o) => parseOrigin(o));
+    if (!ancestors.length) throw previewError(400, 'ancestors must name at least one http(s) origin', 'bad_ancestors');
+    res.json({ frameable: await probeFraming(pane.target, ancestors) });
+  } catch (error) {
+    paneRouteError(res, error, 'GET /api/panes/framing');
+  }
+});
+
+app.delete('/api/panes/:sessionId/:paneId', (req, res) => {
+  const { sessionId, paneId } = req.params;
+  const layout = panes.remove(sessionId, paneId);
+  if (!layout) return res.status(404).json({ error: `No pane ${paneId} in session ${sessionId}`, code: 'no_pane' });
+  res.json({ layout });
+});
+// #endregion
+
 // #region REVIEW
 // API: Send review comments on something the board shows (a file preview today) to a
 // session. The source is described, not interpreted, so a new kind of preview needs a
@@ -3973,11 +4068,7 @@ function parseReviewBody(body) {
   const { source, comments } = body || {};
   if (!source || !REVIEW_KIND_RE.test(source.kind)) throw previewError(400, 'source.kind is required');
   // The label is pasted into the terminal; an ESC could end bracketed paste and submit text.
-  const label = String(source.label || '')
-    // biome-ignore lint/suspicious/noControlCharactersInRegex: strips control characters on purpose
-    .replace(/[\x00-\x1f\x7f]/g, ' ')
-    .trim()
-    .slice(0, 200);
+  const label = oneLine(source.label, 200);
   if (!label) throw previewError(400, 'source.label is required');
   if (!Array.isArray(comments) || !comments.length || comments.length > REVIEW_MAX_COMMENTS) {
     throw previewError(400, `comments must hold 1 to ${REVIEW_MAX_COMMENTS} items`);
@@ -4335,17 +4426,18 @@ async function cleanupAgentActivity() {
   } catch { /* agent-activity dir may not exist */ }
 }
 
-// Dispatch markers, reviews, context status and worktrees: see docs/retention.md.
+// Dispatch markers, pane layouts, reviews, context status and worktrees: see docs/retention.md.
 async function runRetention() {
   try {
     const scan = await scanTranscripts(PROJECTS_DIR);
     const opts = { known: scan?.ids, maxAgeMs: retentionMs(CLAUDE_DIR) };
     const markers = dispatched.prune(opts);
+    const layouts = panes.prune(opts);
     const reviews = await pruneSessionDirs(REVIEW_DIR, opts);
     const contexts = await pruneContextStatus(CONTEXT_STATUS_DIR, opts);
     const wts = worktrees.prune(scan?.dirs);
-    if (markers || reviews || contexts || wts) {
-      console.log(`[retention] removed ${markers} dispatch markers, ${reviews} reviews, ${contexts} context status files, ${wts} worktrees`);
+    if (markers || layouts || reviews || contexts || wts) {
+      console.log(`[retention] removed ${markers} dispatch markers, ${layouts} pane layouts, ${reviews} reviews, ${contexts} context status files, ${wts} worktrees`);
     }
   } catch (e) {
     console.warn('[retention] failed:', e.message);
@@ -4404,6 +4496,7 @@ async function prewarmCaches() {
 }
 
   const onReady = (actualPort) => {
+    boardPort = Number(actualPort);
     terminal.setServerUrl(`http://127.0.0.1:${actualPort}`);
     // The port is configurable and falls back to a random one when taken, so the postman
     // monitor cannot assume it -- publish the live one where it can read it.

package/skill-guides/dispatch.md

@@ -31,5 +31,5 @@ A crashed session sends nothing. To learn when one ends, `SendMessage` it with `
 
 ```bash
 claude-code-kanban dispatch list --json            # still running in cck's terminal
-claude-code-kanban session peek <session-id> --limit 20
+claude-code-kanban session view <session-id>       # its transcript path; read the last lines
 ```