beads-ui 0.3.0 → 0.4.0

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.0",
-  "description": "Local‑first UI for Beads — a fast issue tracker for your coding agent.",
+  "version": "0.4.0",
+  "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,38 +28,42 @@
     "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": "^48.10.2",
+    "eslint-plugin-jsdoc": "^61.1.9",
     "eslint-plugin-n": "^17.9.0",
-    "eslint-plugin-promise": "^6.1.1",
     "globals": "^16.4.0",
     "jsdom": "^27.0.1",
     "prettier": "^3.3.3",
     "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",
     "bin",
-    "docs",
     "server",
     "CHANGES.md",
     "LICENSE",

package/server/app.js

@@ -6,6 +6,7 @@ import path from 'node:path';
 
 /**
  * Create and configure the Express application.
+ *
  * @param {{ host: string, port: number, env: string, app_dir: string, root_dir: string }} config - Server configuration.
  * @returns {Express} Configured Express app instance.
  */
@@ -25,43 +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

@@ -3,6 +3,7 @@ import { resolveDbPath } from './db.js';
 
 /**
  * Resolve the bd executable path.
+ *
  * @returns {string}
  */
 export function getBdBin() {
@@ -16,6 +17,7 @@ export function getBdBin() {
 /**
  * Run the `bd` CLI with provided arguments.
  * Shell is not used to avoid injection; args must be pre-split.
+ *
  * @param {string[]} args - Arguments to pass (e.g., ["list", "--json"]).
  * @param {{ cwd?: string, env?: Record<string, string | undefined>, timeout_ms?: number }} [options]
  * @returns {Promise<{ code: number, stdout: string, stderr: string }>}
@@ -30,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 = [];
@@ -88,6 +90,7 @@ export function runBd(args, options = {}) {
 
 /**
  * Run `bd` and parse JSON from stdout if exit code is 0.
+ *
  * @param {string[]} args - Must include flags that cause JSON to be printed (e.g., `--json`).
  * @param {{ cwd?: string, env?: Record<string, string | undefined>, timeout_ms?: number }} [options]
  * @returns {Promise<{ code: number, stdoutJson?: unknown, stderr?: string }>}
@@ -109,6 +112,7 @@ export async function runBdJson(args, options = {}) {
 
 /**
  * Add a resolved "--db <path>" pair to args when none present.
+ *
  * @param {string[]} args
  * @param {string} cwd
  * @param {Record<string, string | undefined>} env

package/server/cli/commands.js

@@ -13,17 +13,18 @@ import { openUrl, waitForServer } from './open.js';
  * Handle `start` command. Idempotent when already running.
  * - Spawns a detached server process, writes PID file, returns 0.
  * - If already running (PID file present and process alive), prints URL and returns 0.
+ *
  * @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)) {
@@ -31,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);
@@ -52,6 +53,7 @@ export async function handleStart(options) {
  * Handle `stop` command.
  * - Sends SIGTERM and waits for exit (with SIGKILL fallback), removes PID file.
  * - Returns 2 if not running.
+ *
  * @returns {Promise<number>} Exit code
  */
 export async function handleStop() {
@@ -78,13 +80,15 @@ export async function handleStop() {
 
 /**
  * Handle `restart` command: stop (ignore not-running) then start.
+ *
  * @returns {Promise<number>} Exit code (0 on success)
  */
 /**
  * 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.
- * @param {{ no_open?: boolean }} [options]
+ * so restart only opens a browser when `open` is explicitly true.
+ *
+ * @param {{ open?: boolean }} [options]
  * @returns {Promise<number>}
  */
 export async function handleRestart(options) {

package/server/cli/daemon.js

@@ -13,6 +13,7 @@ import { resolveDbPath } from '../db.js';
  * Resolve the runtime directory used for PID and log files.
  * Prefers `BDUI_RUNTIME_DIR`, then `$XDG_RUNTIME_DIR/beads-ui`,
  * and finally `os.tmpdir()/beads-ui`.
+ *
  * @returns {string}
  */
 export function getRuntimeDir() {
@@ -31,6 +32,7 @@ export function getRuntimeDir() {
 
 /**
  * Ensure a directory exists with safe permissions and return its path.
+ *
  * @param {string} dir_path
  * @returns {string}
  */
@@ -61,6 +63,7 @@ export function getLogFilePath() {
 
 /**
  * Read PID from the PID file if present.
+ *
  * @returns {number | null}
  */
 export function readPidFile() {
@@ -100,6 +103,7 @@ export function removePidFile() {
 
 /**
  * Check whether a process is running.
+ *
  * @param {number} pid
  * @returns {boolean}
  */
@@ -122,6 +126,7 @@ export function isProcessRunning(pid) {
 
 /**
  * Compute the absolute path to the server entry file.
+ *
  * @returns {string}
  */
 export function getServerEntryPath() {
@@ -134,9 +139,11 @@ 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();
 
@@ -145,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;
@@ -164,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 =
@@ -183,6 +197,7 @@ export function startDaemon() {
 
 /**
  * Send SIGTERM then (optionally) SIGKILL to stop a process and wait for exit.
+ *
  * @param {number} pid
  * @param {number} timeout_ms
  * @returns {Promise<boolean>} Resolves true if the process is gone.
@@ -235,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,8 +1,10 @@
+import { enableAllDebug } from '../logging.js';
 import { handleRestart, handleStart, handleStop } from './commands.js';
 import { printUsage } from './usage.js';
 
 /**
  * Parse argv into a command token and flags.
+ *
  * @param {string[]} args
  * @returns {{ command: string | null, flags: string[] }}
  */
@@ -17,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 (
@@ -41,12 +43,18 @@ export function parseArgs(args) {
 /**
  * CLI main entry. Returns an exit code and prints usage on `--help` or errors.
  * No side effects beyond invoking stub handlers.
+ *
  * @param {string[]} args
  * @returns {Promise<number>}
  */
 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;
@@ -58,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/open.js

@@ -3,6 +3,7 @@ import http from 'node:http';
 
 /**
  * Compute a platform-specific command to open a URL in the default browser.
+ *
  * @param {string} url
  * @param {string} platform
  * @returns {{ cmd: string, args: string[] }}
@@ -21,6 +22,7 @@ export function computeOpenCommand(url, platform) {
 
 /**
  * Open the given URL in the default browser. Best-effort; resolves true on spawn success.
+ *
  * @param {string} url
  * @returns {Promise<boolean>}
  */
@@ -41,6 +43,7 @@ export async function openUrl(url) {
 /**
  * Wait until the server at the URL accepts a connection, with a brief retry.
  * Does not throw; returns when either a connection was accepted or timeout elapsed.
+ *
  * @param {string} url
  * @param {number} total_timeout_ms
  * @returns {Promise<void>}

package/server/cli/usage.js

@@ -1,5 +1,6 @@
 /**
  * Print CLI usage to a stream-like target.
+ *
  * @param {{ write: (chunk: string) => any }} out_stream
  */
 export function printUsage(out_stream) {
@@ -12,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/config.js

@@ -6,8 +6,9 @@ import { fileURLToPath } from 'node:url';
  * Notes:
  * - `app_dir` is resolved relative to the installed package location.
  * - `root_dir` represents the directory where the process was invoked
- *   (i.e., the current working directory) so DB resolution follows the
- *   caller's context rather than the install location.
+ * (i.e., the current working directory) so DB resolution follows the
+ * caller's context rather than the install location.
+ *
  * @returns {{ host: string, port: number, env: string, app_dir: string, root_dir: string, url: string }}
  */
 export function getConfig() {

package/server/db.js

@@ -11,6 +11,7 @@ import path from 'node:path';
  *
  * Returns a normalized absolute path and a `source` indicator. Existence is
  * returned via the `exists` boolean.
+ *
  * @param {{ cwd?: string, env?: Record<string, string | undefined>, explicit_db?: string }} [options]
  * @returns {{ path: string, source: 'flag'|'env'|'nearest'|'home-default', exists: boolean }}
  */
@@ -37,17 +38,18 @@ 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)
   };
 }
 
 /**
  * Find nearest .beads/*.db by walking up from start.
  * First alphabetical .db.
+ *
  * @param {string} start
  * @returns {string | null}
  */
@@ -55,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
@@ -79,6 +81,7 @@ export function findNearestBeadsDb(start) {
 
 /**
  * Resolve possibly relative `p` against `cwd` to an absolute filesystem path.
+ *
  * @param {string} p
  * @param {string} cwd
  */

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;
 });