@sienklogic/plan-build-run 2.18.1 → 2.19.1

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

@@ -1,232 +0,0 @@
-import { readdir } from 'node:fs/promises';
-import { join } from 'node:path';
-import { readMarkdownFile, validatePath } from '../repositories/planning.repository.js';
-
-/**
- * Format a phase directory name into a human-readable title.
- * Strips the numeric prefix and title-cases each word.
- *
- * @param {string} dirName - Directory name like "04-dashboard-landing-page"
- * @returns {string} Formatted name like "Dashboard Landing Page"
- */
-function formatPhaseName(dirName) {
-  const parts = dirName.split('-');
-  // Remove the numeric prefix (first element)
-  parts.shift();
-  return parts
-    .map(word => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase())
-    .join(' ');
-}
-
-/**
- * Parse the "Task Results" markdown table from a SUMMARY.md body.
- * Returns an array of commit objects extracted from the table rows.
- *
- * Expected table format (produced by pbr executor):
- * | Task | Status | Commit | Files | Verify |
- * |------|--------|--------|-------|--------|
- * | 05-01-T1: Create phase.service.js | done | 2a52581 | 1 | passed |
- *
- * @param {string} rawContent - The markdown body content (after frontmatter)
- * @returns {Array<{task: string, status: string, hash: string, files: number, verify: string}>}
- */
-export function parseTaskResultsTable(rawContent) {
-  if (!rawContent) return [];
-
-  // Find the Task Results section. The table may be followed by another section,
-  // a blank line, or EOF. Use a non-greedy match to capture just the table block.
-  const sectionRegex = /## Task Results\s*\n([\s\S]*?)(?=\n##\s|\n\n\n|$)/;
-  const sectionMatch = rawContent.match(sectionRegex);
-  if (!sectionMatch) return [];
-
-  const tableBlock = sectionMatch[1].trim();
-  const lines = tableBlock.split('\n');
-
-  // Need at least header row + separator row + 1 data row = 3 lines
-  if (lines.length < 3) return [];
-
-  // Skip header row (index 0) and separator row (index 1)
-  const dataRows = lines.slice(2);
-  const commits = [];
-
-  for (const row of dataRows) {
-    // Split by pipe, trim, filter out empty strings from leading/trailing pipes
-    const cells = row.split('|').map(c => c.trim()).filter(c => c);
-    if (cells.length < 5) continue;
-
-    const hash = cells[2];
-    // Skip rows where commit is empty, a dash, or not a hex string
-    if (!hash || hash === '-' || hash === '' || !/^[0-9a-f]{5,40}$/i.test(hash)) continue;
-
-    commits.push({
-      task: cells[0],
-      status: cells[1],
-      hash: hash,
-      files: parseInt(cells[3], 10) || 0,
-      verify: cells[4]
-    });
-  }
-
-  return commits;
-}
-
-/**
- * Get detailed information about a specific phase, including all plans,
- * their summaries, and verification status.
- *
- * @param {string} projectDir - Absolute path to the project root
- * @param {string} phaseId - Two-digit phase identifier (e.g., "04")
- * @returns {Promise<{phaseId: string, phaseName: string, phaseDir: string|null, plans: Array, verification: object|null}>}
- */
-export async function getPhaseDetail(projectDir, phaseId) {
-  const emptyState = { phaseId, phaseName: 'Unknown', phaseDir: null, plans: [], verification: null };
-  const phasesDir = join(projectDir, '.planning', 'phases');
-
-  let phaseDirEntries;
-  try {
-    phaseDirEntries = await readdir(phasesDir, { withFileTypes: true });
-  } catch (error) {
-    if (error.code === 'ENOENT') {
-      return emptyState;
-    }
-    throw error;
-  }
-
-  // Find the directory matching this phaseId (prefer longest name to handle stale renames)
-  const phaseDir = phaseDirEntries
-    .filter(entry => entry.isDirectory() && entry.name.startsWith(`${phaseId}-`))
-    .sort((a, b) => b.name.length - a.name.length)
-    [0];
-
-  if (!phaseDir) {
-    return emptyState;
-  }
-
-  const phaseName = formatPhaseName(phaseDir.name);
-  const phaseFullPath = join(phasesDir, phaseDir.name);
-
-  // Read files in the phase directory
-  const phaseFiles = await readdir(phaseFullPath);
-
-  // Filter and sort PLAN.md files
-  // Supports both naming conventions:
-  //   - NN-NN-PLAN.md (plan ID embedded in filename)
-  //   - PLAN.md (single plan per phase, ID derived from phase directory)
-  const planRegex = /^(?:(?:\d{2}-\d{2})-)?PLAN(?:-\d{2})?\.md$/;
-  const planFiles = phaseFiles
-    .filter(f => planRegex.test(f))
-    .sort();
-
-  // Build summary paths and read them in parallel
-  // Derive planId from filename (NN-NN-PLAN.md) or phase directory (PLAN.md -> NN-01)
-  const summaryPaths = planFiles.map((planFile, index) => {
-    const oldMatch = planFile.match(/^(\d{2}-\d{2})-PLAN\.md$/);
-    const newMatch = planFile.match(/^PLAN-(\d{2})\.md$/);
-    const planId = oldMatch ? oldMatch[1] : newMatch ? `${phaseId.padStart(2, '0')}-${newMatch[1]}` : `${phaseId.padStart(2, '0')}-${String(index + 1).padStart(2, '0')}`;
-    return { planId, planFile, summaryPath: join(phaseFullPath, `SUMMARY-${planId}.md`) };
-  });
-
-  const summaryResults = await Promise.allSettled(
-    summaryPaths.map(({ summaryPath }) => readMarkdownFile(summaryPath))
-  );
-
-  // Map results to plan objects
-  const plans = summaryPaths.map(({ planId, planFile }, index) => {
-    const result = summaryResults[index];
-    if (result.status === 'fulfilled') {
-      return {
-        planId,
-        planFile,
-        summary: result.value.frontmatter,
-        content: result.value.html,
-        commits: parseTaskResultsTable(result.value.rawContent)
-      };
-    }
-    if (result.reason && result.reason.code === 'ENOENT') {
-      return { planId, planFile, summary: null, content: null, commits: [] };
-    }
-    // Unexpected error -- re-throw
-    throw result.reason;
-  });
-
-  // Read VERIFICATION.md
-  let verification = null;
-  try {
-    const verDoc = await readMarkdownFile(join(phaseFullPath, 'VERIFICATION.md'));
-    verification = verDoc.frontmatter;
-  } catch (error) {
-    if (error.code !== 'ENOENT') {
-      throw error;
-    }
-    // ENOENT -> verification stays null
-  }
-
-  return {
-    phaseId,
-    phaseName,
-    phaseDir: phaseDir.name,
-    plans,
-    verification
-  };
-}
-
-/**
- * Read and render a PLAN.md or SUMMARY.md file for a specific phase and plan.
- *
- * @param {string} projectDir - Absolute path to the project root
- * @param {string} phaseId - Two-digit phase identifier (e.g., "04")
- * @param {string} planId - Plan identifier (e.g., "04-01")
- * @param {'plan'|'summary'} docType - Which document to read
- * @returns {Promise<{phaseId: string, planId: string, docType: string, phaseName: string, frontmatter: object, html: string}|null>}
- */
-export async function getPhaseDocument(projectDir, phaseId, planId, docType) {
-  const phasesDir = join(projectDir, '.planning', 'phases');
-
-  let phaseDirEntries;
-  try {
-    phaseDirEntries = await readdir(phasesDir, { withFileTypes: true });
-  } catch (error) {
-    if (error.code === 'ENOENT') return null;
-    throw error;
-  }
-
-  const phaseDir = phaseDirEntries
-    .filter(entry => entry.isDirectory() && entry.name.startsWith(`${phaseId}-`))
-    .sort((a, b) => b.name.length - a.name.length)
-    [0];
-
-  if (!phaseDir) return null;
-
-  const phaseName = formatPhaseName(phaseDir.name);
-  const phaseFullPath = join(phasesDir, phaseDir.name);
-
-  // Try plan ID-prefixed filename first, then fall back to plain PLAN.md
-  // Supports both "01-01-PLAN.md" and "PLAN.md" naming conventions
-  let fileNames;
-  if (docType === 'plan') {
-    fileNames = [`${planId}-PLAN.md`, 'PLAN.md'];
-  } else if (docType === 'verification') {
-    fileNames = ['VERIFICATION.md'];
-  } else {
-    fileNames = [`SUMMARY-${planId}.md`];
-  }
-
-  for (const fileName of fileNames) {
-    const filePath = validatePath(phaseFullPath, fileName);
-    try {
-      const doc = await readMarkdownFile(filePath);
-      return {
-        phaseId,
-        planId,
-        docType,
-        phaseName,
-        frontmatter: doc.frontmatter,
-        html: doc.html
-      };
-    } catch (error) {
-      if (error.code === 'ENOENT') continue;
-      throw error;
-    }
-  }
-  return null;
-}

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

