@pi-unipi/kanboard 2.20.4 → 3.0.0-alpha.0

package/parser/index.ts

@@ -1,94 +0,0 @@
-/**
- * @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 } from "../types.js";
-
-/** 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();
-
-  // Register checkbox-driven parsers (spec, quick-work, debug, fix, chore, review)
-  const { CheckboxParser, CHECKBOX_DOC_CONFIGS } = await import("./checkbox-parser.js");
-  for (const config of CHECKBOX_DOC_CONFIGS) {
-    registry.register(new CheckboxParser(config));
-  }
-
-  // Register plan parser (task-header + status-line format, not checkbox)
-  const { PlanParser } = await import("./plans.js");
-  registry.register(new PlanParser());
-
-  // Register milestone parser (inline frontmatter + phase headers)
-  const { MilestoneParser } = await import("./milestones.js");
-  registry.register(new MilestoneParser());
-
-  return registry;
-}

package/parser/milestones.ts

@@ -1,110 +0,0 @@
-/**
- * @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

@@ -1,111 +0,0 @@
-/**
- * @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";
-import { parseFrontmatter } from "./frontmatter.js";
-
-/** Parse frontmatter from markdown file */
-/** 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,
-    };
-  }
-}

package/server/index.ts

@@ -1,266 +0,0 @@
-/**
- * @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 }> {
-    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);
-
-  const { port, url } = await server.start();
-  return { server, port, url };
-}

package/server/routes/milestone.ts

@@ -1,38 +0,0 @@
-/**
- * @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

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