@sienklogic/plan-build-run 2.0.0

package/dashboard/src/repositories/planning.repository.js

@@ -0,0 +1,128 @@
+import { readFile, readdir } from 'node:fs/promises';
+import { join, resolve, relative, normalize } from 'node:path';
+import matter from 'gray-matter';
+import { marked } from 'marked';
+
+/**
+ * Strip UTF-8 BOM (Byte Order Mark) if present.
+ * Windows editors (Notepad, older VS Code) may prepend BOM to UTF-8 files.
+ * gray-matter will fail to detect frontmatter delimiters if BOM is present.
+ * @param {string} content - Raw file content
+ * @returns {string} Content without BOM
+ */
+function stripBOM(content) {
+  return content.replace(/^\uFEFF/, '');
+}
+
+/**
+ * Validate that a resolved path stays within the base directory.
+ * Prevents path traversal attacks (e.g., ../../etc/passwd).
+ *
+ * @param {string} basePath - Absolute base directory path
+ * @param {string} userPath - User-provided path (may be relative)
+ * @returns {string} Validated absolute path
+ * @throws {Error} With status 403 if path escapes base directory
+ */
+export function validatePath(basePath, userPath) {
+  const resolvedBase = normalize(resolve(basePath));
+  const resolvedUser = normalize(resolve(basePath, userPath));
+
+  // Compute the relative path from base to target
+  const rel = relative(resolvedBase, resolvedUser);
+
+  // If relative path starts with '..' it escaped the base directory.
+  // If rel resolves to an absolute path, it was an absolute path injection.
+  if (rel.startsWith('..') || resolve(rel) === rel) {
+    const err = new Error('Path traversal attempt detected');
+    err.status = 403;
+    err.code = 'PATH_TRAVERSAL';
+    throw err;
+  }
+
+  return resolvedUser;
+}
+
+/**
+ * Read and parse a single markdown file with YAML frontmatter.
+ *
+ * @param {string} filePath - Absolute path to the markdown file
+ * @returns {Promise<{frontmatter: object, html: string, rawContent: string}>}
+ * @throws {Error} ENOENT if file does not exist, parse error if YAML is malformed
+ */
+export async function readMarkdownFile(filePath) {
+  const fileContent = await readFile(filePath, 'utf-8');
+  const cleanContent = stripBOM(fileContent);
+
+  let data, content;
+  try {
+    ({ data, content } = matter(cleanContent, {
+      engines: {
+        javascript: false
+      }
+    }));
+  } catch (error) {
+    // gray-matter throws YAMLException for malformed frontmatter.
+    // Wrap it in a user-friendly error with status 400.
+    if (error.name === 'YAMLException' || (error.constructor && error.constructor.name === 'YAMLException')) {
+      const wrapped = new Error(`Invalid YAML frontmatter in ${filePath}: ${error.message}`);
+      wrapped.status = 400;
+      wrapped.cause = error;
+      throw wrapped;
+    }
+    throw error;
+  }
+
+  const html = marked.parse(content);
+
+  return {
+    frontmatter: data,
+    html,
+    rawContent: content
+  };
+}
+
+/**
+ * Read and parse multiple markdown files in parallel (fail-fast).
+ * If any file fails, the entire operation rejects immediately.
+ *
+ * @param {string[]} filePaths - Array of absolute file paths
+ * @returns {Promise<Array<{frontmatter: object, html: string, rawContent: string}>>}
+ */
+export async function readMarkdownFiles(filePaths) {
+  return Promise.all(
+    filePaths.map(filePath => readMarkdownFile(filePath))
+  );
+}
+
+/**
+ * Read and parse multiple markdown files with partial failure tolerance.
+ * All reads complete even if some fail. Returns settled results.
+ *
+ * @param {string[]} filePaths - Array of absolute file paths
+ * @returns {Promise<Array<{status: 'fulfilled', value: object} | {status: 'rejected', reason: Error}>>}
+ */
+export async function readMarkdownFilesSettled(filePaths) {
+  return Promise.allSettled(
+    filePaths.map(filePath => readMarkdownFile(filePath))
+  );
+}
+
+/**
+ * List all markdown files under the .planning/ directory recursively.
+ * Uses native fs.readdir with recursive option (Node.js 18.17+).
+ *
+ * @param {string} projectDir - Absolute path to the project root
+ * @returns {Promise<string[]>} Array of absolute file paths to .md files
+ * @throws {Error} ENOENT if .planning/ directory does not exist
+ */
+export async function listPlanningFiles(projectDir) {
+  const planningDir = join(projectDir, '.planning');
+  const entries = await readdir(planningDir, {
+    recursive: true,
+    withFileTypes: true
+  });
+
+  return entries
+    .filter(entry => entry.isFile() && entry.name.endsWith('.md'))
+    .map(entry => join(entry.parentPath || entry.path, entry.name));
+}

