@pi-unipi/kanboard 2.0.8 → 2.0.10

package/server/index.ts

@@ -0,0 +1,278 @@
+/**
+ * @pi-unipi/kanboard — HTTP Server
+ *
+ * Lightweight HTTP server with port allocation, PID management,
+ * static file serving, and route registration.
+ */
+
+import * as http from "node:http";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { KANBOARD_DEFAULTS, KANBOARD_DIRS } from "@pi-unipi/core";
+import type { KanboardConfig } from "../types.js";
+
+/** Content-type map for static files */
+const CONTENT_TYPES: Record<string, string> = {
+  ".html": "text/html; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".js": "application/javascript; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".svg": "image/svg+xml",
+  ".ico": "image/x-icon",
+};
+
+/** Route handler type */
+type RouteHandler = (
+  req: http.IncomingMessage,
+  res: http.ServerResponse,
+  params: Record<string, string>,
+) => void | Promise<void>;
+
+/** Registered route */
+interface Route {
+  method: string;
+  pattern: RegExp;
+  paramNames: string[];
+  handler: RouteHandler;
+}
+
+/** Kanboard server instance */
+export class KanboardServer {
+  private server: http.Server | null = null;
+  private config: KanboardConfig;
+  private routes: Route[] = [];
+  private staticDir: string;
+
+  constructor(config?: Partial<KanboardConfig>) {
+    this.config = {
+      port: config?.port ?? KANBOARD_DEFAULTS.PORT,
+      maxPort: config?.maxPort ?? KANBOARD_DEFAULTS.MAX_PORT,
+      docsRoot: config?.docsRoot ?? ".unipi/docs",
+      pidFile: config?.pidFile ?? KANBOARD_DIRS.PID_FILE,
+    };
+    this.staticDir = path.resolve(
+      path.dirname(new URL(import.meta.url).pathname),
+      "..",
+      "ui",
+      "static",
+    );
+  }
+
+  /** Register a route */
+  route(method: string, pattern: string, handler: RouteHandler): void {
+    const paramNames: string[] = [];
+    // Convert Express-style params (:name) to regex capture groups
+    const regexStr = pattern.replace(/:(\w+)/g, (_match, name) => {
+      paramNames.push(name);
+      return "([^/]+)";
+    });
+    this.routes.push({
+      method: method.toUpperCase(),
+      pattern: new RegExp(`^${regexStr}$`),
+      paramNames,
+      handler,
+    });
+  }
+
+  /** Start the server with port allocation */
+  async start(): Promise<{ port: number; url: string }> {
+    // Check for existing instance
+    const existing = this.checkExistingInstance();
+    if (existing) {
+      // Removed console.log — existing instance detection is silent.
+    }
+
+    this.server = http.createServer((req, res) => this.handleRequest(req, res));
+
+    const port = await this.allocatePort();
+    if (port === null) {
+      throw new Error(
+        `[kanboard] Could not bind to any port ${this.config.port}-${this.config.maxPort}`,
+      );
+    }
+
+    // Write PID file
+    this.writePidFile();
+
+    // Graceful shutdown
+    const shutdown = () => {
+      // Removed console.log — shutdown is silent.
+      this.server?.close(() => {
+        this.removePidFile();
+        process.exit(0);
+      });
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+
+    const url = `http://localhost:${port}`;
+    // Removed console.log — server URL visible via /unipi:kanboard or info-screen.
+    return { port, url };
+  }
+
+  /** Stop the server */
+  stop(): void {
+    this.server?.close();
+    this.removePidFile();
+    this.server = null;
+  }
+
+  /** Get the docs root directory */
+  getDocsRoot(): string {
+    return this.config.docsRoot;
+  }
+
+  /** Try ports in range, return first available */
+  private async allocatePort(): Promise<number | null> {
+    for (let port = this.config.port; port <= this.config.maxPort; port++) {
+      try {
+        await this.listen(port);
+        return port;
+      } catch (err: unknown) {
+        if ((err instanceof Error && (err as NodeJS.ErrnoException).code === "EADDRINUSE")) {
+          // Removed console.log — port allocation is silent.
+          continue;
+        }
+        throw err;
+      }
+    }
+    return null;
+  }
+
+  /** Bind server to a port */
+  private listen(port: number): Promise<void> {
+    return new Promise((resolve, reject) => {
+      this.server!.once("error", reject);
+      this.server!.listen(port, () => resolve());
+    });
+  }
+
+  /** Handle incoming HTTP request */
+  private async handleRequest(
+    req: http.IncomingMessage,
+    res: http.ServerResponse,
+  ): Promise<void> {
+    const url = new URL(req.url ?? "/", `http://${req.headers.host}`);
+    const pathname = url.pathname;
+
+    // Static files
+    if (pathname.startsWith("/static/")) {
+      return this.serveStatic(pathname, res);
+    }
+
+    // Match routes
+    for (const route of this.routes) {
+      if (req.method !== route.method) continue;
+      const match = pathname.match(route.pattern);
+      if (match) {
+        const params: Record<string, string> = {};
+        route.paramNames.forEach((name, i) => {
+          params[name] = match[i + 1];
+        });
+        try {
+          await route.handler(req, res, params);
+        } catch (_err: unknown) {
+          // Silently ignore — route handler error, send generic 500.
+          res.writeHead(500, { "Content-Type": "text/plain" });
+          res.end("Internal Server Error");
+        }
+        return;
+      }
+    }
+
+    // 404
+    res.writeHead(404, { "Content-Type": "text/plain" });
+    res.end("Not Found");
+  }
+
+  /** Serve static files from ui/static/ */
+  private serveStatic(pathname: string, res: http.ServerResponse): void {
+    const filePath = path.join(this.staticDir, pathname.replace("/static/", ""));
+    const resolved = path.resolve(filePath);
+
+    // Prevent directory traversal
+    if (!resolved.startsWith(path.resolve(this.staticDir))) {
+      res.writeHead(403, { "Content-Type": "text/plain" });
+      res.end("Forbidden");
+      return;
+    }
+
+    if (!fs.existsSync(resolved)) {
+      res.writeHead(404, { "Content-Type": "text/plain" });
+      res.end("Not Found");
+      return;
+    }
+
+    const ext = path.extname(resolved);
+    const contentType = CONTENT_TYPES[ext] ?? "application/octet-stream";
+    const content = fs.readFileSync(resolved);
+    res.writeHead(200, { "Content-Type": contentType });
+    res.end(content);
+  }
+
+  /** Check if an existing kanboard instance is running */
+  checkExistingInstance(): string | null {
+    try {
+      if (!fs.existsSync(this.config.pidFile)) return null;
+      const pid = parseInt(fs.readFileSync(this.config.pidFile, "utf-8").trim(), 10);
+      if (isNaN(pid)) return null;
+      // Check if process exists
+      process.kill(pid, 0);
+      // Process exists — return warning URL
+      return `http://localhost:${this.config.port} (PID: ${pid})`;
+    } catch {
+      // Process doesn't exist or can't access PID file
+      return null;
+    }
+  }
+
+  /** Write current PID to file */
+  private writePidFile(): void {
+    try {
+      const dir = path.dirname(this.config.pidFile);
+      if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+      }
+      fs.writeFileSync(this.config.pidFile, String(process.pid));
+    } catch (_err: unknown) {
+      // PID write failure — non-critical, kanboard still works.
+    }
+  }
+
+  /** Remove PID file */
+  private removePidFile(): void {
+    try {
+      if (fs.existsSync(this.config.pidFile)) {
+        fs.unlinkSync(this.config.pidFile);
+      }
+    } catch {
+      // Ignore cleanup errors
+    }
+  }
+}
+
+/** Create and start a kanboard server with default routes */
+export async function startServer(
+  config?: Partial<KanboardConfig>,
+): Promise<{ server: KanboardServer; port: number; url: string }> {
+  const server = new KanboardServer(config);
+  const docsRoot = server.getDocsRoot();
+
+  // Register route modules
+  const { registerMilestoneRoutes } = await import("./routes/milestone.js");
+  const { registerWorkflowRoutes } = await import("./routes/workflow.js");
+
+  registerMilestoneRoutes(server, docsRoot);
+  registerWorkflowRoutes(server, docsRoot);
+
+  server.route("POST", "/api/docs/:type/:file/items/:line", async (req, res) => {
+    // Placeholder — will be implemented with actual file updating
+    res.writeHead(200, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({ ok: true }));
+  });
+
+  const { port, url } = await server.start();
+  return { server, port, url };
+}

