bmad-viewer 0.1.5 → 0.1.7

package/README.md

@@ -1,48 +1,94 @@
 # bmad-viewer
 
-Visual dashboard for BMAD (Boring Maintainable Agile Development) projects.
+**Stop wasting tokens asking "where am I?"** — see your BMAD project status, browse the full agent/workflow catalog, and search everything with Ctrl+K. Zero tokens, zero config.
 
-## Features
+![bmad-viewer demo](./docs/demo.gif)
 
-- 📊 Live project dashboard with sprint status visualization
-- 🔍 Fuzzy search across agents, workflows, and tools
-- 📝 Markdown-based wiki with auto-refresh
-- 🎨 Dark/light theme support
-- 🚀 Zero-config - auto-detects `_bmad/` folder
-- 📦 Installable via npx - no global installation needed
+## The problem
 
-## Quick Start
+BMAD is powerful — 21 agents, 43 workflows, hundreds of resources. But:
+
+- **New users** face 500+ markdown files with no map
+- **Active developers** burn tokens every morning asking the agent "where did I leave off?"
+- **Non-technical stakeholders** can't see project progress without opening a terminal
+- **Solo devs** don't know half the capabilities BMAD offers
+
+bmad-viewer fixes all of that with a single command.
+
+## Quick start
+
+**From Claude Code** — just type:
+
+```
+/viewer
+```
+
+The package includes a `/viewer` slash command that auto-installs as a skill. Claude launches the dashboard for you in the background.
+
+**From terminal:**
 
 ```bash
-# Run in a BMAD project directory
 npx bmad-viewer
+```
+
+Auto-detects your `_bmad/` folder, opens your browser, dashboard ready.
+
+## What you get
 
-# Or specify a custom path
-npx bmad-viewer --path /path/to/bmad/project
+**Wiki / Catalog** — Browse all BMAD modules (Core, BMB, BMM, CIS) with a navigable sidebar. Click any agent or workflow to read its full description rendered as clean HTML.
+
+**Project Viewer** — Sprint status at a glance: stats boxes + kanban columns (Pending → In Progress → Done). Reads directly from your `sprint-status.yaml`. Auto-refreshes when files change on disk.
+
+**Fuzzy Search (Ctrl+K)** — Find any agent, workflow, or tool instantly. Tolerates typos. You type "brainstrom", you get "brainstorming".
+
+**Dark/Light theme** — Respects your OS preference, toggle manually anytime. Persists across sessions.
+
+## Who is this for
+
+| You are... | You get... |
+|------------|-----------|
+| New to BMAD | A visual map of everything BMAD offers — no more guessing which agent does what |
+| A developer mid-sprint | Sprint dashboard on your second monitor, always up to date, zero tokens spent |
+| A solo dev | Discover workflows you didn't know existed via search |
+| A stakeholder | A shareable link with project progress — no terminal needed |
+| An open source contributor | A complete catalog to understand how BMAD fits together |
+
+## CLI options
 
-# Custom port
-npx bmad-viewer --port 8080
 ```
+bmad-viewer [options]
+
+Options:
+  --port <number>       Custom port (default: auto-detect from 3000)
+  --path <directory>    Path to BMAD project (default: auto-detect _bmad/ in cwd)
+  --output <directory>  Generate static HTMLs (no server)
+  --no-open             Don't open browser automatically
+  --version             Show version
+  --help                Show help
+```
+
+## How it works
+
+bmad-viewer reads the files BMAD already generates — CSV manifests, YAML configs, Markdown docs — and renders them as a local HTML dashboard. The filesystem is the database. No backend, no data entry, no sync.
+
+When you edit a file, a file watcher detects the change and pushes an update to your browser via WebSocket. The dashboard refreshes automatically.
 
 ## Requirements
 
 - Node.js 18+ (LTS)
+- A project with BMAD installed (`_bmad/` folder)
 
-## Development
+## Try without a BMAD project
 
 ```bash
-# Install dependencies
-npm install
+npx bmad-viewer --path ./node_modules/bmad-viewer/example-data
+```
 
-# Run tests
-npm test
+Bundled example data lets you explore the dashboard without a real project.
 
-# Lint code
-npm run lint
+## Contributing
 