package/dashboard/src/routes/events.routes.js

@@ -0,0 +1,40 @@
+import { Router } from 'express';
+import { addClient, removeClient } from '../services/sse.service.js';
+
+const router = Router();
+
+/**
+ * GET /stream - Server-Sent Events endpoint.
+ * Establishes a long-lived SSE connection. Events are pushed by the SSE service
+ * when the file watcher detects changes. Heartbeat comments every 30s keep the
+ * connection alive.
+ */
+router.get('/stream', (req, res) => {
+  // Set SSE headers
+  res.writeHead(200, {
+    'Content-Type': 'text/event-stream',
+    'Cache-Control': 'no-cache',
+    'Connection': 'keep-alive',
+    'X-Accel-Buffering': 'no'
+  });
+  res.flushHeaders();
+
+  // Send initial connection confirmation
+  res.write(': connected\n\n');
+
+  // Register this client for broadcasts
+  addClient(res);
+
+  // Heartbeat every 30 seconds to keep connection alive
+  const heartbeat = setInterval(() => {
+    res.write(': heartbeat\n\n');
+  }, 30000);
+
+  // Clean up on client disconnect
+  req.on('close', () => {
+    clearInterval(heartbeat);
+    removeClient(res);
+  });
+});
+
+export default router;

package/dashboard/src/routes/index.routes.js

@@ -0,0 +1,31 @@
+import { Router } from 'express';
+import { getHomepage } from '../services/project.service.js';
+import { getDashboardData } from '../services/dashboard.service.js';
+
+const router = Router();
+
+router.get('/', async (req, res) => {
+  const projectDir = req.app.locals.projectDir;
+
+  const [homepageData, dashboardData] = await Promise.all([
+    getHomepage(projectDir),
+    getDashboardData(projectDir)
+  ]);
+
+  const templateData = {
+    ...homepageData,
+    ...dashboardData,
+    activePage: 'dashboard',
+    currentPath: '/'
+  };
+
+  res.setHeader('Vary', 'HX-Request');
+
+  if (req.get('HX-Request') === 'true') {
+    res.render('partials/dashboard-content', templateData);
+  } else {
+    res.render('index', templateData);
+  }
+});
+
+export default router;

package/dashboard/src/routes/pages.routes.js