package/server/routes/milestone.ts

@@ -0,0 +1,38 @@
+/**
+ * @pi-unipi/kanboard — Milestone Routes
+ *
+ * Routes for the milestone page and API.
+ */
+
+import * as path from "node:path";
+import type { KanboardServer } from "../index.js";
+import { ParserRegistry } from "../../parser/index.js";
+import { MilestoneParser } from "../../parser/milestones.js";
+import { renderMilestonePage } from "../../ui/milestone/page.js";
+
+/** Register milestone routes on the server */
+export function registerMilestoneRoutes(
+  server: KanboardServer,
+  docsRoot: string,
+): void {
+  const registry = new ParserRegistry();
+  registry.register(new MilestoneParser());
+
+  const milestonesPath = path.join(docsRoot, "MILESTONES.md");
+
+  // GET / — Milestone page
+  server.route("GET", "/", (_req, res) => {
+    const doc = registry.parse(milestonesPath);
+    const docs = doc ? [doc] : [];
+    const html = renderMilestonePage(docs);
+    res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+    res.end(html);
+  });
+
+  // GET /api/milestones — Milestone JSON data
+  server.route("GET", "/api/milestones", (_req, res) => {
+    const doc = registry.parse(milestonesPath);
+    res.writeHead(200, { "Content-Type": "application/json" });
+    res.end(JSON.stringify(doc ?? { items: [] }));
+  });
+}

