@citadel-labs/beads-ui 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stuart Rimel
+
+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,69 @@
+# beads-board
+
+A minimal kanban dashboard and git log viewer for [Beads](https://github.com/steveyegge/beads). Works standalone as a CLI tool or as a Claude Code plugin.
+
+## Features
+
+- **Kanban board** — Issues organized by status: Ready, In Progress, Blocked, Done
+- **Git log** — Scrollable commit history with branch selector
+- **Bead ID linking** — Bead IDs in commit messages are highlighted as badges
+- **Dark/light theme** — Toggle between themes, dark by default
+- **Auto-refresh** — Polls for updates every 5 seconds
+- **Zero runtime dependencies** — Server uses only Node.js stdlib
+
+## Quick Start
+
+### Standalone CLI (works with any editor)
+
+```bash
+# Install globally
+npm install -g @citadel-labs/beads-ui
+
+# Or run directly with npx (installs temporarily)
+npx @citadel-labs/beads-ui
+```
+
+Then from any project that uses [Beads](https://github.com/steveyegge/beads):
+
+```bash
+cd /path/to/your/project
+bdui                     # Start dashboard for current directory
+bdui /path/to/project    # Or specify a project directory
+bdui --port 9000         # Custom port
+```
+
+Open **http://localhost:8377** in your browser. The server auto-detects an available port and reuses an existing instance if one is already running.
+
+### As a Claude Code Plugin
+
+```bash
+# Install from local directory
+claude --plugin-dir /path/to/beads-board
+
+# Then in any project with .beads/
+/beads-board:start    # Start the dashboard server
+/beads-board:stop     # Stop it
+```
+
+The plugin auto-detects `.beads/` in your project. If your project doesn't use Beads, it will let you know.
+
+## How It Works
+
+The server shells out to `bd` and `git` CLI commands to fetch data, then serves a React dashboard that polls the API every 5 seconds. No direct database access — all data flows through the Beads CLI.
+
+```
+Browser  →  GET /api/*  →  Node.js server  →  bd/git CLI  →  JSON response
+         ←  React app   ←  server/dist/
+```
+
+See [docs/architecture.md](docs/architecture.md) for details.
+
+## Documentation
+
+- [Architecture](docs/architecture.md) — How the server, UI, and plugin fit together
+- [API Reference](docs/api.md) — All API endpoints with examples
+- [Contributing](docs/contributing.md) — How to set up a dev environment and make changes
+
+## License
+
+[MIT](LICENSE)

package/bin/beads-board.js

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+
+const path = require('node:path');
+const fs = require('node:fs');
+
+const args = process.argv.slice(2);
+
+// --help
+if (args.includes('--help') || args.includes('-h')) {
+  console.log(`bdui — Kanban dashboard and git log viewer for Beads
+
+Usage:
+  bdui [project-dir] [options]
+
+Options:
+  --port <port>   Port to listen on (default: 8377)
+  --help, -h      Show this help message
+  --version, -v   Show version number
+
+Examples:
+  bdui                     # Use current directory
+  bdui /path/to/project    # Specify project directory
+  bdui --port 9000         # Custom port`);
+  process.exit(0);
+}
+
+// --version
+if (args.includes('--version') || args.includes('-v')) {
+  const pkg = JSON.parse(fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8'));
+  console.log(pkg.version);
+  process.exit(0);
+}
+
+// Parse --port
+let customPort = null;
+const portIdx = args.indexOf('--port');
+if (portIdx !== -1) {
+  customPort = args[portIdx + 1];
+  if (!customPort || isNaN(parseInt(customPort, 10))) {
+    console.error('Error: --port requires a numeric value');
+    process.exit(1);
+  }
+  args.splice(portIdx, 2);
+}
+
+// Remaining arg is the project directory
+const projectDir = args[0] ? path.resolve(args[0]) : process.cwd();
+
+// Validate project directory exists
+if (!fs.existsSync(projectDir)) {
+  console.error(`Error: directory not found: ${projectDir}`);
+  process.exit(1);
+}
+
+// Check for .beads/ directory
+if (!fs.existsSync(path.join(projectDir, '.beads'))) {
+  console.error(`Error: no .beads/ directory found in ${projectDir}`);
+  console.error('This project does not appear to use Beads issue tracking.');
+  console.error('See https://github.com/steveyegge/beads to get started.');
+  process.exit(1);
+}
+
+// Set PORT env var if custom port specified, then delegate to server
+if (customPort) {
+  process.env.PORT = customPort;
+}
+
+// Rewrite process.argv so server/index.js sees the project dir
+process.argv = [process.argv[0], __filename, projectDir];
+
+require(path.join(__dirname, '..', 'server', 'index.js'));

package/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "@citadel-labs/beads-ui",
+  "version": "1.0.0",
+  "description": "Kanban dashboard and git log viewer for Beads",
+  "bin": {
+    "bdui": "bin/beads-board.js"
+  },
+  "scripts": {
+    "build": "cd ui && npm run build",
+    "start": "node server/index.js"
+  },
+  "license": "MIT"
+}