bmad-viewer 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 bmad-viewer contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,49 @@
+# bmad-viewer
+
+Visual dashboard for BMAD (Boring Maintainable Agile Development) projects.
+
+## Features
+
+- 📊 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
+
+## Quick Start
+
+```bash
+# Run in a BMAD project directory
+npx bmad-viewer
+
+# Or specify a custom path
+npx bmad-viewer --path /path/to/bmad/project
+
+# Custom port
+npx bmad-viewer --port 8080
+```
+
+## Requirements
+
+- Node.js 18+ (LTS)
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Run tests
+npm test
+
+# Lint code
+npm run lint
+
+# Format code
+npm run format
+```
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,139 @@
+#!/usr/bin/env node
+
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
+
+const args = process.argv.slice(2);
+
+// Parse CLI flags
+const flags = {
+	port: null,
+	path: null,
+	output: null,
+	noOpen: false,
+	version: false,
+	help: false,
+};
+
+for (let i = 0; i < args.length; i++) {
+	switch (args[i]) {
+		case '--version':
+		case '-v':
+			flags.version = true;
+			break;
+		case '--help':
+		case '-h':
+			flags.help = true;
+			break;
+		case '--port':
+		case '-p':
+			flags.port = Number.parseInt(args[++i], 10);
+			break;
+		case '--path':
+			flags.path = args[++i];
+			break;
+		case '--output':
+		case '-o':
+			flags.output = args[++i];
+			break;
+		case '--no-open':
+			flags.noOpen = true;
+			break;
+		default:
+			console.error(`Unknown flag: ${args[i]}`);
+			console.error('Run "bmad-viewer --help" for usage information.');
+			process.exit(1);
+	}
+}
+
+// --version
+if (flags.version) {
+	console.log(`bmad-viewer v${pkg.version}`);
+	process.exit(0);
+}
+
+// --help
+if (flags.help) {
+	console.log(`
+bmad-viewer v${pkg.version}
+Visual dashboard for BMAD projects
+
+Usage:
+  bmad-viewer [options]
+
+Options:
+  --port, -p <port>    Set server port (default: auto-detect from 4000)
+  --path <dir>         Path to BMAD project (default: auto-detect _bmad/)
+  --output, -o <dir>   Generate static HTML files (no server)
+  --no-open            Don't open browser automatically
+  --version, -v        Show version number
+  --help, -h           Show this help message
+
+Examples:
+  npx bmad-viewer                          Auto-detect and serve
+  npx bmad-viewer --port 8080              Use specific port
+  npx bmad-viewer --path ./my-project      Specify project path
+  npx bmad-viewer --output ./docs          Generate static files
+`);
+	process.exit(0);
+}
+
+// Validate port
+if (flags.port !== null) {
+	if (Number.isNaN(flags.port) || flags.port < 1024 || flags.port > 65535) {
+		console.error('Error: Port must be between 1024-65535');
+		process.exit(1);
+	}
+}
+
+// Validate path
+if (flags.path !== null) {
+	const { existsSync, statSync } = await import('node:fs');
+	if (!existsSync(flags.path) || !statSync(flags.path).isDirectory()) {
+		console.error(`Error: Path does not exist or is not a directory: ${flags.path}`);
+		process.exit(1);
+	}
+}
+
+// Import and start the application
+const { detectBmadDir } = await import('../src/data/bmad-detector.js');
+const { startServer } = await import('../src/server/http-server.js');
+const { generateStaticSite } = await import('../src/server/static-generator.js');
+
+// Detect BMAD directory
+const bmadDir = flags.path || detectBmadDir(process.cwd());
+
+if (!bmadDir) {
+	console.error(`
+Error: No BMAD installation found.
+
+bmad-viewer looked for a _bmad/ folder in the current directory
+and up to 3 parent directories, but couldn't find one.
+
+Solutions:
+  1. Run this command from within a BMAD project directory
+  2. Specify the path: bmad-viewer --path /path/to/project
+  3. Try the example data: bmad-viewer --path ./node_modules/bmad-viewer/example-data
+
+Learn more: https://github.com/bmad-method/BMAD-METHOD
+`);
+	process.exit(1);
+}
+
+// Static generation mode
+if (flags.output) {
+	await generateStaticSite(bmadDir, flags.output);
+	process.exit(0);
+}
+
+// Server mode (default)
+await startServer({
+	port: flags.port,
+	bmadDir,
+	open: !flags.noOpen,
+});

package/example-data/_bmad/bmm/agents/analyst.md

@@ -0,0 +1,10 @@
+# Analyst Agent
+
+The Analyst agent helps you research and analyze requirements for your project.
+
+## Responsibilities
+
+- Gather business requirements
+- Analyze market conditions
+- Create product briefs
+- Validate assumptions

package/example-data/_bmad/bmm/agents/architect.md

@@ -0,0 +1,10 @@
+# Architect Agent
+
+The Architect agent makes technology and architecture decisions for your project.
+
+## Responsibilities
+
+- Select technology stack
+- Define project structure
+- Create architecture documentation
+- Make implementation pattern decisions

package/example-data/_bmad/bmm/config.yaml

@@ -0,0 +1,4 @@
+project_name: example-project
+user_name: Demo User
+communication_language: english
+version: "6.0.0"

package/example-data/_bmad/core/manifest.csv

@@ -0,0 +1,4 @@
+ID,Title,Type,Description
+bmad-master,BMAD Master,agent,Master orchestrator for BMAD methodology
+workflow-engine,Workflow Engine,tool,Core workflow execution engine
+brainstorming,Brainstorming,workflow,Interactive brainstorming sessions

package/example-data/_bmad-output/implementation-artifacts/sprint-status.yaml

@@ -0,0 +1,16 @@
+generated: 2026-02-16
+project: example-project
+tracking_system: file-system
+story_location: _bmad-output/implementation-artifacts
+
+development_status:
+  epic-1: in-progress
+  1-1-project-setup: done
+  1-2-basic-functionality: in-progress
+  1-3-user-interface: backlog
+  epic-1-retrospective: optional
+
+  epic-2: backlog
+  2-1-advanced-features: backlog
+  2-2-testing: backlog
+  epic-2-retrospective: optional

package/example-data/_bmad-output/planning-artifacts/product-brief.md

@@ -0,0 +1,22 @@
+# Product Brief: Example Project
+
+## Vision
+
+An example project demonstrating BMAD methodology in action.
+
+## Problem Statement
+
+Developers need a clear methodology for AI-assisted development.
+
+## Target Users
+
+- Solo developers
+- Small development teams
+- AI-assisted development practitioners
+
+## Key Features
+
+1. Structured planning workflow
+2. Epic and story organization
+3. Sprint tracking and status
+4. Code review processes

package/package.json

@@ -0,0 +1,56 @@
+{
+	"name": "bmad-viewer",
+	"version": "0.1.0",
+	"description": "Visual dashboard for BMAD (Boring Maintainable Agile Development) projects. Wiki browser + sprint status viewer with live reload.",
+	"type": "module",
+	"bin": {
+		"bmad-viewer": "./bin/cli.js"
+	},
+	"files": [
+		"bin",
+		"src",
+		"public",
+		"example-data",
+		"LICENSE",
+		"README.md"
+	],
+	"engines": {
+		"node": ">=18.0.0"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/CamiloValderramaGonzalez/bmad-viewer.git"
+	},
+	"homepage": "https://github.com/CamiloValderramaGonzalez/bmad-viewer#readme",
+	"bugs": {
+		"url": "https://github.com/CamiloValderramaGonzalez/bmad-viewer/issues"
+	},
+	"dependencies": {
+		"chokidar": "^4.0.1",
+		"fuse.js": "^7.0.0",
+		"js-yaml": "^4.1.0",
+		"marked": "^15.0.4"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "^1.9.4"
+	},
+	"scripts": {
+		"test": "node --test",
+		"lint": "biome check .",
+		"format": "biome format --write ."
+	},
+	"keywords": [
+		"bmad",
+		"agile",
+		"dashboard",
+		"cli",
+		"viewer",
+		"wiki",
+		"sprint",
+		"kanban",
+		"markdown",
+		"project-management"
+	],
+	"author": "",
+	"license": "MIT"
+}