@citadel-labs/beads-ui 2.0.0 → 2.0.2

package/.claude/worktrees/agent-a6ab297c/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/.claude/worktrees/agent-a6ab297c/README.md

@@ -0,0 +1,71 @@
+# 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 in background, prints URL
+bdui /path/to/project    # Specify a project directory
+bdui --port 9000         # Custom port
+bdui status              # Check if dashboard is running
+bdui stop                # Stop the dashboard
+```
+
+The server starts in the background and returns control to your terminal. Open the printed URL (default **http://localhost:8377**) in your browser. Port auto-increments if taken.
+
+### 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/.claude/worktrees/agent-a6ab297c/bin/beads-board.js

@@ -0,0 +1,183 @@
+#!/usr/bin/env node
+
+const path = require('node:path');
+const fs = require('node:fs');
+const { spawn } = require('node:child_process');
+
+const SERVER_SCRIPT = path.join(__dirname, '..', 'server', 'index.js');
+
+// ---------------------------------------------------------------------------
+// Argument parsing
+// ---------------------------------------------------------------------------
+
+const rawArgs = process.argv.slice(2);
+
+// Extract subcommand (start, stop, status) — default to "start"
+const SUBCOMMANDS = ['start', 'stop', 'status'];
+let subcommand = 'start';
+const args = [];
+for (const arg of rawArgs) {
+  if (SUBCOMMANDS.includes(arg) && args.length === 0 && subcommand === 'start') {
+    subcommand = arg;
+  } else {
+    args.push(arg);
+  }
+}
+
+// --help
+if (args.includes('--help') || args.includes('-h')) {
+  console.log(`bdui — Kanban dashboard and git log viewer for Beads
+
+Usage:
+  bdui [project-dir] [options]        Start the dashboard (default)
+  bdui start [project-dir] [options]  Start the dashboard
+  bdui stop [project-dir]             Stop a running dashboard
+  bdui status [project-dir]           Show running dashboard info
+
+Options:
+  --port <port>     Port to listen on (default: 8377)
+  --foreground      Run in foreground (don't daemonize)
+  --help, -h        Show this help message
+  --version, -v     Show version number
+
+Examples:
+  bdui                     # Start dashboard for current directory
+  bdui /path/to/project    # Specify project directory
+  bdui --port 9000         # Custom port
+  bdui stop                # Stop the running dashboard
+  bdui status              # Check if dashboard is running`);
+  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);
+}
+
+// --foreground
+const foreground = args.includes('--foreground');
+const filteredArgs = args.filter(a => a !== '--foreground');
+
+// --port
+let customPort = null;
+const portIdx = filteredArgs.indexOf('--port');
+if (portIdx !== -1) {
+  customPort = filteredArgs[portIdx + 1];
+  if (!customPort || isNaN(parseInt(customPort, 10))) {
+    console.error('Error: --port requires a numeric value');
+    process.exit(1);
+  }
+  filteredArgs.splice(portIdx, 2);
+}
+
+// Remaining arg is the project directory
+const projectDir = filteredArgs[0] ? path.resolve(filteredArgs[0]) : process.cwd();
+
+// ---------------------------------------------------------------------------
+// Validation
+// ---------------------------------------------------------------------------
+
+if (!fs.existsSync(projectDir)) {
+  console.error(`Error: directory not found: ${projectDir}`);
+  process.exit(1);
+}
+
+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);
+}
+
+// ---------------------------------------------------------------------------
+// Pidfile helpers
+// ---------------------------------------------------------------------------
+
+const PIDFILE = path.join(projectDir, '.beads-board.pid');
+
+function getRunningInstance() {
+  try {
+    const data = JSON.parse(fs.readFileSync(PIDFILE, 'utf8'));
+    process.kill(data.pid, 0); // throws if not running
+    return data;
+  } catch {
+    // Clean up stale pidfile
+    try { fs.unlinkSync(PIDFILE); } catch {}
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Subcommands
+// ---------------------------------------------------------------------------
+
+if (subcommand === 'status') {
+  const instance = getRunningInstance();
+  if (instance) {
+    console.log(`beads-board running at http://localhost:${instance.port} (pid ${instance.pid})`);
+  } else {
+    console.log('beads-board is not running');
+    process.exit(1);
+  }
+  process.exit(0);
+}
+
+if (subcommand === 'stop') {
+  const instance = getRunningInstance();
+  if (!instance) {
+    console.log('beads-board is not running');
+    process.exit(0);
+  }
+  try {
+    process.kill(instance.pid, 'SIGTERM');
+    console.log(`beads-board stopped (was http://localhost:${instance.port}, pid ${instance.pid})`);
+  } catch (err) {
+    console.error(`Failed to stop beads-board (pid ${instance.pid}): ${err.message}`);
+    process.exit(1);
+  }
+  process.exit(0);
+}
+
+// subcommand === 'start'
+const existing = getRunningInstance();
+if (existing) {
+  console.log(`beads-board already running at http://localhost:${existing.port} (pid ${existing.pid})`);
+  process.exit(0);
+}
+
+if (foreground) {
+  // Run server in foreground (debugging)
+  if (customPort) process.env.PORT = customPort;
+  process.argv = [process.argv[0], __filename, projectDir];
+  require(SERVER_SCRIPT);
+} else {
+  // Spawn detached server process
+  const env = { ...process.env };
+  if (customPort) env.PORT = customPort;
+
+  const child = spawn(process.execPath, [SERVER_SCRIPT, projectDir], {
+    detached: true,
+    stdio: 'ignore',
+    env,
+    windowsHide: true,
+  });
+  child.unref();
+
+  // Wait for pidfile to confirm startup (poll up to 3s)
+  const start = Date.now();
+  const poll = setInterval(() => {
+    const instance = getRunningInstance();
+    if (instance) {
+      clearInterval(poll);
+      console.log(`beads-board running at http://localhost:${instance.port}`);
+      process.exit(0);
+    }
+    if (Date.now() - start > 3000) {
+      clearInterval(poll);
+      console.error('Error: server failed to start within 3 seconds');
+      process.exit(1);
+    }
+  }, 100);
+}

package/.claude/worktrees/agent-a6ab297c/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@citadel-labs/beads-ui",
+  "version": "2.0.1",
+  "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",
+    "publish:patch": "npm version patch && git push && git push --tags && npm publish --access public",
+    "publish:minor": "npm version minor && git push && git push --tags && npm publish --access public",
+    "publish:major": "npm version major && git push && git push --tags && npm publish --access public"
+  },
+  "license": "MIT"
+}