@sienklogic/plan-build-run 2.24.0 → 2.26.1

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

@@ -7,8 +7,66 @@ import { getAllMilestones, getMilestoneDetail } from '../services/milestone.serv
 import { getProjectAnalytics } from '../services/analytics.service.js';
 import { getLlmMetrics } from '../services/local-llm-metrics.service.js';
 import { listNotes, getNoteBySlug } from '../services/notes.service.js';
+import { listResearchDocs, listCodebaseDocs, getResearchDocBySlug } from '../services/research.service.js';
 import { listQuickTasks, getQuickTask } from '../services/quick.service.js';
 import { listAuditReports, getAuditReport } from '../services/audit.service.js';
+import { readConfig, writeConfig } from '../services/config.service.js';
+import { getRequirementsData } from '../services/requirements.service.js';
+import { listLogFiles, readLogPage } from '../services/log.service.js';
+
+/**
+ * Merge flat HTML form fields back into a nested config object.
+ * Form field names use dot-notation: "features.autoVerify", "models.default".
+ * Boolean checkboxes arrive as "on"/"off" or are absent when unchecked.
+ * @param {object} existing - current config object from disk
+ * @param {object} form - req.body from express.urlencoded
+ * @returns {object}
+ */
+function mergeFormIntoConfig(existing, form) {
+  const result = JSON.parse(JSON.stringify(existing)); // deep clone
+  for (const [key, value] of Object.entries(form)) {
+    const parts = key.split('.');
+    let target = result;
+    for (let i = 0; i < parts.length - 1; i++) {
+      if (target[parts[i]] == null || typeof target[parts[i]] !== 'object') {
+        target[parts[i]] = {};
+      }
+      target = target[parts[i]];
+    }
+    const leaf = parts[parts.length - 1];
+    // Coerce booleans: checkboxes send "on", absent means false
+    if (typeof existing?.[parts[0]]?.[leaf] === 'boolean' || (parts.length === 2 && typeof (existing?.[parts[0]] ?? {})[leaf] === 'boolean')) {
+      target[leaf] = value === 'on' || value === 'true';
+    } else if (typeof target[leaf] === 'number') {
+      target[leaf] = Number(value);
+    } else {
+      target[leaf] = value;
+    }
+  }
+  // Uncheck all feature booleans not present in form (unchecked checkboxes are absent)
+  if (result.features && typeof result.features === 'object') {
+    for (const k of Object.keys(result.features)) {
+      if (typeof result.features[k] === 'boolean' && !(`features.${k}` in form)) {
+        result.features[k] = false;
+      }
+    }
+  }
+  if (result.gates && typeof result.gates === 'object') {
+    for (const k of Object.keys(result.gates)) {
+      if (typeof result.gates[k] === 'boolean' && !(`gates.${k}` in form)) {
+        result.gates[k] = false;
+      }
+    }
+  }
+  if (result.safety && typeof result.safety === 'object') {
+    for (const k of Object.keys(result.safety)) {
+      if (typeof result.safety[k] === 'boolean' && !(`safety.${k}` in form)) {
+        result.safety[k] = false;
+      }
+    }
+  }
+  return result;
+}
 
 const router = Router();
 
@@ -48,13 +106,26 @@ router.get('/phases/:phaseId', async (req, res) => {
   }
 
   const projectDir = req.app.locals.projectDir;
-  const phaseData = await getPhaseDetail(projectDir, phaseId);
+  const [phaseData, roadmapData] = await Promise.all([
+    getPhaseDetail(projectDir, phaseId),
+    getRoadmapData(projectDir)
+  ]);
+
+  const phaseIdNum = parseInt(phaseId, 10);
+  const allPhases = roadmapData.phases || [];
+  const currentIdx = allPhases.findIndex(p => String(p.id) === String(phaseIdNum));
+  const prevPhase = currentIdx > 0 ? allPhases[currentIdx - 1] : null;
+  const nextPhase = currentIdx >= 0 && currentIdx < allPhases.length - 1
+    ? allPhases[currentIdx + 1]
+    : null;
 
   const templateData = {
     title: `Phase ${phaseId}: ${phaseData.phaseName}`,
     activePage: 'phases',
     currentPath: '/phases/' + phaseId,
     breadcrumbs: [{ label: 'Phases', url: '/phases' }, { label: 'Phase ' + phaseId }],
+    prevPhase,
+    nextPhase,
     ...phaseData
   };
 
@@ -462,6 +533,88 @@ router.get('/notes/:slug', async (req, res) => {
   }
 });
 