@@ -0,0 +1,195 @@
+import { Router } from 'express';
+import { getPhaseDetail } from '../services/phase.service.js';
+import { getRoadmapData } from '../services/roadmap.service.js';
+import { listPendingTodos, getTodoDetail, createTodo, completeTodo } from '../services/todo.service.js';
+
+const router = Router();
+
+router.get('/phases', async (req, res) => {
+  const projectDir = req.app.locals.projectDir;
+  const roadmapData = await getRoadmapData(projectDir);
+
+  const templateData = {
+    title: 'Phases',
+    activePage: 'phases',
+    currentPath: '/phases',
+    phases: roadmapData.phases,
+    milestones: roadmapData.milestones
+  };
+
+  res.setHeader('Vary', 'HX-Request');
+
+  if (req.get('HX-Request') === 'true') {
+    res.render('partials/phases-content', templateData);
+  } else {
+    res.render('phases', templateData);
+  }
+});
+
+router.get('/phases/:phaseId', async (req, res) => {
+  const { phaseId } = req.params;
+
+  // Validate phaseId: two digits, optionally followed by decimal (e.g., 01, 05, 3.1)
+  if (!/^\d{1,2}(\.\d+)?$/.test(phaseId)) {
+    const err = new Error('Phase ID must be a number (e.g., 01, 05, 3.1)');
+    err.status = 404;
+    throw err;
+  }
+
+  const projectDir = req.app.locals.projectDir;
+  const phaseData = await getPhaseDetail(projectDir, phaseId);
+
+  const templateData = {
+    title: `Phase ${phaseId}: ${phaseData.phaseName}`,
+    activePage: 'phases',
+    currentPath: '/phases/' + phaseId,
+    ...phaseData
+  };
+
+  res.setHeader('Vary', 'HX-Request');
+
+  if (req.get('HX-Request') === 'true') {
+    res.render('partials/phase-content', templateData);
+  } else {
+    res.render('phase-detail', templateData);
+  }
+});
+
+router.get('/todos', async (req, res) => {
+  const projectDir = req.app.locals.projectDir;
+  const todos = await listPendingTodos(projectDir);
+
+  const templateData = {
+    title: 'Todos',
+    activePage: 'todos',
+    currentPath: '/todos',
+    todos
+  };
+
+  res.setHeader('Vary', 'HX-Request');
+
+  if (req.get('HX-Request') === 'true') {
+    res.render('partials/todos-content', templateData);
+  } else {
+    res.render('todos', templateData);
+  }
+});
+
+router.get('/todos/new', (req, res) => {
+  const templateData = {
+    title: 'Create Todo',
+    activePage: 'todos',
+    currentPath: '/todos/new'
+  };
+
+  res.setHeader('Vary', 'HX-Request');
+
+  if (req.get('HX-Request') === 'true') {
+    res.render('partials/todo-create-content', templateData);
+  } else {
+    res.render('todo-create', templateData);
+  }
+});
+
+router.get('/todos/:id', async (req, res) => {
+  const { id } = req.params;
+
+  // Validate ID format: must be exactly three digits
+  if (!/^\d{3}$/.test(id)) {
+    const err = new Error('Todo ID must be a three-digit number (e.g., 001, 005, 042)');
+    err.status = 404;
+    throw err;
+  }
+
+  const projectDir = req.app.locals.projectDir;
+  const todo = await getTodoDetail(projectDir, id);
+
+  const templateData = {
+    title: `Todo ${todo.id}: ${todo.title}`,
+    activePage: 'todos',
+    currentPath: '/todos/' + id,
+    ...todo
+  };
+
+  res.setHeader('Vary', 'HX-Request');
+
+  if (req.get('HX-Request') === 'true') {
+    res.render('partials/todo-detail-content', templateData);
+  } else {
+    res.render('todo-detail', templateData);
+  }
+});
+
+router.post('/todos', async (req, res) => {
+  const { title, priority, phase, description } = req.body;
+  const projectDir = req.app.locals.projectDir;
+
+  const todoId = await createTodo(projectDir, {
+    title,
+    priority,
+    phase: phase || '',
+    description
+  });
+
+  if (req.get('HX-Request') === 'true') {
+    // For HTMX: fetch the new todo and render its detail as a fragment
+    const todo = await getTodoDetail(projectDir, todoId);
+    res.render('partials/todo-detail-content', {
+      title: `Todo ${todo.id}: ${todo.title}`,
+      activePage: 'todos',
+      currentPath: '/todos/' + todoId,
+      ...todo
+    });
+  } else {
+    res.redirect(`/todos/${todoId}`);
+  }
+});
+
+router.post('/todos/:id/done', async (req, res) => {
+  const { id } = req.params;
+
+  if (!/^\d{3}$/.test(id)) {
+    const err = new Error('Todo ID must be a three-digit number');
+    err.status = 404;
+    throw err;
+  }
+
+  const projectDir = req.app.locals.projectDir;
+  await completeTodo(projectDir, id);
+
+  if (req.get('HX-Request') === 'true') {
+    // For HTMX: re-render the full todo list as a fragment
+    const todos = await listPendingTodos(projectDir);
+    res.render('partials/todos-content', {
+      title: 'Todos',
+      activePage: 'todos',
+      currentPath: '/todos',
+      todos
+    });
+  } else {
+    res.redirect('/todos');
+  }
+});
+
+router.get('/roadmap', async (req, res) => {
+  const projectDir = req.app.locals.projectDir;
+  const roadmapData = await getRoadmapData(projectDir);
+
+  const templateData = {
+    title: 'Roadmap',
+    activePage: 'roadmap',
+    currentPath: '/roadmap',
+    phases: roadmapData.phases,
+    milestones: roadmapData.milestones
+  };
+
+  res.setHeader('Vary', 'HX-Request');
+
+  if (req.get('HX-Request') === 'true') {
+    res.render('partials/roadmap-content', templateData);
+  } else {
+    res.render('roadmap', templateData);
+  }
+});
+
+export default router;

package/dashboard/src/server.js

