@sienklogic/plan-build-run 2.19.0 → 2.19.1

package/dashboard/server/test/cli.test.js

@@ -0,0 +1,34 @@
+/**
+ * cli.test.js -- CLI integration tests for dashboard.
+ *
+ * Verifies that the standalone CLI launcher exists and is valid,
+ * pbr-tools.js has the dashboard case, and server exports are correct.
+ */
+
+'use strict';
+
+const { describe, it } = require('node:test');
+const assert = require('node:assert/strict');
+const path = require('path');
+const fs = require('fs');
+
+const ROOT_DIR = path.resolve(__dirname, '..', '..', '..');
+
+describe('CLI Integration', () => {
+  it('dashboard/bin/cli.cjs exists and is parseable', () => {
+    const cliPath = path.join(ROOT_DIR, 'dashboard', 'bin', 'cli.cjs');
+    assert.ok(fs.existsSync(cliPath), 'cli.cjs should exist');
+    // Verify it parses without syntax errors (don't execute it)
+    const content = fs.readFileSync(cliPath, 'utf-8');
+    assert.ok(content.includes('startServer'), 'cli.cjs should reference startServer');
+    assert.ok(content.includes("require('../server/index')"), 'cli.cjs should require server/index');
+  });
+
+  it.todo('pbr-tools.js contains dashboard case (not yet implemented)');
+
+  it('dashboard/server/index.js exports createApp and startServer', () => {
+    const serverIndex = require('../index');
+    assert.ok(typeof serverIndex.createApp === 'function', 'createApp should be a function');
+    assert.ok(typeof serverIndex.startServer === 'function', 'startServer should be a function');
+  });
+});

package/dashboard/server/test/frontmatter.test.js

@@ -0,0 +1,104 @@
+/**
+ * frontmatter.test.js -- Unit tests for the shared dashboard frontmatter parser.
+ *
+ * Validates CRLF safety, nested YAML, arrays, and edge cases.
+ * The dashboard frontmatter parser is a critical cross-platform surface
+ * since it processes files that may have been created on Windows (CRLF)
+ * or Linux (LF).
+ */
+
+'use strict';
+
+const { describe, it } = require('node:test');
+const assert = require('node:assert/strict');
+const { parseFrontmatter } = require('../lib/frontmatter');
+
+describe('parseFrontmatter', () => {
+  it('extracts key-value pairs from YAML between --- delimiters (LF)', () => {
+    const content = "---\nkey: value\ntitle: Hello World\n---\nbody text";
+    const { frontmatter, body } = parseFrontmatter(content);
+    assert.equal(frontmatter.key, 'value');
+    assert.equal(frontmatter.title, 'Hello World');
+    assert.equal(body, 'body text');
+  });
+
+  it('produces identical output for LF and CRLF input', () => {
+    const lfContent = "---\nkey: value\ncount: 5\n---\nbody text here";
+    const crlfContent = "---\r\nkey: value\r\ncount: 5\r\n---\r\nbody text here";
+
+    const lfResult = parseFrontmatter(lfContent);
+    const crlfResult = parseFrontmatter(crlfContent);
+
+    assert.deepEqual(lfResult.frontmatter, crlfResult.frontmatter,
+      'frontmatter should be identical for LF and CRLF');
+    assert.equal(lfResult.body, crlfResult.body,
+      'body should be identical for LF and CRLF');
+  });
+
+  it('handles nested YAML (2-space indent) returning nested objects', () => {
+    const content = "---\nprogress:\n  total: 5\n  done: 3\n---\n";
+    const { frontmatter } = parseFrontmatter(content);
+    assert.equal(typeof frontmatter.progress, 'object');
+    assert.equal(frontmatter.progress.total, 5);
+    assert.equal(frontmatter.progress.done, 3);
+  });
+
+  it('handles nested YAML with CRLF line endings', () => {
+    const content = "---\r\nprogress:\r\n  total: 5\r\n  done: 3\r\n---\r\nbody";
+    const { frontmatter } = parseFrontmatter(content);
+    assert.equal(typeof frontmatter.progress, 'object');
+    assert.equal(frontmatter.progress.total, 5);
+    assert.equal(frontmatter.progress.done, 3);
+  });
+
+  it('returns empty object for content with no frontmatter', () => {
+    const content = "just body text\nno frontmatter here";
+    const { frontmatter, body } = parseFrontmatter(content);
+    assert.deepEqual(frontmatter, {});
+    assert.ok(body.includes('just body text'));
+  });
+
+  it('handles arrays in frontmatter (inline bracket syntax)', () => {
+    const content = "---\ndepends_on: [plan-01, plan-02]\n---\n";
+    const { frontmatter } = parseFrontmatter(content);
+    assert.ok(Array.isArray(frontmatter.depends_on), 'depends_on should be an array');
+    assert.equal(frontmatter.depends_on.length, 2);
+    assert.equal(frontmatter.depends_on[0], 'plan-01');
+    assert.equal(frontmatter.depends_on[1], 'plan-02');
+  });
+
+  it('handles empty array', () => {
+    const content = "---\ndepends_on: []\n---\n";
+    const { frontmatter } = parseFrontmatter(content);
+    assert.ok(Array.isArray(frontmatter.depends_on));
+    assert.equal(frontmatter.depends_on.length, 0);
+  });
+
+  it('handles boolean values', () => {
+    const content = "---\nautonomous: true\nskip: false\n---\n";
+    const { frontmatter } = parseFrontmatter(content);
+    assert.equal(frontmatter.autonomous, true);
+    assert.equal(frontmatter.skip, false);
+  });
+
+  it('handles numeric values', () => {
+    const content = "---\nplan: 3\nprogress_percent: 67\n---\n";
+    const { frontmatter } = parseFrontmatter(content);
+    assert.equal(frontmatter.plan, 3);
+    assert.equal(frontmatter.progress_percent, 67);
+  });
+
+  it('handles quoted string values', () => {
+    const content = "---\nstatus: \"complete\"\ntitle: 'Hello'\n---\n";
+    const { frontmatter } = parseFrontmatter(content);
+    assert.equal(frontmatter.status, 'complete');
+    assert.equal(frontmatter.title, 'Hello');
+  });
+
+  it('handles empty body after frontmatter', () => {
+    const content = "---\nkey: value\n---\n";
+    const { frontmatter, body } = parseFrontmatter(content);
+    assert.equal(frontmatter.key, 'value');
+    assert.equal(body, '');
+  });
+});