+router.get('/research', async (req, res) => {
+  const projectDir = req.app.locals.projectDir;
+  const [researchDocs, codebaseDocs] = await Promise.all([
+    listResearchDocs(projectDir),
+    listCodebaseDocs(projectDir)
+  ]);
+
+  const templateData = {
+    title: 'Research',
+    activePage: 'research',
+    currentPath: '/research',
+    breadcrumbs: [{ label: 'Research' }],
+    researchDocs,
+    codebaseDocs
+  };
+
+  res.setHeader('Vary', 'HX-Request');
+  if (req.get('HX-Request') === 'true') {
+    res.render('partials/research-content', templateData);
+  } else {
+    res.render('research', templateData);
+  }
+});
+
+router.get('/research/:slug', async (req, res) => {
+  const { slug } = req.params;
+
+  // Validate slug: lowercase alphanumeric, dashes, and dots only
+  if (!/^[a-z0-9._-]+$/.test(slug)) {
+    const err = new Error('Invalid research document slug format');
+    err.status = 404;
+    throw err;
+  }
+
+  const projectDir = req.app.locals.projectDir;
+  const doc = await getResearchDocBySlug(projectDir, slug);
+
+  if (!doc) {
+    const err = new Error(`Research document "${slug}" not found`);
+    err.status = 404;
+    throw err;
+  }
+
+  const templateData = {
+    title: doc.title,
+    activePage: 'research',
+    currentPath: '/research/' + slug,
+    breadcrumbs: [{ label: 'Research', url: '/research' }, { label: doc.title }],
+    ...doc
+  };
+
+  res.setHeader('Vary', 'HX-Request');
+  if (req.get('HX-Request') === 'true') {
+    res.render('partials/research-detail-content', templateData);
+  } else {
+    res.render('research-detail', templateData);
+  }
+});
+
+router.get('/requirements', async (req, res) => {
+  const projectDir = req.app.locals.projectDir;
+  const { sections, totalCount, coveredCount } = await getRequirementsData(projectDir);
+
+  const templateData = {
+    title: 'Requirements',
+    activePage: 'requirements',
+    currentPath: '/requirements',
+    breadcrumbs: [{ label: 'Requirements' }],
+    sections,
+    totalCount,
+    coveredCount,
+    uncoveredCount: totalCount - coveredCount
+  };
+
+  res.setHeader('Vary', 'HX-Request');
+  if (req.get('HX-Request') === 'true') {
+    res.render('partials/requirements-content', templateData);
+  } else {
+    res.render('requirements', templateData);
+  }
+});
+
 router.get('/roadmap', async (req, res) => {
   const projectDir = req.app.locals.projectDir;
   const [roadmapData, stateData] = await Promise.all([
@@ -601,4 +754,100 @@ router.get('/audits/:filename', async (req, res) => {
   }
 });
 
+router.get('/config', async (req, res) => {
+  const projectDir = req.app.locals.projectDir;
+  const config = await readConfig(projectDir);
+
+  const templateData = {
+    title: 'Config',
+    activePage: 'config',
+    currentPath: '/config',
+    breadcrumbs: [{ label: 'Config' }],
+    config: config ?? {}
+  };
+
+  res.setHeader('Vary', 'HX-Request');
+
+  if (req.get('HX-Request') === 'true') {
+    res.render('partials/config-content', templateData);
+  } else {
+    res.render('config', templateData);
+  }
+});
+
+router.get('/logs', async (req, res) => {
+  const projectDir = req.app.locals.projectDir;
+  const { file, page, type, q } = req.query;
+
+  const logFiles = await listLogFiles(projectDir);
+
+  // Determine selected file (first in list if not specified)
+  const selectedFile = file || (logFiles.length > 0 ? logFiles[0].name : null);
+
+  let logData = null;
+  if (selectedFile) {
+    // Validate: no path traversal, must be a .jsonl filename
+    if (/^[\w.-]+\.jsonl$/.test(selectedFile)) {
+      const { join } = await import('node:path');
+      const filePath = join(projectDir, '.planning', 'logs', selectedFile);
+      logData = await readLogPage(filePath, {
+        page: parseInt(page, 10) || 1,
+        pageSize: 100,
+        typeFilter: type || '',
+        q: q || ''
+      });
+    }
+  }
+
+  const templateData = {
+    title: 'Logs',
+    activePage: 'logs',
+    currentPath: '/logs',
+    breadcrumbs: [{ label: 'Logs' }],
+    logFiles,
+    selectedFile,
+    logData,
+    filters: { type: type || '', q: q || '', page: parseInt(page, 10) || 1 }
+  };
+
+  res.setHeader('Vary', 'HX-Request');
+  if (req.get('HX-Request') === 'true') {
+    // If the request is for a different file/filter, re-render only the entries fragment
+    if (req.query.fragment === 'entries') {
+      res.render('partials/log-entries-content', templateData);
+    } else {
+      res.render('partials/logs-content', templateData);
+    }
+  } else {
+    res.render('logs', templateData);
+  }
+});
+
+router.post('/api/config', async (req, res) => {
+  const projectDir = req.app.locals.projectDir;
+
+  // Accept either JSON body (raw editor) or form-encoded (hybrid form)
+  let incoming = req.body;
+
+  // If the request carries a `rawJson` field, parse it as the full config
+  if (typeof incoming.rawJson === 'string') {
+    try {
+      incoming = JSON.parse(incoming.rawJson);
+    } catch {
+      return res.status(400).send('<span class="config-feedback config-feedback--error">Invalid JSON</span>');
+    }
+  } else {
+    // Merge form fields into existing config to avoid clobbering unrendered keys
+    const existing = await readConfig(projectDir) ?? {};
+    incoming = mergeFormIntoConfig(existing, incoming);
+  }
+
+  try {
+    await writeConfig(projectDir, incoming);
+    res.send('<span class="config-feedback config-feedback--success">Saved</span>');
+  } catch (err) {
+    res.status(400).send(`<span class="config-feedback config-feedback--error">${err.message}</span>`);
+  }
+});
+
 export default router;

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

@@ -0,0 +1,140 @@
+import { readFile, writeFile, rename } from 'node:fs/promises';
+import { join } from 'node:path';
+
+/** Default config values used when fields are missing. */
+const CONFIG_DEFAULTS = {
+  version: '2',
+  context_strategy: 'aggressive',
+  mode: 'normal',
+  depth: 'standard',
+  features: {
+    structured_planning: true,
+    goal_verification: true,
+    integration_verification: false,
+    context_isolation: true,
+    atomic_commits: true,
+    session_persistence: true,
+    research_phase: true,
+    plan_checking: true,
+    tdd_mode: false,
+    status_line: true,
+    auto_continue: false,
+    auto_advance: false,
+    team_discussions: false,
+  },
+  models: {
+    researcher: 'sonnet',
+    planner: 'inherit',
+    executor: 'inherit',
+    verifier: 'sonnet',
+    integration_checker: 'sonnet',
+    debugger: 'inherit',
+    mapper: 'sonnet',
+    synthesizer: 'sonnet',
+  },
+  parallelization: {
+    enabled: true,
+    plan_level: true,
+    task_level: false,
+    max_concurrent_agents: 3,
+    min_plans_for_parallel: 2,
+    use_teams: false,
+  },
+  gates: {
+    confirm_project: false,
+    confirm_roadmap: false,
+    confirm_plan: false,
+    confirm_execute: false,
+    confirm_transition: false,
+    issues_review: false,
+  },
+};
+
+/**
+ * Return the default config schema. Useful for UI form generation
+ * and for filling in missing fields on existing configs.
+ * @returns {object}
+ */
+export function getConfigDefaults() {
+  return structuredClone(CONFIG_DEFAULTS);
+}
+
+/**
+ * Deep-merge incoming config with defaults so every expected key exists.
+ * Incoming values take precedence; defaults fill gaps.
+ * @param {object} incoming
+ * @returns {object}
+ */
+export function mergeDefaults(incoming) {
+  const defaults = getConfigDefaults();
+  const merged = { ...defaults, ...incoming };
+  for (const section of ['features', 'models', 'parallelization', 'gates']) {
+    if (defaults[section] && typeof defaults[section] === 'object') {
+      merged[section] = { ...defaults[section], ...(incoming[section] || {}) };
+    }
+  }
+  return merged;
+}
+
+/**
+ * Read and parse .planning/config.json.
+ * @param {string} projectDir
+ * @returns {Promise<object|null>}
+ */
+export async function readConfig(projectDir) {
+  const configPath = join(projectDir, '.planning', 'config.json');
+  try {
+    const raw = await readFile(configPath, 'utf8');
+    return JSON.parse(raw);
+  } catch (err) {
+    if (err.code === 'ENOENT') return null;
+    throw err;
+  }
+}
+
+/**
+ * Validate config shape. Throws with a descriptive message on failure.
+ * @param {object} config
+ */
+export function validateConfig(config) {
+  if (!config || typeof config !== 'object') throw new Error('Config must be an object');
+  if (typeof config.version !== 'string') throw new Error('config.version must be a string');
+  if (config.features != null) {
+    for (const [k, v] of Object.entries(config.features)) {
+      if (typeof v !== 'boolean') throw new Error(`features.${k} must be a boolean`);
+    }
+  }
+  if (config.models != null) {
+    for (const [k, v] of Object.entries(config.models)) {
+      if (typeof v !== 'string') throw new Error(`models.${k} must be a string`);
+    }
+  }
+  if (config.parallelization != null) {
+    const p = config.parallelization;
+    if (p.max_concurrent_agents != null && (typeof p.max_concurrent_agents !== 'number' || p.max_concurrent_agents < 1)) {
+      throw new Error('parallelization.max_concurrent_agents must be a positive number');
+    }
+    if (p.min_plans_for_parallel != null && (typeof p.min_plans_for_parallel !== 'number' || p.min_plans_for_parallel < 1)) {
+      throw new Error('parallelization.min_plans_for_parallel must be a positive number');
+    }
+  }
+  if (config.gates != null) {
+    for (const [k, v] of Object.entries(config.gates)) {
+      if (typeof v !== 'boolean') throw new Error(`gates.${k} must be a boolean`);
+    }
+  }
+}
+
+/**
+ * Atomically write config back to .planning/config.json.
+ * Validates before writing; throws on validation failure (existing file untouched).
+ * @param {string} projectDir
+ * @param {object} config
+ */
+export async function writeConfig(projectDir, config) {
+  validateConfig(config);
+  const configPath = join(projectDir, '.planning', 'config.json');
+  const tmpPath = configPath + '.tmp';
+  await writeFile(tmpPath, JSON.stringify(config, null, 2), 'utf8');
+  await rename(tmpPath, configPath);
+}

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

@@ -1,7 +1,37 @@
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
+import { execFile as execFileCb } from 'node:child_process';
+import { promisify } from 'node:util';
 import { stripBOM } from '../utils/strip-bom.js';
 
+const execFile = promisify(execFileCb);
+
+// Plain-object cache for getRecentActivity: keyed by projectDir
+// Each entry: { data: Array, expiresAt: number }
+const _activityCache = new Map();
+const ACTIVITY_CACHE_TTL_MS = 30_000;
+
+/** Clear activity cache — exported for testing only */
+export function _clearActivityCache() {
+  _activityCache.clear();
+}
+
+/**
+ * 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 '';
+  }
+}
+
 /**
  * Parse STATE.md to extract project status information.
  * Uses regex on raw markdown body text (not YAML frontmatter).
@@ -87,6 +117,19 @@ export async function parseStateFile(projectDir) {
         ? 'in-progress'
         : fmStatus || 'unknown';
 
+    // Map STATE.md status to suggested next PBR command
+    const nextActionMap = {
+      'planning':    '/pbr:plan',
+      'planned':     '/pbr:build',
+      'building':    '/pbr:build',
+      'built':       '/pbr:review',
+      'in-progress': '/pbr:build',
+      'verified':    '/pbr:review',
+      'complete':    '/pbr:milestone',
+      'discussing':  '/pbr:plan',
+    };
+    const nextAction = nextActionMap[fmStatus] || null;
+
     return {
       projectName,
       currentPhase: {
@@ -100,7 +143,8 @@ export async function parseStateFile(projectDir) {
         date: activityDate,
         description: activityDescription
       },
-      progress
+      progress,
+      nextAction
     };
   } catch (error) {
     if (error.code === 'ENOENT') {
@@ -240,13 +284,6 @@ export async function parseRoadmapFile(projectDir) {
   }
 }
 
-/**
- * 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}>}
- */
 /**
  * Derive phase statuses by combining roadmap phases with STATE.md context.
  * Phases before the current phase are marked complete.
@@ -274,10 +311,114 @@ export function derivePhaseStatuses(phases, currentPhase) {
   });
 }
 
+/**
+ * Get recent .planning/ file activity from git log.
+ * Returns up to 10 deduplicated entries (most recent occurrence per path).
+ * Results are cached for 30 seconds.
+ *
+ * @param {string} projectDir - Absolute path to the project root
+ * @returns {Promise<Array<{path: string, timestamp: string, type: string}>>}
+ */
+export async function getRecentActivity(projectDir) {
+  const cached = _activityCache.get(projectDir);
+  if (cached && Date.now() < cached.expiresAt) {
+    return cached.data;
+  }
+
+  try {
+    const output = await git(projectDir, [
+      'log',
+      '--name-only',
+      '--format=COMMIT:%ai',
+      '-n', '40',
+      '--',
+      '.planning/'
+    ]);
+
+    if (!output || !output.trim()) {
+      return [];
+    }
+
+    // Parse output: lines starting with "COMMIT:" set the current timestamp,
+    // non-empty lines that don't start with "COMMIT:" are file paths.
+    const seen = new Map(); // path -> { timestamp, type }
+    let currentTimestamp = '';
+
+    for (const line of output.split('\n')) {
+      const trimmed = line.trim();
+      if (trimmed.startsWith('COMMIT:')) {
+        currentTimestamp = trimmed.slice('COMMIT:'.length).trim();
+      } else if (trimmed && currentTimestamp) {
+        // Only record first occurrence per path (git log is newest-first)
+        if (!seen.has(trimmed)) {
+          seen.set(trimmed, { timestamp: currentTimestamp, type: 'commit' });
+        }
+      }
+    }
+
+    const data = [...seen.entries()]
+      .slice(0, 10)
+      .map(([path, meta]) => ({ path, timestamp: meta.timestamp, type: meta.type }));
+
+    _activityCache.set(projectDir, { data, expiresAt: Date.now() + ACTIVITY_CACHE_TTL_MS });
+    return data;
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Derive contextual quick-action buttons based on current phase status.
+ * Pure function — no I/O.
+ *
+ * @param {{ status: string, id: number }} currentPhase
+ * @returns {Array<{label: string, href: string, primary: boolean}>}
+ */
+export function deriveQuickActions(currentPhase) {
+  const id = String(currentPhase.id).padStart(2, '0');
+  const status = currentPhase.status || '';
+
+  switch (status) {
+    case 'building':
+    case 'in-progress':
+      return [
+        { label: 'Continue Building', href: `/phases/${id}`, primary: true },
+        { label: 'View Roadmap', href: '/roadmap', primary: false }
+      ];
+
+    case 'planning':
+    case 'planned':
+      return [
+        { label: 'View Plans', href: `/phases/${id}`, primary: true },
+        { label: 'Roadmap', href: '/roadmap', primary: false }
+      ];
+
+    case 'complete':
+    case 'verified':
+      return [
+        { label: 'View Phase', href: `/phases/${id}`, primary: false },
+        { label: 'Roadmap', href: '/roadmap', primary: true }
+      ];
+
+    default:
+      return [
+        { label: 'Get Started', href: '/roadmap', primary: true }
+      ];
+  }
+}
+
+/**
+ * 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, recentActivity: Array, quickActions: Array}>}
+ */
 export async function getDashboardData(projectDir) {
-  const [stateData, roadmapData] = await Promise.all([
+  const [stateData, roadmapData, recentActivity] = await Promise.all([
     parseStateFile(projectDir),
-    parseRoadmapFile(projectDir)
+    parseRoadmapFile(projectDir),
+    getRecentActivity(projectDir)
   ]);
 
   const phases = derivePhaseStatuses(roadmapData.phases, stateData.currentPhase);
@@ -288,11 +429,15 @@ export async function getDashboardData(projectDir) {
     ? Math.ceil((completedPhases / phases.length) * 100)
     : stateData.progress;
 
+  const quickActions = deriveQuickActions(stateData.currentPhase);
+
   return {
     projectName: stateData.projectName,
     currentPhase: stateData.currentPhase,
     lastActivity: stateData.lastActivity,
     progress,
-    phases
+    phases,
+    recentActivity,
+    quickActions
   };
 }