@sienklogic/plan-build-run 2.11.0 → 2.12.1

package/dashboard/server/routes/planning.js

@@ -0,0 +1,234 @@
+'use strict';
+
+const express = require('express');
+const fs = require('fs');
+const path = require('path');
+
+const VALID_TYPES = ['milestones', 'phases', 'todos', 'notes', 'quick', 'research'];
+
+const TYPE_METHOD_MAP = {
+  milestones: 'getMilestones',
+  phases: 'getPhases',
+  todos: 'getTodos',
+  notes: 'getNotes',
+  quick: 'getQuick',
+  research: 'getResearch',
+};
+
+/**
+ * Mtime-based optimistic locking middleware (per-route).
+ * Compares If-Unmodified-Since header against file mtime.
+ * Returns 409 if the file was modified after the given timestamp.
+ * @param {string} planningDir - Absolute path to .planning/ directory
+ * @param {string|Function} targetFile - Relative path to target file, or a function (req) => string
+ */
+function checkMtime(planningDir, targetFile) {
+  return (req, res, next) => {
+    const mtimeHeader = req.headers['if-unmodified-since'];
+    if (!mtimeHeader) return next();
+
+    const resolved = typeof targetFile === 'function' ? targetFile(req) : targetFile;
+    if (!resolved) return next();
+
+    const filePath = path.isAbsolute(resolved)
+      ? resolved
+      : path.join(planningDir, resolved);
+
+    try {
+      const stat = fs.statSync(filePath);
+      const headerMs = parseFloat(mtimeHeader);
+      if (!isNaN(headerMs) && stat.mtimeMs > headerMs) {
+        return res.status(409).json({
+          error: 'File modified since last read',
+          currentMtime: stat.mtimeMs,
+        });
+      }
+    } catch (_e) {
+      // File doesn't exist yet — allow write
+    }
+
+    next();
+  };
+}
+
+/**
+ * Planning route factory.
+ * @param {import('../services/planning-reader').PlanningReader} planningReader
+ * @returns {express.Router}
+ */
+function createPlanningRouter(planningReader) {
+  const router = express.Router();
+  const planningDir = planningReader.planningDir;
+
+  // --- Decisions (must be before /:type catch-all) ---
+  router.get('/decisions', async (_req, res) => {
+    try {
+      const decisions = await planningReader.getDecisions();
+      res.json(decisions);
+    } catch (err) {
+      res.status(500).json({ error: err.message });
+    }
+  });
+
+  router.post('/decisions', checkMtime(planningDir, 'STATE.md'), async (req, res) => {
+    try {
+      const { phase, text } = req.body;
+      if (!phase || !text) return res.status(400).json({ error: 'phase and text are required' });
+      const decision = await planningReader.createDecision(phase, text);
+      res.status(201).json(decision);
+    } catch (err) {
+      res.status(500).json({ error: err.message });
+    }
+  });
+
+  // --- Notes CRUD (before /:type catch-all) ---
+  router.post('/notes', async (req, res) => {
+    try {
+      const { title, content, tags } = req.body;
+      if (!title) return res.status(400).json({ error: 'title is required' });
+      const note = await planningReader.createNote(title, content || '', tags || []);
+      res.status(201).json(note);
+    } catch (err) {
+      res.status(500).json({ error: err.message });
+    }
+  });
+
+  router.put('/notes/:id', checkMtime(planningDir, (req) => path.join('notes', req.params.id)), async (req, res) => {
+    try {
+      const { title, content, tags } = req.body;
+      if (!title) return res.status(400).json({ error: 'title is required' });
+      const note = await planningReader.updateNote(req.params.id, title, content || '', tags || []);
+      res.json(note);
+    } catch (err) {
+      res.status(500).json({ error: err.message });
+    }
+  });
+
+  router.delete('/notes/:id', checkMtime(planningDir, (req) => path.join('notes', req.params.id)), async (req, res) => {
+    try {
+      const result = await planningReader.deleteNote(req.params.id);
+      res.json(result);
+    } catch (err) {
+      res.status(500).json({ error: err.message });
+    }
+  });
+
+  // --- Todos CRUD (before /:type catch-all) ---
+  router.post('/todos', async (req, res) => {
+    try {
+      const { title, priority, phase, notes } = req.body;
+      if (!title) return res.status(400).json({ error: 'title is required' });
+      const todo = await planningReader.createTodo(title, priority, phase, notes || '');
+      res.status(201).json(todo);
+    } catch (err) {
+      res.status(500).json({ error: err.message });
+    }
+  });
+
+  router.put('/todos/:id/toggle', checkMtime(planningDir, (req) => {
+    const { currentStatus } = req.body;
+    const dir = currentStatus === 'pending' ? 'pending' : 'done';
+    return path.join('todos', dir, req.params.id);
+  }), async (req, res) => {
+    try {
+      const { currentStatus } = req.body;
+      if (!currentStatus) return res.status(400).json({ error: 'currentStatus is required' });
+      const todo = await planningReader.toggleTodo(req.params.id, currentStatus);
+      res.json(todo);
+    } catch (err) {
+      res.status(500).json({ error: err.message });
+    }
+  });
+
+  router.delete('/todos/:id', checkMtime(planningDir, (req) => {
+    const { status } = req.body;
+    const dir = status === 'done' ? 'done' : 'pending';
+    return path.join('todos', dir, req.params.id);
+  }), async (req, res) => {
+    try {
+      const { status } = req.body;
+      const result = await planningReader.deleteTodo(req.params.id, status || 'pending');
+      res.json(result);
+    } catch (err) {
+      res.status(500).json({ error: err.message });
+    }
+  });
+
+  // --- Phase tasks (before /:type catch-all) ---
+  router.put('/phases/:phaseSlug/tasks/:taskIndex', async (req, res) => {
+    try {
+      const { completed } = req.body;
+      if (typeof completed !== 'boolean') return res.status(400).json({ error: 'completed (boolean) is required' });
+      const task = await planningReader.togglePhaseTask(
+        req.params.phaseSlug,
+        parseInt(req.params.taskIndex, 10),
+        completed
+      );
+      res.json(task);
+    } catch (err) {
+      res.status(500).json({ error: err.message });
+    }
+  });
+
+  // --- Files (raw .md file listing, viewing, editing) ---
+  router.get('/files', async (_req, res) => {
+    try {
+      const files = await planningReader.getFiles();
+      res.json(files);
+    } catch (err) {
+      res.status(500).json({ error: err.message });
+    }
+  });
+
+  router.get('/files/:filename', async (req, res) => {
+    try {
+      const { filename } = req.params;
+      if (!filename.endsWith('.md')) {
+        return res.status(400).json({ error: 'Filename must end with .md' });
+      }
+      const file = await planningReader.getFileContent(filename);
+      res.json(file);
+    } catch (err) {
+      if (err.code === 'ENOENT') {
+        return res.status(404).json({ error: 'File not found' });
+      }
+      res.status(500).json({ error: err.message });
+    }
+  });
+
+  router.put('/files/:filename', checkMtime(planningDir, (req) => req.params.filename), async (req, res) => {
+    try {
+      const { filename } = req.params;
+      if (!filename.endsWith('.md')) {
+        return res.status(400).json({ error: 'Filename must end with .md' });
+      }
+      const result = await planningReader.writeFile(filename, req.body.content);
+      res.json(result);
+    } catch (err) {
+      res.status(500).json({ error: err.message });
+    }
+  });
+
+  // --- GET /:type catch-all (must be last) ---
+  router.get('/:type', async (req, res) => {
+    const { type } = req.params;
+
+    if (!VALID_TYPES.includes(type)) {
+      return res.status(400).json({
+        error: `Invalid planning type: "${type}". Valid types: ${VALID_TYPES.join(', ')}`,
+      });
+    }
+
+    try {
+      const method = TYPE_METHOD_MAP[type];
+      const data = await planningReader[method]();
+      res.json(data);
+    } catch (err) {
+      res.status(500).json({ error: err.message });
+    }
+  });
+
+  return router;
+}
+
+module.exports = createPlanningRouter;

