@sienklogic/plan-build-run 2.0.0

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

@@ -0,0 +1,48 @@
+import chokidar from 'chokidar';
+import { join, relative } from 'node:path';
+
+/**
+ * Create a chokidar file watcher for the .planning/ directory.
+ *
+ * Watches **\/*.md files with awaitWriteFinish to debounce editor saves.
+ * Calls onChange with a normalized event object on add, change, and unlink.
+ *
+ * @param {string} watchPath - Absolute path to the project directory
+ * @param {(event: {path: string, type: string, timestamp: number}) => void} onChange
+ * @returns {import('chokidar').FSWatcher}
+ */
+export function createWatcher(watchPath, onChange) {
+  const planningDir = join(watchPath, '.planning');
+
+  const watcher = chokidar.watch(join(planningDir, '**/*.md'), {
+    ignored: [
+      '**/node_modules/**',
+      '**/.git/**'
+    ],
+    persistent: true,
+    ignoreInitial: true,
+    awaitWriteFinish: {
+      stabilityThreshold: 2000,
+      pollInterval: 100
+    }
+  });
+
+  const handleEvent = (type) => (filePath) => {
+    const relativePath = relative(watchPath, filePath);
+    onChange({
+      path: relativePath,
+      type,
+      timestamp: Date.now()
+    });
+  };
+
+  watcher.on('add', handleEvent('add'));
+  watcher.on('change', handleEvent('change'));
+  watcher.on('unlink', handleEvent('unlink'));
+
+  watcher.on('error', (error) => {
+    console.error('Watcher error:', error.message);
+  });
+
+  return watcher;
+}

package/dashboard/src/views/coming-soon.ejs

@@ -0,0 +1,11 @@
+<%- include('partials/layout-top', { title: title, activePage: activePage }) %>
+
+<h1><%= featureName %></h1>
+<p>This feature is coming soon.</p>
+<p>
+  The <strong><%= featureName %></strong> view is planned but not yet implemented.
+  Check back in a future phase.
+</p>
+<p><a href="/">Back to Dashboard</a></p>
+
+<%- include('partials/layout-bottom') %>

package/dashboard/src/views/error.ejs

@@ -0,0 +1,13 @@
+<%- include('partials/layout-top', { title: typeof title !== 'undefined' ? title : 'Error', activePage: '' }) %>
+
+<h1>Error <%= status %></h1>
+<p><%= message %></p>
+<% if (typeof stack !== 'undefined' && stack) { %>
+<details>
+  <summary>Stack Trace (Development Only)</summary>
+  <pre><code><%= stack %></code></pre>
+</details>
+<% } %>
+<p><a href="/">Return to Dashboard</a></p>
+
+<%- include('partials/layout-bottom') %>

package/dashboard/src/views/index.ejs

@@ -0,0 +1,5 @@
+<%- include('partials/layout-top', { title: title, activePage: 'dashboard' }) %>
+
+<%- include('partials/dashboard-content') %>
+
+<%- include('partials/layout-bottom') %>

package/dashboard/src/views/layout.ejs

@@ -0,0 +1 @@
+<%# This file is deprecated. See partials/layout-top.ejs and partials/layout-bottom.ejs %>

package/dashboard/src/views/partials/dashboard-content.ejs

