@sienklogic/plan-build-run 2.19.0 → 2.19.2

package/dashboard/bin/cli.cjs

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+'use strict';
+
+const path = require('path');
+const fs = require('fs');
+
+// --- Argument parsing ---
+
+const args = process.argv.slice(2);
+
+function getArg(name) {
+  const idx = args.indexOf(name);
+  if (idx === -1) return undefined;
+  return args[idx + 1];
+}
+
+function hasFlag(name) {
+  return args.includes(name);
+}
+
+if (hasFlag('--help') || hasFlag('-h')) {
+  console.log(`
+Usage: pbr-dashboard --dir <project-path> [options]
+
+Options:
+  --dir <path>   Project directory (required)
+  --port <num>   Port number (default: 3141, or set PBR_DASHBOARD_PORT env var)
+  --open         Auto-open browser after start
+  --stop         Stop a running dashboard on the given port
+  --help, -h     Show this help message
+`);
+  process.exit(0);
+}
+
+// --- Stop handler (before --dir requirement) ---
+
+if (hasFlag('--stop')) {
+  const portArg = getArg('--port');
+  const port = Number(portArg) || Number(process.env.PBR_DASHBOARD_PORT) || 3141;
+  const { stopDashboard } = require('./stop.cjs');
+  const stopped = stopDashboard(port);
+  process.exit(stopped ? 0 : 1);
+}
+
+// --- Resolve arguments ---
+
+const dir = getArg('--dir');
+if (!dir) {
+  console.error('PBR > Error: --dir <project-path> is required');
+  console.error('PBR > Run with --help for usage information');
+  process.exit(1);
+}
+
+const resolvedDir = path.resolve(dir);
+const planningDir = path.join(resolvedDir, '.planning');
+const portArg = getArg('--port');
+const port = Number(portArg) || Number(process.env.PBR_DASHBOARD_PORT) || 3141;
+const shouldOpen = hasFlag('--open');
+
+// --- Validate directory ---
+
+if (!fs.existsSync(resolvedDir)) {
+  console.error(`PBR > Error: Directory does not exist: ${resolvedDir}`);
+  process.exit(1);
+}
+
+if (!fs.existsSync(planningDir)) {
+  console.warn(`PBR > Warning: No .planning/ directory found in ${resolvedDir}`);
+  console.warn('PBR > Dashboard may show empty data');
+}
+
+// --- Start server ---
+
+const { startServer } = require('../server/index');
+
+startServer({ planningDir, port });
+
+console.log(`PBR > Dashboard running at http://localhost:${port}`);
+
+// --- Auto-open browser ---
+
+if (shouldOpen) {
+  setTimeout(() => {
+    const { exec } = require('child_process');
+    const platform = process.platform;
+    const url = `http://localhost:${port}`;
+
+    if (platform === 'win32') {
+      exec(`start ${url}`);
+    } else if (platform === 'darwin') {
+      exec(`open ${url}`);
+    } else {
+      exec(`xdg-open ${url}`);
+    }
+  }, 500);
+}