package/server/routes/workflow.ts

@@ -0,0 +1,41 @@
+/**
+ * @pi-unipi/kanboard — Workflow Routes
+ *
+ * Routes for the workflow page and API.
+ */
+
+import type { KanboardServer } from "../index.js";
+import { ParserRegistry, createDefaultRegistry } from "../../parser/index.js";
+import { renderWorkflowPage } from "../../ui/workflow/page.js";
+
+/** Register workflow routes on the server */
+export function registerWorkflowRoutes(
+  server: KanboardServer,
+  docsRoot: string,
+): void {
+  let registry: ParserRegistry | null = null;
+
+  const getRegistry = async (): Promise<ParserRegistry> => {
+    if (!registry) {
+      registry = await createDefaultRegistry();
+    }
+    return registry;
+  };
+
+  // GET /workflow — Workflow page
+  server.route("GET", "/workflow", async (_req, res) => {
+    const reg = await getRegistry();
+    const docs = reg.parseAll(docsRoot);
+    const html = renderWorkflowPage(docs);
+    res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+    res.end(html);
+  });
+
+  // GET /api/workflow — Workflow JSON data
+  server.route("GET", "/api/workflow", async (_req, res) => {
+    const reg = await getRegistry();
+    const docs = reg.parseAll(docsRoot);
+    res.writeHead(200, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({ docs }));
+  });
+}

package/tui/kanboard-overlay.ts

