@sienklogic/plan-build-run 2.0.0

package/dashboard/public/css/layout.css

@@ -0,0 +1,406 @@
+/* ============================================
+   Towline Dashboard — Layout & Typography
+   ============================================ */
+
+/* --- Custom Properties --- */
+:root {
+  --sidebar-width: 220px;
+  --header-height: 3.5rem;
+  --content-max-width: 960px;
+  --font-sans: 'Inter', system-ui, -apple-system, sans-serif;
+  --font-mono: 'JetBrains Mono', ui-monospace, 'Cascadia Code', 'Fira Code', monospace;
+  --space-xs: 0.25rem;
+  --space-sm: 0.5rem;
+  --space-md: 1rem;
+  --space-lg: 1.5rem;
+  --space-xl: 2rem;
+  --space-2xl: 3rem;
+  --radius-sm: 0.375rem;
+  --radius-md: 0.5rem;
+  --border-subtle: rgba(255, 255, 255, 0.08);
+  --bg-surface: rgba(255, 255, 255, 0.03);
+  --bg-surface-hover: rgba(255, 255, 255, 0.06);
+  --text-dim: rgba(255, 255, 255, 0.5);
+}
+
+/* --- Typography Override --- */
+html {
+  font-family: var(--font-sans);
+  font-size: 15px;
+  letter-spacing: -0.01em;
+}
+
+code, pre, kbd, samp {
+  font-family: var(--font-mono);
+  font-size: 0.875em;
+}
+
+h1 { font-size: 1.75rem; font-weight: 700; letter-spacing: -0.025em; margin-bottom: var(--space-sm); }
+h2 { font-size: 1.35rem; font-weight: 600; letter-spacing: -0.02em; margin-top: var(--space-2xl); margin-bottom: var(--space-md); }
+h3 { font-size: 1.1rem; font-weight: 600; }
+
+p { line-height: 1.65; }
+
+small { font-size: 0.8125rem; color: var(--text-dim); }
+
+/* --- Page Grid Layout --- */
+.page-wrapper {
+  display: grid;
+  gap: 0;
+  grid-template-columns: var(--sidebar-width) 1fr;
+  grid-template-rows: var(--header-height) 1fr auto;
+  grid-template-areas:
+    "header  header"
+    "sidebar content"
+    "footer  footer";
+  min-height: 100vh;
+}
+
+/* --- Header --- */
+.page-wrapper > header {
+  grid-area: header;
+  display: flex;
+  align-items: center;
+  padding: 0 var(--space-xl);
+  border-bottom: 1px solid var(--border-subtle);
+  background: var(--bg-surface);
+  backdrop-filter: blur(8px);
+  position: sticky;
+  top: 0;
+  z-index: 10;
+}
+
+.page-wrapper > header nav {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  width: 100%;
+  margin: 0;
+  padding: 0;
+}
+
+.page-wrapper > header nav strong {
+  font-size: 1rem;
+  font-weight: 600;
+  letter-spacing: -0.02em;
+  white-space: nowrap;
+}
+
+.page-wrapper > header nav ul {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+}
+
+/* --- Sidebar --- */
+.page-wrapper > aside.sidebar {
+  grid-area: sidebar;
+  padding: var(--space-lg) 0;
+  border-right: 1px solid var(--border-subtle);
+  background: var(--bg-surface);
+  position: sticky;
+  top: var(--header-height);
+  height: calc(100vh - var(--header-height));
+  overflow-y: auto;
+}
+
+aside.sidebar nav ul {
+  list-style: none;
+  padding: 0;
+  margin: 0;
+}
+
+aside.sidebar nav li {
+  margin: 0;
+  padding: 0;
+}
+
+aside.sidebar nav a {
+  display: flex;
+  align-items: center;
+  padding: 0.6rem var(--space-lg);
+  text-decoration: none;
+  border-left: 3px solid transparent;
+  font-size: 0.9rem;
+  font-weight: 500;
+  color: var(--text-dim);
+  transition: all 0.15s ease;
+}
+
+aside.sidebar nav a:hover {
+  color: var(--pico-color);
+  background: var(--bg-surface-hover);
+  border-left-color: rgba(255, 255, 255, 0.15);
+}
+
+aside.sidebar nav a[aria-current="page"] {
+  font-weight: 600;
+  color: var(--pico-primary);
+  border-left-color: var(--pico-primary);
+  background: var(--bg-surface-hover);
+}
+
+/* --- Main Content --- */
+.page-wrapper > main {
+  grid-area: content;
+  padding: var(--space-xl) var(--space-2xl);
+  overflow-y: auto;
+  max-width: calc(var(--content-max-width) + var(--space-2xl) * 2);
+}
+
+/* --- Footer --- */
+.page-wrapper > footer {
+  grid-area: footer;
+  padding: var(--space-md) var(--space-xl);
+  border-top: 1px solid var(--border-subtle);
+  text-align: center;
+}
+
+.page-wrapper > footer small {
+  font-size: 0.75rem;
+  color: var(--text-dim);
+}
+
+/* --- Article Cards --- */
+article {
+  border: 1px solid var(--border-subtle);
+  border-radius: var(--radius-md);
+  background: var(--bg-surface);
+  margin-bottom: var(--space-lg);
+}
+
+article > header {
+  border-bottom: 1px solid var(--border-subtle);
+  padding: var(--space-md) var(--space-lg);
+  background: rgba(255, 255, 255, 0.02);
+  border-radius: var(--radius-md) var(--radius-md) 0 0;
+}
+
+article > header strong {
+  font-size: 0.95rem;
+  font-weight: 600;
+}
+
+/* --- Tables --- */
+.table-wrap {
+  overflow-x: auto;
+  -webkit-overflow-scrolling: touch;
+  margin: 0 calc(-1 * var(--space-lg));
+  padding: 0 var(--space-lg);
+}
+
+table {
+  font-size: 0.875rem;
+  border-collapse: collapse;
+  width: 100%;
+}
+
+th {
+  font-weight: 600;
+  font-size: 0.8125rem;
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+  color: var(--text-dim);
+  white-space: nowrap;
+}
+
+td {
+  vertical-align: top;
+  line-height: 1.5;
+}
+
+/* --- Progress Bar --- */
+progress {
+  height: 0.5rem;
+  border-radius: 999px;
+}
+
+progress::-webkit-progress-bar {
+  background: rgba(255, 255, 255, 0.08);
+  border-radius: 999px;
+}
+
+progress::-webkit-progress-value {
+  background: var(--pico-primary);
+  border-radius: 999px;
+  transition: width 0.4s ease;
+}
+
+progress::-moz-progress-bar {
+  background: var(--pico-primary);
+  border-radius: 999px;
+}
+
+/* --- Details/Summary --- */
+details {
+  margin: var(--space-sm) 0;
+  border: none;
+}
+
+details summary {
+  font-size: 0.875rem;
+  font-weight: 500;
+  cursor: pointer;
+  padding: var(--space-xs) 0;
+  color: var(--pico-primary);
+}
+
+details summary:hover {
+  text-decoration: underline;
+}
+
+details ul {
+  margin-top: var(--space-xs);
+  padding-left: var(--space-lg);
+}
+
+details li {
+  font-size: 0.875rem;
+  line-height: 1.6;
+}
+
+/* --- Inline Code --- */
+:not(pre) > code {
+  font-size: 0.8125em;
+  padding: 0.15em 0.4em;
+  border-radius: var(--radius-sm);
+  background: rgba(255, 255, 255, 0.06);
+}
+
+/* --- Back Link --- */
+main > p:first-of-type > a[href="/"] {
+  font-size: 0.875rem;
+  color: var(--text-dim);
+  text-decoration: none;
+}
+
+main > p:first-of-type > a[href="/"]:hover {
+  color: var(--pico-primary);
+}
+
+/* --- SSE Connection Status --- */
+#sse-status {
+  display: inline-block;
+  width: 8px;
+  height: 8px;
+  border-radius: 50%;
+  margin-left: var(--space-sm);
+  vertical-align: middle;
+  transition: background-color 0.3s ease;
+}
+
+#sse-status[data-connected="true"] {
+  background-color: var(--status-complete);
+}
+
+#sse-status[data-connected="false"] {
+  background-color: var(--status-not-started);
+}
+
+/* --- Mobile hamburger toggle --- */
+.sidebar-toggle {
+  display: none;
+  background: none;
+  border: 1px solid var(--border-subtle);
+  border-radius: var(--radius-sm);
+  color: var(--pico-color);
+  font-size: 1.25rem;
+  padding: 0.25rem 0.5rem;
+  cursor: pointer;
+  line-height: 1;
+}
+
+/* ============================================
+   Responsive Breakpoints
+   ============================================ */
+
+/* Tablet: narrower sidebar */
+@media (max-width: 1024px) {
+  :root {
+    --sidebar-width: 180px;
+  }
+
+  .page-wrapper > main {
+    padding: var(--space-lg) var(--space-xl);
+  }
+}
+
+/* Mobile: sidebar collapses to top nav */
+@media (max-width: 768px) {
+  .page-wrapper {
+    grid-template-columns: 1fr;
+    grid-template-rows: var(--header-height) auto 1fr auto;
+    grid-template-areas:
+      "header"
+      "sidebar"
+      "content"
+      "footer";
+  }
+
+  .sidebar-toggle {
+    display: block;
+  }
+
+  .page-wrapper > aside.sidebar {
+    position: static;
+    height: auto;
+    border-right: none;
+    border-bottom: 1px solid var(--border-subtle);
+    padding: 0;
+    overflow: visible;
+    display: none;
+  }
+
+  .page-wrapper > aside.sidebar.open {
+    display: block;
+  }
+
+  aside.sidebar nav ul {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 0;
+    padding: var(--space-sm) var(--space-md);
+  }
+
+  aside.sidebar nav a {
+    border-left: none;
+    border-bottom: 2px solid transparent;
+    padding: var(--space-sm) var(--space-md);
+    font-size: 0.85rem;
+  }
+
+  aside.sidebar nav a[aria-current="page"] {
+    border-left: none;
+    border-bottom-color: var(--pico-primary);
+  }
+
+  aside.sidebar nav a:hover {
+    border-left: none;
+  }
+
+  .page-wrapper > main {
+    padding: var(--space-lg) var(--space-md);
+  }
+
+  h1 { font-size: 1.4rem; }
+  h2 { font-size: 1.15rem; }
+
+  table {
+    font-size: 0.8125rem;
+  }
+}
+
+/* Small mobile */
+@media (max-width: 480px) {
+  html {
+    font-size: 14px;
+  }
+
+  .page-wrapper > main {
+    padding: var(--space-md);
+  }
+
+  article > header {
+    padding: var(--space-sm) var(--space-md);
+  }
+}

