pi-kanban 0.3.1 → 2.0.0

package/lib/contain.js

@@ -0,0 +1,78 @@
+'use strict';
+
+// Path containment check.
+//
+// The obvious implementation — `child.startsWith(root)` — is wrong twice over:
+// it accepts a sibling directory that merely shares a prefix ("/plugins/foo-evil"
+// passes a check for "/plugins/foo"), and it is blind to symlinks, `..`, casing
+// and Windows 8.3 short names. This uses path.relative instead, and canonicalises
+// both sides first.
+//
+// Forked from scripts/security-lib/contain.js in the claude-code-hub repo; this copy is
+// maintained here.
+
+const path = require('node:path');
+const fs = require('node:fs');
+
+const IS_WIN = process.platform === 'win32';
+
+// realpath the deepest existing ancestor, then re-append the non-existent tail,
+// so a not-yet-created file under a symlinked directory still canonicalises.
+function realpathDeepest(target) {
+  let cur = target;
+  const tail = [];
+  for (;;) {
+    try {
+      const real = fs.realpathSync.native(cur);
+      return tail.length ? path.join(real, ...tail.reverse()) : real;
+    } catch {
+      const parent = path.dirname(cur);
+      if (parent === cur) return target; // reached the volume root, nothing resolvable
+      tail.push(path.basename(cur));
+      cur = parent;
+    }
+  }
+}
+
+function canonical(target, deepest) {
+  let out = path.resolve(target);
+  if (deepest) out = realpathDeepest(out);
+  else { try { out = fs.realpathSync.native(out); } catch { /* may not exist yet */ } }
+  // realpathSync.native has already expanded 8.3 short names (PROGRA~1) and fixed
+  // the casing of the existing portion; lowercase covers the rest.
+  return IS_WIN ? out.toLowerCase() : out;
+}
+
+function beneath(canonicalChild, root) {
+  const rel = path.relative(canonical(root, false), canonicalChild);
+  // '' means child === root. An absolute rel means a different drive or UNC share,
+  // which path.relative signals by giving up — reject those.
+  if (rel === '') return true;
+  if (path.isAbsolute(rel)) return false;
+  return rel !== '..' && !rel.startsWith(`..${path.sep}`);
+}
+
+/**
+ * True iff `child` is `root` itself or lies beneath it.
+ * @param {string} child
+ * @param {string} root
+ */
+function isContained(child, root) {
+  if (typeof child !== 'string' || typeof root !== 'string' || !child || !root) return false;
+  return beneath(canonical(child, true), root);
+}
+
+/**
+ * True iff `child` is contained by any of `roots`. Canonicalises the child once
+ * instead of once per root — callers testing a single path against several roots
+ * were paying that walk repeatedly.
+ * @param {string} child
+ * @param {string[]} roots
+ */
+function isContainedAny(child, roots) {
+  if (typeof child !== 'string' || !child || !Array.isArray(roots)) return false;
+  const c = canonical(child, true);
+  return roots.some((r) => typeof r === 'string' && r && beneath(c, r));
+}
+
+module.exports = { isContained, isContainedAny, realpathDeepest };

package/lib/dispatch-reports.js