package/dashboard/bin/stop.cjs

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+'use strict';
+
+const http = require('http');
+const { execSync } = require('child_process');
+
+/**
+ * Stop a running PBR dashboard on the given port.
+ *
+ * 1. Confirms the dashboard is running via /api/health
+ * 2. Finds the PID listening on that port (platform-specific)
+ * 3. Kills the process (taskkill on Windows, SIGTERM on Unix)
+ *
+ * @param {number} port - The port the dashboard is running on
+ * @returns {boolean} true if stopped successfully, false otherwise
+ */
+function stopDashboard(port) {
+  // Step 1: Check if dashboard is actually running
+  if (!isDashboardRunning(port)) {
+    console.log(`No dashboard running on port ${port}`);
+    return false;
+  }
+
+  // Step 2: Find the PID
+  let pid;
+  try {
+    pid = findPid(port);
+  } catch (err) {
+    console.error(`Failed to find process on port ${port}: ${err.message}`);
+    return false;
+  }
+
+  if (!pid) {
+    console.error(`Could not determine PID for port ${port}`);
+    return false;
+  }
+
+  // Step 3: Kill the process
+  try {
+    killProcess(pid);
+    console.log(`Dashboard on port ${port} stopped (PID ${pid})`);
+    return true;
+  } catch (err) {
+    console.error(`Failed to stop dashboard (PID ${pid}): ${err.message}`);
+    return false;
+  }
+}
+
+/**
+ * Synchronously check if the dashboard is reachable on the given port.
+ * Spawns a short-lived node subprocess to make an HTTP request.
+ */
+function isDashboardRunning(port) {
+  try {
+    const script = [
+      "const h=require('http');",
+      `const r=h.get('http://localhost:${port}/api/health',{timeout:2000},res=>{`,
+      '  process.exit(res.statusCode===200?0:1)',
+      '});',
+      "r.on('error',()=>process.exit(1));",
+      "r.on('timeout',()=>{r.destroy();process.exit(1)})",
+    ].join('');
+    execSync(`node -e "${script}"`, { timeout: 5000, stdio: 'ignore' });
+    return true;
+  } catch (_e) {
+    return false;
+  }
+}
+
+/**
+ * Find the PID of the process listening on the given port.
+ * Platform-specific implementation.
+ */
+function findPid(port) {
+  if (process.platform === 'win32') {
+    return findPidWindows(port);
+  }
+  return findPidUnix(port);
+}
+
+/**
+ * Windows: use netstat -ano to find the PID.
+ */
+function findPidWindows(port) {
+  const output = execSync(
+    `netstat -ano | findstr "LISTENING" | findstr ":${port}"`,
+    { encoding: 'utf-8', timeout: 5000 }
+  ).trim();
+
+  // Each line looks like: TCP  0.0.0.0:3141  0.0.0.0:0  LISTENING  12345
+  const lines = output.split(/\r?\n/).filter(Boolean);
+  for (const line of lines) {
+    // Match the exact port (avoid matching :31410 when looking for :3141)
+    const portPattern = new RegExp(`:${port}\\s`);
+    if (portPattern.test(line)) {
+      const parts = line.trim().split(/\s+/);
+      const pid = parseInt(parts[parts.length - 1], 10);
+      if (pid && !isNaN(pid)) return pid;
+    }
+  }
+  return null;
+}
+
+/**
+ * Unix: use lsof to find the PID.
+ */
+function findPidUnix(port) {
+  const output = execSync(`lsof -ti :${port}`, {
+    encoding: 'utf-8',
+    timeout: 5000,
+  }).trim();
+
+  // lsof may return multiple PIDs (one per line), take the first
+  const pid = parseInt(output.split(/\r?\n/)[0], 10);
+  return isNaN(pid) ? null : pid;
+}
+
+/**
+ * Kill a process by PID. Platform-specific.
+ */
+function killProcess(pid) {
+  if (process.platform === 'win32') {
+    execSync(`taskkill /PID ${pid} /F`, { timeout: 5000, stdio: 'ignore' });
+  } else {
+    process.kill(pid, 'SIGTERM');
+  }
+}
+
+module.exports = { stopDashboard };

package/dashboard/eslint.config.js

@@ -0,0 +1,37 @@
+import js from '@eslint/js';
+import react from 'eslint-plugin-react';
+import reactHooks from 'eslint-plugin-react-hooks';
+import globals from 'globals';
+
+export default [
+  js.configs.recommended,
+  {
+    files: ['src/**/*.{js,jsx}'],
+    plugins: { react, 'react-hooks': reactHooks },
+    languageOptions: {
+      globals: { ...globals.browser },
+      parserOptions: { ecmaFeatures: { jsx: true } },
+    },
+    rules: {
+      ...react.configs.recommended.rules,
+      ...reactHooks.configs.recommended.rules,
+      'react/react-in-jsx-scope': 'off',
+      'react/prop-types': 'off',
+      'no-unused-vars': ['error', { argsIgnorePattern: '^_', caughtErrorsIgnorePattern: '^_' }],
+    },
+    settings: { react: { version: 'detect' } },
+  },
+  {
+    files: ['server/**/*.js'],
+    languageOptions: {
+      globals: { ...globals.node },
+      sourceType: 'commonjs',
+    },
+    rules: {
+      'no-unused-vars': ['error', { argsIgnorePattern: '^_', caughtErrorsIgnorePattern: '^_' }],
+    },
+  },
+  {
+    ignores: ['dist/', 'node_modules/'],
+  },
+];

package/dashboard/index.html

@@ -0,0 +1,20 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>PBR Dashboard</title>
+  <link rel="preconnect" href="https://fonts.googleapis.com" />
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+  <link href="https://fonts.googleapis.com/css2?family=DM+Sans:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;600&display=swap" rel="stylesheet" />
+  <style>
+    *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
+    body { overflow: hidden; }
+    @keyframes pulse { 0%, 100% { opacity: 1; } 50% { opacity: 0.5; } }
+  </style>
+</head>
+<body>
+  <div id="root"></div>
+  <script type="module" src="/src/main.jsx"></script>
+</body>
+</html>

