@pi-unipi/kanboard 0.1.2

package/README.md

@@ -0,0 +1,137 @@
+# @pi-unipi/kanboard
+
+Visualization layer for unipi workflow data. Kanboard provides an HTTP server with htmx + Alpine.js UI, modular parsers for all workflow document types, two web pages (Milestones + Workflow), a TUI overlay with tasks list and kanban board, and a doctor skill for parser diagnostics.
+
+## Quick Start
+
+```bash
+# Start the kanboard server
+/unipi:kanboard
+
+# Diagnose parser issues
+/unipi:kanboard-doctor
+```
+
+## Architecture
+
+```
+kanboard/
+├── server/          # HTTP server with port allocation
+│   ├── index.ts     # Server core (KanboardServer class)
+│   └── routes/      # Route handlers (milestone, workflow)
+├── parser/          # Document parsers
+│   ├── index.ts     # ParserRegistry + createDefaultRegistry()
+│   ├── specs.ts     # Spec parser (checklist items)
+│   ├── plans.ts     # Plan parser (task statuses)
+│   ├── milestones.ts # Milestone parser
+│   └── remaining.ts # Quick-work, debug, fix, chore, review
+├── ui/              # Web UI
+│   ├── layouts/     # Base HTML layout
+│   ├── static/      # CSS + JS (style.css, app.js)
+│   ├── components/  # Reusable components
+│   ├── milestone/   # Milestone page renderer
+│   └── workflow/    # Workflow page renderer
+├── tui/             # TUI overlay
+│   └── kanboard-overlay.ts
+├── skills/          # Skills
+│   └── kanboard-doctor/ # Parser diagnostics
+├── commands.ts      # Command registration
+├── types.ts         # Shared TypeScript types
+└── index.ts         # Extension entry point
+```
+
+## Web Pages
+
+### Milestones (`/`)
+- Displays MILESTONES.md phases with progress bars
+- Checklist items with status indicators (✓ done, ○ todo)
+- Collapsible sections per phase
+- Copy-to-clipboard for `/unipi:milestone-update`
+
+### Workflow (`/workflow`)
+- Cards grouped by document type (specs, plans, fixes, etc.)
+- Progress indicators per card
+- Alpine.js filtering by status (All, To Do, In Progress, Done)
+- Copy-to-clipboard for relevant commands
+
+## TUI Overlay
+
+Two tabs accessible via the kanboard overlay:
+
+- **Tasks** — Flat list of all tasks from all documents with status icons
+- **Board** — Kanban columns (To Do / In Progress / Done)
+
+### Controls
+- `j/k` — Navigate up/down
+- `h/l` — Switch columns (Board tab)
+- `Tab` or `b` — Switch between Tasks/Board tabs
+- `t` — Switch to Tasks tab
+- `gg/G` — Jump to top/bottom
+- `q/Esc` — Close overlay
+
+## API Endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/` | Milestone page |
+| GET | `/workflow` | Workflow page |
+| GET | `/api/milestones` | Milestone JSON data |
+| GET | `/api/workflow` | Workflow JSON data |
+| POST | `/api/docs/:type/:file/items/:line` | Update item status |
+
+## Parser System
+
+Kanboard parses 8 document types from `.unipi/docs/`:
+
+| Type | Directory | What's Parsed |
+|------|-----------|---------------|
+| Spec | `specs/` | `- [ ]` / `- [x]` checklist items |
+| Plan | `plans/` | `unstarted:` / `in-progress:` / `completed:` statuses |
+| Milestone | `MILESTONES.md` | Phase headers + checklist items |
+| Quick-work | `quick-work/` | Title + checklist items |
+| Debug | `debug/` | Headers + checklists |
+| Fix | `fix/` | Headers + checklists + related debug ref |
+| Chore | `chore/` | Chore steps as checklist items |
+| Review | `reviews/` | Review remarks as checklist items |
+
+### Parser Warnings
+
+Parsers are resilient — they collect warnings per file and return partial results:
+- Empty checkbox text
+- Malformed checkboxes
+- Missing frontmatter
+- Unparseable lines
+
+Warnings are surfaced in the kanboard-doctor skill.
+
+## Doctor Skill
+
+The `kanboard-doctor` skill runs all parsers and produces a diagnostic report:
+
+1. **Run All Parsers** — Parse every document
+2. **Collect Errors** — Group warnings by file
+3. **Present Report** — Structured error listing
+4. **Fix One by One** — Suggest fixes, ask user to confirm
+5. **Re-validate** — Re-run parser after each fix
+
+## Server Configuration
+
+Default configuration (from `@pi-unipi/core`):
+
+```typescript
+KANBOARD_DEFAULTS = {
+  PORT: 8165,      // Starting port
+  MAX_PORT: 8175,  // Maximum port to try
+}
+```
+
+- Port allocation: tries 8165, increments on EADDRINUSE
+- PID file: `.unipi/kanboard.pid`
+- Graceful shutdown on SIGINT/SIGTERM
+- Static files served from `ui/static/`
+
+## Dependencies
+
+- `@pi-unipi/core` — Shared constants and utilities
+- `@mariozechner/pi-coding-agent` — Extension API
+- `@mariozechner/pi-tui` — TUI overlay API

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@pi-unipi/kanboard",
+  "version": "0.1.2",
+  "description": "Visualization layer for unipi workflow — HTTP server with htmx/Alpine.js UI, modular parsers, TUI overlay, and kanban board",
+  "type": "module",
+  "license": "MIT",
+  "author": "Neuron Mr White",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Neuron-Mr-White/unipi.git",
+    "directory": "packages/kanboard"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi-coding-agent",
+    "unipi",
+    "kanboard",
+    "kanban",
+    "visualization",
+    "milestones",
+    "workflow"
+  ],
+  "files": [
+    "src/**/*.ts",
+    "ui/**/*.ts",
+    "ui/**/*.css",
+    "ui/**/*.js",
+    "skills/**/*",
+    "README.md"
+  ],
+  "pi": {
+    "extensions": [
+      "index.ts"
+    ],
+    "skills": [
+      "skills"
+    ]
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@pi-unipi/core": "*"
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "*",
+    "@mariozechner/pi-tui": "*"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.0",
+    "typescript": "^6.0.0"
+  }
+}