package/dashboard/server/routes/progress.js

@@ -0,0 +1,77 @@
+'use strict';
+
+const express = require('express');
+const path = require('path');
+
+const router = express.Router();
+
+/**
+ * Resolve the planning directory from request app config.
+ */
+function getPlanningDir(req) {
+  return req.app.locals.options.planningDir;
+}
+
+/**
+ * Load config from the planning directory.
+ */
+function loadConfig(planningDir) {
+  try {
+    const configPath = path.join(planningDir, 'config.json');
+    const fs = require('fs');
+    if (!fs.existsSync(configPath)) return {};
+    return JSON.parse(fs.readFileSync(configPath, 'utf8'));
+  } catch (_e) {
+    return {};
+  }
+}
+
+/**
+ * GET /api/progress
+ * Returns phase dependency graph, agent activity, and summary stats.
+ */
+router.get('/', (req, res) => {
+  try {
+    const planningDir = getPlanningDir(req);
+    const config = loadConfig(planningDir);
+    const { getProgressData } = require('../../../plan-build-run/bin/lib/progress-visualization.cjs');
+    const result = getProgressData(planningDir, config);
+    res.json(result);
+  } catch (err) {
+    res.status(500).json({ error: err.message });
+  }
+});
+
+/**
+ * GET /api/progress/onboarding
+ * Returns the generated onboarding guide.
+ */
+router.get('/onboarding', (req, res) => {
+  try {
+    const planningDir = getPlanningDir(req);
+    const config = loadConfig(planningDir);
+    const { generateOnboardingGuide } = require('../../../plan-build-run/bin/lib/onboarding-generator.cjs');
+    const result = generateOnboardingGuide(planningDir, config);
+    res.json(result);
+  } catch (err) {
+    res.status(500).json({ error: err.message });
+  }
+});
+
+/**
+ * GET /api/progress/help-context
+ * Returns contextual help suggestions based on current state.
+ */
+router.get('/help-context', (req, res) => {
+  try {
+    const planningDir = getPlanningDir(req);
+    const config = loadConfig(planningDir);
+    const { getContextualHelp } = require('../../../plan-build-run/bin/lib/contextual-help.cjs');
+    const result = getContextualHelp(planningDir, config);
+    res.json(result);
+  } catch (err) {
+    res.status(500).json({ error: err.message });
+  }
+});
+
+module.exports = router;