package/dashboard/package.json

@@ -1,37 +1,39 @@
 {
-  "name": "plan-build-run-dashboard",
-  "version": "0.1.0",
-  "description": "Web dashboard for viewing Plan-Build-Run project planning state",
+  "name": "pbr-dashboard",
+  "private": true,
+  "version": "0.0.1",
   "type": "module",
   "bin": {
-    "pbr-dashboard": "./bin/cli.js"
+    "pbr-dashboard": "./bin/cli.cjs"
   },
   "scripts": {
-    "start": "node bin/cli.js",
-    "dev": "node --watch bin/cli.js",
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview",
+    "lint": "eslint src/ server/",
     "test": "vitest run",
-    "test:coverage": "vitest run --coverage"
+    "test:watch": "vitest"
   },
-  "keywords": [
-    "plan-build-run",
-    "dashboard",
-    "planning"
-  ],
-  "license": "MIT",
   "dependencies": {
-    "@rollup/rollup-win32-x64-msvc": "^4.57.1",
-    "chokidar": "^5.0.0",
-    "commander": "^12.1.0",
-    "ejs": "^3.1.10",
-    "express": "^5.1.0",
-    "gray-matter": "^4.0.3",
-    "helmet": "^8.1.0",
-    "marked": "^17.0.1"
+    "@rollup/rollup-win32-x64-msvc": "^4.59.0",
+    "lucide-react": "^0.577.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "recharts": "^3.8.0"
   },
   "devDependencies": {
-    "@vitest/coverage-v8": "^4.0.18",
-    "memfs": "^4.56.10",
-    "supertest": "^7.2.2",
-    "vitest": "^3.1.0"
+    "@eslint/js": "^9.39.4",
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
+    "@testing-library/user-event": "^14.6.1",
+    "@vitejs/plugin-react": "^5.1.4",
+    "eslint": "^9.39.4",
+    "eslint-plugin-react": "^7.37.5",
+    "eslint-plugin-react-hooks": "^7.0.1",
+    "globals": "^17.4.0",
+    "jsdom": "^28.1.0",
+    "vite": "^7.3.1",
+    "vitest": "^4.0.18"
   }
 }

package/dashboard/server/index.js

