@sienklogic/plan-build-run 2.14.0 → 2.16.0

package/dashboard/public/js/sse-client.js

@@ -0,0 +1,99 @@
+/**
+ * Custom SSE client with exponential backoff reconnection and state recovery.
+ */
+(function () {
+  'use strict';
+
+  class SSEClient {
+    constructor(url) {
+      this.baseUrl = url;
+      this.lastEventId = null;
+      this.backoff = 1000;
+      this.maxBackoff = 30000;
+      this.reconnectTimer = null;
+      this.es = null;
+      this.connect();
+    }
+
+    connect() {
+      if (this.es) {
+        this.es.close();
+      }
+
+      let url = this.baseUrl;
+      if (this.lastEventId) {
+        const sep = url.includes('?') ? '&' : '?';
+        url += sep + 'lastEventId=' + encodeURIComponent(this.lastEventId);
+      }
+
+      this.es = new EventSource(url);
+
+      this.es.onopen = () => {
+        this.backoff = 1000;
+        this.updateStatus(true);
+      };
+
+      this.es.onerror = () => {
+        this.es.close();
+        this.updateStatus(false);
+        this.scheduleReconnect();
+      };
+
+      this.es.addEventListener('file-change', (e) => {
+        if (e.lastEventId) {
+          this.lastEventId = e.lastEventId;
+        }
+        this.refreshContent();
+      });
+
+      this.es.addEventListener('state-recovery', (e) => {
+        if (e.lastEventId) {
+          this.lastEventId = e.lastEventId;
+        }
+        this.refreshContent();
+      });
+    }
+
+    scheduleReconnect() {
+      if (this.reconnectTimer) {
+        clearTimeout(this.reconnectTimer);
+      }
+      const jitter = this.backoff * (0.5 + Math.random() * 0.5);
+      this.reconnectTimer = setTimeout(() => {
+        this.connect();
+      }, jitter);
+      this.backoff = Math.min(this.backoff * 2, this.maxBackoff);
+    }
+
+    updateStatus(connected) {
+      const dot = document.getElementById('sse-status');
+      if (dot) {
+        dot.setAttribute('data-connected', String(connected));
+      }
+    }
+
+    refreshContent() {
+      const currentPath = window.location.pathname;
+      fetch(currentPath, {
+        headers: { 'HX-Request': 'true' }
+      })
+        .then((res) => {
+          if (res.ok) return res.text();
+          throw new Error('Fetch failed: ' + res.status);
+        })
+        .then((html) => {
+          const target = document.getElementById('main-content');
+          if (target) {
+            target.innerHTML = html;
+          }
+        })
+        .catch((err) => {
+          console.error('SSE content refresh failed:', err.message);
+        });
+    }
+  }
+
+  document.addEventListener('DOMContentLoaded', () => {
+    new SSEClient('/api/events/stream');
+  });
+})();

package/dashboard/public/js/theme-toggle.js

@@ -0,0 +1,46 @@
+/* theme-toggle.js — Toggle light/dark theme via data-theme attribute + localStorage */
+(function () {
+  'use strict';
+
+  var STORAGE_KEY = 'pbr-theme';
+
+  function getEffectiveTheme() {
+    var explicit = document.documentElement.dataset.theme;
+    if (explicit === 'light' || explicit === 'dark') return explicit;
+    return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
+  }
+
+  function updateIcon(btn, theme) {
+    // Show sun when dark (click to go light), moon when light (click to go dark)
+    btn.textContent = theme === 'dark' ? '\u2600\uFE0F' : '\uD83C\uDF19';
+    btn.setAttribute('aria-label', theme === 'dark' ? 'Switch to light theme' : 'Switch to dark theme');
+  }
+
+  document.addEventListener('DOMContentLoaded', function () {
+    var btn = document.getElementById('theme-toggle');
+    if (!btn) return;
+
+    // Apply stored theme (also done in layout-top inline script for flash prevention)
+    var stored = localStorage.getItem(STORAGE_KEY);
+    if (stored) {
+      document.documentElement.dataset.theme = stored;
+    }
+
+    updateIcon(btn, getEffectiveTheme());
+
+    btn.addEventListener('click', function () {
+      var current = getEffectiveTheme();
+      var next = current === 'dark' ? 'light' : 'dark';
+      document.documentElement.dataset.theme = next;
+      localStorage.setItem(STORAGE_KEY, next);
+      updateIcon(btn, next);
+    });
+
+    // Update icon if system preference changes and no explicit preference is stored
+    window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', function () {
+      if (!localStorage.getItem(STORAGE_KEY)) {
+        updateIcon(btn, getEffectiveTheme());
+      }
+    });
+  });
+})();