package/dashboard/server/routes/projects.js

@@ -0,0 +1,36 @@
+'use strict';
+
+const express = require('express');
+
+/**
+ * Projects route factory.
+ * For MVP, returns the current project derived from planningDir.
+ *
+ * @param {import('../services/planning-reader').PlanningReader} planningReader
+ * @returns {express.Router}
+ */
+function createProjectsRouter(planningReader) {
+  const router = express.Router();
+  let activeProjectId = 'current';
+
+  router.get('/', (_req, res) => {
+    const projectPath = planningReader.planningDir.replace(/[/\\]\.planning\/?$/, '');
+    res.json([
+      {
+        id: 'current',
+        name: require('path').basename(projectPath),
+        path: projectPath,
+        active: activeProjectId === 'current',
+      },
+    ]);
+  });
+
+  router.put('/:id/active', (req, res) => {
+    activeProjectId = req.params.id;
+    res.json({ active: activeProjectId });
+  });
+
+  return router;
+}
+
+module.exports = createProjectsRouter;

package/dashboard/server/routes/requirements.js

@@ -0,0 +1,40 @@
+'use strict';
+
+const express = require('express');
+const path = require('path');
+const { safeReadFile } = require('../services/planning-reader');
+
+/**
+ * Requirements route factory.
+ * Parses REQUIREMENTS.md and returns structured requirement data.
+ *
+ * @param {import('../services/planning-reader').PlanningReader} planningReader
+ * @returns {express.Router}
+ */
+function createRequirementsRouter(planningReader) {
+  const router = express.Router();
+
+  router.get('/', async (_req, res) => {
+    try {
+      const content = await safeReadFile(path.join(planningReader.planningDir, 'REQUIREMENTS.md'));
+      if (!content) return res.json({ requirements: [], sections: [] });
+      const reqs = [];
+      const regex = /^- \[([ x])\] \*\*(\w+-\d+)\*\*:\s*(.+)$/gm;
+      let match;
+      while ((match = regex.exec(content)) !== null) {
+        reqs.push({
+          id: match[2],
+          description: match[3].trim(),
+          status: match[1] === 'x' ? 'complete' : 'pending',
+        });
+      }
+      res.json({ requirements: reqs });
+    } catch (err) {
+      res.status(500).json({ error: err.message });
+    }
+  });
+
+  return router;
+}
+
+module.exports = createRequirementsRouter;

package/dashboard/server/routes/roadmap.js

