@pi-unipi/kanboard 2.0.8 → 2.0.9

package/commands.ts

@@ -0,0 +1,84 @@
+/**
+ * @pi-unipi/kanboard — Command Registration
+ *
+ * Registers kanboard and kanboard-doctor commands.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { UNIPI_PREFIX, KANBOARD_COMMANDS, KANBOARD_DIRS, UNIPI_EVENTS, emitEvent } from "@pi-unipi/core";
+import { startServer, KanboardServer } from "./server/index.js";
+import { renderKanboardOverlay } from "./tui/kanboard-overlay.js";
+
+/** Module-level reference to running server */
+let runningServer: KanboardServer | null = null;
+
+/** Check if a kanboard server is running via PID file */
+function isPidFileRunning(pidFile: string): boolean {
+  try {
+    if (!fs.existsSync(pidFile)) return false;
+    const pid = parseInt(fs.readFileSync(pidFile, "utf-8").trim(), 10);
+    if (isNaN(pid)) return false;
+    process.kill(pid, 0); // Check if process exists
+    return true;
+  } catch {
+    // Process doesn't exist or can't access PID file
+    try {
+       fs.unlinkSync(pidFile);
+    } catch {}
+    return false;
+  }
+}
+
+/** Register kanboard commands */
+export function registerCommands(pi: ExtensionAPI): void {
+  // kanboard — Toggle server start/stop
+  pi.registerCommand(
+    `${UNIPI_PREFIX}${KANBOARD_COMMANDS.KANBOARD}`,
+    {
+      description: "Toggle kanboard visualization server",
+      handler: async (_args: string, ctx: ExtensionCommandContext) => {
+        const pidFile = path.resolve(KANBOARD_DIRS.PID_FILE);
+
+        try {
+          // Case 1: We have a live reference in this process
+          if (runningServer) {
+            runningServer.stop();
+            runningServer = null;
+            ctx.ui.notify("Kanboard stopped", "info");
+            return;
+          }
+
+          // Case 2: PID file shows a running instance (from previous process)
+          if (isPidFileRunning(pidFile)) {
+            // PID file exists but we don't have a reference — stale or external.
+            // Remove stale PID file and let user know.
+            try { fs.unlinkSync(pidFile); } catch {}
+            ctx.ui.notify("Kanboard was running in a previous session. PID file cleaned. Run again to start fresh.", "info");
+            return;
+          }
+
+          // Case 3: No running instance — start fresh
+          const { server, url } = await startServer();
+          runningServer = server;
+          ctx.ui.notify(`Kanboard running at ${url}`, "info");
+        } catch (err: unknown) {
+          ctx.ui.notify(`Kanboard error: ${err instanceof Error ? err.message : String(err)}`, "error");
+        }
+      },
+    },
+  );
+
+  // kanboard-doctor — Load doctor skill
+  pi.registerCommand(
+    `${UNIPI_PREFIX}${KANBOARD_COMMANDS.KANBOARD_DOCTOR}`,
+    {
+      description: "Diagnose and fix kanboard parser issues",
+      handler: async (_args: string, ctx: ExtensionCommandContext) => {
+        ctx.ui.notify("Loading kanboard-doctor skill...", "info");
+        // The skill will be loaded by the skill system via resources_discover
+      },
+    },
+  );
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/kanboard",
-  "version": "2.0.8",
+  "version": "2.0.9",
   "description": "Visualization layer for unipi workflow — HTTP server with htmx/Alpine.js UI, modular parsers, TUI overlay, and kanban board",
   "type": "module",
   "main": "index.ts",
@@ -23,7 +23,12 @@
     "workflow"
   ],
   "files": [
-    "src/**/*.ts",
+    "index.ts",
+    "commands.ts",
+    "types.ts",
+    "parser/**/*.ts",
+    "server/**/*.ts",
+    "tui/**/*.ts",
     "ui/**/*.ts",
     "ui/**/*.css",
     "ui/**/*.js",

package/parser/index.ts

@@ -0,0 +1,121 @@
+/**
+ * @pi-unipi/kanboard — Parser Registry
+ *
+ * Central registry for document parsers. Auto-detects doc type
+ * by file path and routes to the appropriate parser.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { DocParser, ParsedDoc, DocType } from "../types.js";
+
+/** Path patterns for doc type detection */
+const PATH_PATTERNS: Array<{ pattern: RegExp; type: DocType }> = [
+  { pattern: /\/specs\//, type: "spec" },
+  { pattern: /\/plans\//, type: "plan" },
+  { pattern: /MILESTONES\.md$/i, type: "milestone" },
+  { pattern: /\/quick-work\//, type: "quick-work" },
+  { pattern: /\/debug\//, type: "debug" },
+  { pattern: /\/fix\//, type: "fix" },
+  { pattern: /\/chore\//, type: "chore" },
+  { pattern: /\/reviews\//, type: "review" },
+];
+
+/** Detect doc type from file path */
+export function detectDocType(filePath: string): DocType | null {
+  for (const { pattern, type } of PATH_PATTERNS) {
+    if (pattern.test(filePath)) return type;
+  }
+  return null;
+}
+
+/** Parser registry — manages all document parsers */
+export class ParserRegistry {
+  private parsers: DocParser[] = [];
+
+  /** Register a parser */
+  register(parser: DocParser): void {
+    this.parsers.push(parser);
+  }
+
+  /** Parse a single file using the matching parser */
+  parse(filePath: string): ParsedDoc | null {
+    for (const parser of this.parsers) {
+      if (parser.canParse(filePath)) {
+        return parser.parse(filePath);
+      }
+    }
+    return null;
+  }
+
+  /** Parse all matching files in a directory */
+  parseAll(dir: string): ParsedDoc[] {
+    const results: ParsedDoc[] = [];
+    const files = this.findDocFiles(dir);
+
+    for (const file of files) {
+      const doc = this.parse(file);
+      if (doc) {
+        results.push(doc);
+      }
+    }
+
+    return results;
+  }
+
+  /** Recursively find .md files in docs directory */
+  private findDocFiles(dir: string): string[] {
+    const files: string[] = [];
+
+    if (!fs.existsSync(dir)) return files;
+
+    const walk = (currentDir: string) => {
+      let entries: fs.Dirent[];
+      try {
+        entries = fs.readdirSync(currentDir, { withFileTypes: true });
+      } catch {
+        return;
+      }
+
+      for (const entry of entries) {
+        const fullPath = path.join(currentDir, entry.name);
+        if (entry.isDirectory() && !entry.name.startsWith(".")) {
+          walk(fullPath);
+        } else if (entry.isFile() && entry.name.endsWith(".md")) {
+          files.push(fullPath);
+        }
+      }
+    };
+
+    walk(dir);
+    return files;
+  }
+}
+
+/** Create a registry with all default parsers registered */
+export async function createDefaultRegistry(): Promise<ParserRegistry> {
+  const registry = new ParserRegistry();
+
+  // Import and register all parsers
+  const { SpecParser } = await import("./specs.js");
+  const { PlanParser } = await import("./plans.js");
+  const { MilestoneParser } = await import("./milestones.js");
+  const {
+    QuickWorkParser,
+    DebugParser,
+    FixParser,
+    ChoreParser,
+    ReviewParser,
+  } = await import("./remaining.js");
+
+  registry.register(new SpecParser());
+  registry.register(new PlanParser());
+  registry.register(new MilestoneParser());
+  registry.register(new QuickWorkParser());
+  registry.register(new DebugParser());
+  registry.register(new FixParser());
+  registry.register(new ChoreParser());
+  registry.register(new ReviewParser());
+
+  return registry;
+}

package/parser/milestones.ts

@@ -0,0 +1,110 @@
+/**
+ * @pi-unipi/kanboard — Milestone Parser
+ *
+ * Parses MILESTONES.md. Imports `parseMilestones` from `@pi-unipi/milestone`
+ * and converts MilestoneDoc to ParsedDoc format.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { DocParser, ParsedDoc, ParsedItem } from "../types.js";
+
+/** Milestone parser — converts MilestoneDoc to ParsedDoc */
+export class MilestoneParser implements DocParser {
+  canParse(filePath: string): boolean {
+    return /MILESTONES\.md$/i.test(filePath);
+  }
+
+  parse(filePath: string): ParsedDoc {
+    const warnings: string[] = [];
+    const items: ParsedItem[] = [];
+    let content: string;
+
+    try {
+      content = fs.readFileSync(filePath, "utf-8");
+    } catch (err: unknown) {
+      warnings.push(`Could not read file: ${err instanceof Error ? err.message : String(err)}`);
+      return this.emptyDoc(filePath, warnings);
+    }
+
+    const lines = content.split("\n");
+    const fileName = path.basename(filePath);
+
+    // Inline parsing — extract phases and items directly
+    // This avoids requiring @pi-unipi/milestone as a runtime dependency
+    let currentPhase = "";
+    let inFrontmatter = false;
+    let frontmatterDone = false;
+    let title = "Project Milestones";
+
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      const lineNum = i + 1;
+
+      // Frontmatter parsing
+      if (lineNum === 1 && line.trim() === "---") {
+        inFrontmatter = true;
+        continue;
+      }
+      if (inFrontmatter && line.trim() === "---") {
+        inFrontmatter = false;
+        frontmatterDone = true;
+        continue;
+      }
+      if (inFrontmatter) {
+        const titleMatch = line.match(/^title:\s*(.+)$/);
+        if (titleMatch) {
+          title = titleMatch[1].trim().replace(/^["']|["']$/g, "");
+        }
+        continue;
+      }
+
+      // Phase headers (## Phase N: Name)
+      const phaseMatch = line.match(/^##\s+(.+)$/);
+      if (phaseMatch) {
+        currentPhase = phaseMatch[1].trim();
+        continue;
+      }
+
+      // Checklist items (- [ ] or - [x])
+      const checkboxMatch = line.match(/^\s*-\s*\[([ xX])\]\s*(.*)$/);
+      if (checkboxMatch) {
+        const checked = checkboxMatch[1].toLowerCase() === "x";
+        const text = checkboxMatch[2].trim();
+
+        if (!text) {
+          warnings.push(`Line ${lineNum}: Empty checkbox text`);
+          continue;
+        }
+
+        items.push({
+          text: currentPhase ? `[${currentPhase}] ${text}` : text,
+          status: checked ? "done" : "todo",
+          lineNumber: lineNum,
+          sourceFile: fileName,
+          command: `/unipi:milestone-update`,
+        });
+      }
+    }
+
+    return {
+      type: "milestone",
+      title,
+      filePath,
+      items,
+      metadata: {},
+      warnings,
+    };
+  }
+
+  private emptyDoc(filePath: string, warnings: string[]): ParsedDoc {
+    return {
+      type: "milestone",
+      title: "Project Milestones",
+      filePath,
+      items: [],
+      metadata: {},
+      warnings,
+    };
+  }
+}

package/parser/plans.ts

@@ -0,0 +1,133 @@
+/**
+ * @pi-unipi/kanboard — Plan Parser
+ *
+ * Parses plans for task statuses. Handles the format:
+ * ### Task N — Name
+ * - **Status:** unstarted|in-progress|completed|failed|awaiting_user|blocked|skipped
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { DocParser, ParsedDoc, ParsedItem, ItemStatus } from "../types.js";
+
+/** Parse frontmatter from markdown file */
+function parseFrontmatter(content: string): {
+  metadata: Record<string, string>;
+  bodyStart: number;
+} {
+  const metadata: Record<string, string> = {};
+  const lines = content.split("\n");
+
+  if (lines[0]?.trim() !== "---") return { metadata, bodyStart: 0 };
+
+  for (let i = 1; i < lines.length; i++) {
+    const line = lines[i];
+    if (line.trim() === "---") {
+      return { metadata, bodyStart: i + 1 };
+    }
+    const match = line.match(/^(\w[\w-]*):\s*(.*)$/);
+    if (match) {
+      metadata[match[1]] = match[2].trim();
+    }
+  }
+
+  return { metadata, bodyStart: 0 };
+}
+
+/** Status keyword to ItemStatus mapping */
+const STATUS_MAP: Record<string, ItemStatus> = {
+  unstarted: "todo",
+  "in-progress": "in-progress",
+  completed: "done",
+  failed: "todo",
+  awaiting_user: "in-progress",
+  blocked: "in-progress",
+  skipped: "done",
+  reviewed: "reviewed",
+};
+
+/** Task header pattern */
+const TASK_HEADER_PATTERN = /^###\s+Task\s+\d+\s*[—–-]\s*(.+)$/;
+
+/** Status line pattern: - **Status:** keyword */
+const STATUS_LINE_PATTERN =
+  /^\s*-\s*\*\*Status:\*\*\s*(unstarted|in-progress|completed|failed|awaiting_user|blocked|skipped|reviewed)\s*$/;
+
+/** Plan parser — extracts task statuses from plans */
+export class PlanParser implements DocParser {
+  canParse(filePath: string): boolean {
+    return /\/plans\//.test(filePath) && filePath.endsWith(".md");
+  }
+
+  parse(filePath: string): ParsedDoc {
+    const warnings: string[] = [];
+    const items: ParsedItem[] = [];
+    let content: string;
+
+    try {
+      content = fs.readFileSync(filePath, "utf-8");
+    } catch (err: unknown) {
+      warnings.push(`Could not read file: ${err instanceof Error ? err.message : String(err)}`);
+      return this.emptyDoc(filePath, warnings);
+    }
+
+    const { metadata, bodyStart } = parseFrontmatter(content);
+    const lines = content.split("\n");
+    const fileName = path.basename(filePath);
+
+    let currentTaskName: string | null = null;
+    let currentTaskLine: number | null = null;
+
+    for (let i = bodyStart; i < lines.length; i++) {
+      const line = lines[i];
+      const lineNum = i + 1; // 1-indexed
+
+      // Match task headers: ### Task N — Name
+      const headerMatch = line.match(TASK_HEADER_PATTERN);
+      if (headerMatch) {
+        currentTaskName = headerMatch[1].trim();
+        currentTaskLine = lineNum;
+        continue;
+      }
+
+      // Match status lines: - **Status:** keyword
+      const statusMatch = line.match(STATUS_LINE_PATTERN);
+      if (statusMatch && currentTaskName) {
+        const statusKey = statusMatch[1];
+        const status = STATUS_MAP[statusKey] ?? "todo";
+
+        items.push({
+          text: currentTaskName,
+          status,
+          lineNumber: currentTaskLine ?? lineNum,
+          sourceFile: fileName,
+          command: `/unipi:work plan:${fileName}`,
+        });
+
+        // Reset current task
+        currentTaskName = null;
+        currentTaskLine = null;
+      }
+    }
+
+    return {
+      type: "plan",
+      title: metadata.title ?? fileName.replace(/\.md$/, ""),
+      filePath,
+      items,
+      metadata,
+      warnings,
+    };
+  }
+
+  private emptyDoc(filePath: string, warnings: string[]): ParsedDoc {
+    return {
+      type: "plan",
+      title: path.basename(filePath).replace(/\.md$/, ""),
+      filePath,
+      items: [],
+      metadata: {},
+      warnings,
+    };
+  }
+}