@@ -0,0 +1,77 @@
+<h1><%= projectName %></h1>
+
+<!-- Project Overview Card -->
+<article>
+  <header>
+    <strong>Current Phase</strong>
+  </header>
+  <% if (currentPhase.id > 0) { %>
+    <p>
+      <span class="status-badge" data-status="in-progress">Phase <%= currentPhase.id %></span>
+      <%= currentPhase.name %>
+    </p>
+    <p><small><%= currentPhase.planStatus %></small></p>
+  <% } else { %>
+    <p>No active phase. Project has not started yet.</p>
+  <% } %>
+
+  <% if (lastActivity.date) { %>
+    <p><small>Last activity: <%= lastActivity.date %> &mdash; <%= lastActivity.description %></small></p>
+  <% } %>
+</article>
+
+<!-- Overall Progress -->
+<article>
+  <header>
+    <strong>Overall Progress</strong>
+  </header>
+  <progress value="<%= progress %>" max="100"></progress>
+  <p><%= progress %>% complete (<%= phases.filter(p => p.status === 'complete').length %> of <%= phases.length %> phases)</p>
+</article>
+
+<!-- Phase List -->
+<article>
+  <header>
+    <strong>All Phases</strong>
+  </header>
+  <% if (phases.length > 0) { %>
+    <div class="table-wrap">
+    <table>
+      <thead>
+        <tr>
+          <th scope="col">Phase</th>
+          <th scope="col">Name</th>
+          <th scope="col">Description</th>
+          <th scope="col">Status</th>
+        </tr>
+      </thead>
+      <tbody>
+        <% phases.forEach(function(phase) { %>
+        <tr>
+          <td><%= String(phase.id).padStart(2, '0') %></td>
+          <td><a href="/phases/<%= String(phase.id).padStart(2, '0') %>"><%= phase.name %></a></td>
+          <td><%= phase.description %></td>
+          <td>
+            <span class="status-badge" data-status="<%= phase.status %>">
+              <%= phase.status.replace('-', ' ') %>
+            </span>
+          </td>
+        </tr>
+        <% }); %>
+      </tbody>
+    </table>
+    </div>
+  <% } else { %>
+    <p>No phases found. Add a ROADMAP.md file to your .planning/ directory to see phases here.</p>
+  <% } %>
+</article>
+
+<!-- README Content (if available) -->
+<% if (content && content !== '<p>No project README found.</p>') { %>
+<article>
+  <header>
+    <strong>Project Notes</strong>
+  </header>
+  <%- content %>
+</article>
+<% } %>

package/dashboard/src/views/partials/footer.ejs

@@ -0,0 +1,3 @@
+<footer>
+  <small>PBR Dashboard v0.1.0</small>
+</footer>

package/dashboard/src/views/partials/head.ejs

@@ -0,0 +1,21 @@
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title><%= typeof title !== 'undefined' ? title : 'Plan-Build-Run' %> - Plan-Build-Run</title>
+  <link rel="preconnect" href="https://cdn.jsdelivr.net" crossorigin>
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@picocss/pico@2/css/pico.min.css">
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/fontsource/fonts/inter@latest/latin-400-normal.min.css">
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/fontsource/fonts/inter@latest/latin-600-normal.min.css">
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/fontsource/fonts/inter@latest/latin-700-normal.min.css">
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/fontsource/fonts/jetbrains-mono@latest/latin-400-normal.min.css">
+  <link rel="stylesheet" href="/css/layout.css">
+  <link rel="stylesheet" href="/css/status-colors.css">
+  <script
+    src="https://cdn.jsdelivr.net/npm/htmx.org@2.0.8/dist/htmx.min.js"
+    integrity="sha384-/TgkGk7p307TH7EXJDuUlgG3Ce1UVolAOFopFekQkkXihi5u/6OCvVKyz1W+idaz"
+    crossorigin="anonymous">
+  </script>
+  <script src="https://cdn.jsdelivr.net/npm/htmx-ext-sse@2.2.2/sse.js"></script>
+  <script src="/js/htmx-title.js"></script>
+  <script src="/js/sidebar-toggle.js"></script>
+</head>

package/dashboard/src/views/partials/header.ejs

@@ -0,0 +1,12 @@
+<header>
+  <nav>
+    <ul>
+      <li><strong>PBR Dashboard</strong></li>
+    </ul>
+    <ul>
+      <li>
+        <button class="sidebar-toggle" aria-label="Toggle navigation">&#9776;</button>
+      </li>
+    </ul>
+  </nav>
+</header>

package/dashboard/src/views/partials/layout-bottom.ejs

@@ -0,0 +1,15 @@
+    </main>
+    <%- include('footer') %>
+  </div>
+  <div hx-ext="sse"
+       sse-connect="/api/events/stream"
+       sse-close="close">
+    <div hx-trigger="sse:file-change"
+         hx-get="<%= typeof currentPath !== 'undefined' ? currentPath : '/' %>"
+         hx-target="#main-content"
+         hx-swap="innerHTML"
+         style="display:none;">
+    </div>
+  </div>
+</body>
+</html>