package/skills/kanboard-doctor/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: kanboard-doctor
+description: "Diagnose and fix kanboard parser issues — validates all workflow documents, reports errors, suggests fixes."
+---
+
+# Kanboard Doctor
+
+Diagnose parser issues across all workflow documents. Non-destructive — only suggests fixes, asks user to confirm.
+
+## Phase 1: Run All Parsers
+
+Execute each parser against its document type directory:
+
+1. Load the parser registry from `@pi-unipi/kanboard`
+2. Run `registry.parseAll(".unipi/docs")` to parse all documents
+3. Collect all `ParsedDoc` results including their `warnings` arrays
+
+## Phase 2: Collect Errors
+
+Group warnings and errors by file with line numbers:
+
+1. For each `ParsedDoc` with `warnings.length > 0`:
+   - Group by `filePath`
+   - Include line numbers where available
+   - Categorize: malformed checkboxes, empty fields, parse failures
+2. Also flag documents that returned 0 items (may indicate parsing failure)
+
+## Phase 3: Present Report
+
+Show a structured error report:
+
+```
+📋 Kanboard Doctor Report
+
+Files scanned: N
+Files with issues: M
+
+📄 .unipi/docs/specs/example.md
+  ⚠ Line 15: Empty checkbox text
+  ⚠ Line 23: Malformed checkbox (missing bracket)
+
+📄 .unipi/docs/plans/old-plan.md
+  ⚠ Line 5: Empty task name after status
+```
+
+## Phase 4: Fix One by One
+
+For each issue, suggest a fix and ask user to confirm:
+
+1. Show the problematic line with context
+2. Suggest the corrected version
+3. Ask: "Apply this fix? (y/n)"
+4. If yes, apply the fix using the edit tool
+5. Move to next issue
+
+**Non-destructive rules:**
+- Never modify without asking
+- Show before/after for each change
+- Allow skipping individual fixes
+- Allow "fix all" for simple patterns (e.g., trailing whitespace)
+
+## Phase 5: Re-validate
+
+After each fix, re-run the parser on the modified file:
+
+1. Parse the file again
+2. Verify the specific error is resolved
+3. Check that no new errors were introduced
+4. Report: "✓ Fixed" or "✗ Still has issues"
+
+After all fixes, run full `registry.parseAll()` to confirm clean state.