@@ -0,0 +1,69 @@
+'use strict';
+
+const express = require('express');
+
+/**
+ * Roadmap route factory.
+ * Reads ROADMAP.md via PlanningReader and returns structured milestone + phase data.
+ *
+ * @param {import('../services/planning-reader').PlanningReader} planningReader
+ * @returns {express.Router}
+ */
+function createRoadmapRouter(planningReader) {
+  const router = express.Router();
+
+  /**
+   * GET /phases/:slug - Return detail for a single phase (plans, summaries, verifications, context).
+   */
+  router.get('/phases/:slug', async (req, res) => {
+    try {
+      const detail = await planningReader.getPhaseDetail(req.params.slug);
+      const isEmpty = detail.plans.length === 0 && detail.summaries.length === 0
+        && detail.verifications.length === 0 && detail.context.length === 0;
+      if (isEmpty) {
+        return res.status(404).json({ error: 'Phase not found' });
+      }
+      res.json(detail);
+    } catch (err) {
+      res.status(500).json({ error: err.message });
+    }
+  });
+
+  /**
+   * GET / - Return roadmap phases with milestone header info.
+   */
+  router.get('/', async (_req, res) => {
+    try {
+      const [milestones, phases] = await Promise.all([
+        planningReader.getMilestones(),
+        planningReader.getRoadmapPhases(),
+      ]);
+
+      // Build milestone header from first active (or only) milestone
+      const activeMilestone = milestones.find(m => !m.archived) || milestones[0] || null;
+      const milestone = activeMilestone ? {
+        name: activeMilestone.name,
+        goal: activeMilestone.description || null,
+        phaseCount: phases.length,
+        reqCoverage: null,
+      } : null;
+
+      // Backward compat: also include flat items array
+      const items = milestones.map((ms, i) => ({
+        id: ms.id || `ms-${i}`,
+        title: ms.title || ms.name,
+        tier: ms.archived ? 1 : (ms.version ? 2 : 3),
+        st: ms.archived ? 'done' : 'in-progress',
+        s: ms.version || '-',
+      }));
+
+      res.json({ milestone, phases, items });
+    } catch (err) {
+      res.status(500).json({ error: err.message });
+    }
+  });
+
+  return router;
+}
+
+module.exports = createRoadmapRouter;

package/dashboard/server/routes/status.js

@@ -0,0 +1,25 @@
+'use strict';
+
+const express = require('express');
+
+/**
+ * Status route factory.
+ * @param {import('../services/planning-reader').PlanningReader} planningReader
+ * @returns {express.Router}
+ */
+function createStatusRouter(planningReader) {
+  const router = express.Router();
+
+  router.get('/', async (_req, res) => {
+    try {
+      const status = await planningReader.getStatus();
+      res.json(status);
+    } catch (err) {
+      res.status(500).json({ error: err.message });
+    }
+  });
+
+  return router;
+}
+
+module.exports = createStatusRouter;

package/dashboard/server/routes/telemetry.js