@@ -0,0 +1,151 @@
+'use strict';
+
+const express = require('express');
+const cors = require('cors');
+const path = require('path');
+const healthRouter = require('./routes/health');
+const progressRouter = require('./routes/progress');
+const { PlanningReader } = require('./services/planning-reader');
+const createStatusRouter = require('./routes/status');
+const createProjectsRouter = require('./routes/projects');
+const createPlanningRouter = require('./routes/planning');
+const createConfigRouter = require('./routes/config');
+const createTelemetryRouter = require('./routes/telemetry');
+const createAgentsRouter = require('./routes/agents');
+const createMemoryRouter = require('./routes/memory');
+const createRoadmapRouter = require('./routes/roadmap');
+const createRequirementsRouter = require('./routes/requirements');
+const createIntelRouter = require('./routes/intel');
+const createIncidentsRouter = require('./routes/incidents');
+const createSessionsRouter = require('./routes/sessions');
+const { setupStatic } = require('./middleware/static');
+const { setupWebSocket } = require('./ws');
+const { FileWatcher } = require('./services/file-watcher');
+
+/**
+ * Create an Express app with the given options.
+ * Pure factory — no side effects (does not listen).
+ *
+ * @param {object} [options]
+ * @param {string} [options.planningDir] - Path to .planning/ directory
+ * @param {string} [options.distDir]     - Path to built frontend assets
+ * @param {number} [options.port]        - Port to listen on
+ * @returns {{ app: Express, options: object }}
+ */
+function createApp(options = {}) {
+  const resolved = {
+    planningDir: options.planningDir || path.join(process.cwd(), '.planning'),
+    distDir: options.distDir || path.join(__dirname, '..', 'dist'),
+    port: options.port != null ? options.port : (Number(process.env.PBR_DASHBOARD_PORT) || (() => {
+      throw new Error('Port is required: pass via options.port or PBR_DASHBOARD_PORT env var');
+    })()),
+  };
+
+  const app = express();
+
+  // Core middleware
+  app.use(cors({
+    origin: (origin, callback) => {
+      // Allow requests with no origin (same-origin, curl, etc.) or localhost
+      if (!origin || /^https?:\/\/(localhost|127\.0\.0\.1)(:\d+)?$/.test(origin)) {
+        callback(null, true);
+      } else {
+        callback(new Error('Not allowed by CORS'));
+      }
+    }
+  }));
+  app.use(express.json());
+
+  // Store resolved options on app for downstream middleware
+  app.locals.options = resolved;
+
+  // Create shared services
+  const planningReader = new PlanningReader(resolved.planningDir);
+
+  // API routes — health first for fast health checks
+  app.use('/api/health', healthRouter);
+  app.use('/api/progress', progressRouter);
+  app.use('/api/status', createStatusRouter(planningReader));
+  app.use('/api/projects', createProjectsRouter(planningReader));
+  app.use('/api/planning', createPlanningRouter(planningReader));
+  app.use('/api/config', createConfigRouter(planningReader));
+  app.use('/api/telemetry', createTelemetryRouter({ planningDir: resolved.planningDir }));
+  const agentsRouter = createAgentsRouter({ planningDir: resolved.planningDir });
+  app.use('/api/agents', agentsRouter);
+  // Alias /api/hooks and /api/errors to agents sub-routes for HooksPage
+  app.use('/api/hooks', (req, res, next) => { req.url = '/hooks' + req.url; agentsRouter(req, res, next); });
+  app.use('/api/errors', (req, res, next) => { req.url = '/errors' + req.url; agentsRouter(req, res, next); });
+  app.use('/api/memory', createMemoryRouter({ planningDir: resolved.planningDir, planningReader }));
+  app.use('/api/roadmap', createRoadmapRouter(planningReader));
+  app.use('/api/requirements', createRequirementsRouter(planningReader));
+  app.use('/api/intel', createIntelRouter({ planningDir: resolved.planningDir }));
+  app.use('/api/incidents', createIncidentsRouter({ planningDir: resolved.planningDir }));
+  app.use('/api/sessions', createSessionsRouter({ planningDir: resolved.planningDir }));
+
+  // 404 handler for unmatched /api/* routes
+  app.all(/^\/api\//, (_req, res) => {
+    res.status(404).json({ error: 'Not found' });
+  });
+
+  // Static file serving and SPA fallback
+  setupStatic(app, resolved.distDir);
+
+  return { app, options: resolved };
+}
+
+/**
+ * Start the server, binding to the configured port.
+ *
+ * @param {object} [options] - Same options as createApp
+ * @returns {import('http').Server}
+ */
+function startServer(options = {}) {
+  const { app, options: resolved } = createApp(options);
+  const server = app.listen(resolved.port, () => {
+    console.log(`PBR Dashboard server listening on port ${resolved.port}`);
+  });
+
+  // File watcher for real-time updates
+  const fileWatcher = new FileWatcher(resolved.planningDir);
+
+  // Attach WebSocket server to HTTP server
+  const { wss } = setupWebSocket(server, fileWatcher);
+
+  // Start watching for file changes
+  fileWatcher.start().then(() => {
+    console.log(`File watcher started on ${resolved.planningDir}`);
+  }).catch((err) => {
+    console.error('Failed to start file watcher:', err.message);
+  });
+
+  // Graceful shutdown
+  const shutdown = () => {
+    console.log('Shutting down...');
+    fileWatcher.stop().catch(() => {});
+    wss.close();
+    server.close();
+  };
+
+  process.on('SIGTERM', shutdown);
+  process.on('SIGINT', shutdown);
+
+  return server;
+}
+
+// Direct execution
+if (require.main === module || process.argv[1] === __filename) {
+  // Parse --dir and --port from command line args
+  const args = process.argv.slice(2);
+  const dirIdx = args.indexOf('--dir');
+  const portIdx = args.indexOf('--port');
+  const opts = {};
+  if (dirIdx !== -1 && args[dirIdx + 1]) {
+    opts.planningDir = path.join(path.resolve(args[dirIdx + 1]), '.planning');
+  }
+  if (portIdx !== -1 && args[portIdx + 1]) {
+    opts.port = Number(args[portIdx + 1]);
+  }
+  startServer(opts);
+}
+
+module.exports = { createApp, startServer };

package/dashboard/server/lib/frontmatter.js