@@ -0,0 +1,86 @@
+'use strict';
+
+// A dispatched session's report back to the session that started it. The worker posts it once it
+// is done; the starter's call long-polls for it. The report lives on the dispatch marker, so it
+// waits there when the starter polls late or the board restarts in between.
+
+const MAX_REPORT = 16 * 1024;
+const WAIT_MAX_MS = 25_000;
+
+function parseReport(body) {
+  const text = body?.text;
+  if (typeof text !== 'string' || !text.trim()) return { error: 'text is required' };
+  if (text.length > MAX_REPORT) return { error: `text must be at most ${MAX_REPORT} characters` };
+  return { text: text.trim() };
+}
+
+/**
+ * @param {object} o
+ * @param {ReturnType<import('./retention').createDispatchedStore>} o.dispatched
+ * @param {(session: string) => boolean} o.isRunning  the session's terminal still runs
+ */
+function createDispatchReports({ dispatched, isRunning }) {
+  const waiters = new Map();
+
+  // Null for a session that was not dispatched.
+  function status(id) {
+    const marker = dispatched.get(id);
+    if (!marker) return null;
+    if (marker.report) return { status: 'reported', ...marker.report };
+    return isRunning(id) ? { status: 'pending' } : { status: 'ended' };
+  }
+
+  // Wakes the waiters of a session to read its status again: a report came, or its terminal ended.
+  function notify(id) {
+    const set = waiters.get(id);
+    if (!set) return;
+    waiters.delete(id);
+    for (const wake of set) wake();
+  }
+
+  function post(id, text) {
+    const report = dispatched.setReport(id, text);
+    if (report) notify(id);
+    return report;
+  }
+
+  async function wait(id, ms) {
+    const now = status(id);
+    if (!now || now.status !== 'pending' || ms <= 0) return now;
+    await new Promise((resolve) => {
+      const wake = () => {
+        clearTimeout(timer);
+        resolve();
+      };
+      const timer = setTimeout(() => {
+        const set = waiters.get(id);
+        set?.delete(wake);
+        if (set && !set.size) waiters.delete(id);
+        resolve();
+      }, Math.min(ms, WAIT_MAX_MS));
+      timer.unref?.();
+      if (!waiters.has(id)) waiters.set(id, new Set());
+      waiters.get(id).add(wake);
+    });
+    return status(id);
+  }
+
+  return { status, post, wait, notify };
+}
+
+// Shared by the CLI and the pi tools, so both print and match dispatches the same way.
+function dispatchLine(d) {
+  return [d.session, d.name, d.group && `[${d.group}]`, d.cwd, d.reportedAt && '(reported)'].filter(Boolean).join('  ');
+}
+
+function matchDispatches(rows, query) {
+  return rows.filter((r) => r.name === query || r.session.startsWith(query));
+}
+
+function reportText(session, r) {
+  if (r.status === 'reported') return `Report from ${session}:\n${r.text}`;
+  if (r.status === 'ended') return `The terminal of ${session} ended without a report.`;
+  return `${session} has not reported yet.`;
+}
+
+module.exports = { createDispatchReports, parseReport, dispatchLine, matchDispatches, reportText, MAX_REPORT, WAIT_MAX_MS };

package/lib/file-url.js

