@sienklogic/plan-build-run 2.19.0 → 2.19.2

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('../../../plugins/pbr/scripts/lib/progress-visualization');
+    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('../../../plugins/pbr/scripts/lib/onboarding-generator');
+    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('../../../plugins/pbr/scripts/lib/contextual-help');
+    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/sessions.js

@@ -0,0 +1,70 @@
+'use strict';
+
+const express = require('express');
+const fs = require('fs');
+const path = require('path');
+const { parseFrontmatter } = require('../lib/frontmatter');
+
+/**
+ * Sessions route factory.
+ * Reads session snapshots from .planning/sessions/ directory.
+ *
+ * @param {object} options
+ * @param {string} options.planningDir - Path to .planning/ directory
+ * @returns {express.Router}
+ */
+function createSessionsRouter({ planningDir }) {
+  const router = express.Router();
+
+  /**
+   * GET / - Return parsed session objects from .planning/sessions/.
+   * Reads .json and .md files, returns array sorted by timestamp descending.
+   */
+  router.get('/', async (_req, res) => {
+    try {
+      const sessionsDir = path.join(planningDir, 'sessions');
+      const sessions = [];
+
+      let dirEntries = [];
+      try {
+        dirEntries = await fs.promises.readdir(sessionsDir);
+      } catch (_e) {
+        // No sessions directory — return empty
+        return res.json([]);
+      }
+
+      for (const file of dirEntries) {
+        const filePath = path.join(sessionsDir, file);
+
+        try {
+          if (file.endsWith('.json')) {
+            const raw = await fs.promises.readFile(filePath, 'utf-8');
+            const parsed = JSON.parse(raw);
+            sessions.push({ file, ...parsed });
+          } else if (file.endsWith('.md')) {
+            const raw = await fs.promises.readFile(filePath, 'utf-8');
+            const { frontmatter, body } = parseFrontmatter(raw);
+            sessions.push({ file, ...frontmatter, body: body.slice(0, 500) });
+          }
+        } catch (_e) {
+          // Skip unreadable files
+        }
+      }
+
+      // Sort by timestamp descending
+      sessions.sort((a, b) => {
+        const tsA = a.timestamp || a.ts || a.date || '';
+        const tsB = b.timestamp || b.ts || b.date || '';
+        return String(tsB).localeCompare(String(tsA));
+      });
+
+      res.json(sessions);
+    } catch (err) {
+      res.status(500).json({ error: err.message });
+    }
+  });
+
+  return router;
+}
+
+module.exports = createSessionsRouter;

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;