package/dashboard/server/test/isolation.test.js

@@ -0,0 +1,32 @@
+/**
+ * isolation.test.js -- Verifies dashboard dependency isolation.
+ *
+ * Ensures root package.json has no production dependencies (empty object)
+ * and dashboard/server/package.json contains required packages.
+ */
+
+'use strict';
+
+const { describe, it } = require('node:test');
+const assert = require('node:assert/strict');
+const path = require('path');
+const fs = require('fs');
+
+const ROOT_DIR = path.resolve(__dirname, '..', '..', '..');
+
+describe('Dependency Isolation', () => {
+  it('root package.json has empty dependencies', () => {
+    const rootPkg = JSON.parse(fs.readFileSync(path.join(ROOT_DIR, 'package.json'), 'utf-8'));
+    const deps = rootPkg.dependencies || {};
+    assert.deepEqual(deps, {}, 'root dependencies should be empty');
+  });
+
+  it('dashboard/server/package.json contains express, ws, chokidar, cors', () => {
+    const serverPkg = JSON.parse(fs.readFileSync(path.join(ROOT_DIR, 'dashboard', 'server', 'package.json'), 'utf-8'));
+    const deps = serverPkg.dependencies || {};
+    assert.ok(deps.express, 'should have express');
+    assert.ok(deps.ws, 'should have ws');
+    assert.ok(deps.chokidar, 'should have chokidar');
+    assert.ok(deps.cors, 'should have cors');
+  });
+});

package/dashboard/server/test/planning-reader.test.js