@@ -0,0 +1,38 @@
+'use strict';
+
+// Some tools hand out a `file://` URL where a path is expected — Explorer's
+// "copy as path" on a network share, a PDF viewer's location bar, a chat client
+// that linkifies attachments. Windows apps also emit the non-standard backslash
+// spelling `file:\\\C:\dir\a.md`. Both are normalized to a plain OS path so the
+// user does not have to hand-edit what their clipboard produced.
+
+const { fileURLToPath } = require('node:url');
+
+// Matches any number of leading slashes before a drive letter, so it re-spells both
+// the well-formed `file:///C:/dir` and `file://C:/dir`, where the parser reads C: as
+// a host and rejects the URL outright. Anything else — POSIX paths, UNC shares — is
+// left for the parser.
+const DRIVE_URL = /^file:\/*([a-zA-Z]:.*)$/;
+
+/**
+ * Convert a `file://` URL to an OS path. Any other string is returned unchanged,
+ * as is a URL too malformed to parse — the caller reports "not found" on the
+ * literal text, which is more useful than a parser error.
+ * @param {string} value
+ */
+function fileUrlToPath(value) {
+  if (typeof value !== 'string' || !/^file:/i.test(value)) return value;
+  // Backslashes are not legal in a URL, so this cannot corrupt a well-formed one.
+  let url = value.replace(/\\/g, '/');
+  // A scheme with no path body: POSIX Node resolves it to "/" rather than throwing.
+  if (/^file:\/*$/i.test(url)) return value;
+  const drive = DRIVE_URL.exec(url);
+  if (drive) url = `file:///${drive[1]}`;
+  try {
+    return fileURLToPath(url);
+  } catch {
+    return value;
+  }
+}
+
+module.exports = { fileUrlToPath };

package/lib/folder-dialog.js

@@ -0,0 +1,91 @@
+'use strict';
+
+// Opens the OS folder picker on the machine running pi-kanban. 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:PK_PICK_START) { $d.SelectedPath = $env:PK_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, PK_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/frame-policy.js

@@ -0,0 +1,79 @@
+// Whether a page lets the board frame it, from its response headers. The parent page gets no
+// signal when a cross-origin frame is refused (Chrome fires `load` on its error page), so the
+// server reads the headers instead. Rules: CSP3 frame-ancestors (it wins over X-Frame-Options
+// when present) and the HTML spec's X-Frame-Options processing.
+
+const { portOf } = require('./panes');
+
+const PROBE_TIMEOUT_MS = 5000;
+
+function parseOrigin(value) {
+  try {
+    const u = new URL(value);
+    return u.protocol === 'http:' || u.protocol === 'https:' ? u : null;
+  } catch {
+    return null;
+  }
+}
+
+// CSP3 lets an http source match https too.
+const schemeOk = (want, got) => want === got || (want === 'http:' && got === 'https:');
+
+function matchesSource(source, ancestor, self) {
+  const s = source.toLowerCase();
+  if (s === "'self'") return ancestor.origin === self.origin;
+  if (s === '*') return true;
+  if (/^[a-z][a-z0-9+.-]*:$/.test(s)) return schemeOk(s, ancestor.protocol);
+  const m = /^(?:([a-z][a-z0-9+.-]*):\/\/)?(\*|(?:\*\.)?[^:/]+)(?::(\d+|\*))?(?:\/.*)?$/.exec(s);
+  if (!m) return false;
+  const [, scheme, host, port] = m;
+  const want = scheme ? `${scheme}:` : self.protocol;
+  if (!schemeOk(want, ancestor.protocol)) return false;
+  const hostOk = host === '*' || (host.startsWith('*.') ? ancestor.hostname.endsWith(host.slice(1)) : host === ancestor.hostname);
+  if (!hostOk) return false;
+  if (port === '*' || (!port && ancestor.port === '')) return true;
+  return Number(port) === portOf(ancestor) || (port === '80' && ancestor.protocol === 'https:' && ancestor.port === '');
+}
+
+function frameAncestorsLists(csp) {
+  const lists = [];
+  for (const policy of String(csp || '').split(',')) {
+    for (const directive of policy.split(';')) {
+      const [name, ...sources] = directive.trim().split(/\s+/);
+      if (name?.toLowerCase() === 'frame-ancestors') {
+        lists.push(sources);
+        break;
+      }
+    }
+  }
+  return lists;
+}
+
+// headers: Fetch Headers. target: the final URL of the response. ancestors: every origin above
+// the frame. Answers true, false, or null when it cannot tell.
+function framingVerdict(headers, { target, ancestors }) {
+  const self = parseOrigin(target);
+  const chain = ancestors.map(parseOrigin).filter(Boolean);
+  if (!self || !chain.length) return null;
+  const lists = frameAncestorsLists(headers.get('content-security-policy'));
+  if (lists.length) return lists.every((sources) => chain.every((a) => sources.some((src) => matchesSource(src, a, self))));
+  const xfo = String(headers.get('x-frame-options') || '')
+    .split(',')
+    .map((v) => v.trim().toLowerCase());
+  if (xfo.includes('deny')) return false;
+  return !xfo.includes('sameorigin') || chain.every((a) => a.origin === self.origin);
+}
+
+// GETs the page and drops the body once the headers arrive. A network error or a timeout
+// answers null, and the board frames the page anyway.
+async function probeFraming(target, ancestors, { fetchImpl = fetch } = {}) {
+  try {
+    const res = await fetchImpl(target, { redirect: 'follow', signal: AbortSignal.timeout(PROBE_TIMEOUT_MS) });
+    res.body?.cancel().catch(() => {});
+    return framingVerdict(res.headers, { target: res.url || target, ancestors });
+  } catch {
+    return null;
+  }
+}
+
+module.exports = { framingVerdict, parseOrigin, probeFraming };

package/lib/git-branch.js

@@ -1,112 +1,47 @@
+// Read from HEAD rather than by spawning git: a sync spawn on the session-list path blocks the
+// event loop for up to half a second per cwd on Windows, and terminal input waits behind it.
+
 const fs = require('node:fs');
 const path = require('node:path');
-const { spawn } = require('node:child_process');
-
-// cwd -> { branch: string|null, headMtimeMs: number, isRepo: boolean, checkedAt: number }
-const cache = new Map();
-const inflight = new Map();
-
-const MAX_CONCURRENT = 4;
-const SPAWN_TIMEOUT_MS = 500;
-// re-check non-repos every 30s so newly-cloned repos surface without a server restart
-const NEGATIVE_TTL_MS = 30_000;
-// skip statSync within this window of a known-good cache hit; keeps list endpoints from
-// hitting the FS once per session per request when the same cwds repeat
-const POSITIVE_TTL_MS = 2_000;
-let running = 0;
-const queue = [];
-
-function pump() {
-  while (running < MAX_CONCURRENT && queue.length) {
-    const job = queue.shift();
-    running++;
-    job().finally(() => { running--; pump(); });
-  }
-}
-
-function headMtime(cwd) {
-  try { return fs.statSync(path.join(cwd, '.git', 'HEAD')).mtimeMs; }
-  catch { return null; }
-}
-
-function spawnGit(cwd) {
-  return new Promise((resolve) => {
-    let stdout = '';
-    let done = false;
-    let proc;
-    try {
-      proc = spawn('git', ['-C', cwd, 'rev-parse', '--abbrev-ref', 'HEAD'], {
-        windowsHide: true,
-      });
-    } catch { resolve(null); return; }
-    const timer = setTimeout(() => {
-      if (done) return;
-      done = true;
-      try { proc.kill(); } catch {}
-      resolve(null);
-    }, SPAWN_TIMEOUT_MS);
-    proc.stdout.on('data', (b) => { stdout += b.toString(); });
-    proc.on('error', () => {
-      if (done) return;
-      done = true; clearTimeout(timer); resolve(null);
-    });
-    proc.on('close', (code) => {
-      if (done) return;
-      done = true; clearTimeout(timer);
-      if (code !== 0) { resolve(null); return; }
-      const branch = stdout.trim();
-      resolve(branch || null);
-    });
-  });
-}
 
-function getBranch(cwd, onResolved) {
-  if (!cwd) return null;
-  const entry = cache.get(cwd);
-  const now = Date.now();
-
-  if (entry && entry.isRepo && now - entry.checkedAt < POSITIVE_TTL_MS) {
-    return entry.branch;
-  }
-
-  const mtime = headMtime(cwd);
-
-  if (mtime === null) {
-    if (entry && entry.isRepo === false && now - entry.checkedAt < NEGATIVE_TTL_MS) {
-      return null;
-    }
-    cache.set(cwd, { branch: null, headMtimeMs: 0, isRepo: false, checkedAt: now });
+const REF_RE = /^ref:\s*refs\/heads\/(.+)$/;
+const GITDIR_RE = /^gitdir:\s*(.+)$/;
+
+// `.git` is a directory in an ordinary checkout and a `gitdir:` pointer file in a linked
+// worktree or a submodule.
+function headFile(dir, readFile) {
+  const dotGit = path.join(dir, '.git');
+  let text;
+  try {
+    text = readFile(dotGit);
+  } catch (e) {
+    if (e.code === 'EISDIR') return path.join(dotGit, 'HEAD');
     return null;
   }
-
-  if (entry && entry.isRepo && entry.headMtimeMs === mtime) {
-    entry.checkedAt = now;
-    return entry.branch;
-  }
-
-  scheduleResolve(cwd, mtime, entry, onResolved);
-  return entry && entry.isRepo ? entry.branch : null;
+  const m = GITDIR_RE.exec(text.trim());
+  return m ? path.join(path.resolve(dir, m[1]), 'HEAD') : null;
 }
 
-function scheduleResolve(cwd, mtime, prevEntry, onResolved) {
-  if (inflight.has(cwd)) {
-    if (onResolved) inflight.get(cwd).then((b) => {
-      if (!prevEntry || prevEntry.branch !== b) onResolved(b);
-    });
-    return;
+/**
+ * @param {string} cwd
+ * @param {(file: string) => string} [readFile]
+ * @returns {string|null} null outside a repo and on a detached HEAD
+ */
+function readGitBranch(cwd, readFile = (f) => fs.readFileSync(f, 'utf8')) {
+  for (let dir = path.resolve(cwd); ; ) {
+    const head = headFile(dir, readFile);
+    if (head) {
+      try {
+        const m = REF_RE.exec(readFile(head).trim());
+        return m ? m[1] : null;
+      } catch {
+        return null;
+      }
+    }
+    const up = path.dirname(dir);
+    if (up === dir) return null;
+    dir = up;
   }
-  const prevBranch = prevEntry ? prevEntry.branch : undefined;
-  const p = new Promise((resolve) => {
-    queue.push(async () => {
-      const branch = await spawnGit(cwd);
-      cache.set(cwd, { branch, headMtimeMs: mtime, isRepo: branch !== null, checkedAt: Date.now() });
-      inflight.delete(cwd);
-      resolve(branch);
-    });
-    pump();
-  });
-  inflight.set(cwd, p);
-  if (onResolved) p.then((b) => { if (b !== prevBranch) onResolved(b); });
 }
 
-module.exports = { getBranch };
+module.exports = { readGitBranch };

package/lib/http-error.js

@@ -0,0 +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, expose: true });
+}
+
+module.exports = { httpError };