package/dashboard/src/views/partials/layout-top.ejs

@@ -0,0 +1,8 @@
+<!DOCTYPE html>
+<html lang="en">
+<%- include('head', { title: typeof title !== 'undefined' ? title : 'PBR Dashboard' }) %>
+<body>
+  <div class="page-wrapper">
+    <%- include('header') %>
+    <%- include('sidebar', { activePage: typeof activePage !== 'undefined' ? activePage : '' }) %>
+    <main id="main-content">

package/dashboard/src/views/partials/phase-content.ejs

@@ -0,0 +1,181 @@
+<h1>Phase <%= phaseId %>: <%= phaseName %></h1>
+
+<p><a href="/">&larr; Back to Dashboard</a></p>
+
+<% if (verification) { %>
+<!-- Verification Summary Card -->
+<article>
+  <header>
+    <strong>Verification Status</strong>
+  </header>
+  <%
+    // Map verification status to CSS status-badge data-status values
+    var verificationCssStatus = 'not-started';
+    if (verification.status === 'passed') verificationCssStatus = 'complete';
+    else if (verification.status === 'failed') verificationCssStatus = 'blocked';
+    else if (verification.status === 'partial') verificationCssStatus = 'in-progress';
+  %>
+  <p>
+    <span class="status-badge" data-status="<%= verificationCssStatus %>">
+      <%= verification.status.toUpperCase() %>
+    </span>
+    <% if (verification.verified) { %>
+      &nbsp; Verified: <%= new Date(verification.verified).toLocaleString() %>
+    <% } %>
+  </p>
+  <% if (verification.score) { %>
+    <p>
+      Score: <%= verification.score.verified %>/<%= verification.score.total_must_haves %> must-haves verified
+    </p>
+    <% if (verification.score.failed > 0) { %>
+      <p><strong><%= verification.score.failed %> must-haves FAILED</strong></p>
+    <% } %>
+  <% } %>
+  <% if (verification.gaps && verification.gaps.length > 0) { %>
+    <details>
+      <summary>Verification Gaps (<%= verification.gaps.length %>)</summary>
+      <ul>
+        <% verification.gaps.forEach(function(gap) { %>
+          <li><%= gap %></li>
+        <% }); %>
+      </ul>
+    </details>
+  <% } %>
+</article>
+<% } %>
+
+<% if (plans.length === 0) { %>
+<!-- Empty State -->
+<article>
+  <p>No plans found for this phase. This phase may not have been planned yet.</p>
+</article>
+<% } else { %>
+
+<h2>Plans (<%= plans.length %>)</h2>
+
+<!-- Plan Cards -->
+<% plans.forEach(function(plan) { %>
+<article>
+  <header>
+    <strong>Plan <%= plan.planId %></strong>
+    <% if (plan.summary && plan.summary.status) { %>
+      &nbsp;
+      <span class="status-badge" data-status="<%= plan.summary.status %>">
+        <%= plan.summary.status.replace('-', ' ') %>
+      </span>
+    <% } %>
+  </header>
+
+  <% if (plan.summary) { %>
+
+    <% if (plan.summary.subsystem) { %>
+      <p><strong>Subsystem:</strong> <%= plan.summary.subsystem %></p>
+    <% } %>
+
+    <% if (plan.summary.key_decisions && plan.summary.key_decisions.length > 0) { %>
+      <details>
+        <summary>Key Decisions (<%= plan.summary.key_decisions.length %>)</summary>
+        <ul>
+          <% plan.summary.key_decisions.forEach(function(decision) { %>
+            <li><%= decision %></li>
+          <% }); %>
+        </ul>
+      </details>
+    <% } %>
+
+    <% if (plan.summary.key_files && plan.summary.key_files.length > 0) { %>
+      <details>
+        <summary>Key Files (<%= plan.summary.key_files.length %>)</summary>
+        <ul>
+          <% plan.summary.key_files.forEach(function(file) { %>
+            <li><code><%= file %></code></li>
+          <% }); %>
+        </ul>
+      </details>
+    <% } %>
+
+    <% if (plan.summary.deferred && plan.summary.deferred.length > 0) { %>
+      <details>
+        <summary>Deferred Items (<%= plan.summary.deferred.length %>)</summary>
+        <ul>
+          <% plan.summary.deferred.forEach(function(item) { %>
+            <li><%= item %></li>
+          <% }); %>
+        </ul>
+      </details>
+    <% } %>
+
+    <% if (plan.summary.metrics) { %>
+      <p>
+        <small>
+          <% if (plan.summary.metrics.duration_minutes != null) { %>
+            Duration: <%= plan.summary.metrics.duration_minutes %> min
+          <% } %>
+          <% if (plan.summary.metrics.commits != null) { %>
+            | Commits: <%= plan.summary.metrics.commits %>
+          <% } %>
+          <% if (plan.summary.metrics.files_created != null || plan.summary.metrics.files_modified != null) { %>
+            | Files: <%= plan.summary.metrics.files_created || 0 %> created, <%= plan.summary.metrics.files_modified || 0 %> modified
+          <% } %>
+        </small>
+      </p>
+    <% } %>
+
+  <% } else { %>
+    <!-- Plan exists but not executed yet -->
+    <p><em>Plan file exists but has not been executed yet. No summary available.</em></p>
+  <% } %>
+</article>
+<% }); %>
+
+<% } %>
+
+<!-- Commit History Section -->
+<%
+  // Collect all commits across all plans, tagged with their planId
+  var allCommits = [];
+  plans.forEach(function(plan) {
+    if (plan.commits && plan.commits.length > 0) {
+      plan.commits.forEach(function(commit) {
+        allCommits.push({ planId: plan.planId, commit: commit });
+      });
+    }
+  });
+%>
+
+<h2>Commit History (<%= allCommits.length %>)</h2>
+
+<% if (allCommits.length === 0) { %>
+<article>
+  <p><em>No commits yet for this phase.</em></p>
+</article>
+<% } else { %>
+<div class="table-wrap">
+<table>
+  <thead>
+    <tr>
+      <th>Commit</th>
+      <th>Task</th>
+      <th>Plan</th>
+      <th>Files</th>
+      <th>Status</th>
+    </tr>
+  </thead>
+  <tbody>
+    <% allCommits.forEach(function(entry) { %>
+    <tr>
+      <td><code><%= entry.commit.hash %></code></td>
+      <td><%= entry.commit.task %></td>
+      <td><%= entry.planId %></td>
+      <td><%= entry.commit.files %></td>
+      <td>
+        <span class="status-badge" data-status="<%= entry.commit.verify === 'passed' ? 'complete' : (entry.commit.verify === 'failed' ? 'blocked' : 'in-progress') %>">
+          <%= entry.commit.verify %>
+        </span>
+      </td>
+    </tr>
+    <% }); %>
+  </tbody>
+</table>
+</div>
+<% } %>