package/ui/components/checklist.ts

@@ -0,0 +1,58 @@
+/**
+ * @pi-unipi/kanboard — Checklist Component
+ *
+ * Reusable checklist renderer with status indicators and copy buttons.
+ */
+
+import type { ParsedItem } from "../../types.js";
+
+/** Escape HTML */
+function esc(text: string): string {
+  return text
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#39;");
+}
+
+/** Status icon */
+function statusIcon(status: string): string {
+  switch (status) {
+    case "done":
+      return "✓";
+    case "in-progress":
+      return "◐";
+    default:
+      return "○";
+  }
+}
+
+/**
+ * Render a checklist of items.
+ */
+export function renderChecklist(items: ParsedItem[]): string {
+  if (items.length === 0) {
+    return '<div class="empty-state"><p class="empty-state-text">No items</p></div>';
+  }
+
+  const rows = items
+    .map(
+      (item) => `
+    <li class="checklist-item">
+      <span class="checklist-status ${item.status}" aria-label="${item.status}">
+        <span aria-hidden="true">${statusIcon(item.status)}</span>
+        <span class="visually-hidden">${item.status}</span>
+      </span>
+      <span class="checklist-text${item.status === "done" ? " done" : ""}">${esc(item.text)}</span>
+      ${
+        item.command
+          ? `<button class="copy-btn" onclick="copyToClipboard('${esc(item.command)}', event)" aria-label="Copy ${esc(item.command)} to clipboard">${esc(item.command)}</button>`
+          : ""
+      }
+    </li>`,
+    )
+    .join("\n");
+
+  return `<ul class="checklist">${rows}</ul>`;
+}

package/ui/components/copy-button.ts

@@ -0,0 +1,23 @@
+/**
+ * @pi-unipi/kanboard — Copy Button Component
+ *
+ * Reusable copy-to-clipboard button with visual feedback.
+ */
+
+/** Escape HTML */
+function esc(text: string): string {
+  return text
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#39;");
+}
+
+/**
+ * Render a copy-to-clipboard button.
+ */
+export function renderCopyButton(text: string, label?: string): string {
+  const displayLabel = label ?? (text.length > 40 ? text.slice(0, 37) + "..." : text);
+  return `<button class="copy-btn" onclick="copyToClipboard('${esc(text)}', event)" title="${esc(text)}" aria-label="Copy ${esc(displayLabel)} to clipboard">${esc(displayLabel)}</button>`;
+}

package/ui/components/status-badge.ts

@@ -0,0 +1,21 @@
+/**
+ * @pi-unipi/kanboard — Status Badge Component
+ *
+ * Color-coded status badge for items.
+ */
+
+/** Status badge labels */
+const BADGE_LABELS: Record<string, string> = {
+  done: "Done",
+  "in-progress": "In Progress",
+  todo: "To Do",
+  reviewed: "Reviewed",
+};
+
+/**
+ * Render a status badge.
+ */
+export function renderStatusBadge(status: string): string {
+  const label = BADGE_LABELS[status] ?? status;
+  return `<span class="badge badge-${status}">${label}</span>`;
+}

package/ui/layouts/base.ts