package/dashboard/src/app.js

@@ -8,6 +8,7 @@ import pagesRouter from './routes/pages.routes.js';
 import eventsRouter from './routes/events.routes.js';
 import notFoundHandler from './middleware/notFoundHandler.js';
 import errorHandler from './middleware/errorHandler.js';
+import currentPhaseMiddleware from './middleware/current-phase.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -63,6 +64,9 @@ export function createApp(config) {
     next();
   });
 
+  // Current phase middleware (populates res.locals.currentPhase for templates)
+  app.use(currentPhaseMiddleware);
+
   // Routes
   app.use('/', indexRouter);
   app.use('/', pagesRouter);

package/dashboard/src/middleware/current-phase.js

@@ -0,0 +1,24 @@
+import { parseStateFile } from '../services/dashboard.service.js';
+
+/**
+ * Middleware that reads STATE.md and sets res.locals.currentPhase
+ * for use in sidebar and other templates.
+ */
+export default async function currentPhaseMiddleware(req, res, next) {
+  try {
+    const state = await parseStateFile(req.app.locals.projectDir);
+    const cp = state.currentPhase;
+    if (cp && cp.id > 0) {
+      res.locals.currentPhase = {
+        number: cp.id,
+        name: cp.name,
+        status: cp.status
+      };
+    } else {
+      res.locals.currentPhase = null;
+    }
+  } catch (_err) {
+    res.locals.currentPhase = null;
+  }
+  next();
+}

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