@@ -1,57 +0,0 @@
-import { join, resolve, relative } from 'node:path';
-import { readMarkdownFile, listPlanningFiles } from '../repositories/planning.repository.js';
-
-/**
- * Get homepage data for the dashboard.
- * Reads .planning/README.md if it exists, returns fallback data if not.
- *
- * @param {string} projectDir - Absolute path to the project root
- * @returns {Promise<{title: string, projectDir: string, content: string}>}
- */
-export async function getHomepage(projectDir) {
-  try {
-    const readmePath = join(projectDir, '.planning', 'README.md');
-    const { frontmatter, html } = await readMarkdownFile(readmePath);
-
-    return {
-      title: frontmatter.title || 'PBR Dashboard',
-      projectDir,
-      content: html
-    };
-  } catch (error) {
-    if (error.code === 'ENOENT') {
-      return {
-        title: 'Welcome',
-        projectDir,
-        content: '<p>No project README found.</p>'
-      };
-    }
-    throw error;
-  }
-}
-
-/**
- * Read a specific markdown file from within the .planning/ directory.
- * Validates that the resolved path stays within .planning/ to prevent
- * path traversal attacks.
- *
- * @param {string} projectDir - Absolute path to the project root
- * @param {string} relativePath - Path relative to .planning/ (e.g., 'phases/01/PLAN.md')
- * @returns {Promise<{frontmatter: object, html: string, rawContent: string}>}
- * @throws {Error} If path escapes .planning/ or file not found
- */
-export async function getMarkdownFile(projectDir, relativePath) {
-  const planningDir = resolve(projectDir, '.planning');
-  const filePath = resolve(planningDir, relativePath);
-
-  // Path traversal protection: ensure resolved path is under .planning/
-  const rel = relative(planningDir, filePath);
-  if (rel.startsWith('..') || resolve(filePath) !== filePath && rel.startsWith('..')) {
-    const err = new Error('Path traversal not allowed: path escapes .planning/ directory');
-    err.code = 'PATH_TRAVERSAL';
-    err.status = 403;
-    throw err;
-  }
-
-  return readMarkdownFile(filePath);
-}

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

