@pi-unipi/kanboard 2.0.7 → 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/index.ts

@@ -0,0 +1,79 @@
+/**
+ * @pi-unipi/kanboard — Extension entry
+ *
+ * Visualization layer for unipi workflow data.
+ * HTTP server with htmx + Alpine.js UI, modular parsers, TUI overlay, and kanban board.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { MODULES, KANBOARD_COMMANDS } from "@pi-unipi/core";
+import { registerCommands } from "./commands.js";
+
+/** Package version */
+const VERSION = "0.1.0";
+
+export default function (pi: ExtensionAPI): void {
+  // Register skills directory
+  const skillsDir = new URL("./skills", import.meta.url).pathname;
+
+  pi.on("resources_discover", async () => {
+    return {
+      skillPaths: [skillsDir],
+    };
+  });
+
+  // Register commands
+  registerCommands(pi);
+
+  // Note: Badge generation on first message is handled by the utility module.
+  // Kanboard no longer manages badge generation to avoid duplication.
+
+  // Register info-screen group
+  const registry = globalThis.__unipi_info_registry;
+  if (registry) {
+    registry.registerGroup({
+      id: "kanboard",
+      name: "Kanboard",
+      icon: "📋",
+      priority: 50,
+      config: {
+        showByDefault: true,
+        stats: [
+          { id: "status", label: "Server Status", show: true },
+          { id: "url", label: "URL", show: true },
+          { id: "docs", label: "Documents", show: true },
+          { id: "tasks", label: "Tasks", show: true },
+        ],
+      },
+      dataProvider: async () => {
+        const { createDefaultRegistry } = await import("./parser/index.js");
+        const registry = await createDefaultRegistry();
+        const docs = registry.parseAll(".unipi/docs");
+        const totalItems = docs.reduce((sum, d) => sum + d.items.length, 0);
+        const doneItems = docs.reduce(
+          (sum, d) => sum + d.items.filter((i) => i.status === "done").length,
+          0,
+        );
+
+        return {
+          status: {
+            value: "Ready",
+            detail: "Server not running (use /unipi:kanboard to start)",
+          },
+          url: {
+            value: "—",
+            detail: "Start server to get URL",
+          },
+          docs: {
+            value: String(docs.length),
+            detail: `${docs.length} documents parsed`,
+          },
+          tasks: {
+            value: `${doneItems}/${totalItems}`,
+            detail: `${totalItems > 0 ? Math.round((doneItems / totalItems) * 100) : 0}% complete`,
+          },
+        };
+      },
+    });
+  }
+}

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@pi-unipi/kanboard",
-  "version": "2.0.7",
+  "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",
   "license": "MIT",
   "author": "Neuron Mr White",
   "repository": {
@@ -22,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",
@@ -44,8 +50,8 @@
     "@pi-unipi/core": "*"
   },
   "peerDependencies": {
-    "@mariozechner/pi-coding-agent": "*",
-    "@mariozechner/pi-tui": "*"
+    "@earendil-works/pi-coding-agent": "^0.75.5",
+    "@earendil-works/pi-tui": "^0.75.5"
   },
   "devDependencies": {
     "@types/node": "^25.6.0",

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,
+    };
+  }
+}