-# Format code
-npm run format
-```
+Issues and PRs welcome at [github.com/CamiloValderramaGonzalez/bmad-viewer](https://github.com/CamiloValderramaGonzalez/bmad-viewer).
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "bmad-viewer",
-	"version": "0.1.5",
+	"version": "0.1.7",
 	"description": "Visual dashboard for BMAD (Boring Maintainable Agile Development) projects. Wiki browser + sprint status viewer with live reload.",
 	"type": "module",
 	"bin": {
@@ -30,7 +30,8 @@
 		"chokidar": "^4.0.1",
 		"fuse.js": "^7.0.0",
 		"js-yaml": "^4.1.0",
-		"marked": "^15.0.4"
+		"marked": "^15.0.4",
+		"ws": "^8.19.0"
 	},
 	"devDependencies": {
 		"@biomejs/biome": "^1.9.4"

package/src/server/http-server.js

@@ -5,7 +5,7 @@ import { fileURLToPath } from 'node:url';
 import { dirname } from 'node:path';
 import { getMimeType } from './mime-types.js';
 import { findAvailablePort } from './port-finder.js';
-import { handleUpgrade, broadcastChange } from './websocket.js';
+import { attachWebSocket, broadcastChange } from './websocket.js';
 import { createFileWatcher } from '../watchers/file-watcher.js';
 import { buildDataModel } from '../data/data-model.js';
 import { renderDashboard } from './renderer.js';
@@ -30,7 +30,7 @@ export async function startServer({ port, bmadDir, open }) {
 		const pathname = url.pathname;
 
 		// Security headers
-		res.setHeader('Content-Security-Policy', "default-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'");
+		res.setHeader('Content-Security-Policy', "default-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; connect-src 'self' ws://localhost:* ws://127.0.0.1:*");
 		res.setHeader('X-Content-Type-Options', 'nosniff');
 
 		// API endpoint: get fresh HTML
@@ -60,10 +60,8 @@ export async function startServer({ port, bmadDir, open }) {
 		res.end(html);
 	});
 
-	// WebSocket upgrade handler
-	server.on('upgrade', (req, socket, head) => {
-		handleUpgrade(req, socket, head);
-	});
+	// WebSocket server
+	attachWebSocket(server);
 
 	// File watcher for live reload
 	const pendingChanges = [];

package/src/server/websocket.js

@@ -1,110 +1,35 @@
-import { createHash } from 'node:crypto';
+import { WebSocketServer } from 'ws';
 
-/** @type {Set<import('net').Socket>} */
-const clients = new Set();
+/** @type {import('ws').WebSocketServer|null} */
+let wss = null;
 
 /**
- * Handle WebSocket upgrade request manually using Node.js built-in APIs.
- * No external dependencies needed.
- *
- * @param {import('http').IncomingMessage} req
- * @param {import('net').Socket} socket
- * @param {Buffer} head
+ * Attach WebSocket server to an existing HTTP server.
+ * @param {import('http').Server} server
  */
-export function handleUpgrade(req, socket, head) {
-	const key = req.headers['sec-websocket-key'];
-	if (!key) {
-		socket.destroy();
-		return;
-	}
-
-	const acceptKey = createHash('sha1')
-		.update(`${key}258EAFA5-E914-47DA-95CA-5AB5DC11CE10`)
-		.digest('base64');
-
-	const responseHeaders = [
-		'HTTP/1.1 101 Switching Protocols',
-		'Upgrade: websocket',
-		'Connection: Upgrade',
-		`Sec-WebSocket-Accept: ${acceptKey}`,
-		'',
-		'',
-	].join('\r\n');
+export function attachWebSocket(server) {
+	wss = new WebSocketServer({ server });
 
-	socket.write(responseHeaders);
-	clients.add(socket);
-
-	socket.on('close', () => clients.delete(socket));
-	socket.on('error', () => {
-		clients.delete(socket);
-		socket.destroy();
+	wss.on('connection', (ws) => {
+		ws.on('error', () => {});
 	});
-
-	// Handle incoming frames (ping/pong, close)
-	socket.on('data', (buffer) => {
-		const opcode = buffer[0] & 0x0f;
-		// Close frame
-		if (opcode === 0x08) {
-			clients.delete(socket);
-			socket.end();
-		}
-		// Ping frame — respond with pong
-		if (opcode === 0x09) {
-			const pong = Buffer.alloc(2);
-			pong[0] = 0x8a; // FIN + pong opcode
-			pong[1] = 0;
-			socket.write(pong);
-		}
-	});
-}
-
-/**
- * Send a WebSocket text frame to a socket.
- * @param {import('net').Socket} socket
- * @param {string} message
- */
-function sendFrame(socket, message) {
-	const payload = Buffer.from(message, 'utf8');
-	const frame = [];
-
-	// FIN + text opcode
-	frame.push(0x81);
-
-	// Payload length
-	if (payload.length < 126) {
-		frame.push(payload.length);
-	} else if (payload.length < 65536) {
-		frame.push(126);
-		frame.push((payload.length >> 8) & 0xff);
-		frame.push(payload.length & 0xff);
-	} else {
-		frame.push(127);
-		const lenBuf = Buffer.alloc(8);
-		lenBuf.writeBigUInt64BE(BigInt(payload.length));
-		frame.push(...lenBuf);
-	}
-
-	const header = Buffer.from(frame);
-	socket.write(Buffer.concat([header, payload]));
 }
 
 /**
  * Broadcast a file change event to all connected WebSocket clients.
- * @param {string[]} changedPaths - Array of changed file paths
+ * @param {string[]} changedPaths
  */
 export function broadcastChange(changedPaths) {
+	if (!wss) return;
+
 	const message = JSON.stringify({
 		type: 'file-changed',
 		paths: changedPaths,
 	});
 
-	for (const client of clients) {
-		try {
-			if (!client.destroyed) {
-				sendFrame(client, message);
-			}
-		} catch {
-			clients.delete(client);
+	for (const client of wss.clients) {
+		if (client.readyState === 1) { // WebSocket.OPEN
+			client.send(message);
 		}
 	}
 }
@@ -113,14 +38,9 @@ export function broadcastChange(changedPaths) {
  * Close all WebSocket connections.
  */
 export function closeAllConnections() {
-	for (const client of clients) {
-		try {
-			client.end();
-		} catch {
-			// ignore
-		}
+	if (wss) {
+		wss.close();
 	}
-	clients.clear();
 }
 
 /**
@@ -128,5 +48,5 @@ export function closeAllConnections() {
  * @returns {number}
  */
 export function getClientCount() {
-	return clients.size;
+	return wss ? wss.clients.size : 0;
 }

package/src/watchers/file-watcher.js

@@ -16,9 +16,11 @@ export function createFileWatcher(bmadDir, onChange) {
 	const watcher = chokidar.watch([watchPath, outputPath], {
 		persistent: true,
 		ignoreInitial: true,
+		usePolling: true,
+		interval: 500,
 		awaitWriteFinish: {
-			stabilityThreshold: 100,
-			pollInterval: 50,
+			stabilityThreshold: 200,
+			pollInterval: 100,
 		},
 	});