@@ -0,0 +1,171 @@
+'use strict';
+
+const express = require('express');
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Telemetry route factory.
+ * Reads hook event log and telemetry data from .planning/.
+ *
+ * @param {object} options
+ * @param {string} options.planningDir - Path to .planning/ directory
+ * @returns {express.Router}
+ */
+function createTelemetryRouter({ planningDir }) {
+  const router = express.Router();
+
+  /**
+   * GET / - Return telemetry metrics.
+   * Reads logs/hooks.jsonl for aggregate metrics.
+   */
+  router.get('/', async (_req, res) => {
+    try {
+      const eventsPath = path.join(planningDir, 'logs', 'hooks.jsonl');
+      let events = [];
+
+      try {
+        const raw = await fs.promises.readFile(eventsPath, 'utf-8');
+        events = raw
+          .split('\n')
+          .filter(line => line.trim())
+          .map(line => {
+            try { return JSON.parse(line); } catch (_e) { return null; }
+          })
+          .filter(Boolean);
+      } catch (_e) {
+        // No events file -- return empty metrics
+      }
+
+      // Count unique hook types
+      const hookTypeCounts = {};
+      for (const evt of events) {
+        const hook = evt.hook || evt.event || evt.type || 'unknown';
+        hookTypeCounts[hook] = (hookTypeCounts[hook] || 0) + 1;
+      }
+      const uniqueHookTypeCount = Object.keys(hookTypeCounts).length;
+
+      // Count events in last 24 hours
+      const now = Date.now();
+      const oneDayAgo = now - 24 * 60 * 60 * 1000;
+      const recentEventCount = events.filter(evt => {
+        const ts = evt.ts || evt.time;
+        if (!ts) return false;
+        const evtTime = new Date(ts).getTime();
+        return !isNaN(evtTime) && evtTime >= oneDayAgo;
+      }).length;
+
+      const metrics = {
+        totalEvents: events.length,
+        hookTypes: uniqueHookTypeCount,
+        recentEvents: recentEventCount,
+      };
+
+      // tokenHistory -- group events by date, count per day (last 14 days)
+      const dayMap = {};
+      for (const evt of events) {
+        const ts = evt.ts || evt.time;
+        if (!ts) continue;
+        const d = new Date(ts);
+        if (isNaN(d.getTime())) continue;
+        const dateStr = d.toISOString().slice(0, 10);
+        dayMap[dateStr] = (dayMap[dateStr] || 0) + 1;
+      }
+      const today = new Date();
+      const tokenHistory = [];
+      for (let i = 13; i >= 0; i--) {
+        const d = new Date(today);
+        d.setDate(d.getDate() - i);
+        const dateStr = d.toISOString().slice(0, 10);
+        tokenHistory.push({ date: dateStr, tokens: dayMap[dateStr] || 0 });
+      }
+
+      // phaseDistribution -- derive phase from hook name patterns
+      function derivePhase(evt) {
+        const hook = (evt.hook || evt.event || evt.type || '').toLowerCase();
+        const category = (evt.category || '').toLowerCase();
+        if (hook.includes('plan') || category.includes('plan')) return 'Plan';
+        if (hook.includes('build') || category.includes('build')) return 'Build';
+        if (hook.includes('review') || category.includes('review')) return 'Review';
+        return 'Run';
+      }
+
+      const phaseCounts = {};
+      for (const evt of events) {
+        const phase = derivePhase(evt);
+        phaseCounts[phase] = (phaseCounts[phase] || 0) + 1;
+      }
+      const phaseDistribution = Object.entries(phaseCounts).map(([name, value]) => ({ name, value }));
+
+      // subagents -- map last 20 events into subagent-like shape
+      function formatDuration(evt) {
+        const dur = evt.duration;
+        if (dur == null) return '-';
+        if (typeof dur === 'number') {
+          if (dur < 1000) return `${dur}ms`;
+          return `${(dur / 1000).toFixed(1)}s`;
+        }
+        return String(dur);
+      }
+
+      const subagents = events.slice(-20).map(evt => ({
+        name: evt.hook || evt.event || 'unknown',
+        task: evt.tool || '-',
+        phase: derivePhase(evt),
+        model: '-',
+        tokens: 0,
+        time: formatDuration(evt),
+        status: evt.status || 'success',
+      }));
+
+      // successData -- group by date, compute success rate per day
+      const daySuccessMap = {};
+      for (const evt of events) {
+        const ts = evt.ts || evt.time;
+        if (!ts) continue;
+        const d = new Date(ts);
+        if (isNaN(d.getTime())) continue;
+        const dateStr = d.toISOString().slice(0, 10);
+        if (!daySuccessMap[dateStr]) {
+          daySuccessMap[dateStr] = { total: 0, success: 0 };
+        }
+        daySuccessMap[dateStr].total++;
+        const status = evt.status || (evt.level === 'error' ? 'error' : 'success');
+        if (status === 'success') {
+          daySuccessMap[dateStr].success++;
+        }
+      }
+      const successData = [];
+      for (let i = 13; i >= 0; i--) {
+        const d = new Date(today);
+        d.setDate(d.getDate() - i);
+        const dateStr = d.toISOString().slice(0, 10);
+        const entry = daySuccessMap[dateStr];
+        const rate = entry ? Math.round((entry.success / entry.total) * 100) : 0;
+        successData.push({ date: dateStr, rate });
+      }
+
+      // subagentPerf -- per-hook-type performance data
+      const subagentPerf = Object.entries(hookTypeCounts).map(([name, count]) => ({
+        name,
+        count,
+      }));
+
+      res.json({
+        metrics,
+        tokenHistory,
+        phaseDistribution,
+        subagents,
+        successData,
+        subagentPerf,
+        contextRadar: {},
+      });
+    } catch (err) {
+      res.status(500).json({ error: err.message });
+    }
+  });
+
+  return router;
+}
+
+module.exports = createTelemetryRouter;