@@ -1,244 +0,0 @@
-import { readFile, readdir } from 'node:fs/promises';
-import { join } from 'node:path';
-import { parseRoadmapFile } from './dashboard.service.js';
-
-/**
- * Strip UTF-8 BOM from file content.
- * Duplicated 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/, '');
-}
-
-/**
- * Count the number of PLAN.md files in a phase directory.
- *
- * @param {string} projectDir - Absolute path to the project root
- * @param {number} phaseId - Numeric phase ID (e.g., 1, 5, 12)
- * @returns {Promise<number>} Number of NN-NN-PLAN.md files found
- */
-async function countPlansForPhase(projectDir, phaseId) {
-  const phaseIdPadded = String(phaseId).padStart(2, '0');
-  const phasesDir = join(projectDir, '.planning', 'phases');
-
-  try {
-    const entries = await readdir(phasesDir, { withFileTypes: true });
-    // When multiple directories match (e.g. stale rename leftover), prefer the longest name
-    const matchingDirs = entries
-      .filter(e => e.isDirectory() && e.name.startsWith(`${phaseIdPadded}-`))
-      .sort((a, b) => b.name.length - a.name.length);
-    const phaseDir = matchingDirs[0];
-
-    if (!phaseDir) return 0;
-
-    const phaseFiles = await readdir(join(phasesDir, phaseDir.name));
-    return phaseFiles.filter(f => /^(?:(?:\d{2}-\d{2})-)?PLAN(?:-\d{2})?\.md$/.test(f)).length;
-  } catch (err) {
-    if (err.code === 'ENOENT') return 0;
-    throw err;
-  }
-}
-
-/**
- * Extract dependency information from all Phase Details sections in ROADMAP.md.
- *
- * @param {string} roadmapContent - Raw ROADMAP.md content
- * @returns {Map<number, number[]>} Map of phaseId -> array of dependency phase IDs
- */
-function extractAllDependencies(roadmapContent) {
-  const dependencyMap = new Map();
-
-  // Match Phase Details sections: "### Phase NN: ..." followed by "**Depends on**: ..."
-  const sectionRegex = /### Phase (\d+):[\s\S]*?\*\*Depends on:?\*\*:?\s*([^\n]+)/g;
-  let match;
-
-  while ((match = sectionRegex.exec(roadmapContent)) !== null) {
-    const phaseId = parseInt(match[1], 10);
-    const depText = match[2].trim();
-
-    if (depText.toLowerCase().includes('none')) {
-      dependencyMap.set(phaseId, []);
-      continue;
-    }
-
-    // Extract phase numbers from "Phase 01, Phase 02" format
-    const deps = [];
-    const depMatches = depText.matchAll(/Phase (\d+)/g);
-    for (const dm of depMatches) {
-      deps.push(parseInt(dm[1], 10));
-    }
-    dependencyMap.set(phaseId, deps);
-  }
-
-  return dependencyMap;
-}
-
-/**
- * Extract milestone information from ROADMAP.md.
- * Parses explicit "## Milestone:" sections and infers the implicit first milestone
- * from the roadmap title (phases before the first explicit milestone).
- *
- * @param {string} roadmapContent - Raw ROADMAP.md content (newlines normalized)
- * @returns {Array<{name: string, goal: string, startPhase: number, endPhase: number}>}
- */
-function extractMilestones(roadmapContent) {
-  const milestones = [];
-
-  // Get project title from H1: "# Roadmap: PBR Dashboard"
-  const titleMatch = roadmapContent.match(/^# Roadmap:\s*(.+)$/m);
-  const projectTitle = titleMatch ? titleMatch[1].trim() : 'Project';
-
-  // Parse explicit milestones: "## Milestone: Name\n\n**Goal:** ...\n**Phases:** N - M"
-  const milestoneRegex = /## Milestone:\s*(.+)\n+\*\*Goal:?\*\*:?\s*(.+)\n\*\*Phases:?\*\*:?\s*(\d+)\s*-\s*(\d+)/g;
-  const explicit = [];
-  for (const match of roadmapContent.matchAll(milestoneRegex)) {
-    explicit.push({
-      name: match[1].trim(),
-      goal: match[2].trim(),
-      startPhase: parseInt(match[3], 10),
-      endPhase: parseInt(match[4], 10)
-    });
-  }
-
-  // Sort explicit milestones by start phase
-  explicit.sort((a, b) => a.startPhase - b.startPhase);
-
-  // Infer implicit first milestone (phases before first explicit milestone)
-  if (explicit.length > 0) {
-    const firstStart = explicit[0].startPhase;
-    if (firstStart > 1) {
-      milestones.push({
-        name: projectTitle,
-        goal: '',
-        startPhase: 1,
-        endPhase: firstStart - 1
-      });
-    }
-  } else {
-    // No explicit milestones — all phases belong to the project
-    milestones.push({
-      name: projectTitle,
-      goal: '',
-      startPhase: 1,
-      endPhase: 9999
-    });
-  }
-
-  milestones.push(...explicit);
-  return milestones;
-}
-
-/**
- * Get enhanced roadmap data with plan counts, dependencies, and milestones.
- * Combines parseRoadmapFile with raw ROADMAP.md reading for dependency
- * extraction, milestone parsing, and directory scanning for plan counts.
- *
- * @param {string} projectDir - Absolute path to the project root
- * @returns {Promise<{phases: Array, milestones: Array}>}
- */
-/**
- * Generate a Mermaid flowchart string from ROADMAP.md phase dependencies.
- *
- * @param {string} projectDir - Absolute path to the project root
- * @returns {Promise<string>} Mermaid flowchart definition
- */
-export async function generateDependencyMermaid(projectDir) {
-  const { phases, milestones } = await getRoadmapData(projectDir);
-
-  if (phases.length === 0) {
-    return 'graph TD\n  empty["No phases found"]';
-  }
-
-  // Read raw ROADMAP.md for dependencies
-  let dependencyMap = new Map();
-  try {
-    const roadmapPath = join(projectDir, '.planning', 'ROADMAP.md');
-    const rawContent = stripBOM(await readFile(roadmapPath, 'utf-8')).replace(/\r\n/g, '\n');
-    dependencyMap = extractAllDependencies(rawContent);
-  } catch (_err) {
-    // No ROADMAP.md — proceed with no deps
-  }
-
-  // Detect current phase (first non-complete phase, or last phase)
-  const currentPhase = phases.find(p => p.status !== 'Complete') || phases[phases.length - 1];
-
-  const lines = ['graph TD'];
-
-  // Group phases by milestone
-  const phaseById = new Map(phases.map(p => [p.id, p]));
-
-  if (milestones.length > 0) {
-    for (const ms of milestones) {
-      const msPhases = phases.filter(p => p.id >= ms.startPhase && p.id <= ms.endPhase);
-      if (msPhases.length === 0) continue;
-      const safeName = ms.name.replace(/"/g, '#quot;');
-      lines.push(`  subgraph ${safeName}`);
-      for (const p of msPhases) {
-        const label = `Phase ${p.id}: ${p.name}`.replace(/"/g, '#quot;');
-        lines.push(`    P${p.id}["${label}"]`);
-      }
-      lines.push('  end');
-    }
-  } else {
-    for (const p of phases) {
-      const label = `Phase ${p.id}: ${p.name}`.replace(/"/g, '#quot;');
-      lines.push(`  P${p.id}["${label}"]`);
-    }
-  }
-
-  // Add dependency edges
-  for (const [phaseId, deps] of dependencyMap) {
-    if (!phaseById.has(phaseId)) continue;
-    for (const depId of deps) {
-      if (phaseById.has(depId)) {
-        lines.push(`  P${depId} --> P${phaseId}`);
-      }
-    }
-  }
-
-  // Style current phase
-  if (currentPhase) {
-    lines.push(`  style P${currentPhase.id} fill:#4caf50,color:#fff`);
-  }
-
-  // Click handlers
-  for (const p of phases) {
-    lines.push(`  click P${p.id} "/phases/${p.id}"`);
-  }
-
-  return lines.join('\n');
-}
-
-export async function getRoadmapData(projectDir) {
-  const { phases: basePhases } = await parseRoadmapFile(projectDir);
-
-  if (basePhases.length === 0) {
-    return { phases: [], milestones: [] };
-  }
-
-  // Read raw ROADMAP.md for dependencies and milestones
-  let dependencyMap = new Map();
-  let milestones = [];
-  try {
-    const roadmapPath = join(projectDir, '.planning', 'ROADMAP.md');
-    const rawContent = stripBOM(await readFile(roadmapPath, 'utf-8')).replace(/\r\n/g, '\n');
-    dependencyMap = extractAllDependencies(rawContent);
-    milestones = extractMilestones(rawContent);
-  } catch (err) {
-    if (err.code !== 'ENOENT') throw err;
-  }
-
-  // Enhance each phase with plan count and dependencies in parallel
-  const enhancedPhases = await Promise.all(
-    basePhases.map(async (phase) => {
-      const planCount = await countPlansForPhase(projectDir, phase.id);
-      const dependencies = dependencyMap.get(phase.id) || [];
-      return { ...phase, planCount, dependencies };
-    })
-  );
-
-  return { phases: enhancedPhases, milestones };
-}

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

@@ -1,58 +0,0 @@
-/**
- * SSE (Server-Sent Events) service.
- * Manages a Set of active client response objects and provides
- * broadcast functionality to send events to all connected browsers.
- */
-
-/** @type {Set<import('http').ServerResponse>} */
-const clients = new Set();
-
-/**
- * Register a client response object for SSE broadcasting.
- * @param {import('http').ServerResponse} res
- */
-export function addClient(res) {
-  clients.add(res);
-}
-
-/**
- * Remove a client response object (called on disconnect).
- * @param {import('http').ServerResponse} res
- */
-export function removeClient(res) {
-  clients.delete(res);
-}
-
-/**
- * Broadcast an SSE event to all connected clients.
- * Clients that throw on write are automatically removed.
- * @param {string} eventType - SSE event name (e.g. 'file-change')
- * @param {object} data - Payload to JSON-serialize in the data field
- */
-export function broadcast(eventType, data) {
-  const id = Date.now();
-  const message = `event: ${eventType}\ndata: ${JSON.stringify(data)}\nid: ${id}\n\n`;
-
-  for (const client of clients) {
-    try {
-      client.write(message);
-    } catch {
-      clients.delete(client);
-    }
-  }
-}
-
-/**
- * Return the number of currently connected clients.
- * @returns {number}
- */
-export function getClientCount() {
-  return clients.size;
-}
-
-/**
- * Remove all clients. Used in tests to reset state between test cases.
- */
-export function clearClients() {
-  clients.clear();
-}