@@ -22,6 +22,11 @@ router.get('/stream', (req, res) => {
   // Send initial connection confirmation
   res.write(': connected\n\n');
 
+  // If client reconnected with a lastEventId, send state-recovery event
+  if (req.query.lastEventId) {
+    res.write(`event: state-recovery\ndata: {"action":"refresh"}\nid: ${Date.now()}\n\n`);
+  }
+
   // Register this client for broadcasts
   addClient(res);
 

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

@@ -16,7 +16,8 @@ router.get('/', async (req, res) => {
     ...homepageData,
     ...dashboardData,
     activePage: 'dashboard',
-    currentPath: '/'
+    currentPath: '/',
+    breadcrumbs: []
   };
 
   res.setHeader('Vary', 'HX-Request');

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

@@ -1,9 +1,10 @@
 import { Router } from 'express';
 import { getPhaseDetail, getPhaseDocument } from '../services/phase.service.js';
-import { getRoadmapData } from '../services/roadmap.service.js';
+import { getRoadmapData, generateDependencyMermaid } from '../services/roadmap.service.js';
 import { parseStateFile, derivePhaseStatuses } from '../services/dashboard.service.js';
 import { listPendingTodos, getTodoDetail, createTodo, completeTodo } from '../services/todo.service.js';
 import { getAllMilestones, getMilestoneDetail } from '../services/milestone.service.js';
+import { getProjectAnalytics } from '../services/analytics.service.js';
 
 const router = Router();
 
@@ -19,7 +20,8 @@ router.get('/phases', async (req, res) => {
     activePage: 'phases',
     currentPath: '/phases',
     phases: derivePhaseStatuses(roadmapData.phases, stateData.currentPhase),
-    milestones: roadmapData.milestones
+    milestones: roadmapData.milestones,
+    breadcrumbs: [{ label: 'Phases' }]
   };
 
   res.setHeader('Vary', 'HX-Request');
@@ -48,6 +50,7 @@ router.get('/phases/:phaseId', async (req, res) => {
     title: `Phase ${phaseId}: ${phaseData.phaseName}`,
     activePage: 'phases',
     currentPath: '/phases/' + phaseId,
+    breadcrumbs: [{ label: 'Phases', url: '/phases' }, { label: 'Phase ' + phaseId }],
     ...phaseData
   };
 
@@ -98,6 +101,7 @@ router.get('/phases/:phaseId/:planId/:docType', async (req, res) => {
     title: `${docLabel} ${planId} — Phase ${phaseId}: ${doc.phaseName}`,
     activePage: 'phases',
     currentPath: `/phases/${phaseId}/${planId}/${docType}`,
+    breadcrumbs: [{ label: 'Phases', url: '/phases' }, { label: 'Phase ' + phaseId, url: '/phases/' + phaseId }, { label: docLabel + ' ' + planId }],
     ...doc
   };
 
@@ -112,13 +116,20 @@ router.get('/phases/:phaseId/:planId/:docType', async (req, res) => {
 
 router.get('/todos', async (req, res) => {
   const projectDir = req.app.locals.projectDir;
-  const todos = await listPendingTodos(projectDir);
+  const { priority, status, q } = req.query;
+  const filters = {};
+  if (priority) filters.priority = priority;
+  if (status) filters.status = status;
+  if (q) filters.q = q;
+  const todos = await listPendingTodos(projectDir, filters);
 
   const templateData = {
     title: 'Todos',
     activePage: 'todos',
     currentPath: '/todos',
-    todos
+    breadcrumbs: [{ label: 'Todos' }],
+    todos,
+    filters: { priority: priority || '', status: status || '', q: q || '' }
   };
 
   res.setHeader('Vary', 'HX-Request');
@@ -130,11 +141,40 @@ router.get('/todos', async (req, res) => {
   }
 });
 
+router.post('/todos/bulk-complete', async (req, res) => {
+  const projectDir = req.app.locals.projectDir;
+  const { priority, status, q } = req.query;
+  const filters = {};
+  if (priority) filters.priority = priority;
+  if (status) filters.status = status;
+  if (q) filters.q = q;
+
+  const todos = await listPendingTodos(projectDir, filters);
+  for (const todo of todos) {
+    await completeTodo(projectDir, todo.id);
+  }
+
+  if (req.get('HX-Request') === 'true') {
+    const remaining = await listPendingTodos(projectDir);
+    res.render('partials/todos-content', {
+      title: 'Todos',
+      activePage: 'todos',
+      currentPath: '/todos',
+      breadcrumbs: [{ label: 'Todos' }],
+      todos: remaining,
+      filters: { priority: '', status: '', q: '' }
+    });
+  } else {
+    res.redirect('/todos');
+  }
+});
+
 router.get('/todos/new', (req, res) => {
   const templateData = {
     title: 'Create Todo',
     activePage: 'todos',
-    currentPath: '/todos/new'
+    currentPath: '/todos/new',
+    breadcrumbs: [{ label: 'Todos', url: '/todos' }, { label: 'Create' }]
   };
 
   res.setHeader('Vary', 'HX-Request');
@@ -163,6 +203,7 @@ router.get('/todos/:id', async (req, res) => {
     title: `Todo ${todo.id}: ${todo.title}`,
     activePage: 'todos',
     currentPath: '/todos/' + id,
+    breadcrumbs: [{ label: 'Todos', url: '/todos' }, { label: 'Todo ' + id }],
     ...todo
   };
 
@@ -193,6 +234,7 @@ router.post('/todos', async (req, res) => {
       title: `Todo ${todo.id}: ${todo.title}`,
       activePage: 'todos',
       currentPath: '/todos/' + todoId,
+      breadcrumbs: [{ label: 'Todos', url: '/todos' }, { label: 'Todo ' + todoId }],
       ...todo
     });
   } else {
@@ -219,6 +261,7 @@ router.post('/todos/:id/done', async (req, res) => {
       title: 'Todos',
       activePage: 'todos',
       currentPath: '/todos',
+      breadcrumbs: [{ label: 'Todos' }],
       todos
     });
   } else {
@@ -234,6 +277,7 @@ router.get('/milestones', async (req, res) => {
     title: 'Milestones',
     activePage: 'milestones',
     currentPath: '/milestones',
+    breadcrumbs: [{ label: 'Milestones' }],
     ...milestoneData
   };
 
@@ -269,6 +313,7 @@ router.get('/milestones/:version', async (req, res) => {
     title: `Milestone v${version}`,
     activePage: 'milestones',
     currentPath: '/milestones/' + version,
+    breadcrumbs: [{ label: 'Milestones', url: '/milestones' }, { label: 'v' + version }],
     ...detail
   };
 
@@ -281,6 +326,48 @@ router.get('/milestones/:version', async (req, res) => {
   }
 });
 
+router.get('/dependencies', async (req, res) => {
+  const projectDir = req.app.locals.projectDir;
+  const mermaidCode = await generateDependencyMermaid(projectDir);
+
+  const templateData = {
+    title: 'Dependencies',
+    activePage: 'dependencies',
+    currentPath: '/dependencies',
+    breadcrumbs: [{ label: 'Dependencies' }],
+    mermaidCode
+  };
+
+  res.setHeader('Vary', 'HX-Request');
+
+  if (req.get('HX-Request') === 'true') {
+    res.render('partials/dependencies-content', templateData);
+  } else {
+    res.render('dependencies', templateData);
+  }
+});
+
+router.get('/analytics', async (req, res) => {
+  const projectDir = req.app.locals.projectDir;
+  const analytics = await getProjectAnalytics(projectDir);
+
+  const templateData = {
+    title: 'Analytics',
+    activePage: 'analytics',
+    currentPath: '/analytics',
+    breadcrumbs: [{ label: 'Analytics' }],
+    analytics
+  };
+
+  res.setHeader('Vary', 'HX-Request');
+
+  if (req.get('HX-Request') === 'true') {
+    res.render('partials/analytics-content', templateData);
+  } else {
+    res.render('analytics', templateData);
+  }
+});
+
 router.get('/roadmap', async (req, res) => {
   const projectDir = req.app.locals.projectDir;
   const [roadmapData, stateData] = await Promise.all([
@@ -293,7 +380,8 @@ router.get('/roadmap', async (req, res) => {
     activePage: 'roadmap',
     currentPath: '/roadmap',
     phases: derivePhaseStatuses(roadmapData.phases, stateData.currentPhase),
-    milestones: roadmapData.milestones
+    milestones: roadmapData.milestones,
+    breadcrumbs: [{ label: 'Roadmap' }]
   };
 
   res.setHeader('Vary', 'HX-Request');

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

@@ -0,0 +1,143 @@
+import { execFile as execFileCb } from 'node:child_process';
+import { readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+import { TTLCache } from '../utils/cache.js';
+
+const execFile = promisify(execFileCb);
+
+export const cache = new TTLCache(60_000); // 60s TTL
+
+/**
+ * Run a git command in the given directory, returning stdout.
+ * Returns empty string on failure.
+ */
+async function git(projectDir, args) {
+  try {
+    const { stdout } = await execFile('git', args, {
+      cwd: projectDir,
+      maxBuffer: 10 * 1024 * 1024
+    });
+    return stdout;
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * Compute project analytics from git history and .planning/ files.
+ *
+ * @param {string} projectDir - Absolute path to the project root
+ * @returns {Promise<{phases: Array, summary: object, warning?: string}>}
+ */
+export async function getProjectAnalytics(projectDir) {
+  const cacheKey = `analytics:${projectDir}`;
+  const cached = cache.get(cacheKey);
+  if (cached) return cached;
+
+  const phasesDir = join(projectDir, '.planning', 'phases');
+  let phaseDirs = [];
+  let warning = null;
+
+  try {
+    const entries = await readdir(phasesDir, { withFileTypes: true });
+    phaseDirs = entries
+      .filter(e => e.isDirectory() && /^\d{2}-/.test(e.name))
+      .sort((a, b) => a.name.localeCompare(b.name));
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      warning = 'No .planning/phases/ directory found';
+    } else {
+      warning = `Failed to read phases directory: ${err.message}`;
+    }
+  }
+
+  // Get all commit log lines once
+  const allLog = await git(projectDir, ['log', '--oneline', '--all']);
+  const allLogLines = allLog ? allLog.trim().split('\n').filter(Boolean) : [];
+
+  // Get numstat for lines changed
+  const numstatRaw = await git(projectDir, ['log', '--numstat', '--all', '--format=COMMIT:%s']);
+
+  const phases = [];
+
+  for (const dir of phaseDirs) {
+    const phaseNum = dir.name.split('-')[0];
+    const phaseName = dir.name.split('-').slice(1).map(
+      w => w.charAt(0).toUpperCase() + w.slice(1).toLowerCase()
+    ).join(' ');
+
+    // Commit count: match scope pattern (NN-
+    const scopePattern = new RegExp(`\\(${phaseNum}-`);
+    const commitCount = allLogLines.filter(line => scopePattern.test(line)).length;
+
+    // Phase duration from git dates
+    const dateOutput = await git(projectDir, [
+      'log', '--format=%aI', '--', `.planning/phases/${dir.name}/`
+    ]);
+    const dates = dateOutput.trim().split('\n').filter(Boolean).map(d => new Date(d));
+    let duration = null;
+    if (dates.length >= 2) {
+      const earliest = new Date(Math.min(...dates));
+      const latest = new Date(Math.max(...dates));
+      const days = Math.round((latest - earliest) / (1000 * 60 * 60 * 24));
+      duration = `${days}d`;
+    } else if (dates.length === 1) {
+      duration = '0d';
+    }
+
+    // Plan count
+    let planCount = 0;
+    try {
+      const files = await readdir(join(phasesDir, dir.name));
+      planCount = files.filter(f => /^(?:\d{2}-\d{2}-)?PLAN.*\.md$/i.test(f)).length;
+    } catch {
+      // ignore
+    }
+
+    // Lines changed: parse numstat output for commits matching this phase scope
+    let linesChanged = 0;
+    if (numstatRaw) {
+      let currentCommitMatches = false;
+      for (const line of numstatRaw.split('\n')) {
+        if (line.startsWith('COMMIT:')) {
+          currentCommitMatches = scopePattern.test(line);
+        } else if (currentCommitMatches && line.trim()) {
+          const parts = line.split('\t');
+          if (parts.length >= 2) {
+            const added = parseInt(parts[0], 10) || 0;
+            const deleted = parseInt(parts[1], 10) || 0;
+            linesChanged += added + deleted;
+          }
+        }
+      }
+    }
+
+    phases.push({
+      phaseId: phaseNum,
+      phaseName,
+      commitCount,
+      duration,
+      planCount,
+      linesChanged
+    });
+  }
+
+  // Aggregate summary
+  const totalCommits = phases.reduce((s, p) => s + p.commitCount, 0);
+  const totalPhases = phases.length;
+  const durations = phases.filter(p => p.duration).map(p => parseInt(p.duration, 10));
+  const avgDuration = durations.length
+    ? `${Math.round(durations.reduce((s, d) => s + d, 0) / durations.length)}d`
+    : 'N/A';
+  const totalLinesChanged = phases.reduce((s, p) => s + p.linesChanged, 0);
+
+  const result = {
+    phases,
+    summary: { totalCommits, totalPhases, avgDuration, totalLinesChanged },
+    ...(warning ? { warning } : {})
+  };
+
+  cache.set(cacheKey, result);
+  return result;
+}

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

@@ -2,6 +2,9 @@ import { readdir } from 'node:fs/promises';
 import { join } from 'node:path';
 import { readMarkdownFile } from '../repositories/planning.repository.js';
 import { getRoadmapData } from './roadmap.service.js';
+import { TTLCache } from '../utils/cache.js';
+
+export const cache = new TTLCache(300_000); // 300s TTL
 
 /**
  * Scan .planning/milestones/ for archived milestone files.
@@ -14,6 +17,10 @@ import { getRoadmapData } from './roadmap.service.js';
  * @returns {Promise<Array<{version: string, name: string, date: string, duration: string, files: string[]}>>}
  */
 export async function listArchivedMilestones(projectDir) {
+  const cacheKey = `milestones:${projectDir}`;
+  const cached = cache.get(cacheKey);
+  if (cached) return cached;
+
   const milestonesDir = join(projectDir, '.planning', 'milestones');
 
   let entries;
@@ -64,8 +71,9 @@ export async function listArchivedMilestones(projectDir) {
     versionMap.get(version).files.push(entry.name);
   }
 
-  // Try to parse STATS.md for each version to get name/date/duration
+  // Try to parse STATS.md for each version to get name/date/duration/stats
   for (const [version, milestone] of versionMap) {
+    milestone.stats = { phaseCount: 0, commitCount: 0, deliverables: [] };
     let statsPath;
     if (milestone.format === 'directory') {
       if (milestone.files.includes('STATS.md')) {
@@ -80,22 +88,53 @@ export async function listArchivedMilestones(projectDir) {
 
     if (statsPath) {
       try {
-        const { frontmatter } = await readMarkdownFile(statsPath);
+        const { frontmatter, html } = await readMarkdownFile(statsPath);
         milestone.name = frontmatter.milestone || frontmatter.name || `v${version}`;
         milestone.date = frontmatter.completed || frontmatter.date || '';
         milestone.duration = frontmatter.duration || '';
+        milestone.stats.phaseCount = frontmatter.phases_completed || frontmatter.phase_count || 0;
+        milestone.stats.commitCount = frontmatter.total_commits || frontmatter.commit_count || 0;
+        milestone.stats.statsHtml = html || '';
       } catch (_e) {
         milestone.name = `v${version}`;
       }
     } else {
       milestone.name = `v${version}`;
     }
+
+    // Try to read deliverables from archived ROADMAP.md
+    if (milestone.format === 'directory' && milestone.files.includes('ROADMAP.md')) {
+      try {
+        const { frontmatter: rmFm } = await readMarkdownFile(join(milestonesDir, `v${version}`, 'ROADMAP.md'));
+        if (Array.isArray(rmFm.phases)) {
+          milestone.stats.deliverables = rmFm.phases.map(p => typeof p === 'string' ? p : (p.name || p.title || ''));
+        }
+      } catch (_e) { /* ignore */ }
+    }
+
+    // Try phases/ subdirectory for deliverables if none found yet
+    if (milestone.format === 'directory' && milestone.stats.deliverables.length === 0) {
+      try {
+        const phasesDir = join(milestonesDir, `v${version}`, 'phases');
+        const phaseDirs = await readdir(phasesDir, { withFileTypes: true });
+        milestone.stats.deliverables = phaseDirs
+          .filter(d => d.isDirectory())
+          .map(d => d.name)
+          .sort();
+        if (milestone.stats.phaseCount === 0) {
+          milestone.stats.phaseCount = milestone.stats.deliverables.length;
+        }
+      } catch (_e) { /* no phases dir */ }
+    }
   }
 
   // Sort by version descending (newest first) — strip internal format field
-  return [...versionMap.values()]
+  const result = [...versionMap.values()]
     .sort((a, b) => b.version.localeCompare(a.version, undefined, { numeric: true }))
     .map(({ format: _f, ...rest }) => rest);
+
+  cache.set(cacheKey, result);
+  return result;
 }
 
 /**
@@ -105,15 +144,22 @@ export async function listArchivedMilestones(projectDir) {
  * @returns {Promise<{active: Array, archived: Array}>}
  */
 export async function getAllMilestones(projectDir) {
+  const allCacheKey = `all-milestones:${projectDir}`;
+  const allCached = cache.get(allCacheKey);
+  if (allCached) return allCached;
+
   const [roadmapData, archived] = await Promise.all([
     getRoadmapData(projectDir),
     listArchivedMilestones(projectDir)
   ]);
 
-  return {
+  const allResult = {
     active: roadmapData.milestones || [],
     archived
   };
+
+  cache.set(allCacheKey, allResult);
+  return allResult;
 }
 
 /**