@sienklogic/plan-build-run 2.0.0 → 2.0.1

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

@@ -1,167 +1,220 @@
-import { readdir } from 'node:fs/promises';
-import { join } from 'node:path';
-import { readMarkdownFile } 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
-  const planRegex = /^\d{2}-\d{2}-PLAN\.md$/;
-  const planIdRegex = /^(\d{2}-\d{2})-PLAN\.md$/;
-  const planFiles = phaseFiles
-    .filter(f => planRegex.test(f))
-    .sort();
-
-  // Build summary paths and read them in parallel
-  const summaryPaths = planFiles.map(planFile => {
-    const match = planFile.match(planIdRegex);
-    const planId = match[1];
-    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
-  };
-}
+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
+  const planRegex = /^\d{2}-\d{2}-PLAN\.md$/;
+  const planIdRegex = /^(\d{2}-\d{2})-PLAN\.md$/;
+  const planFiles = phaseFiles
+    .filter(f => planRegex.test(f))
+    .sort();
+
+  // Build summary paths and read them in parallel
+  const summaryPaths = planFiles.map(planFile => {
+    const match = planFile.match(planIdRegex);
+    const planId = match[1];
+    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);
+
+  const fileName = docType === 'plan'
+    ? `${planId}-PLAN.md`
+    : `SUMMARY-${planId}.md`;
+
+  // Validate the path stays within the phase directory
+  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') return null;
+    throw error;
+  }
+}

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

@@ -1,57 +1,57 @@
-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);
-}
+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);
+}