@@ -0,0 +1,42 @@
+import { createApp } from './app.js';
+import { createWatcher } from './services/watcher.service.js';
+import { broadcast } from './services/sse.service.js';
+
+export function startServer(config) {
+  const app = createApp(config);
+  const { port, projectDir } = config;
+
+  // Start file watcher for live updates
+  const watcher = createWatcher(projectDir, (event) => {
+    broadcast('file-change', event);
+  });
+
+  const server = app.listen(port, '127.0.0.1', () => {
+    console.log(`PBR Dashboard running at http://127.0.0.1:${port}`);
+    console.log(`Project directory: ${projectDir}`);
+    console.log('File watcher active on .planning/**/*.md');
+  });
+
+  const shutdown = async (signal) => {
+    console.log(`${signal} received. Shutting down PBR Dashboard...`);
+
+    // Close watcher first (stops generating events)
+    try {
+      await watcher.close();
+      console.log('File watcher closed.');
+    } catch (err) {
+      console.error('Error closing watcher:', err.message);
+    }
+
+    // Then close the HTTP server
+    server.close(() => {
+      console.log('Server closed.');
+      process.exit(0);
+    });
+  };
+
+  process.on('SIGTERM', () => shutdown('SIGTERM'));
+  process.on('SIGINT', () => shutdown('SIGINT'));
+
+  return server;
+}

package/dashboard/src/services/dashboard.service.js