package/dashboard/public/css/status-colors.css

@@ -0,0 +1,98 @@
+/* ============================================
+   Status Colors & Badges
+   ============================================ */
+
+:root {
+  --status-complete: #34d399;
+  --status-in-progress: #fbbf24;
+  --status-blocked: #f87171;
+  --status-not-started: #6b7280;
+}
+
+/* Text color by status */
+[data-status="complete"] { color: var(--status-complete); }
+[data-status="in-progress"] { color: var(--status-in-progress); }
+[data-status="blocked"],
+[data-status="failed"] { color: var(--status-blocked); }
+[data-status="not-started"],
+[data-status="pending"] { color: var(--status-not-started); }
+[data-status="passed"] { color: var(--status-complete); }
+[data-status="partial"] { color: var(--status-in-progress); }
+
+/* Status badge */
+.status-badge {
+  display: inline-flex;
+  align-items: center;
+  padding: 0.15rem 0.55rem;
+  border-radius: 999px;
+  font-size: 0.75rem;
+  font-weight: 600;
+  letter-spacing: 0.02em;
+  line-height: 1.5;
+  white-space: nowrap;
+  border: 1px solid transparent;
+}
+
+/* Dark-friendly badge colors — softer backgrounds with good contrast */
+.status-badge[data-status="complete"] {
+  background: rgba(52, 211, 153, 0.12);
+  color: #6ee7b7;
+  border-color: rgba(52, 211, 153, 0.2);
+}
+
+.status-badge[data-status="in-progress"] {
+  background: rgba(251, 191, 36, 0.12);
+  color: #fcd34d;
+  border-color: rgba(251, 191, 36, 0.2);
+}
+
+.status-badge[data-status="blocked"],
+.status-badge[data-status="failed"] {
+  background: rgba(248, 113, 113, 0.12);
+  color: #fca5a5;
+  border-color: rgba(248, 113, 113, 0.2);
+}
+
+.status-badge[data-status="not-started"],
+.status-badge[data-status="pending"] {
+  background: rgba(107, 114, 128, 0.12);
+  color: #9ca3af;
+  border-color: rgba(107, 114, 128, 0.2);
+}
+
+.status-badge[data-status="passed"] {
+  background: rgba(52, 211, 153, 0.12);
+  color: #6ee7b7;
+  border-color: rgba(52, 211, 153, 0.2);
+}
+
+.status-badge[data-status="partial"] {
+  background: rgba(251, 191, 36, 0.12);
+  color: #fcd34d;
+  border-color: rgba(251, 191, 36, 0.2);
+}
+
+/* Priority badge variants */
+.status-badge[data-priority="P0"] {
+  background: rgba(248, 113, 113, 0.12);
+  color: #fca5a5;
+  border-color: rgba(248, 113, 113, 0.2);
+}
+
+.status-badge[data-priority="P1"] {
+  background: rgba(251, 146, 60, 0.12);
+  color: #fdba74;
+  border-color: rgba(251, 146, 60, 0.2);
+}
+
+.status-badge[data-priority="P2"] {
+  background: rgba(251, 191, 36, 0.12);
+  color: #fcd34d;
+  border-color: rgba(251, 191, 36, 0.2);
+}
+
+.status-badge[data-priority="PX"] {
+  background: rgba(129, 140, 248, 0.12);
+  color: #a5b4fc;
+  border-color: rgba(129, 140, 248, 0.2);
+}