@@ -0,0 +1,300 @@
+/**
+ * @pi-unipi/kanboard — Kanboard TUI Overlay
+ *
+ * Two tabs: Tasks list and Kanban Board.
+ * Uses pi-tui overlay API (same pattern as MCP add overlay).
+ */
+
+import {
+  Key,
+  matchesKey,
+  truncateToWidth,
+  type TUI,
+  visibleWidth,
+} from "@earendil-works/pi-tui";
+import type { Theme, KeybindingsManager } from "@earendil-works/pi-coding-agent";
+import type { ParsedDoc, ParsedItem, ItemStatus } from "../types.js";
+import { createDefaultRegistry } from "../parser/index.js";
+
+type Tab = "tasks" | "board";
+
+interface KanboardState {
+  tab: Tab;
+  tasks: ParsedItem[];
+  taskIndex: number;
+  taskScroll: number;
+  /** Board columns: index into tasks array grouped by status */
+  boardColumns: {
+    todo: number[];
+    inProgress: number[];
+    done: number[];
+  };
+  boardCol: number; // 0=todo, 1=inProgress, 2=done
+  boardIndex: number[];
+  pendingG: boolean;
+  docsRoot: string;
+}
+
+/** Status icon */
+function statusIcon(status: ItemStatus): string {
+  switch (status) {
+    case "done":
+      return "✓";
+    case "in-progress":
+      return "◐";
+    default:
+      return "○";
+  }
+}
+
+/** Pad string to visible width */
+function padVisible(content: string, targetWidth: number): string {
+  const pad = Math.max(0, targetWidth - visibleWidth(content));
+  return content + " ".repeat(pad);
+}
+
+/**
+ * Render the kanboard overlay.
+ */
+export function renderKanboardOverlay(params?: {
+  docsRoot?: string;
+  onComplete?: () => void;
+}) {
+  return (
+    tui: TUI,
+    theme: Theme,
+    _kb: KeybindingsManager,
+    done: (result: { viewed: boolean } | null) => void,
+  ) => {
+    const state: KanboardState = {
+      tab: "tasks",
+      tasks: [],
+      taskIndex: 0,
+      taskScroll: 0,
+      boardColumns: { todo: [], inProgress: [], done: [] },
+      boardCol: 0,
+      boardIndex: [0, 0, 0],
+      pendingG: false,
+      docsRoot: params?.docsRoot ?? ".unipi/docs",
+    };
+
+    // Load data
+    let loaded = false;
+    const ensureLoaded = async () => {
+      if (loaded) return;
+      const registry = await createDefaultRegistry();
+      const docs = registry.parseAll(state.docsRoot);
+      state.tasks = docs.flatMap((d) => d.items);
+
+      // Build board columns
+      state.boardColumns = { todo: [], inProgress: [], done: [] };
+      state.tasks.forEach((item, idx) => {
+        if (item.status === "done") state.boardColumns.done.push(idx);
+        else if (item.status === "in-progress") state.boardColumns.inProgress.push(idx);
+        else state.boardColumns.todo.push(idx);
+      });
+
+      // Init board indices
+      state.boardIndex = [
+        0,
+        0,
+        0,
+      ];
+
+      loaded = true;
+    };
+
+    const render = async () => {
+      await ensureLoaded();
+
+      const width = tui.terminal?.columns ?? 80;
+      const height = tui.terminal?.rows ?? 24;
+      const lines: string[] = [];
+
+      // Header
+      const header = " 📋 Kanboard ";
+      const tabLine =
+        "  [T]asks  |  [B]oard  ".replace(
+          state.tab === "tasks" ? "[T]" : "T",
+          state.tab === "tasks" ? "▸T" : " T",
+        ).replace(
+          state.tab === "board" ? "[B]" : "B",
+          state.tab === "board" ? "▸B" : " B",
+        );
+      lines.push(truncateToWidth(header, width));
+      lines.push(truncateToWidth(tabLine, width));
+      lines.push("─".repeat(width));
+
+      if (state.tab === "tasks") {
+        renderTasksTab(lines, width, height - 5);
+      } else {
+        renderBoardTab(lines, width, height - 5);
+      }
+
+      // Footer
+      lines.push("─".repeat(width));
+      const footer = " j/k: navigate  Tab: switch tab  q/Esc: close ";
+      lines.push(truncateToWidth(footer, width));
+
+      (tui as unknown as { setContent(lines: string[]): void }).setContent(lines);
+    };
+
+    const renderTasksTab = (lines: string[], width: number, maxLines: number) => {
+      if (state.tasks.length === 0) {
+        lines.push(truncateToWidth("  No tasks found.", width));
+        return;
+      }
+
+      // Ensure index in range
+      state.taskIndex = Math.min(state.taskIndex, state.tasks.length - 1);
+      state.taskIndex = Math.max(0, state.taskIndex);
+
+      // Scroll to keep selected visible
+      if (state.taskIndex < state.taskScroll) state.taskScroll = state.taskIndex;
+      if (state.taskIndex >= state.taskScroll + maxLines) {
+        state.taskScroll = state.taskIndex - maxLines + 1;
+      }
+
+      const visible = state.tasks.slice(
+        state.taskScroll,
+        state.taskScroll + maxLines,
+      );
+
+      for (let i = 0; i < visible.length; i++) {
+        const item = visible[i];
+        const globalIdx = state.taskScroll + i;
+        const selected = globalIdx === state.taskIndex;
+        const prefix = selected ? " ▸ " : "   ";
+        const icon = statusIcon(item.status);
+        const source = `[${item.sourceFile}]`;
+        const line = `${prefix}${icon} ${item.text}  ${source}`;
+        lines.push(
+          truncateToWidth(
+            selected ? `\x1b[7m${padVisible(line, width)}\x1b[0m` : line,
+            width,
+          ),
+        );
+      }
+    };
+
+    const renderBoardTab = (lines: string[], width: number, maxLines: number) => {
+      const colWidth = Math.floor(width / 3);
+      const cols: Array<{ title: string; indices: number[]; colIdx: number }> = [
+        { title: "To Do", indices: state.boardColumns.todo, colIdx: 0 },
+        { title: "In Progress", indices: state.boardColumns.inProgress, colIdx: 1 },
+        { title: "Done", indices: state.boardColumns.done, colIdx: 2 },
+      ];
+
+      // Column headers
+      let headerLine = "";
+      for (const col of cols) {
+        const isActive = col.colIdx === state.boardCol;
+        const title = isActive ? `▸ ${col.title}` : `  ${col.title}`;
+        headerLine += padVisible(` ${title} (${col.indices.length})`, colWidth);
+      }
+      lines.push(truncateToWidth(headerLine, width));
+      lines.push("─".repeat(width));
+
+      // Column items
+      const maxItems = Math.max(
+        ...cols.map((c) => c.indices.length),
+        maxLines - 2,
+      );
+      for (let row = 0; row < Math.min(maxItems, maxLines - 2); row++) {
+        let rowLine = "";
+        for (const col of cols) {
+          const active = col.colIdx === state.boardCol;
+          const boardIdx = state.boardIndex[col.colIdx] ?? 0;
+          if (row < col.indices.length) {
+            const item = state.tasks[col.indices[row]];
+            const selected = active && row === boardIdx;
+            const icon = statusIcon(item.status);
+            const text = truncateToWidth(` ${icon} ${item.text}`, colWidth - 1);
+            if (selected) {
+              rowLine += `\x1b[7m${padVisible(text, colWidth)}\x1b[0m`;
+            } else {
+              rowLine += padVisible(text, colWidth);
+            }
+          } else {
+            rowLine += padVisible("", colWidth);
+          }
+        }
+        lines.push(truncateToWidth(rowLine, width));
+      }
+    };
+
+    const handleKey = async (key: string) => {
+      await ensureLoaded();
+
+      // Close
+      if (matchesKey(key, "q") || matchesKey(key, "escape")) {
+        done({ viewed: true });
+        return;
+      }
+
+      // Tab switching
+      if (matchesKey(key, "tab") || matchesKey(key, "b")) {
+        state.tab = state.tab === "tasks" ? "board" : "tasks";
+        render();
+        return;
+      }
+
+      if (matchesKey(key, "t")) {
+        state.tab = "tasks";
+        render();
+        return;
+      }
+
+      // Navigation
+      if (state.tab === "tasks") {
+        if (matchesKey(key, "j") || matchesKey(key, "down")) {
+          state.taskIndex = Math.min(state.taskIndex + 1, state.tasks.length - 1);
+        } else if (matchesKey(key, "k") || matchesKey(key, "up")) {
+          state.taskIndex = Math.max(state.taskIndex - 1, 0);
+        } else if (matchesKey(key, "g")) {
+          if (state.pendingG) {
+            state.taskIndex = 0;
+            state.pendingG = false;
+          } else {
+            state.pendingG = true;
+            setTimeout(() => {
+              state.pendingG = false;
+            }, 500);
+          }
+        } else if (matchesKey(key, "shift+g")) {
+          state.taskIndex = state.tasks.length - 1;
+        }
+      } else {
+        // Board navigation
+        const cols = [
+          state.boardColumns.todo,
+          state.boardColumns.inProgress,
+          state.boardColumns.done,
+        ];
+
+        if (matchesKey(key, "h") || matchesKey(key, "left")) {
+          state.boardCol = Math.max(0, state.boardCol - 1);
+        } else if (matchesKey(key, "l") || matchesKey(key, "right")) {
+          state.boardCol = Math.min(2, state.boardCol + 1);
+        } else if (matchesKey(key, "j") || matchesKey(key, "down")) {
+          const col = cols[state.boardCol];
+          state.boardIndex[state.boardCol] = Math.min(
+            state.boardIndex[state.boardCol] + 1,
+            col.length - 1,
+          );
+        } else if (matchesKey(key, "k") || matchesKey(key, "up")) {
+          state.boardIndex[state.boardCol] = Math.max(
+            state.boardIndex[state.boardCol] - 1,
+            0,
+          );
+        }
+      }
+
+      render();
+    };
+
+    // Start
+    render();
+    (tui as unknown as { on(event: string, handler: (data: string) => void): void }).on("key", handleKey);
+  };
+}