@sienklogic/plan-build-run 2.34.0 → 2.38.0

package/plugins/pbr/scripts/lib/roadmap.js

@@ -0,0 +1,175 @@
+/**
+ * lib/roadmap.js — ROADMAP.md operations for Plan-Build-Run tools.
+ *
+ * Handles parsing and updating the ROADMAP.md phase overview table.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { lockedFileUpdate, validateStatusTransition } = require('./core');
+
+// --- Parsers ---
+
+function parseRoadmapMd(content) {
+  const result = { phases: [], has_progress_table: false };
+
+  // Find Phase Overview table
+  const overviewMatch = content.match(/## Phase Overview[\s\S]*?\|[\s\S]*?(?=\n##|\s*$)/);
+  if (overviewMatch) {
+    const rows = overviewMatch[0].split('\n').filter(r => r.includes('|'));
+    // Skip header and separator rows
+    for (let i = 2; i < rows.length; i++) {
+      const cols = rows[i].split('|').map(c => c.trim()).filter(Boolean);
+      if (cols.length >= 3) {
+        result.phases.push({
+          number: cols[0],
+          name: cols[1],
+          goal: cols[2],
+          plans: cols[3] || '',
+          wave: cols[4] || '',
+          status: cols[5] || 'pending'
+        });
+      }
+    }
+  }
+
+  // Check for Progress table
+  result.has_progress_table = /## Progress/.test(content);
+
+  return result;
+}
+
+// --- Table helpers ---
+
+/**
+ * Find the row index of a phase in a ROADMAP.md table.
+ * @returns {number} Line index or -1 if not found
+ */
+function findRoadmapRow(lines, phaseNum) {
+  const paddedPhase = phaseNum.padStart(2, '0');
+  for (let i = 0; i < lines.length; i++) {
+    if (!lines[i].includes('|')) continue;
+    const parts = lines[i].split('|');
+    if (parts.length < 3) continue;
+    const phaseCol = parts[1] ? parts[1].trim() : '';
+    if (phaseCol === paddedPhase) {
+      return i;
+    }
+  }
+  return -1;
+}
+
+/**
+ * Update a specific column in a markdown table row.
+ * @param {string} row - The full table row string (e.g., "| 01 | Setup | ... |")
+ * @param {number} columnIndex - 0-based column index (Phase=0, Name=1, ..., Status=5)
+ * @param {string} newValue - New cell value
+ * @returns {string} Updated row
+ */
+function updateTableRow(row, columnIndex, newValue) {
+  const parts = row.split('|');
+  // parts[0] is empty (before first |), data starts at parts[1]
+  const partIndex = columnIndex + 1;
+  if (partIndex < parts.length) {
+    parts[partIndex] = ` ${newValue} `;
+  }
+  return parts.join('|');
+}
+
+// --- Mutation commands ---
+
+/**
+ * Update the Status column for a phase in ROADMAP.md's Phase Overview table.
+ *
+ * @param {string} phaseNum - Phase number
+ * @param {string} newStatus - New status value
+ * @param {string} [planningDir] - Path to .planning directory
+ */
+function roadmapUpdateStatus(phaseNum, newStatus, planningDir) {
+  const dir = planningDir || path.join(process.env.PBR_PROJECT_ROOT || process.cwd(), '.planning');
+  const roadmapPath = path.join(dir, 'ROADMAP.md');
+  if (!fs.existsSync(roadmapPath)) {
+    return { success: false, error: 'ROADMAP.md not found' };
+  }
+
+  let oldStatus = null;
+
+  const result = lockedFileUpdate(roadmapPath, (content) => {
+    const lines = content.split('\n');
+    const rowIdx = findRoadmapRow(lines, phaseNum);
+    if (rowIdx === -1) {
+      return content; // No matching row found
+    }
+    const parts = lines[rowIdx].split('|');
+    oldStatus = parts[6] ? parts[6].trim() : 'unknown';
+    lines[rowIdx] = updateTableRow(lines[rowIdx], 5, newStatus);
+    return lines.join('\n');
+  });
+
+  if (!oldStatus) {
+    return { success: false, error: `Phase ${phaseNum} not found in ROADMAP.md table` };
+  }
+
+  // Advisory transition validation — warn on suspicious transitions but don't block
+  const transition = validateStatusTransition(oldStatus, newStatus);
+  if (!transition.valid && transition.warning) {
+    process.stderr.write(`[pbr-tools] WARNING: ${transition.warning}\n`);
+  }
+
+  if (result.success) {
+    const response = { success: true, old_status: oldStatus, new_status: newStatus };
+    if (!transition.valid) {
+      response.transition_warning = transition.warning;
+    }
+    return response;
+  }
+  return { success: false, error: result.error };
+}
+
+/**
+ * Update the Plans column for a phase in ROADMAP.md's Phase Overview table.
+ *
+ * @param {string} phaseNum - Phase number
+ * @param {string} complete - Completed plan count
+ * @param {string} total - Total plan count
+ * @param {string} [planningDir] - Path to .planning directory
+ */
+function roadmapUpdatePlans(phaseNum, complete, total, planningDir) {
+  const dir = planningDir || path.join(process.env.PBR_PROJECT_ROOT || process.cwd(), '.planning');
+  const roadmapPath = path.join(dir, 'ROADMAP.md');
+  if (!fs.existsSync(roadmapPath)) {
+    return { success: false, error: 'ROADMAP.md not found' };
+  }
+
+  let oldPlans = null;
+  const newPlans = `${complete}/${total}`;
+
+  const result = lockedFileUpdate(roadmapPath, (content) => {
+    const lines = content.split('\n');
+    const rowIdx = findRoadmapRow(lines, phaseNum);
+    if (rowIdx === -1) {
+      return content;
+    }
+    const parts = lines[rowIdx].split('|');
+    oldPlans = parts[4] ? parts[4].trim() : 'unknown';
+    lines[rowIdx] = updateTableRow(lines[rowIdx], 3, newPlans);
+    return lines.join('\n');
+  });
+
+  if (!oldPlans) {
+    return { success: false, error: `Phase ${phaseNum} not found in ROADMAP.md table` };
+  }
+
+  if (result.success) {
+    return { success: true, old_plans: oldPlans, new_plans: newPlans };
+  }
+  return { success: false, error: result.error };
+}
+
+module.exports = {
+  parseRoadmapMd,
+  findRoadmapRow,
+  updateTableRow,
+  roadmapUpdateStatus,
+  roadmapUpdatePlans
+};