package/dashboard/public/js/htmx-title.js

@@ -0,0 +1,5 @@
+// Update document.title from HX-Title response header on HTMX navigation
+document.addEventListener('htmx:afterSettle', function(event) {
+  var title = event.detail.xhr && event.detail.xhr.getResponseHeader('HX-Title');
+  if (title) document.title = title;
+});

package/dashboard/public/js/sidebar-toggle.js

@@ -0,0 +1,20 @@
+// Mobile sidebar toggle
+document.addEventListener('DOMContentLoaded', function() {
+  var toggle = document.querySelector('.sidebar-toggle');
+  var sidebar = document.querySelector('.sidebar');
+  if (toggle && sidebar) {
+    toggle.addEventListener('click', function() {
+      sidebar.classList.toggle('open');
+    });
+  }
+
+  // Close sidebar when a nav link is clicked (mobile)
+  var navLinks = sidebar ? sidebar.querySelectorAll('a') : [];
+  navLinks.forEach(function(link) {
+    link.addEventListener('click', function() {
+      if (window.innerWidth <= 768) {
+        sidebar.classList.remove('open');
+      }
+    });
+  });
+});

package/dashboard/src/app.js

@@ -0,0 +1,78 @@
+import express from 'express';
+import helmet from 'helmet';
+import { join } from 'path';
+import { fileURLToPath } from 'url';
+import { dirname } from 'path';
+import indexRouter from './routes/index.routes.js';
+import pagesRouter from './routes/pages.routes.js';
+import eventsRouter from './routes/events.routes.js';
+import notFoundHandler from './middleware/notFoundHandler.js';
+import errorHandler from './middleware/errorHandler.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+export function createApp(config) {
+  const app = express();
+
+  // Security headers via Helmet
+  // CSP allows CDN scripts (HTMX, Pico.css, htmx-ext-sse) and inline styles
+  app.use(helmet({
+    contentSecurityPolicy: {
+      directives: {
+        defaultSrc: ["'self'"],
+        scriptSrc: ["'self'", "https://cdn.jsdelivr.net"],
+        styleSrc: ["'self'", "'unsafe-inline'", "https://cdn.jsdelivr.net"],
+        imgSrc: ["'self'", "data:"],
+        connectSrc: ["'self'"],
+        fontSrc: ["'self'", "https://cdn.jsdelivr.net"]
+      }
+    }
+  }));
+  app.disable('x-powered-by');
+
+  // Store config for access in routes/services
+  app.locals.projectDir = config.projectDir;
+
+  // View engine setup -- all paths use path.join (cross-platform)
+  app.set('views', join(__dirname, 'views'));
+  app.set('view engine', 'ejs');
+
+  // Built-in middleware
+  app.use(express.json());
+  app.use(express.urlencoded({ extended: false }));
+
+  // Handle common browser auto-requests cleanly (no stack traces in logs)
+  app.get('/favicon.ico', (req, res) => res.status(204).end());
+  app.get('/sw.js', (req, res) => res.status(404).end());
+
+  // Static files
+  app.use(express.static(join(__dirname, '..', 'public')));
+
+  // Auto-set HX-Title on HTMX partial responses so document.title stays current
+  app.use((req, res, next) => {
+    if (req.get('HX-Request') === 'true') {
+      const originalRender = res.render.bind(res);
+      res.render = function(view, options, callback) {
+        if (options && options.title && !res.getHeader('HX-Title')) {
+          res.setHeader('HX-Title', `${options.title} - Plan-Build-Run`);
+        }
+        return originalRender(view, options, callback);
+      };
+    }
+    next();
+  });
+
+  // Routes
+  app.use('/', indexRouter);
+  app.use('/', pagesRouter);
+  app.use('/api/events', eventsRouter);
+
+  // 404 catch-all (after routes, before error handler)
+  app.use(notFoundHandler);
+
+  // Error handler MUST be registered last
+  app.use(errorHandler);
+
+  return app;
+}