@@ -0,0 +1,92 @@
+'use strict';
+
+/**
+ * Parse YAML-like frontmatter from a markdown string.
+ * Splits on `---` delimiters and extracts key: value pairs.
+ * Handles quoted strings, numbers, booleans, inline arrays,
+ * and one level of nested YAML indentation (2-space indent).
+ *
+ * @param {string} content - Raw file content
+ * @returns {{ frontmatter: object, body: string }}
+ */
+function parseFrontmatter(content) {
+  const normalized = content.replace(/\r\n/g, '\n');
+  const match = normalized.match(/^---\n([\s\S]*?)\n---/);
+  if (!match) return { frontmatter: {}, body: normalized };
+
+  const raw = match[1];
+  const body = normalized.slice(match[0].length).trim();
+  const frontmatter = {};
+  const lines = raw.split('\n');
+
+  let currentParent = null;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+
+    // Check for nested key (2-space indented under a parent)
+    if (currentParent && /^ {2}\w/.test(line)) {
+      const kv = line.match(/^\s+(\w[\w_-]*)\s*:\s*(.+)$/);
+      if (kv) {
+        if (typeof frontmatter[currentParent] !== 'object' || frontmatter[currentParent] === null) {
+          frontmatter[currentParent] = {};
+        }
+        frontmatter[currentParent][kv[1]] = parseValue(kv[2].trim());
+      }
+      continue;
+    }
+
+    // Top-level key
+    currentParent = null;
+    const kv = line.match(/^(\w[\w_-]*)\s*:\s*(.+)$/);
+    if (kv) {
+      frontmatter[kv[1]] = parseValue(kv[2].trim());
+      continue;
+    }
+
+    // Parent key with no inline value (e.g., "progress:")
+    const parentMatch = line.match(/^(\w[\w_-]*)\s*:\s*$/);
+    if (parentMatch) {
+      currentParent = parentMatch[1];
+      // Initialize as empty object; will be populated by nested lines
+      frontmatter[currentParent] = {};
+      continue;
+    }
+  }
+
+  return { frontmatter, body };
+}
+
+/**
+ * Parse a single YAML value string into its JS equivalent.
+ * @param {string} val - Raw value string
+ * @returns {string|number|boolean|string[]}
+ */
+function parseValue(val) {
+  // Strip surrounding quotes
+  if ((val.startsWith('"') && val.endsWith('"')) ||
+      (val.startsWith("'") && val.endsWith("'"))) {
+    return val.slice(1, -1);
+  }
+  // Inline array: [a, b, c]
+  if (val.startsWith('[') && val.endsWith(']')) {
+    return val.slice(1, -1).split(',').map(s => {
+      s = s.trim();
+      if ((s.startsWith('"') && s.endsWith('"')) ||
+          (s.startsWith("'") && s.endsWith("'"))) {
+        s = s.slice(1, -1);
+      }
+      return s;
+    }).filter(s => s.length > 0);
+  }
+  // Boolean
+  if (val === 'true') return true;
+  if (val === 'false') return false;
+  // Number
+  if (/^\d+$/.test(val)) return parseInt(val, 10);
+  if (/^\d+\.\d+$/.test(val)) return parseFloat(val);
+
+  return val;
+}
+
+module.exports = { parseFrontmatter };

package/dashboard/server/middleware/static.js

@@ -0,0 +1,35 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const express = require('express');
+
+/**
+ * Set up static file serving and SPA fallback.
+ *
+ * If distDir does not exist, static serving is skipped entirely
+ * (server still works for API routes without a frontend build).
+ *
+ * @param {import('express').Express} app
+ * @param {string} distDir - Path to built frontend assets
+ */
+function setupStatic(app, distDir) {
+  if (!fs.existsSync(distDir)) {
+    return;
+  }
+
+  // Serve static files from distDir
+  app.use(express.static(distDir));
+
+  // SPA fallback: serve index.html for GET requests not matching /api/*
+  app.get(/^\/(?!api\/).*/, (req, res) => {
+    const indexPath = path.join(distDir, 'index.html');
+    if (fs.existsSync(indexPath)) {
+      res.sendFile(indexPath);
+    } else {
+      res.status(404).json({ error: 'Not found' });
+    }
+  });
+}
+
+module.exports = { setupStatic };

package/dashboard/server/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "pbr-dashboard-server",
+  "version": "1.0.0",
+  "description": "Express server for PBR Dashboard v4",
+  "main": "index.js",
+  "scripts": {
+    "start": "node index.js",
+    "dev": "node --watch index.js"
+  },
+  "dependencies": {
+    "express": "^5.1.0",
+    "cors": "^2.8.5",
+    "ws": "^8.18.0",
+    "chokidar": "^4.0.0"
+  }
+}