@@ -0,0 +1,151 @@
+/**
+ * planning-reader.test.js -- Unit tests for the dashboard planning-reader service.
+ *
+ * Validates cross-platform path construction (path.join usage),
+ * structured return values, and graceful handling of missing files.
+ */
+
+'use strict';
+
+const { describe, it, before } = require('node:test');
+const assert = require('node:assert/strict');
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+
+const { PlanningReader } = require('../services/planning-reader');
+
+// Use PBR fixture files as test data source
+const FIXTURES_DIR = path.resolve(__dirname, '../../../plugins/pbr/scripts/test/fixtures');
+
+describe('PlanningReader', () => {
+  describe('with missing directory', () => {
+    it('getStatus returns error for nonexistent planning dir', async () => {
+      const reader = new PlanningReader('/nonexistent/path/.planning');
+      const result = await reader.getStatus();
+      assert.ok(result.error, 'should return error for missing STATE.md');
+    });
+
+    it('getPhases returns empty array for nonexistent phases dir', async () => {
+      const reader = new PlanningReader('/nonexistent/path/.planning');
+      const result = await reader.getPhases();
+      assert.ok(Array.isArray(result), 'should return array');
+      assert.equal(result.length, 0, 'should be empty');
+    });
+
+    it('getTodos returns empty arrays for nonexistent todos dir', async () => {
+      const reader = new PlanningReader('/nonexistent/path/.planning');
+      const result = await reader.getTodos();
+      assert.ok(Array.isArray(result), 'should return array');
+      assert.equal(result.length, 0, 'should be empty');
+    });
+
+    it('getConfig returns empty object for missing config', async () => {
+      const reader = new PlanningReader('/nonexistent/path/.planning');
+      const result = await reader.getConfig();
+      assert.deepEqual(result, {}, 'should return empty object');
+    });
+
+    it('getMilestones returns empty array for missing roadmap', async () => {
+      const reader = new PlanningReader('/nonexistent/path/.planning');
+      const result = await reader.getMilestones();
+      assert.ok(Array.isArray(result), 'should return array');
+      assert.equal(result.length, 0, 'should be empty');
+    });
+  });
+
+  describe('with fixture-based temp directory', () => {
+    let tmpDir;
+    let reader;
+
+    before(() => {
+      // Create a minimal .planning structure using fixture files
+      tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pbr-test-'));
+      const planningDir = tmpDir; // tmpDir IS the planning dir
+
+      // Copy STATE.md fixture
+      fs.copyFileSync(
+        path.join(FIXTURES_DIR, 'state.md'),
+        path.join(planningDir, 'STATE.md')
+      );
+
+      // Copy config.json fixture
+      fs.copyFileSync(
+        path.join(FIXTURES_DIR, 'config.json'),
+        path.join(planningDir, 'config.json')
+      );
+
+      // Copy roadmap.md as ROADMAP.md
+      fs.copyFileSync(
+        path.join(FIXTURES_DIR, 'roadmap.md'),
+        path.join(planningDir, 'ROADMAP.md')
+      );
+
+      // Create a minimal phases directory
+      const phasesDir = path.join(planningDir, 'phases');
+      fs.mkdirSync(phasesDir, { recursive: true });
+      const phase01Dir = path.join(phasesDir, '01-foundation');
+      fs.mkdirSync(phase01Dir, { recursive: true });
+      fs.copyFileSync(
+        path.join(FIXTURES_DIR, 'plan.md'),
+        path.join(phase01Dir, 'PLAN-01.md')
+      );
+      fs.copyFileSync(
+        path.join(FIXTURES_DIR, 'summary.md'),
+        path.join(phase01Dir, 'SUMMARY-01.md')
+      );
+
+      reader = new PlanningReader(planningDir);
+    });
+
+    it('getStatus returns structured state object', async () => {
+      const result = await reader.getStatus();
+      assert.ok(!result.error, 'should not have error');
+      assert.ok(result.gsd_state_version, 'should have gsd_state_version');
+      assert.ok(result.status, 'should have status');
+      assert.ok(result.milestone, 'should have milestone');
+    });
+
+    it('getConfig returns parsed config', async () => {
+      const result = await reader.getConfig();
+      assert.equal(result.mode, 'interactive');
+      assert.equal(result.depth, 'standard');
+      assert.equal(typeof result.git, 'object');
+    });
+
+    it('getPhases returns phase list from disk', async () => {
+      const result = await reader.getPhases();
+      assert.ok(Array.isArray(result));
+      assert.ok(result.length > 0, 'should find at least one phase');
+      const phase1 = result.find(p => p.slug === '01-foundation');
+      assert.ok(phase1, 'should find 01-foundation phase');
+      assert.ok(phase1.taskList.length > 0, 'should have tasks');
+    });
+
+    it('getMilestones parses roadmap milestones', async () => {
+      const result = await reader.getMilestones();
+      assert.ok(Array.isArray(result));
+      assert.ok(result.length > 0, 'should find at least one milestone');
+      assert.equal(result[0].name, 'v1.0');
+    });
+  });
+
+  describe('path construction safety', () => {
+    it('uses path.join in constructor and methods (source audit)', () => {
+      // Read the source file and verify path.join usage, no string concatenation for paths
+      const source = fs.readFileSync(
+        path.resolve(__dirname, '../services/planning-reader.js'),
+        'utf-8'
+      );
+
+      // Count path.join calls
+      const joinCount = (source.match(/path\.join\(/g) || []).length;
+      assert.ok(joinCount >= 5, `should use path.join frequently (found ${joinCount} uses)`);
+
+      // Check for dangerous string concatenation patterns with path separators
+      const dangerousConcat = source.match(/['"`]\s*\+\s*['"`]\/|['"`]\/['"`]\s*\+/g);
+      assert.equal(dangerousConcat, null,
+        'should not use string concatenation with path separators');
+    });
+  });
+});

package/dashboard/server/test/routes.test.js

@@ -0,0 +1,91 @@
+/**
+ * routes.test.js -- API endpoint tests for the dashboard server.
+ *
+ * Validates health, status, requirements, roadmap, config endpoints,
+ * and 404 handling for unmatched /api/* routes.
+ */
+
+'use strict';
+
+const { describe, it, before, after } = require('node:test');
+const assert = require('node:assert/strict');
+const path = require('path');
+const http = require('http');
+
+const { createApp } = require('../index');
+
+// Point planningDir at the real .planning/ directory for integration tests
+const PLANNING_DIR = path.resolve(__dirname, '..', '..', '..', '.planning');
+
+function get(port, urlPath) {
+  return new Promise((resolve, reject) => {
+    const req = http.get(`http://127.0.0.1:${port}${urlPath}`, (res) => {
+      let data = '';
+      res.on('data', (chunk) => { data += chunk; });
+      res.on('end', () => {
+        try {
+          resolve({ status: res.statusCode, body: JSON.parse(data) });
+        } catch (_e) {
+          resolve({ status: res.statusCode, body: data });
+        }
+      });
+    });
+    req.on('error', reject);
+  });
+}
+
+describe('Dashboard API Routes', () => {
+  let server;
+  let port;
+
+  before(async () => {
+    const { app } = createApp({ planningDir: PLANNING_DIR, port: 0 });
+    server = app.listen(0);
+    await new Promise((resolve) => server.on('listening', resolve));
+    port = server.address().port;
+  });
+
+  after(async () => {
+    if (server) {
+      await new Promise((resolve) => server.close(resolve));
+    }
+  });
+
+  it('GET /api/health returns 200 with status ok', async () => {
+    const { status, body } = await get(port, '/api/health');
+    assert.equal(status, 200);
+    assert.equal(body.status, 'ok');
+    assert.ok(typeof body.uptime === 'number', 'uptime should be a number');
+    assert.ok(body.version, 'version should be present');
+  });
+
+  it('GET /api/status returns 200 with object', async () => {
+    const { status, body } = await get(port, '/api/status');
+    assert.equal(status, 200);
+    assert.ok(typeof body === 'object', 'body should be an object');
+  });
+
+  it('GET /api/requirements returns 200 with requirements array', async () => {
+    const { status, body } = await get(port, '/api/requirements');
+    assert.equal(status, 200);
+    assert.ok(Array.isArray(body.requirements), 'requirements should be an array');
+  });
+
+  it('GET /api/roadmap returns 200 with phases array', async () => {
+    const { status, body } = await get(port, '/api/roadmap');
+    assert.equal(status, 200);
+    assert.ok(Array.isArray(body.phases), 'phases should be an array');
+  });
+
+  it('GET /api/config returns 200 with object', async () => {
+    const { status, body } = await get(port, '/api/config');
+    assert.equal(status, 200);
+    assert.ok(typeof body === 'object', 'config should be an object');
+  });
+
+  it('GET /api/nonexistent returns 404', async () => {
+    const { status, body } = await get(port, '/api/nonexistent');
+    assert.equal(status, 404);
+    assert.ok(body.error, 'should have error message');
+  });
+});

package/dashboard/server/test/ws.test.js

@@ -0,0 +1,81 @@
+/**
+ * ws.test.js -- WebSocket tests for the dashboard server.
+ *
+ * Validates WebSocket connection, welcome message format,
+ * and broadcast functionality.
+ */
+
+'use strict';
+
+const { describe, it, before, after } = require('node:test');
+const assert = require('node:assert/strict');
+const http = require('http');
+const WebSocket = require('ws');
+
+const { setupWebSocket, broadcast } = require('../ws');
+
+describe('WebSocket', () => {
+  let server;
+  let wss;
+  let port;
+
+  before(async () => {
+    server = http.createServer();
+    // Pass null fileWatcher -- we test broadcast separately
+    const result = setupWebSocket(server, null);
+    wss = result.wss;
+    server.listen(0);
+    await new Promise((resolve) => server.on('listening', resolve));
+    port = server.address().port;
+  });
+
+  after(async () => {
+    // Close all client connections
+    for (const client of wss.clients) {
+      client.terminate();
+    }
+    wss.close();
+    await new Promise((resolve) => server.close(resolve));
+  });
+
+  it('receives welcome message with type connection on connect', async () => {
+    const ws = new WebSocket(`ws://127.0.0.1:${port}/ws`);
+    const msg = await new Promise((resolve, reject) => {
+      ws.on('message', (data) => resolve(JSON.parse(data.toString())));
+      ws.on('error', reject);
+      setTimeout(() => reject(new Error('timeout')), 5000);
+    });
+    assert.equal(msg.type, 'connection');
+    assert.equal(msg.source, 'server');
+    assert.ok(msg.ts, 'should have timestamp');
+    ws.close();
+  });
+
+  it('broadcast sends to all open clients', async () => {
+    // Connect two clients
+    const ws1 = new WebSocket(`ws://127.0.0.1:${port}/ws`);
+    const ws2 = new WebSocket(`ws://127.0.0.1:${port}/ws`);
+
+    // Wait for both to be open and receive welcome
+    await Promise.all([
+      new Promise((resolve) => ws1.on('message', resolve)),
+      new Promise((resolve) => ws2.on('message', resolve)),
+    ]);
+
+    // Set up message listeners for broadcast
+    const received1 = new Promise((resolve) => ws1.on('message', (data) => resolve(JSON.parse(data.toString()))));
+    const received2 = new Promise((resolve) => ws2.on('message', (data) => resolve(JSON.parse(data.toString()))));
+
+    // Broadcast a test event
+    broadcast(wss, { type: 'test', msg: 'hello' });
+
+    const [msg1, msg2] = await Promise.all([received1, received2]);
+    assert.equal(msg1.type, 'test');
+    assert.equal(msg1.msg, 'hello');
+    assert.equal(msg2.type, 'test');
+    assert.equal(msg2.msg, 'hello');
+
+    ws1.close();
+    ws2.close();
+  });
+});

package/dashboard/server/ws.js

@@ -0,0 +1,96 @@
+'use strict';
+
+const { WebSocketServer, WebSocket } = require('ws');
+
+/**
+ * Broadcast a LiveEvent to all connected WebSocket clients.
+ *
+ * @param {WebSocketServer} wss - The WebSocket server instance
+ * @param {object} event - LiveEvent-shaped object to broadcast
+ */
+function broadcast(wss, event) {
+  const data = JSON.stringify(event);
+  for (const client of wss.clients) {
+    if (client.readyState === WebSocket.OPEN) {
+      try {
+        client.send(data);
+      } catch (_err) {
+        // Per-client send errors are non-fatal
+      }
+    }
+  }
+}
+
+/**
+ * Attach a WebSocket server to an HTTP server and wire it to a FileWatcher.
+ *
+ * - Clients connect at /ws
+ * - On connect, clients receive a welcome message
+ * - File change events from the watcher are broadcast to all clients
+ * - Heartbeat ping/pong runs every 30s to detect stale connections
+ *
+ * @param {import('http').Server} server - HTTP server to attach to
+ * @param {import('./services/file-watcher').FileWatcher} fileWatcher - FileWatcher instance
+ * @returns {{ wss: WebSocketServer }}
+ */
+function setupWebSocket(server, fileWatcher) {
+  const wss = new WebSocketServer({ server, path: '/ws' });
+
+  // Track alive status for heartbeat
+  const aliveMap = new WeakMap();
+
+  wss.on('connection', (ws) => {
+    aliveMap.set(ws, true);
+    console.log(`WebSocket client connected (${wss.clients.size} total)`);
+
+    // Send welcome message
+    ws.send(JSON.stringify({
+      ts: new Date().toISOString(),
+      type: 'connection',
+      source: 'server',
+      msg: 'Connected to PBR Dashboard WebSocket',
+      level: 'info',
+    }));
+
+    ws.on('pong', () => {
+      aliveMap.set(ws, true);
+    });
+
+    ws.on('error', () => {
+      // Errors are non-fatal; client will be cleaned up on close
+    });
+
+    ws.on('close', () => {
+      aliveMap.delete(ws);
+      console.log(`WebSocket client disconnected (${wss.clients.size} total)`);
+    });
+  });
+
+  // Heartbeat: ping all clients every 30s, terminate unresponsive ones
+  const heartbeatInterval = setInterval(() => {
+    for (const ws of wss.clients) {
+      if (aliveMap.get(ws) === false) {
+        ws.terminate();
+        continue;
+      }
+      aliveMap.set(ws, false);
+      ws.ping();
+    }
+  }, 30000);
+
+  // Clean up heartbeat when server closes
+  wss.on('close', () => {
+    clearInterval(heartbeatInterval);
+  });
+
+  // Forward file watcher events to all clients
+  if (fileWatcher) {
+    fileWatcher.on('event', (event) => {
+      broadcast(wss, event);
+    });
+  }
+
+  return { wss };
+}
+
+module.exports = { setupWebSocket, broadcast };