package/dashboard/src/middleware/errorHandler.js

@@ -0,0 +1,52 @@
+/**
+ * Express error-handling middleware.
+ * MUST have exactly 4 parameters for Express to recognize it as an error handler.
+ */
+
+// eslint-disable-next-line no-unused-vars
+export default function errorHandler(err, req, res, next) {
+  // If headers already sent, delegate to Express default handler
+  if (res.headersSent) {
+    return next(err);
+  }
+
+  const isDev = process.env.NODE_ENV !== 'production';
+  const status = err.status || err.statusCode || 500;
+
+  // Logging -- skip stack traces for 404s (they're expected, not bugs)
+  if (status === 404) {
+    console.warn(`404: ${req.originalUrl}`);
+  } else {
+    console.error('Unhandled error:', err.message);
+    if (isDev) {
+      console.error(err.stack);
+    }
+  }
+
+  // Detect HTMX requests
+  const isHtmx = req.get('HX-Request') === 'true';
+
+  // Set Vary header for proper caching
+  res.setHeader('Vary', 'HX-Request');
+
+  // Build template data
+  const templateData = {
+    title: `Error ${status}`,
+    status,
+    message: err.message || 'Internal Server Error',
+    stack: isDev ? err.stack : null,
+    activePage: ''
+  };
+
+  // Render response
+  if (isHtmx) {
+    let html = `<h1>Error ${status}</h1><p>${templateData.message}</p>`;
+    if (templateData.stack) {
+      html += `<pre><code>${templateData.stack}</code></pre>`;
+    }
+    html += '<p><a href="/">Return to Dashboard</a></p>';
+    return res.status(status).send(html);
+  }
+
+  res.status(status).render('error', templateData);
+}

package/dashboard/src/middleware/notFoundHandler.js

@@ -0,0 +1,9 @@
+/**
+ * 404 catch-all handler for routes that don't match any defined route.
+ * Must be registered AFTER all route handlers but BEFORE the error handler.
+ */
+export default function notFoundHandler(req, res, next) {
+  const err = new Error(`Page not found: ${req.originalUrl}`);
+  err.status = 404;
+  next(err);
+}