pi-kanban 0.1.0

package/README.md

@@ -0,0 +1,44 @@
+# pi-kanban
+
+Web dashboard for the [pi coding agent](https://pi.dev) — sessions, todos, subagents, observability.
+
+![pi-kanban dashboard](assets/pi-kanban-poster.png)
+
+## Try it now
+
+**[→ Open the live demo](https://nikiforovall.blog/pi-kanban/)**
+
+Click around a fully interactive dashboard with synthesized sessions, tasks, and subagents — no install. Toggle the theme, browse projects, expand a subagent's review, open the storage manager. Everything works in-browser.
+
+When you're ready to run it on your own pi sessions, install below.
+
+## Installation
+
+```sh
+pi install npm:pi-kanban
+```
+
+Then use `/kanban start | stop | restart | status | open | web | app | pin | sticky-pin | unpin | preview | link` from inside pi.
+
+Or run standalone:
+
+```sh
+npx pi-kanban
+```
+
+### Companion pi extensions
+
+pi-kanban surfaces data produced by two other pi extensions. Install them alongside for the full experience:
+
+```sh
+pi install npm:pi-subagents
+pi install npm:@juicesharp/rpiv-todo
+```
+
+- [`pi-subagents`](https://www.npmjs.com/package/pi-subagents) — spawns named subagent sessions; pi-kanban renders them under each parent session.
+- [`@juicesharp/rpiv-todo`](https://www.npmjs.com/package/@juicesharp/rpiv-todo) — task tracking that pi-kanban displays as kanban columns.
+
+## Documentation
+
+- [User guide](docs/user-guide.md) — slash commands, layout, sessions, subagents, storage manager, keyboard shortcuts.
+- [Theming](docs/theming.md) — built-in themes, configuration, custom theme authoring.

package/extensions/kanban.ts

@@ -0,0 +1,382 @@
+import { spawn, spawnSync, type ChildProcess } from "node:child_process";
+import { createRequire } from "node:module";
+import { readFileSync } from "node:fs";
+import { createConnection } from "node:net";
+import { homedir } from "node:os";
+import { isAbsolute, join as joinPath, resolve as resolvePath } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+
+const extDir = fileURLToPath(new URL(".", import.meta.url));
+const taskStore = createRequire(import.meta.url)(
+	resolvePath(extDir, "..", "lib", "task-store.js"),
+) as {
+	reconcileFromSnapshot: (sessionId: string, snapshot: unknown[]) => void;
+	cleanupIfAllCompleted: (sessionId: string) => boolean;
+};
+
+let child: ChildProcess | null = null;
+let lastStderr = "";
+const port = 3460;
+
+const KANBAN_DIR = joinPath(homedir(), ".pi", "agent", "kanban");
+const SETTINGS_PATH = joinPath(KANBAN_DIR, "settings.json");
+const DEFAULT_THEME_DIR = joinPath(KANBAN_DIR, "themes");
+
+type KanbanSettings = {
+	themes?: {
+		light?: string;
+		dark?: string;
+		dir?: string;
+	};
+};
+
+function readSettings(): KanbanSettings {
+	try {
+		return JSON.parse(readFileSync(SETTINGS_PATH, "utf8")) as KanbanSettings;
+	} catch (e: any) {
+		if (e?.code !== "ENOENT") console.warn(`pi-kanban: cannot read ${SETTINGS_PATH}: ${e.message}`);
+		return {};
+	}
+}
+
+function buildServerEnv(): NodeJS.ProcessEnv {
+	const settings = readSettings();
+	const t = settings.themes ?? {};
+	const env: NodeJS.ProcessEnv = { ...process.env, PORT: String(port) };
+	env.KANBAN_THEME_DIR = process.env.KANBAN_THEME_DIR ?? t.dir ?? DEFAULT_THEME_DIR;
+	if (process.env.KANBAN_LIGHT_THEME ?? t.light) {
+		env.KANBAN_LIGHT_THEME = process.env.KANBAN_LIGHT_THEME ?? t.light;
+	}
+	if (process.env.KANBAN_DARK_THEME ?? t.dark) {
+		env.KANBAN_DARK_THEME = process.env.KANBAN_DARK_THEME ?? t.dark;
+	}
+	return env;
+}
+
+const SUBCOMMANDS = [
+	"start",
+	"stop",
+	"restart",
+	"status",
+	"open",
+	"web",
+	"app",
+	"pin",
+	"sticky-pin",
+	"unpin",
+	"preview",
+	"link",
+] as const;
+type Sub = (typeof SUBCOMMANDS)[number];
+
+function probePort(p: number, timeoutMs = 250): Promise<boolean> {
+	return new Promise((resolve) => {
+		const sock = createConnection({ port: p, host: "127.0.0.1" });
+		const done = (ok: boolean) => {
+			sock.destroy();
+			resolve(ok);
+		};
+		sock.setTimeout(timeoutMs);
+		sock.once("connect", () => done(true));
+		sock.once("timeout", () => done(false));
+		sock.once("error", () => done(false));
+	});
+}
+
+async function waitForPort(p: number, totalMs = 5000): Promise<boolean> {
+	const start = Date.now();
+	while (Date.now() - start < totalMs) {
+		if (await probePort(p)) return true;
+		await new Promise((r) => setTimeout(r, 150));
+	}
+	return false;
+}
+
+async function api(path: string, init?: RequestInit): Promise<Response> {
+	return fetch(`http://127.0.0.1:${port}${path}`, init);
+}
+
+async function postPin(id: string, state: "pinned" | "sticky" | "none"): Promise<Response> {
+	return api("/api/session/pin", {
+		method: "POST",
+		headers: { "Content-Type": "application/json" },
+		body: JSON.stringify({ id, state }),
+	});
+}
+
+async function postSessionOpen(id: string): Promise<Response> {
+	return api("/api/session/open", {
+		method: "POST",
+		headers: { "Content-Type": "application/json" },
+		body: JSON.stringify({ id }),
+	});
+}
+
+async function postPreview(filePath: string, sessionId: string | null, link = false): Promise<Response> {
+	return api("/api/preview", {
+		method: "POST",
+		headers: { "Content-Type": "application/json" },
+		body: JSON.stringify({ path: filePath, sessionId, link }),
+	});
+}
+
+function splitArgs(args: string): string[] {
+	return args.trim().split(/\s+/).filter(Boolean);
+}
+
+function findPidsOnPort(p: number): number[] {
+	if (process.platform === "win32") {
+		const r = spawnSync("netstat", ["-ano", "-p", "tcp"], { encoding: "utf8" });
+		if (r.status !== 0) return [];
+		const pids = new Set<number>();
+		for (const line of r.stdout.split(/\r?\n/)) {
+			const m = line.match(/^\s*TCP\s+\S+:(\d+)\s+\S+\s+LISTENING\s+(\d+)/i);
+			if (m && Number(m[1]) === p) pids.add(Number(m[2]));
+		}
+		return [...pids];
+	}
+	const r = spawnSync("lsof", ["-tiTCP:" + p, "-sTCP:LISTEN"], { encoding: "utf8" });
+	if (r.status !== 0) return [];
+	return r.stdout
+		.split(/\s+/)
+		.map((s) => Number(s))
+		.filter((n) => Number.isFinite(n) && n > 0);
+}
+
+function killPid(pid: number): void {
+	if (process.platform === "win32") {
+		spawnSync("taskkill", ["/F", "/PID", String(pid)], { stdio: "ignore" });
+	} else {
+		try {
+			process.kill(pid, "SIGKILL");
+		} catch {}
+	}
+}
+
+async function ensureRunning(notify: (msg: string, level: "info" | "error") => void): Promise<boolean> {
+	if (await probePort(port)) return true;
+	notify(`pi-kanban not running. Start it with /kanban start`, "error");
+	return false;
+}
+
+export default function kanbanExtension(pi: ExtensionAPI) {
+	const serverPath = resolvePath(extDir, "..", "server.js");
+	const url = `http://localhost:${port}`;
+
+	pi.on("tool_result", async (event, ctx) => {
+		if (event.toolName !== "todo") return;
+		const sessionId = ctx.sessionManager.getSessionId();
+		const tasks = (event.details as any)?.tasks;
+		if (sessionId && Array.isArray(tasks)) {
+			try {
+				taskStore.reconcileFromSnapshot(sessionId, tasks);
+				taskStore.cleanupIfAllCompleted(sessionId);
+			} catch (e: any) { console.warn(`pi-kanban: reconcile failed: ${e?.message ?? e}`); }
+		}
+	});
+
+	pi.on("session_start", async (_event, ctx) => {
+		const sessionId = ctx.sessionManager.getSessionId();
+		if (!sessionId) return;
+		const branch = ctx.sessionManager.getBranch();
+		for (let i = branch.length - 1; i >= 0; i--) {
+			const entry = branch[i];
+			if (entry.type !== "message") continue;
+			const msg: any = (entry as any).message;
+			if (msg?.role !== "toolResult" || msg?.toolName !== "todo") continue;
+			const tasks = msg?.details?.tasks;
+			if (!Array.isArray(tasks)) continue;
+			try {
+				taskStore.reconcileFromSnapshot(sessionId, tasks);
+				taskStore.cleanupIfAllCompleted(sessionId);
+			} catch (e: any) { console.warn(`pi-kanban: backfill failed: ${e?.message ?? e}`); }
+			return;
+		}
+	});
+
+	type Notify = (m: string, l?: "info" | "error") => void;
+
+	async function startServer(notify: Notify, opts: { silentSuccess?: boolean } = {}): Promise<boolean> {
+		if (await probePort(port)) {
+			notify(`pi-kanban already listening on ${url} — run /kanban open or /kanban web`);
+			return true;
+		}
+		lastStderr = "";
+		child = spawn(process.execPath, [serverPath], {
+			env: buildServerEnv(),
+			stdio: ["ignore", "ignore", "pipe"],
+			detached: true,
+			windowsHide: true,
+		});
+		child.stderr?.on("data", (b) => {
+			lastStderr += b.toString();
+		});
+		child.on("exit", () => {
+			child = null;
+		});
+
+		if (!(await waitForPort(port))) {
+			notify(
+				`pi-kanban failed to start.\n${lastStderr.slice(-500) || "(no stderr)"}`,
+				"error",
+			);
+			return false;
+		}
+		// Detach: stop holding the child to the parent's lifetime so /kanban survives
+		// when the pi process that ran /kanban start exits.
+		child.stderr?.removeAllListeners("data");
+		child.stderr?.resume();
+		child.unref();
+		if (!opts.silentSuccess) {
+			notify(`pi-kanban started → ${url} — run /kanban open or /kanban web to launch it`);
+		}
+		return true;
+	}
+
+	async function stopServer(notify: Notify, opts: { silentSuccess?: boolean } = {}): Promise<boolean> {
+		if (child) child.kill("SIGINT");
+		child = null;
+
+		if (await probePort(port)) {
+			const pids = findPidsOnPort(port);
+			for (const pid of pids) killPid(pid);
+			await new Promise((r) => setTimeout(r, 300));
+			const stillUp = await probePort(port);
+			if (stillUp) {
+				notify(
+					`port ${port} still in use after killing pids ${pids.join(",") || "?"}`,
+					"error",
+				);
+				return false;
+			}
+			if (!opts.silentSuccess) {
+				notify(`pi-kanban stopped (killed orphan pid${pids.length > 1 ? "s" : ""} ${pids.join(",")})`);
+			}
+			return true;
+		}
+		if (!opts.silentSuccess) notify("pi-kanban stopped");
+		return true;
+	}
+
+	pi.registerCommand("kanban", {
+		description:
+			"pi-kanban dashboard: start | stop | restart | status | open | web | app | pin | sticky-pin | unpin | preview | link",
+		getArgumentCompletions: (prefix) =>
+			SUBCOMMANDS.filter((s) => s.startsWith(prefix)).map((s) => ({ value: s, label: s })),
+		handler: async (args, ctx) => {
+			const tokens = splitArgs(args);
+			const sub = (tokens[0] || "start") as Sub;
+			const rest = tokens.slice(1);
+			const notify = (m: string, l: "info" | "error" = "info") => ctx.ui.notify(m, l);
+
+			if (sub === "start") {
+				await startServer(notify);
+				return;
+			}
+
+			if (sub === "stop") {
+				await stopServer(notify);
+				return;
+			}
+
+			if (sub === "restart") {
+				if (!(await stopServer(notify, { silentSuccess: true }))) return;
+				if (!(await startServer(notify, { silentSuccess: true }))) return;
+				notify(`pi-kanban restarted → ${url}`);
+				return;
+			}
+
+			if (sub === "status") {
+				const up = await probePort(port);
+				const owned = child ? ` (pid ${child.pid})` : " (external)";
+				notify(up ? `running on ${url}${owned}` : "not running");
+				return;
+			}
+
+			if (sub === "open") {
+				if (!(await ensureRunning(notify))) return;
+				const id = rest[0] ?? ctx.sessionManager.getSessionId() ?? null;
+				if (!id) {
+					notify("Usage: /kanban open <session-id> (no current session to default to)", "error");
+					return;
+				}
+				const res = await postSessionOpen(id);
+				if (!res.ok) {
+					notify(`open failed (${res.status}): ${await res.text()}`, "error");
+					return;
+				}
+				const usedCurrent = !rest[0];
+				notify(`opened: ${id}${usedCurrent ? " (current)" : ""}`);
+				return;
+			}
+
+			if (sub === "web") {
+				const { default: open } = await import("open");
+				await open(url);
+				return;
+			}
+
+			if (sub === "app") {
+				const { default: open, apps } = await import("open");
+				for (const name of [apps.chrome, apps.edge, apps.browser]) {
+					try {
+						await open(url, { app: { name, arguments: [`--app=${url}`] } });
+						return;
+					} catch {}
+				}
+				notify("Could not find Chrome/Edge for PWA window mode", "error");
+				return;
+			}
+
+			if (sub === "pin" || sub === "sticky-pin" || sub === "unpin") {
+				if (!(await ensureRunning(notify))) return;
+				const id = rest[0] ?? ctx.sessionManager.getSessionId() ?? null;
+				if (!id) {
+					notify(`Usage: /kanban ${sub} <session-id> (no current session to default to)`, "error");
+					return;
+				}
+				const PIN_STATE = { "sticky-pin": "sticky", "unpin": "none", "pin": "pinned" } as const;
+				const state = PIN_STATE[sub];
+				const res = await postPin(id, state);
+				if (!res.ok) {
+					notify(`${sub} failed (${res.status}): ${await res.text()}`, "error");
+					return;
+				}
+				const usedCurrent = !rest[0];
+				const verb = sub === "unpin" ? "unpinned" : state;
+				notify(`${verb}: ${id}${usedCurrent ? " (current)" : ""}`);
+				return;
+			}
+
+			if (sub === "preview" || sub === "link") {
+				if (!(await ensureRunning(notify))) return;
+				const file = rest[0];
+				if (!file) {
+					notify(`Usage: /kanban ${sub} <file.md> [session-id]`, "error");
+					return;
+				}
+				const sessionId = rest[1] ?? ctx.sessionManager.getSessionId() ?? null;
+				if (sub === "link" && !sessionId) {
+					notify("Usage: /kanban link <file.md> <session-id> (no current session to default to)", "error");
+					return;
+				}
+				const expanded =
+					file === "~" || file.startsWith("~/") || file.startsWith("~\\")
+						? joinPath(homedir(), file.slice(1))
+						: file;
+				const abs = isAbsolute(expanded) ? expanded : resolvePath(process.cwd(), expanded);
+				const res = await postPreview(abs, sessionId, sub === "link");
+				if (!res.ok) {
+					notify(`${sub} failed (${res.status}): ${await res.text()}`, "error");
+					return;
+				}
+				const usedCurrent = !rest[1] && sessionId;
+				notify(`${sub}: ${abs}${sessionId ? ` → session ${sessionId}${usedCurrent ? " (current)" : ""}` : ""}`);
+				return;
+			}
+
+			notify(`Unknown subcommand: ${sub}. Try: ${SUBCOMMANDS.join(", ")}`, "error");
+		},
+	});
+}

package/lib/git-branch.js

@@ -0,0 +1,112 @@
+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 });
+    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;
+}
+
+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;
+  }
+  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 };