beads-ui 0.3.1 → 0.4.1

package/bin/bdui.js

@@ -4,6 +4,7 @@
  * Delegates to `server/cli/index.js` and sets the process exit code.
  */
 import { main } from '../server/cli/index.js';
+import { debug } from '../server/logging.js';
 
 const argv = process.argv.slice(2);
 
@@ -13,6 +14,6 @@ try {
     process.exitCode = code;
   }
 } catch (err) {
-  console.error(String(/** @type {any} */ (err)?.message || err));
+  debug('cli')('fatal %o', err);
   process.exitCode = 1;
 }

package/package.json

@@ -1,7 +1,13 @@
 {
   "name": "beads-ui",
-  "version": "0.3.1",
-  "description": "Local‑first UI for Beads — a fast issue tracker for your coding agent.",
+  "version": "0.4.1",
+  "description": "Local UI for Beads — Collaborate on issues with your coding agent.",
+  "keywords": [
+    "agent",
+    "issue-tracker",
+    "local-first",
+    "ai-tools"
+  ],
   "homepage": "https://github.com/mantoni/beads-ui",
   "type": "module",
   "bin": {
@@ -12,7 +18,8 @@
   },
   "scripts": {
     "all": "npm run lint && npm run typecheck && npm test && npm run format:check",
-    "start": "node server/index.js",
+    "start": "node server/index.js --debug",
+    "build": "node scripts/build-frontend.js",
     "test": "vitest run",
     "test:watch": "vitest",
     "typecheck": "tsc -p tsconfig.json --noEmit",
@@ -21,15 +28,26 @@
     "format:check": "prettier --check .",
     "preversion": "npm run all",
     "version": "changes --commits --footer",
-    "postversion": "git push --follow-tags && npm publish"
+    "postversion": "git push --follow-tags && npm publish",
+    "prepack": "NODE_ENV=production npm run build"
+  },
+  "dependencies": {
+    "debug": "^4.4.3",
+    "dompurify": "^3.3.0",
+    "express": "^5.1.0",
+    "lit-html": "^3.3.1",
+    "marked": "^16.4.1",
+    "ws": "^8.18.3"
   },
   "devDependencies": {
     "@eslint/js": "^9.38.0",
     "@studio/changes": "^3.0.0",
     "@trivago/prettier-plugin-sort-imports": "^5.2.2",
+    "@types/debug": "^4.1.12",
     "@types/express": "^5.0.3",
     "@types/node": "^22.7.4",
     "@types/ws": "^8.18.1",
+    "esbuild": "^0.25.11",
     "eslint": "^9.11.0",
     "eslint-plugin-import": "^2.29.1",
     "eslint-plugin-jsdoc": "^61.1.9",
@@ -40,18 +58,13 @@
     "typescript": "^5.6.3",
     "vitest": "^2.1.3"
   },
-  "dependencies": {
-    "dompurify": "^3.3.0",
-    "esbuild": "^0.25.11",
-    "express": "^5.1.0",
-    "lit-html": "^3.3.1",
-    "marked": "^16.4.1",
-    "ws": "^8.18.3"
-  },
   "files": [
-    "app",
+    "app/index.html",
+    "app/styles.css",
+    "app/main.bundle.js",
+    "app/main.bundle.js.map",
+    "app/protocol.js",
     "bin",
-    "docs",
     "server",
     "CHANGES.md",
     "LICENSE",

package/server/app.js

@@ -26,44 +26,46 @@ export function createApp(config) {
     res.status(200).send({ ok: true });
   });
 
-  /**
-   * On-demand bundle for the browser using esbuild.
-   * Note: esbuild is loaded lazily so tests don't require it to be installed.
-   *
-   * @param {Request} _req
-   * @param {Response} res
-   */
-  app.get('/main.bundle.js', async (_req, res) => {
-    try {
-      const esbuild = await import('esbuild');
-      const entry = path.join(config.app_dir, 'main.js');
-      const result = await esbuild.build({
-        entryPoints: [entry],
-        bundle: true,
-        format: 'esm',
-        platform: 'browser',
-        target: 'es2020',
-        sourcemap: config.env === 'production' ? false : 'inline',
-        minify: config.env === 'production',
-        write: false
-      });
-      const out = result.outputFiles && result.outputFiles[0];
-      if (!out) {
-        res.status(500).type('text/plain').send('Bundle failed: no output');
-        return;
-      }
-      res.setHeader('Content-Type', 'application/javascript; charset=utf-8');
-      if (config.env !== 'production') {
+  // In development, support on-demand bundling for a smooth DX.
+  // In production, we expect `app/main.bundle.js` to be pre-built and served statically.
+  if (config.env !== 'production') {
+    /**
+     * On-demand bundle for the browser using esbuild.
+     * Note: esbuild is loaded lazily so tests don't require it to be installed.
+     *
+     * @param {Request} _req
+     * @param {Response} res
+     */
+    app.get('/main.bundle.js', async (_req, res) => {
+      try {
+        const esbuild = await import('esbuild');
+        const entry = path.join(config.app_dir, 'main.js');
+        const result = await esbuild.build({
+          entryPoints: [entry],
+          bundle: true,
+          format: 'esm',
+          platform: 'browser',
+          target: 'es2020',
+          sourcemap: 'inline',
+          minify: false,
+          write: false
+        });
+        const out = result.outputFiles && result.outputFiles[0];
+        if (!out) {
+          res.status(500).type('text/plain').send('Bundle failed: no output');
+          return;
+        }
+        res.setHeader('Content-Type', 'application/javascript; charset=utf-8');
         res.setHeader('Cache-Control', 'no-store');
+        res.send(out.text);
+      } catch (err) {
+        res
+          .status(500)
+          .type('text/plain')
+          .send('Bundle error: ' + (err && /** @type {any} */ (err).message));
       }
-      res.send(out.text);
-    } catch (err) {
-      res
-        .status(500)
-        .type('text/plain')
-        .send('Bundle error: ' + (err && /** @type {any} */ (err).message));
-    }
-  });
+    });
+  }
 
   // Static assets from /app
   app.use(express.static(config.app_dir));

package/server/bd.js

@@ -32,10 +32,10 @@ export function runBd(args, options = {}) {
 
   // Ensure a consistent DB by injecting --db if missing, following beads precedence.
   /** @type {string[]} */
-  const finalArgs = withDbArg(args, spawn_opts.cwd, spawn_opts.env);
+  const final_args = withDbArg(args, spawn_opts.cwd, spawn_opts.env);
 
   return new Promise((resolve) => {
-    const child = spawn(bin, finalArgs, spawn_opts);
+    const child = spawn(bin, final_args, spawn_opts);
 
     /** @type {string[]} */
     const out_chunks = [];

package/server/cli/commands.js

@@ -17,14 +17,14 @@ import { openUrl, waitForServer } from './open.js';
  * @returns {Promise<number>} Exit code (0 on success)
  */
 /**
- * @param {{ no_open?: boolean }} [options]
+ * @param {{ open?: boolean, is_debug?: boolean }} [options]
  */
 export async function handleStart(options) {
-  // Default behavior: do not open a browser unless explicitly requested.
-  const no_open = options?.no_open !== false;
+  // Default: do not open a browser unless explicitly requested via `open: true`.
+  const should_open = options?.open === true;
   const existing_pid = readPidFile();
   if (existing_pid && isProcessRunning(existing_pid)) {
-    printServerUrl();
+    console.warn('Server is already running.');
     return 0;
   }
   if (existing_pid && !isProcessRunning(existing_pid)) {
@@ -32,11 +32,11 @@ export async function handleStart(options) {
     removePidFile();
   }
 
-  const started = startDaemon();
+  const started = startDaemon({ is_debug: options?.is_debug });
   if (started && started.pid > 0) {
     printServerUrl();
     // Auto-open the browser once for a fresh daemon start
-    if (!no_open) {
+    if (should_open) {
       const { url } = getConfig();
       // Wait briefly for the server to accept connections (single retry window)
       await waitForServer(url, 600);
@@ -86,9 +86,9 @@ export async function handleStop() {
 /**
  * Handle `restart` command: stop (ignore not-running) then start.
  * Accepts the same options as `handleStart` and passes them through,
- * so restart only opens a browser when `no_open` is explicitly false.
+ * so restart only opens a browser when `open` is explicitly true.
  *
- * @param {{ no_open?: boolean }} [options]
+ * @param {{ open?: boolean }} [options]
  * @returns {Promise<number>}
  */
 export async function handleRestart(options) {

package/server/cli/daemon.js

@@ -140,9 +140,10 @@ export function getServerEntryPath() {
  * Spawn the server as a detached daemon, redirecting stdio to the log file.
  * Writes the PID file upon success.
  *
+ * @param {{ is_debug?: boolean }} [options]
  * @returns {{ pid: number } | null} Returns child PID on success; null on failure.
  */
-export function startDaemon() {
+export function startDaemon(options = {}) {
   const server_entry = getServerEntryPath();
   const log_file = getLogFilePath();
 
@@ -151,6 +152,9 @@ export function startDaemon() {
   let log_fd;
   try {
     log_fd = fs.openSync(log_file, 'a');
+    if (options.is_debug) {
+      console.debug('log file  ', log_file);
+    }
   } catch {
     // If log cannot be opened, fallback to ignoring stdio
     log_fd = -1;
@@ -170,11 +174,15 @@ export function startDaemon() {
     child.unref();
     const child_pid = typeof child.pid === 'number' ? child.pid : -1;
     if (child_pid > 0) {
+      if (options.is_debug) {
+        console.debug('starting  ', child_pid);
+      }
       writePidFile(child_pid);
       return { pid: child_pid };
     }
     return null;
   } catch (err) {
+    console.error('start error', err);
     // Log startup error to log file for traceability
     try {
       const message =
@@ -242,12 +250,12 @@ function sleep(ms) {
  * Print the server URL derived from current config.
  */
 export function printServerUrl() {
-  const { url } = getConfig();
-  console.log(url);
-
   // Resolve from the caller's working directory by default
   const resolved_db = resolveDbPath();
   console.log(
-    `db: ${resolved_db.path} (${resolved_db.source}${resolved_db.exists ? '' : ', missing'})`
+    `beads db   ${resolved_db.path} (${resolved_db.source}${resolved_db.exists ? '' : ', missing'})`
   );
+
+  const { url, env } = getConfig();
+  console.log(`beads ui   listening on ${url} (${env})`);
 }

package/server/cli/index.js

@@ -1,3 +1,4 @@
+import { enableAllDebug } from '../logging.js';
 import { handleRestart, handleStart, handleStop } from './commands.js';
 import { printUsage } from './usage.js';
 
@@ -18,12 +19,12 @@ export function parseArgs(args) {
       flags.push('help');
       continue;
     }
-    if (token === '--open') {
-      flags.push('open');
+    if (token === '--debug' || token === '-d') {
+      flags.push('debug');
       continue;
     }
-    if (token === '--no-open') {
-      flags.push('no-open');
+    if (token === '--open') {
+      flags.push('open');
       continue;
     }
     if (
@@ -49,6 +50,11 @@ export function parseArgs(args) {
 export async function main(args) {
   const { command, flags } = parseArgs(args);
 
+  const is_debug = flags.includes('debug');
+  if (is_debug) {
+    enableAllDebug();
+  }
+
   if (flags.includes('help')) {
     printUsage(process.stdout);
     return 0;
@@ -60,42 +66,22 @@ export async function main(args) {
 
   if (command === 'start') {
     /**
-     * Default behavior: do NOT open a browser.
-     * `--open` explicitly opens, overriding env/config; `--no-open` forces closed.
+     * Default behavior: do NOT open a browser. `--open` explicitly opens.
      */
     const options = {
-      no_open: true
+      open: flags.includes('open'),
+      is_debug: is_debug || Boolean(process.env.DEBUG)
     };
-
-    const has_open = flags.includes('open');
-    const has_no_open = flags.includes('no-open');
-    const env_no_open = String(process.env.BDUI_NO_OPEN || '') === '1';
-
-    if (has_open) {
-      options.no_open = false;
-    } else if (has_no_open) {
-      options.no_open = true;
-    } else if (env_no_open) {
-      options.no_open = true;
-    }
     return await handleStart(options);
   }
   if (command === 'stop') {
     return await handleStop();
   }
   if (command === 'restart') {
-    const options = { no_open: true };
-    const has_open = flags.includes('open');
-    const has_no_open = flags.includes('no-open');
-    const env_no_open = String(process.env.BDUI_NO_OPEN || '') === '1';
-
-    if (has_open) {
-      options.no_open = false;
-    } else if (has_no_open) {
-      options.no_open = true;
-    } else if (env_no_open) {
-      options.no_open = true;
-    }
+    const options = {
+      open: flags.includes('open'),
+      is_debug: is_debug || Boolean(process.env.DEBUG)
+    };
     return await handleRestart(options);
   }
 

package/server/cli/usage.js

@@ -13,8 +13,9 @@ export function printUsage(out_stream) {
     '  restart     Restart the UI server',
     '',
     'Options:',
-    '  -h, --help   Show this help message',
-    '      --open   Open the browser after start/restart',
+    '  -h, --help    Show this help message',
+    '  -d, --debug   Enable debug logging',
+    '      --open    Open the browser after start/restart',
     ''
   ];
   for (const line of lines) {

package/server/db.js

@@ -38,11 +38,11 @@ export function resolveDbPath(options = {}) {
   }
 
   // 4) ~/.beads/default.db
-  const homeDefault = path.join(os.homedir(), '.beads', 'default.db');
+  const home_default = path.join(os.homedir(), '.beads', 'default.db');
   return {
-    path: homeDefault,
+    path: home_default,
     source: 'home-default',
-    exists: fileExists(homeDefault)
+    exists: fileExists(home_default)
   };
 }
 
@@ -57,15 +57,15 @@ export function findNearestBeadsDb(start) {
   let dir = path.resolve(start);
   // Cap iterations to avoid infinite loop in degenerate cases
   for (let i = 0; i < 100; i++) {
-    const beadsDir = path.join(dir, '.beads');
+    const beads_dir = path.join(dir, '.beads');
     try {
-      const entries = fs.readdirSync(beadsDir, { withFileTypes: true });
+      const entries = fs.readdirSync(beads_dir, { withFileTypes: true });
       const dbs = entries
         .filter((e) => e.isFile() && e.name.endsWith('.db'))
         .map((e) => e.name)
         .sort();
       if (dbs.length > 0) {
-        return path.join(beadsDir, dbs[0]);
+        return path.join(beads_dir, dbs[0]);
       }
     } catch {
       // ignore and walk up

package/server/index.js

@@ -1,12 +1,19 @@
 import { createServer } from 'node:http';
 import { createApp } from './app.js';
+import { printServerUrl } from './cli/daemon.js';
 import { getConfig } from './config.js';
+import { debug, enableAllDebug } from './logging.js';
 import { watchDb } from './watcher.js';
 import { attachWsServer } from './ws.js';
 
+if (process.argv.includes('--debug') || process.argv.includes('-d')) {
+  enableAllDebug();
+}
+
 const config = getConfig();
 const app = createApp(config);
 const server = createServer(app);
+const log = debug('server');
 const { scheduleListRefresh } = attachWsServer(server, {
   path: '/ws',
   heartbeat_ms: 30000,
@@ -17,17 +24,16 @@ const { scheduleListRefresh } = attachWsServer(server, {
 // Watch the active beads DB and schedule subscription refresh for active lists
 watchDb(config.root_dir, () => {
   // Schedule subscription list refresh run for active subscriptions
+  log('db change detected → schedule refresh');
   scheduleListRefresh();
   // v2: all updates flow via subscription push envelopes only
 });
 
 server.listen(config.port, config.host, () => {
-  console.log(
-    `beads-ui server listening on http://${config.host}:${config.port} (${config.env})`
-  );
+  printServerUrl();
 });
 
 server.on('error', (err) => {
-  console.error('Server error:', err);
+  log('server error %o', err);
   process.exitCode = 1;
 });

package/server/logging.js

@@ -0,0 +1,23 @@
+/**
+ * Debug logger helper for Node server/CLI.
+ */
+import createDebug from 'debug';
+
+/**
+ * Create a namespaced logger for Node runtime.
+ *
+ * @param {string} ns - Module namespace suffix (e.g., 'ws', 'watcher').
+ */
+export function debug(ns) {
+  return createDebug(`beads-ui:${ns}`);
+}
+
+/**
+ * Enable all `beads-ui:*` debug logs at runtime for Node/CLI.
+ * Safe to call multiple times.
+ */
+export function enableAllDebug() {
+  // `debug` exposes a global enable/disable API.
+  // Enabling after loggers are created updates their `.enabled` state.
+  createDebug.enable(process.env.DEBUG || 'beads-ui:*');
+}

package/server/watcher.js

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { resolveDbPath } from './db.js';
+import { debug } from './logging.js';
 
 /**
  * Watch the resolved beads SQLite DB file and invoke a callback after a debounce window.
@@ -13,6 +14,7 @@ import { resolveDbPath } from './db.js';
  */
 export function watchDb(root_dir, onChange, options = {}) {
   const debounce_ms = options.debounce_ms ?? 250;
+  const log = debug('watcher');
 
   /** @type {ReturnType<typeof setTimeout> | undefined} */
   let timer;
@@ -44,10 +46,9 @@ export function watchDb(root_dir, onChange, options = {}) {
     current_dir = path.dirname(current_path);
     current_file = path.basename(current_path);
     if (!resolved.exists) {
-      console.warn(
-        'watchDb: resolved DB does not exist yet:',
-        current_path,
-        '\nHint: set --db, export BEADS_DB, or run `bd init` in your workspace.'
+      log(
+        'resolved DB missing: %s – Hint: set --db, export BEADS_DB, or run `bd init` in your workspace.',
+        current_path
       );
     }
 
@@ -61,12 +62,13 @@ export function watchDb(root_dir, onChange, options = {}) {
             return;
           }
           if (event_type === 'change' || event_type === 'rename') {
+            log('fs %s %s', event_type, filename || '');
             schedule();
           }
         }
       );
     } catch (err) {
-      console.warn('watchDb: unable to watch directory', current_dir, err);
+      log('unable to watch directory %s %o', current_dir, err);
     }
   };
 

package/server/ws.js

@@ -4,12 +4,15 @@
  * @import { MessageType } from '../app/protocol.js'
  */
 import { WebSocketServer } from 'ws';
+import { isRequest, makeError, makeOk } from '../app/protocol.js';
 import { runBd, runBdJson } from './bd.js';
 import { fetchListForSubscription } from './list-adapters.js';
-import { isRequest, makeError, makeOk } from './protocol.js';
+import { debug } from './logging.js';
 import { keyOf, registry } from './subscriptions.js';
 import { validateSubscribeListPayload } from './validators.js';
 
+const log = debug('ws');
+
 /**
  * Debounced refresh scheduling for active list subscriptions.
  * A trailing window coalesces rapid change bursts into a single refresh run.
@@ -77,6 +80,7 @@ function triggerMutationRefreshOnce(timeout_ms = 500) {
 
   // After resolution, run a single refresh across active subs and clear gate
   void p.then(async () => {
+    log('mutation window resolved → refresh active subs');
     try {
       await refreshAllActiveListSubscriptions();
     } catch {
@@ -321,17 +325,17 @@ async function refreshAndPublish(spec) {
       return;
     }
     const items = applyClosedIssuesFilter(spec, res.items);
-    const prevSize = registry.get(key)?.itemsById.size || 0;
+    const prev_size = registry.get(key)?.itemsById.size || 0;
     const delta = registry.applyItems(key, items);
     const entry = registry.get(key);
     if (!entry || entry.subscribers.size === 0) {
       return;
     }
     /** @type {Map<string, any>} */
-    const byId = new Map();
+    const by_id = new Map();
     for (const it of items) {
       if (it && typeof it.id === 'string') {
-        byId.set(it.id, it);
+        by_id.set(it.id, it);
       }
     }
     for (const ws of entry.subscribers) {
@@ -339,20 +343,20 @@ async function refreshAndPublish(spec) {
       const s = ensureSubs(ws);
       const subs = s.list_subs || new Map();
       /** @type {string[]} */
-      const clientIds = [];
+      const client_ids = [];
       for (const [cid, v] of subs.entries()) {
-        if (v.key === key) clientIds.push(cid);
+        if (v.key === key) client_ids.push(cid);
       }
-      if (clientIds.length === 0) continue;
-      if (prevSize === 0) {
-        for (const cid of clientIds) {
+      if (client_ids.length === 0) continue;
+      if (prev_size === 0) {
+        for (const cid of client_ids) {
           emitSubscriptionSnapshot(ws, cid, key, items);
         }
         continue;
       }
-      for (const cid of clientIds) {
+      for (const cid of client_ids) {
         for (const id of [...delta.added, ...delta.updated]) {
-          const issue = byId.get(id);
+          const issue = by_id.get(id);
           if (issue) {
             emitSubscriptionUpsert(ws, cid, key, issue);
           }
@@ -413,6 +417,7 @@ export function attachWsServer(http_server, options = {}) {
 
   // Heartbeat: track if client answered the last ping
   wss.on('connection', (ws) => {
+    log('client connected');
     // @ts-expect-error add marker property
     ws.isAlive = true;
 
@@ -507,6 +512,7 @@ export async function handleMessage(ws, data) {
   }
 
   if (!isRequest(json)) {
+    log('invalid request');
     const reply = {
       id: 'unknown',
       ok: false,
@@ -527,6 +533,7 @@ export async function handleMessage(ws, data) {
 
   // subscribe-list: payload { id: string, type: string, params?: object }
   if (req.type === 'subscribe-list') {
+    log('subscribe-list %s', /** @type {any} */ (req.payload)?.id || '');
     const validation = validateSubscribeListPayload(
       /** @type {any} */ (req.payload || {})
     );
@@ -562,6 +569,7 @@ export async function handleMessage(ws, data) {
 
   // unsubscribe-list: payload { id: string }
   if (req.type === 'unsubscribe-list') {
+    log('unsubscribe-list %s', /** @type {any} */ (req.payload)?.id || '');
     const { id: client_id } = /** @type {any} */ (req.payload || {});
     if (typeof client_id !== 'string' || client_id.length === 0) {
       ws.send(
@@ -646,6 +654,7 @@ export async function handleMessage(ws, data) {
 
   // update-status
   if (req.type === 'update-status') {
+    log('update-status');
     const { id, status } = /** @type {any} */ (req.payload);
     const allowed = new Set(['open', 'in_progress', 'closed']);
     if (
@@ -691,6 +700,7 @@ export async function handleMessage(ws, data) {
 
   // update-priority
   if (req.type === 'update-priority') {
+    log('update-priority');
     const { id, priority } = /** @type {any} */ (req.payload);
     if (
       typeof id !== 'string' ||
@@ -735,6 +745,7 @@ export async function handleMessage(ws, data) {
 
   // edit-text
   if (req.type === 'edit-text') {
+    log('edit-text');
     const { id, field, value } = /** @type {any} */ (req.payload);
     if (
       typeof id !== 'string' ||
@@ -798,6 +809,7 @@ export async function handleMessage(ws, data) {
 
   // create-issue
   if (req.type === 'create-issue') {
+    log('create-issue');
     const { title, type, priority, description } = /** @type {any} */ (
       req.payload || {}
     );