package/dashboard/src/views/partials/phases-content.ejs

@@ -0,0 +1,117 @@
+<h1>Phases</h1>
+
+<% if (phases.length === 0) { %>
+<article>
+  <p>No phases found. Add a ROADMAP.md file to your .planning/ directory to see phases here.</p>
+</article>
+<% } else { %>
+
+<%
+  // Build milestone-to-phases mapping
+  const milestoneGroups = milestones.map(m => ({
+    ...m,
+    phases: phases.filter(p => p.id >= m.startPhase && p.id <= m.endPhase)
+  })).filter(g => g.phases.length > 0);
+
+  // Collect any phases not covered by a milestone
+  const coveredIds = new Set(milestoneGroups.flatMap(g => g.phases.map(p => p.id)));
+  const ungrouped = phases.filter(p => !coveredIds.has(p.id));
+%>
+
+<!-- Summary -->
+<article>
+  <header><strong>Summary</strong></header>
+  <p>
+    <%= phases.filter(p => p.status === 'complete').length %> of <%= phases.length %> phases complete
+    across <%= milestoneGroups.length %> milestone<%= milestoneGroups.length !== 1 ? 's' : '' %>.
+  </p>
+  <progress value="<%= phases.filter(p => p.status === 'complete').length %>" max="<%= phases.length %>"></progress>
+</article>
+
+<% milestoneGroups.forEach(function(group) { %>
+<article>
+  <header>
+    <strong><%= group.name %></strong>
+    <small>(Phases <%= String(group.startPhase).padStart(2, '0') %>&ndash;<%= String(group.endPhase).padStart(2, '0') %>)</small>
+    &mdash;
+    <%
+      const groupComplete = group.phases.filter(p => p.status === 'complete').length;
+      const groupTotal = group.phases.length;
+    %>
+    <span class="status-badge" data-status="<%= groupComplete === groupTotal ? 'complete' : (groupComplete > 0 ? 'in-progress' : 'not-started') %>">
+      <%= groupComplete %>/<%= groupTotal %>
+    </span>
+  </header>
+  <% if (group.goal) { %>
+    <p><small><%= group.goal %></small></p>
+  <% } %>
+  <div class="table-wrap">
+  <table>
+    <thead>
+      <tr>
+        <th scope="col">Phase</th>
+        <th scope="col">Name</th>
+        <th scope="col">Plans</th>
+        <th scope="col">Status</th>
+      </tr>
+    </thead>
+    <tbody>
+      <% group.phases.forEach(function(phase) { %>
+      <tr>
+        <td><%= String(phase.id).padStart(2, '0') %></td>
+        <td>
+          <a href="/phases/<%= String(phase.id).padStart(2, '0') %>">
+            <%= phase.name %>
+          </a>
+        </td>
+        <td><%= phase.planCount %></td>
+        <td>
+          <span class="status-badge" data-status="<%= phase.status %>">
+            <%= phase.status.replace('-', ' ') %>
+          </span>
+        </td>
+      </tr>
+      <% }); %>
+    </tbody>
+  </table>
+  </div>
+</article>
+<% }); %>
+
+<% if (ungrouped.length > 0) { %>
+<article>
+  <header><strong>Other Phases</strong></header>
+  <div class="table-wrap">
+  <table>
+    <thead>
+      <tr>
+        <th scope="col">Phase</th>
+        <th scope="col">Name</th>
+        <th scope="col">Plans</th>
+        <th scope="col">Status</th>
+      </tr>
+    </thead>
+    <tbody>
+      <% ungrouped.forEach(function(phase) { %>
+      <tr>
+        <td><%= String(phase.id).padStart(2, '0') %></td>
+        <td>
+          <a href="/phases/<%= String(phase.id).padStart(2, '0') %>">
+            <%= phase.name %>
+          </a>
+        </td>
+        <td><%= phase.planCount %></td>
+        <td>
+          <span class="status-badge" data-status="<%= phase.status %>">
+            <%= phase.status.replace('-', ' ') %>
+          </span>
+        </td>
+      </tr>
+      <% }); %>
+    </tbody>
+  </table>
+  </div>
+</article>
+<% } %>
+
+<% } %>