@@ -0,0 +1,68 @@
+/**
+ * @pi-unipi/kanboard — Base HTML Layout
+ *
+ * Shared layout for all kanboard web pages.
+ * Includes htmx + Alpine.js CDN, Google Fonts, and responsive layout.
+ */
+
+/** Active page type */
+export type ActivePage = "milestones" | "workflow";
+
+/**
+ * Render the full HTML layout wrapping page content.
+ */
+export function renderLayout(
+  title: string,
+  content: string,
+  activePage: ActivePage,
+): string {
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>${escapeHtml(title)} — Kanboard</title>
+  <script src="https://unpkg.com/htmx.org@1.9.12"></script>
+  <script defer src="https://unpkg.com/alpinejs@3.14.3/dist/cdn.min.js"></script>
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link href="https://fonts.googleapis.com/css2?family=Bodoni+Moda:ital,opsz,wght@1,6..96,400..900&family=Onest:wght@100..900&family=JetBrains+Mono:wght@400;500&display=swap" rel="stylesheet">
+  <link rel="stylesheet" href="/static/style.css">
+</head>
+<body>
+  <nav class="navbar">
+    <div class="nav-brand">
+      <span class="nav-icon">✦</span>
+      <span class="nav-title">Kanboard</span>
+    </div>
+    <div class="nav-links">
+      <a href="/" class="nav-link ${activePage === "milestones" ? "active" : ""}" ${activePage === "milestones" ? 'aria-current="page"' : ""}>
+        Milestones
+      </a>
+      <a href="/workflow" class="nav-link ${activePage === "workflow" ? "active" : ""}" ${activePage === "workflow" ? 'aria-current="page"' : ""}>
+        Workflow
+      </a>
+    </div>
+  </nav>
+
+  <main class="container">
+    ${content}
+  </main>
+
+  <footer class="footer">
+    <span>pi-unipi / kanboard</span>
+  </footer>
+
+  <script src="/static/app.js"></script>
+</body>
+</html>`;
+}
+
+/** Escape HTML special characters */
+function escapeHtml(text: string): string {
+  return text
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}

package/ui/milestone/page.ts

@@ -0,0 +1,140 @@
+/**
+ * @pi-unipi/kanboard — Milestone Page
+ *
+ * Renders the milestone page with phases, progress bars, and checklists.
+ */
+
+import type { ParsedDoc, ParsedItem } from "../../types.js";
+import { renderLayout } from "../layouts/base.js";
+
+/** Escape HTML special characters */
+function esc(text: string): string {
+  return text
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}
+
+/** Render status icon for an item */
+function statusIcon(status: string): string {
+  switch (status) {
+    case "done":
+      return "✓";
+    case "in-progress":
+      return "◐";
+    default:
+      return "○";
+  }
+}
+
+/** Render a single checklist item */
+function renderItem(item: ParsedItem): string {
+  const doneClass = item.status === "done" ? " done" : "";
+  const commandBtn = item.command
+    ? `<button class="copy-btn" onclick="copyToClipboard('${esc(item.command)}', event)" aria-label="Copy ${esc(item.command)} to clipboard">${esc(item.command)}</button>`
+    : "";
+
+  return `
+    <li class="checklist-item">
+      <span class="checklist-status ${item.status}" aria-label="${item.status}">
+        <span aria-hidden="true">${statusIcon(item.status)}</span>
+        <span class="visually-hidden">${item.status}</span>
+      </span>
+      <span class="checklist-text${doneClass}">${esc(item.text)}</span>
+      ${commandBtn}
+    </li>`;
+}
+
+/** Render the milestone page */
+export function renderMilestonePage(docs: ParsedDoc[]): string {
+  if (docs.length === 0) {
+    const content = `
+      <div class="page-header">
+        <h1 class="page-title">Milestones</h1>
+        <p class="page-subtitle">Track project progress</p>
+      </div>
+      <div class="empty-state">
+        <div class="empty-state-icon">✦</div>
+        <p class="empty-state-text">No MILESTONES.md found</p>
+      </div>`;
+    return renderLayout("Milestones", content, "milestones");
+  }
+
+  const doc = docs[0];
+  const totalItems = doc.items.length;
+  const doneItems = doc.items.filter((i) => i.status === "done").length;
+  const percent = totalItems > 0 ? Math.round((doneItems / totalItems) * 100) : 0;
+
+  const phases = groupByPhase(doc.items);
+
+  let phasesHtml = "";
+  for (const [phase, items] of Object.entries(phases)) {
+    const phaseTotal = items.length;
+    const phaseDone = items.filter((i) => i.status === "done").length;
+    const phasePercent = phaseTotal > 0 ? Math.round((phaseDone / phaseTotal) * 100) : 0;
+
+    phasesHtml += `
+      <div class="section">
+        <button type="button" class="section-header" aria-expanded="true" onclick="toggleSection(event)">
+          <span class="section-toggle">▶</span>
+          <div class="section-title-wrap">
+            <h2 class="section-title">${esc(phase)}</h2>
+          </div>
+          <span class="section-count">${phaseDone}/${phaseTotal}</span>
+          <div class="progress-bar" style="--progress: ${phasePercent};">
+            <div class="progress-fill"></div>
+          </div>
+        </button>
+        <div class="section-content">
+          <ul class="checklist">
+            ${items.map(renderItem).join("\n")}
+          </ul>
+        </div>
+      </div>`;
+  }
+
+  const content = `
+    <div class="page-header">
+      <h1 class="page-title">${esc(doc.title)}</h1>
+      <p class="page-subtitle">${doneItems}/${totalItems} items complete</p>
+      <div class="progress-bar" style="--progress: ${percent};">
+        <div class="progress-fill"></div>
+      </div>
+      <div class="page-header-stat">${percent}% complete</div>
+    </div>
+
+    ${phasesHtml}
+
+    ${doc.warnings.length > 0 ? renderWarnings(doc.warnings) : ""}`;
+
+  return renderLayout("Milestones", content, "milestones");
+}
+
+/** Group items by their phase prefix [Phase Name] */
+function groupByPhase(items: ParsedItem[]): Record<string, ParsedItem[]> {
+  const phases: Record<string, ParsedItem[]> = {};
+
+  for (const item of items) {
+    const match = item.text.match(/^\[(.+?)\]\s*(.*)$/);
+    if (match) {
+      const phase = match[1];
+      const text = match[2];
+      if (!phases[phase]) phases[phase] = [];
+      phases[phase].push({ ...item, text });
+    } else {
+      if (!phases["Other"]) phases["Other"] = [];
+      phases["Other"].push(item);
+    }
+  }
+
+  return phases;
+}
+
+/** Render warnings list */
+function renderWarnings(warnings: string[]): string {
+  return `
+    <div class="warnings">
+      ${warnings.map((w) => `<div class="warning-item">${esc(w)}</div>`).join("\n")}
+    </div>`;
+}

package/ui/static/app.js

@@ -0,0 +1,73 @@
+/* @pi-unipi/kanboard — Client-side JavaScript */
+
+/**
+ * Copy text to clipboard and show feedback.
+ */
+function copyToClipboard(text, event) {
+  navigator.clipboard.writeText(text).then(() => {
+    const btn = event.currentTarget;
+    btn.classList.add("copied");
+    const original = btn.innerHTML;
+    btn.innerHTML = '<span>copied</span>';
+    setTimeout(() => {
+      btn.classList.remove("copied");
+      btn.innerHTML = original;
+    }, 1800);
+  });
+}
+
+/**
+ * Toggle a section's expanded state with animation.
+ */
+function toggleSection(event) {
+  const header = event.currentTarget;
+  const content = header.nextElementSibling;
+  if (!content) return;
+
+  const wasOpen = header.getAttribute("aria-expanded") === "true";
+  header.setAttribute("aria-expanded", wasOpen ? "false" : "true");
+
+  const prefersReducedMotion = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+
+  if (!wasOpen) {
+    content.style.display = "block";
+    if (!prefersReducedMotion) {
+      content.style.opacity = "0";
+      content.style.transform = "translateY(-4px)";
+      requestAnimationFrame(() => {
+        content.style.transition = "opacity 0.2s ease, transform 0.2s ease";
+        content.style.opacity = "1";
+        content.style.transform = "translateY(0)";
+      });
+    } else {
+      content.style.opacity = "1";
+      content.style.transform = "translateY(0)";
+    }
+  } else {
+    if (!prefersReducedMotion) {
+      content.style.transition = "opacity 0.15s ease";
+      content.style.opacity = "0";
+      setTimeout(() => {
+        content.style.display = "none";
+      }, 150);
+    } else {
+      content.style.display = "none";
+    }
+  }
+}
+
+/**
+ * Alpine.js data for filtering items by status.
+ */
+function kanboardFilters() {
+  return {
+    filter: "all",
+    setFilter(f) {
+      this.filter = f;
+    },
+    isVisible(status) {
+      if (this.filter === "all") return true;
+      return status === this.filter;
+    },
+  };
+}