@@ -0,0 +1,222 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+/**
+ * Strip UTF-8 BOM from file content.
+ * Duplicated from planning.repository.js intentionally --
+ * this service reads raw text, not via the repository layer.
+ *
+ * @param {string} content - Raw file content
+ * @returns {string} Content without BOM
+ */
+function stripBOM(content) {
+  return content.replace(/^\uFEFF/, '');
+}
+
+/**
+ * Parse STATE.md to extract project status information.
+ * Uses regex on raw markdown body text (not YAML frontmatter).
+ *
+ * @param {string} projectDir - Absolute path to the project root
+ * @returns {Promise<{projectName: string, currentPhase: object, lastActivity: object, progress: number}>}
+ */
+export async function parseStateFile(projectDir) {
+  try {
+    const path = join(projectDir, '.planning', 'STATE.md');
+    const raw = await readFile(path, 'utf-8');
+    const content = stripBOM(raw);
+
+    // Extract project name from **Current focus:** line
+    let projectName = 'Unknown Project';
+    const focusMatch = content.match(/\*\*Current focus:\*\*\s*(.+)/);
+    if (focusMatch) {
+      projectName = focusMatch[1].trim();
+    } else {
+      // Fallback: try H1 heading
+      const h1Match = content.match(/^# (.+)/m);
+      if (h1Match) {
+        projectName = h1Match[1].trim();
+      }
+    }
+
+    // Extract current phase: "Phase: 3 of 12 (UI Shell)"
+    let currentPhaseId = 0;
+    let totalPhases = 0;
+    let phaseName = 'Not Started';
+    const phaseMatch = content.match(/Phase:\s*(\d+)\s*of\s*(\d+)\s*\(([^)]+)\)/);
+    if (phaseMatch) {
+      currentPhaseId = parseInt(phaseMatch[1], 10);
+      totalPhases = parseInt(phaseMatch[2], 10);
+      phaseName = phaseMatch[3].trim();
+    }
+
+    // Extract plan status: "Plan: 2 of 2 complete"
+    let planStatus = 'N/A';
+    const planMatch = content.match(/Plan:\s*(.+)/);
+    if (planMatch) {
+      planStatus = planMatch[1].trim();
+    }
+
+    // Extract last activity: "Last activity: 2026-02-08 -- Phase 3 built (...)"
+    let activityDate = '';
+    let activityDescription = 'No activity recorded';
+    const activityMatch = content.match(/Last activity:\s*([\d-]+)\s*--\s*(.+)/);
+    if (activityMatch) {
+      activityDate = activityMatch[1].trim();
+      activityDescription = activityMatch[2].trim();
+    }
+
+    // Extract progress percentage: "Progress: [...] 25%"
+    let progress = 0;
+    const progressMatch = content.match(/Progress:.*?(\d+)%/);
+    if (progressMatch) {
+      progress = parseInt(progressMatch[1], 10);
+    } else if (totalPhases > 0) {
+      // Calculate from phase numbers if no explicit progress
+      progress = Math.ceil((currentPhaseId / totalPhases) * 100);
+    }
+
+    return {
+      projectName,
+      currentPhase: {
+        id: currentPhaseId,
+        total: totalPhases,
+        name: phaseName,
+        planStatus
+      },
+      lastActivity: {
+        date: activityDate,
+        description: activityDescription
+      },
+      progress
+    };
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      return {
+        projectName: 'Unknown Project',
+        currentPhase: { id: 0, total: 0, name: 'Not Started', planStatus: 'N/A' },
+        lastActivity: { date: '', description: 'No activity recorded' },
+        progress: 0
+      };
+    }
+    throw error;
+  }
+}
+
+/**
+ * Parse ROADMAP.md to extract phase list from Progress table and checkbox list.
+ * Uses the Progress table as primary source (contains ALL phases including those
+ * added under milestone headings). Falls back to checkbox parsing for older
+ * roadmaps that don't have a Progress table.
+ *
+ * @param {string} projectDir - Absolute path to the project root
+ * @returns {Promise<{phases: Array<{id: number, name: string, description: string, status: string}>, progress: number}>}
+ */
+export async function parseRoadmapFile(projectDir) {
+  try {
+    const filePath = join(projectDir, '.planning', 'ROADMAP.md');
+    const raw = await readFile(filePath, 'utf-8');
+    const content = stripBOM(raw).replace(/\r\n/g, '\n');
+
+    // 1. Parse descriptions from checkbox list: "- [x] Phase 01: Name -- Description"
+    const checkboxMap = new Map();
+    const checkboxRegex = /^- \[([ xX])\] Phase (\d+):\s*([^-]+?)\s*--\s*(.+)$/gm;
+    for (const match of content.matchAll(checkboxRegex)) {
+      const id = parseInt(match[2], 10);
+      checkboxMap.set(id, {
+        name: match[3].trim(),
+        description: match[4].trim(),
+        status: (match[1] === 'x' || match[1] === 'X') ? 'complete' : 'not-started'
+      });
+    }
+
+    // 2. Parse descriptions from Phase Details: "### Phase NN: Name\n**Goal**: ..."
+    const goalMap = new Map();
+    const goalRegex = /### Phase (\d+):\s*(.+)\n\*\*Goal\*\*:\s*(.+)/g;
+    for (const match of content.matchAll(goalRegex)) {
+      goalMap.set(parseInt(match[1], 10), match[3].trim());
+    }
+
+    // 3. Parse Progress table: "| 01. Name | 2/2 | Complete | 2026-02-08 |"
+    const progressRegex = /^\|\s*(\d+)\.\s+(.+?)\s*\|\s*(\d+)\/([\d?]+)\s*\|\s*(.+?)\s*\|\s*(.+?)\s*\|$/gm;
+    const progressPhases = [];
+    for (const match of content.matchAll(progressRegex)) {
+      const id = parseInt(match[1], 10);
+      const name = match[2].trim();
+      const statusText = match[5].trim().toLowerCase();
+
+      // Get description: prefer checkbox description, fall back to Phase Details Goal
+      const cbInfo = checkboxMap.get(id);
+      const goalDesc = goalMap.get(id);
+      const description = cbInfo?.description || goalDesc || '';
+
+      let status;
+      if (statusText === 'complete') status = 'complete';
+      else if (statusText === 'in progress') status = 'in-progress';
+      else status = 'not-started';
+
+      progressPhases.push({ id, name, description, status });
+    }
+
+    // Use Progress table if available, otherwise fall back to checkbox parsing
+    let phases;
+    if (progressPhases.length > 0) {
+      phases = progressPhases;
+    } else {
+      phases = [...checkboxMap.entries()]
+        .map(([id, info]) => ({
+          id,
+          name: info.name,
+          description: info.description,
+          status: info.status
+        }))
+        .sort((a, b) => a.id - b.id);
+    }
+
+    const completed = phases.filter(p => p.status === 'complete').length;
+    const total = phases.length;
+    const progress = total > 0 ? Math.ceil((completed / total) * 100) : 0;
+
+    return { phases, progress };
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      return { phases: [], progress: 0 };
+    }
+    throw error;
+  }
+}
+
+/**
+ * Get combined dashboard data by parsing both STATE.md and ROADMAP.md.
+ * Orchestrates both parsers in parallel and derives in-progress status.
+ *
+ * @param {string} projectDir - Absolute path to the project root
+ * @returns {Promise<{projectName: string, currentPhase: object, lastActivity: object, progress: number, phases: Array}>}
+ */
+export async function getDashboardData(projectDir) {
+  const [stateData, roadmapData] = await Promise.all([
+    parseStateFile(projectDir),
+    parseRoadmapFile(projectDir)
+  ]);
+
+  // Derive "in-progress" status for the current phase
+  const phases = roadmapData.phases.map(phase => ({
+    ...phase,
+    status: (phase.id === stateData.currentPhase.id && phase.status !== 'complete')
+      ? 'in-progress'
+      : phase.status
+  }));
+
+  // Prefer roadmap progress if phases exist, otherwise use state progress
+  const progress = roadmapData.phases.length > 0
+    ? roadmapData.progress
+    : stateData.progress;
+
+  return {
+    projectName: stateData.projectName,
+    currentPhase: stateData.currentPhase,
+    lastActivity: stateData.lastActivity,
+    progress,
+    phases
+  };
+}