package/plugins/pbr/scripts/lib/state.js

@@ -0,0 +1,397 @@
+/**
+ * lib/state.js — STATE.md operations for Plan-Build-Run tools.
+ *
+ * Handles loading, parsing, updating, patching, and advancing STATE.md.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const {
+  parseYamlFrontmatter,
+  findFiles,
+  lockedFileUpdate,
+  calculateProgress,
+  determinePhaseStatus
+} = require('./core');
+
+// --- Parsers ---
+
+function parseStateMd(content) {
+  const result = {
+    current_phase: null,
+    phase_name: null,
+    progress: null,
+    status: null,
+    line_count: content.split('\n').length,
+    format: 'legacy' // 'legacy' or 'frontmatter'
+  };
+
+  // Check for YAML frontmatter (version 2 format)
+  const frontmatter = parseYamlFrontmatter(content);
+  if (frontmatter.version === 2 || frontmatter.current_phase !== undefined) {
+    result.format = 'frontmatter';
+    result.current_phase = frontmatter.current_phase || null;
+    result.total_phases = frontmatter.total_phases || null;
+    result.phase_name = frontmatter.phase_slug || frontmatter.phase_name || null;
+    result.status = frontmatter.status || null;
+    result.progress = frontmatter.progress_percent !== undefined ? frontmatter.progress_percent : null;
+    result.plans_total = frontmatter.plans_total || null;
+    result.plans_complete = frontmatter.plans_complete || null;
+    result.last_activity = frontmatter.last_activity || null;
+    result.last_command = frontmatter.last_command || null;
+    result.blockers = frontmatter.blockers || [];
+    return result;
+  }
+
+  // Legacy regex-based parsing (version 1 format, no frontmatter)
+  // DEPRECATED (2026-02): v1 STATE.md format (no YAML frontmatter) is deprecated.
+  // New projects should use v2 (frontmatter) format, generated by /pbr:setup.
+  // v1 support will be removed in a future major version.
+  process.stderr.write('[pbr] WARNING: STATE.md uses legacy v1 format. Run /pbr:setup to migrate to v2 format.\n');
+  // Extract "Phase: N of M"
+  const phaseMatch = content.match(/Phase:\s*(\d+)\s+of\s+(\d+)/);
+  if (phaseMatch) {
+    result.current_phase = parseInt(phaseMatch[1], 10);
+    result.total_phases = parseInt(phaseMatch[2], 10);
+  }
+
+  // Extract phase name (line after "Phase:")
+  const nameMatch = content.match(/--\s+(.+?)(?:\n|$)/);
+  if (nameMatch) {
+    result.phase_name = nameMatch[1].trim();
+  }
+
+  // Extract progress percentage
+  const progressMatch = content.match(/(\d+)%/);
+  if (progressMatch) {
+    result.progress = parseInt(progressMatch[1], 10);
+  }
+
+  // Extract plan status
+  const statusMatch = content.match(/Status:\s*(.+?)(?:\n|$)/i);
+  if (statusMatch) {
+    result.status = statusMatch[1].trim();
+  }
+
+  return result;
+}
+
+// --- Mutation helpers ---
+
+/**
+ * Update a field in legacy (non-frontmatter) STATE.md content.
+ * Pure function: content in, content out.
+ */
+function updateLegacyStateField(content, field, value) {
+  const lines = content.split('\n');
+
+  switch (field) {
+    case 'current_phase': {
+      const idx = lines.findIndex(l => /Phase:\s*\d+\s+of\s+\d+/.test(l));
+      if (idx !== -1) {
+        lines[idx] = lines[idx].replace(/(Phase:\s*)\d+/, (_, prefix) => `${prefix}${value}`);
+      }
+      break;
+    }
+    case 'status': {
+      const idx = lines.findIndex(l => /^Status:/i.test(l));
+      if (idx !== -1) {
+        lines[idx] = `Status: ${value}`;
+      } else {
+        const phaseIdx = lines.findIndex(l => /Phase:/.test(l));
+        if (phaseIdx !== -1) {
+          lines.splice(phaseIdx + 1, 0, `Status: ${value}`);
+        } else {
+          lines.push(`Status: ${value}`);
+        }
+      }
+      break;
+    }
+    case 'plans_complete': {
+      const idx = lines.findIndex(l => /Plan:\s*\d+\s+of\s+\d+/.test(l));
+      if (idx !== -1) {
+        lines[idx] = lines[idx].replace(/(Plan:\s*)\d+/, (_, prefix) => `${prefix}${value}`);
+      }
+      break;
+    }
+    case 'last_activity': {
+      const idx = lines.findIndex(l => /^Last Activity:/i.test(l));
+      if (idx !== -1) {
+        lines[idx] = `Last Activity: ${value}`;
+      } else {
+        const statusIdx = lines.findIndex(l => /^Status:/i.test(l));
+        if (statusIdx !== -1) {
+          lines.splice(statusIdx + 1, 0, `Last Activity: ${value}`);
+        } else {
+          lines.push(`Last Activity: ${value}`);
+        }
+      }
+      break;
+    }
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Update a field in YAML frontmatter content.
+ * Pure function: content in, content out.
+ */
+function updateFrontmatterField(content, field, value) {
+  const match = content.match(/^(---\s*\n)([\s\S]*?)(\n---)/);
+  if (!match) return content;
+
+  const before = match[1];
+  let yaml = match[2];
+  const after = match[3];
+  const rest = content.slice(match[0].length);
+
+  // Format value: integers stay bare, strings get quotes
+  const isNum = /^\d+$/.test(String(value));
+  const formatted = isNum ? value : `"${value}"`;
+
+  const fieldRegex = new RegExp(`^(${field})\\s*:.*$`, 'm');
+  if (fieldRegex.test(yaml)) {
+    yaml = yaml.replace(fieldRegex, () => `${field}: ${formatted}`);
+  } else {
+    yaml = yaml + `\n${field}: ${formatted}`;
+  }
+
+  return before + yaml + after + rest;
+}
+
+// --- Commands ---
+
+/**
+ * Load full project state from .planning/ directory.
+ *
+ * @param {string} [planningDir] - Path to .planning directory
+ * @returns {object} Full state object
+ */
+function stateLoad(planningDir) {
+  const dir = planningDir || path.join(process.env.PBR_PROJECT_ROOT || process.cwd(), '.planning');
+  const { parseRoadmapMd } = require('./roadmap');
+
+  const result = {
+    exists: false,
+    config: null,
+    state: null,
+    roadmap: null,
+    phase_count: 0,
+    current_phase: null,
+    progress: null
+  };
+
+  if (!fs.existsSync(dir)) {
+    return result;
+  }
+  result.exists = true;
+
+  // Load config.json
+  const configPath = path.join(dir, 'config.json');
+  if (fs.existsSync(configPath)) {
+    try {
+      result.config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    } catch (_) {
+      result.config = { _error: 'Failed to parse config.json' };
+    }
+  }
+
+  // Load STATE.md
+  const statePath = path.join(dir, 'STATE.md');
+  if (fs.existsSync(statePath)) {
+    const content = fs.readFileSync(statePath, 'utf8');
+    result.state = parseStateMd(content);
+  }
+
+  // Load ROADMAP.md
+  const roadmapPath = path.join(dir, 'ROADMAP.md');
+  if (fs.existsSync(roadmapPath)) {
+    const content = fs.readFileSync(roadmapPath, 'utf8');
+    result.roadmap = parseRoadmapMd(content);
+    result.phase_count = result.roadmap.phases.length;
+  }
+
+  // Extract current phase
+  if (result.state && result.state.current_phase) {
+    result.current_phase = result.state.current_phase;
+  }
+
+  // Calculate progress
+  result.progress = calculateProgress(dir);
+
+  return result;
+}
+
+/**
+ * Recalculate progress from filesystem.
+ *
+ * @param {string} [planningDir] - Path to .planning directory
+ * @returns {object} Progress object
+ */
+function stateCheckProgress(planningDir) {
+  const dir = planningDir || path.join(process.env.PBR_PROJECT_ROOT || process.cwd(), '.planning');
+  const phasesDir = path.join(dir, 'phases');
+  if (!fs.existsSync(phasesDir)) {
+    return { phases: [], total_plans: 0, completed_plans: 0, percentage: 0 };
+  }
+
+  const phases = [];
+  let totalPlans = 0;
+  let completedPlans = 0;
+
+  const entries = fs.readdirSync(phasesDir, { withFileTypes: true })
+    .filter(e => e.isDirectory())
+    .sort((a, b) => a.name.localeCompare(b.name));
+
+  for (const entry of entries) {
+    const phaseDir = path.join(phasesDir, entry.name);
+    const plans = findFiles(phaseDir, /-PLAN\.md$/);
+    const summaries = findFiles(phaseDir, /^SUMMARY-.*\.md$/);
+    const verification = fs.existsSync(path.join(phaseDir, 'VERIFICATION.md'));
+
+    const completedSummaries = summaries.filter(s => {
+      const content = fs.readFileSync(path.join(phaseDir, s), 'utf8');
+      return /status:\s*["']?complete/i.test(content);
+    });
+
+    const phaseInfoObj = {
+      directory: entry.name,
+      plans: plans.length,
+      summaries: summaries.length,
+      completed: completedSummaries.length,
+      has_verification: verification,
+      status: determinePhaseStatus(plans.length, completedSummaries.length, summaries.length, verification, phaseDir)
+    };
+
+    phases.push(phaseInfoObj);
+    totalPlans += plans.length;
+    completedPlans += completedSummaries.length;
+  }
+
+  return {
+    phases,
+    total_plans: totalPlans,
+    completed_plans: completedPlans,
+    percentage: totalPlans > 0 ? Math.round((completedPlans / totalPlans) * 100) : 0
+  };
+}
+
+/**
+ * Atomically update a field in STATE.md using lockedFileUpdate.
+ * Supports both legacy and frontmatter (v2) formats.
+ *
+ * @param {string} field - One of: current_phase, status, plans_complete, last_activity
+ * @param {string} value - New value (use 'now' for last_activity to auto-timestamp)
+ * @param {string} [planningDir] - Path to .planning directory
+ */
+function stateUpdate(field, value, planningDir) {
+  const dir = planningDir || path.join(process.env.PBR_PROJECT_ROOT || process.cwd(), '.planning');
+  const statePath = path.join(dir, 'STATE.md');
+  if (!fs.existsSync(statePath)) {
+    return { success: false, error: 'STATE.md not found' };
+  }
+
+  const validFields = ['current_phase', 'status', 'plans_complete', 'last_activity'];
+  if (!validFields.includes(field)) {
+    return { success: false, error: `Invalid field: ${field}. Valid fields: ${validFields.join(', ')}` };
+  }
+
+  // Auto-timestamp
+  if (field === 'last_activity' && value === 'now') {
+    value = new Date().toISOString().slice(0, 19).replace('T', ' ');
+  }
+
+  const result = lockedFileUpdate(statePath, (content) => {
+    const fm = parseYamlFrontmatter(content);
+    if (fm.version === 2 || fm.current_phase !== undefined) {
+      return updateFrontmatterField(content, field, value);
+    }
+    return updateLegacyStateField(content, field, value);
+  });
+
+  if (result.success) {
+    return { success: true, field, value };
+  }
+  return { success: false, error: result.error };
+}
+
+/**
+ * Batch-update multiple STATE.md fields at once.
+ *
+ * @param {string} jsonStr - JSON string of field:value pairs
+ * @param {string} [planningDir] - Path to .planning directory
+ */
+function statePatch(jsonStr, planningDir) {
+  const dir = planningDir || path.join(process.env.PBR_PROJECT_ROOT || process.cwd(), '.planning');
+  const statePath = path.join(dir, 'STATE.md');
+  if (!fs.existsSync(statePath)) return { success: false, error: "STATE.md not found" };
+  let fields;
+  try { fields = JSON.parse(jsonStr); } catch (_e) { return { success: false, error: "Invalid JSON" }; }
+  const validFields = ["current_phase", "status", "plans_complete", "last_activity", "progress_percent", "phase_slug", "total_phases", "last_command", "blockers"];
+  const updates = [], errors = [];
+  for (const [field, value] of Object.entries(fields)) {
+    if (!validFields.includes(field)) { errors.push("Unknown field: " + field); continue; }
+    try { stateUpdate(field, String(value), dir); updates.push(field); } catch (e) { errors.push(field + ": " + e.message); }
+  }
+  return { success: errors.length === 0, updated: updates, errors: errors.length > 0 ? errors : undefined };
+}
+
+/**
+ * Advance the plan counter in STATE.md by 1.
+ *
+ * @param {string} [planningDir] - Path to .planning directory
+ */
+function stateAdvancePlan(planningDir) {
+  const dir = planningDir || path.join(process.env.PBR_PROJECT_ROOT || process.cwd(), '.planning');
+  const statePath = path.join(dir, 'STATE.md');
+  if (!fs.existsSync(statePath)) return { success: false, error: "STATE.md not found" };
+  const stateContent = fs.readFileSync(statePath, "utf8");
+  const planMatch = stateContent.match(/Plan:\s*(\d+)\s+of\s+(\d+)/);
+  if (!planMatch) return { success: false, error: "Could not find Plan: N of M in STATE.md" };
+  const current = parseInt(planMatch[1], 10), total = parseInt(planMatch[2], 10);
+  const next = Math.min(current + 1, total);
+  stateUpdate("plans_complete", String(next), dir);
+  const progressPct = total > 0 ? Math.round((next / total) * 100) : 0;
+  stateUpdate("progress_percent", String(progressPct), dir);
+  return { success: true, previous_plan: current, current_plan: next, total_plans: total, progress_percent: progressPct };
+}
+
+/**
+ * Record a session metric in STATE.md + HISTORY.md.
+ *
+ * @param {string[]} metricArgs - CLI args like ['--duration', '30m', '--plans-completed', '3']
+ * @param {string} [planningDir] - Path to .planning directory
+ */
+function stateRecordMetric(metricArgs, planningDir) {
+  const dir = planningDir || path.join(process.env.PBR_PROJECT_ROOT || process.cwd(), '.planning');
+  const { historyAppend } = require('./history');
+  let duration = null, plansCompleted = null;
+  for (let i = 0; i < metricArgs.length; i++) {
+    if (metricArgs[i] === "--duration" && metricArgs[i + 1]) {
+      const match = metricArgs[i + 1].match(/(\d+)(m|s|h)/);
+      if (match) { const val = parseInt(match[1], 10); const unit = match[2]; duration = unit === "h" ? val * 60 : unit === "s" ? Math.round(val / 60) : val; }
+      i++;
+    } else if (metricArgs[i] === "--plans-completed" && metricArgs[i + 1]) {
+      plansCompleted = parseInt(metricArgs[i + 1], 10); i++;
+    }
+  }
+  const parts = [];
+  if (duration !== null) parts.push("duration: " + duration + "m");
+  if (plansCompleted !== null) parts.push("plans_completed: " + plansCompleted);
+  if (parts.length > 0) historyAppend({ type: "metric", title: "Session metric", body: parts.join(", ") }, dir);
+  stateUpdate("last_activity", "now", dir);
+  return { success: true, duration_minutes: duration, plans_completed: plansCompleted };
+}
+
+module.exports = {
+  parseStateMd,
+  updateLegacyStateField,
+  updateFrontmatterField,
+  stateLoad,
+  stateCheckProgress,
+  stateUpdate,
+  statePatch,
+  stateAdvancePlan,
+  stateRecordMetric
+};