package/dashboard/src/views/partials/roadmap-content.ejs

@@ -0,0 +1,142 @@
+<h1>Project Roadmap</h1>
+
+<% if (phases.length === 0) { %>
+<article>
+  <p>No phases found. Add a ROADMAP.md file to your .planning/ directory to see the roadmap here.</p>
+</article>
+<% } else { %>
+
+<%
+  // Group phases by milestone
+  const msGroups = (typeof milestones !== 'undefined' && milestones.length > 0)
+    ? milestones.map(m => ({
+        ...m,
+        phases: phases.filter(p => p.id >= m.startPhase && p.id <= m.endPhase)
+      })).filter(g => g.phases.length > 0)
+    : [{ name: 'All Phases', goal: '', startPhase: 1, endPhase: 9999, phases: phases }];
+
+  const coveredIds = new Set(msGroups.flatMap(g => g.phases.map(p => p.id)));
+  const ungroupedPhases = phases.filter(p => !coveredIds.has(p.id));
+%>
+
+<!-- Overall Progress -->
+<article>
+  <header><strong>Overall Progress</strong></header>
+  <%
+    const totalComplete = phases.filter(p => p.status === 'complete').length;
+    const totalPhases = phases.length;
+    const pct = totalPhases > 0 ? Math.round((totalComplete / totalPhases) * 100) : 0;
+  %>
+  <progress value="<%= totalComplete %>" max="<%= totalPhases %>"></progress>
+  <p><%= pct %>% complete (<%= totalComplete %> of <%= totalPhases %> phases)</p>
+</article>
+
+<% msGroups.forEach(function(group) { %>
+<article>
+  <header>
+    <strong><%= group.name %></strong>
+    <% if (group.startPhase && group.endPhase < 9999) { %>
+      <small>(Phases <%= String(group.startPhase).padStart(2, '0') %>&ndash;<%= String(group.endPhase).padStart(2, '0') %>)</small>
+    <% } %>
+    &mdash;
+    <%
+      const gc = group.phases.filter(p => p.status === 'complete').length;
+      const gt = group.phases.length;
+    %>
+    <span class="status-badge" data-status="<%= gc === gt ? 'complete' : (gc > 0 ? 'in-progress' : 'not-started') %>">
+      <%= gc %>/<%= gt %>
+    </span>
+  </header>
+  <% if (group.goal) { %>
+    <p><small><%= group.goal %></small></p>
+  <% } %>
+  <div class="table-wrap">
+  <table>
+    <thead>
+      <tr>
+        <th scope="col">Phase</th>
+        <th scope="col">Name</th>
+        <th scope="col">Plans</th>
+        <th scope="col">Status</th>
+        <th scope="col">Depends On</th>
+      </tr>
+    </thead>
+    <tbody>
+      <% group.phases.forEach(function(phase) { %>
+      <tr>
+        <td><%= String(phase.id).padStart(2, '0') %></td>
+        <td>
+          <a href="/phases/<%= String(phase.id).padStart(2, '0') %>">
+            <%= phase.name %>
+          </a>
+        </td>
+        <td><%= phase.planCount %></td>
+        <td>
+          <span class="status-badge" data-status="<%= phase.status %>">
+            <%= phase.status.replace('-', ' ') %>
+          </span>
+        </td>
+        <td>
+          <% if (phase.dependencies && phase.dependencies.length > 0) { %>
+            <% phase.dependencies.forEach(function(dep, idx) { %>
+              <a href="/phases/<%= String(dep).padStart(2, '0') %>"><%= String(dep).padStart(2, '0') %></a><% if (idx < phase.dependencies.length - 1) { %>, <% } %>
+            <% }); %>
+          <% } else { %>
+            <small>None</small>
+          <% } %>
+        </td>
+      </tr>
+      <% }); %>
+    </tbody>
+  </table>
+  </div>
+</article>
+<% }); %>
+
+<% if (ungroupedPhases.length > 0) { %>
+<article>
+  <header><strong>Other Phases</strong></header>
+  <div class="table-wrap">
+  <table>
+    <thead>
+      <tr>
+        <th scope="col">Phase</th>
+        <th scope="col">Name</th>
+        <th scope="col">Plans</th>
+        <th scope="col">Status</th>
+        <th scope="col">Depends On</th>
+      </tr>
+    </thead>
+    <tbody>
+      <% ungroupedPhases.forEach(function(phase) { %>
+      <tr>
+        <td><%= String(phase.id).padStart(2, '0') %></td>
+        <td>
+          <a href="/phases/<%= String(phase.id).padStart(2, '0') %>">
+            <%= phase.name %>
+          </a>
+        </td>
+        <td><%= phase.planCount %></td>
+        <td>
+          <span class="status-badge" data-status="<%= phase.status %>">
+            <%= phase.status.replace('-', ' ') %>
+          </span>
+        </td>
+        <td>
+          <% if (phase.dependencies && phase.dependencies.length > 0) { %>
+            <% phase.dependencies.forEach(function(dep, idx) { %>
+              <a href="/phases/<%= String(dep).padStart(2, '0') %>"><%= String(dep).padStart(2, '0') %></a><% if (idx < phase.dependencies.length - 1) { %>, <% } %>
+            <% }); %>
+          <% } else { %>
+            <small>None</small>
+          <% } %>
+        </td>
+      </tr>
+      <% }); %>
+    </tbody>
+  </table>
+  </div>
+</article>
+<% } %>
+
+<% } %>