beads-ui 0.1.1 → 0.2.0

package/app/views/new-issue-dialog.js

@@ -0,0 +1,352 @@
+import { ISSUE_TYPES, typeLabel } from '../utils/issue-type.js';
+import { priority_levels } from '../utils/priority.js';
+
+/**
+ * Create and manage the New Issue dialog (native <dialog>).
+ * @param {HTMLElement} mount_element - Container to attach dialog (e.g., main#app)
+ * @param {(type: import('../protocol.js').MessageType, payload?: unknown) => Promise<unknown>} sendFn - Transport function
+ * @param {{ gotoIssue: (id: string) => void }} router - Router for opening details after create
+ * @param {{ setState: (patch: any) => void, getState: () => any }} [store]
+ * @returns {{ open: () => void, close: () => void }}
+ */
+export function createNewIssueDialog(mount_element, sendFn, router, store) {
+  /** @type {HTMLDialogElement} */
+  const dialog = /** @type {any} */ (document.createElement('dialog'));
+  dialog.id = 'new-issue-dialog';
+  dialog.setAttribute('role', 'dialog');
+  dialog.setAttribute('aria-modal', 'true');
+
+  dialog.innerHTML = `
+    <div class="new-issue__container" part="container">
+      <header class="new-issue__header">
+        <div class="new-issue__title">New Issue</div>
+        <button type="button" class="new-issue__close" aria-label="Close">×</button>
+      </header>
+      <div class="new-issue__body">
+        <form id="new-issue-form" class="new-issue__form">
+          <label for="new-title">Title</label>
+          <input id="new-title" name="title" type="text" required placeholder="Short summary" />
+
+          <label for="new-type">Type</label>
+          <select id="new-type" name="type" aria-label="Issue type"></select>
+
+          <label for="new-priority">Priority</label>
+          <select id="new-priority" name="priority" aria-label="Priority"></select>
+
+          <label for="new-labels">Labels</label>
+          <input id="new-labels" name="labels" type="text" placeholder="comma,separated" />
+
+          <label for="new-description">Description</label>
+          <textarea id="new-description" name="description" rows="6" placeholder="Optional markdown description"></textarea>
+
+          <div aria-live="polite" role="status" class="new-issue__error" id="new-issue-error"></div>
+
+          <div class="new-issue__actions" style="grid-column: 1 / -1">
+            <button type="button" id="btn-cancel">Cancel (Esc)</button>
+            <button type="submit" id="btn-create">Create</button>
+          </div>
+        </form>
+      </div>
+    </div>
+  `;
+
+  mount_element.appendChild(dialog);
+
+  /** @type {HTMLFormElement} */
+  const form = /** @type {any} */ (dialog.querySelector('#new-issue-form'));
+  /** @type {HTMLInputElement} */
+  const input_title = /** @type {any} */ (dialog.querySelector('#new-title'));
+  /** @type {HTMLSelectElement} */
+  const sel_type = /** @type {any} */ (dialog.querySelector('#new-type'));
+  /** @type {HTMLSelectElement} */
+  const sel_priority = /** @type {any} */ (
+    dialog.querySelector('#new-priority')
+  );
+  /** @type {HTMLInputElement} */
+  const input_labels = /** @type {any} */ (dialog.querySelector('#new-labels'));
+  /** @type {HTMLTextAreaElement} */
+  const input_description = /** @type {any} */ (
+    dialog.querySelector('#new-description')
+  );
+  /** @type {HTMLDivElement} */
+  const error_box = /** @type {any} */ (
+    dialog.querySelector('#new-issue-error')
+  );
+  /** @type {HTMLButtonElement} */
+  const btn_cancel = /** @type {any} */ (dialog.querySelector('#btn-cancel'));
+  /** @type {HTMLButtonElement} */
+  const btn_create = /** @type {any} */ (dialog.querySelector('#btn-create'));
+  /** @type {HTMLButtonElement} */
+  const btn_close = /** @type {any} */ (
+    dialog.querySelector('.new-issue__close')
+  );
+
+  // Populate selects
+  function populateSelects() {
+    sel_type.replaceChildren();
+    // Empty option to allow leaving type unspecified
+    const optEmpty = document.createElement('option');
+    optEmpty.value = '';
+    optEmpty.textContent = '— Select —';
+    sel_type.appendChild(optEmpty);
+    for (const t of ISSUE_TYPES) {
+      const o = document.createElement('option');
+      o.value = t;
+      o.textContent = typeLabel(t);
+      sel_type.appendChild(o);
+    }
+
+    sel_priority.replaceChildren();
+    for (let i = 0; i <= 4; i += 1) {
+      const o = document.createElement('option');
+      o.value = String(i);
+      const label = priority_levels[i] || 'Medium';
+      o.textContent = `${i} – ${label}`;
+      sel_priority.appendChild(o);
+    }
+  }
+  populateSelects();
+
+  function requestClose() {
+    try {
+      if (typeof dialog.close === 'function') {
+        dialog.close();
+      } else {
+        dialog.removeAttribute('open');
+      }
+    } catch {
+      dialog.removeAttribute('open');
+    }
+  }
+
+  /**
+   * @param {boolean} is_busy
+   */
+  function setBusy(is_busy) {
+    input_title.disabled = is_busy;
+    sel_type.disabled = is_busy;
+    sel_priority.disabled = is_busy;
+    input_labels.disabled = is_busy;
+    input_description.disabled = is_busy;
+    btn_cancel.disabled = is_busy;
+    btn_create.disabled = is_busy;
+    btn_create.textContent = is_busy ? 'Creating…' : 'Create';
+  }
+
+  function clearError() {
+    error_box.textContent = '';
+  }
+
+  /**
+   * @param {string} msg
+   */
+  function setError(msg) {
+    error_box.textContent = msg;
+  }
+
+  function loadDefaults() {
+    try {
+      const t = window.localStorage.getItem('beads-ui.new.type');
+      if (t) {
+        sel_type.value = t;
+      } else {
+        sel_type.value = '';
+      }
+      const p = window.localStorage.getItem('beads-ui.new.priority');
+      if (p && /^\d$/.test(p)) {
+        sel_priority.value = p;
+      } else {
+        sel_priority.value = '2';
+      }
+    } catch {
+      sel_type.value = '';
+      sel_priority.value = '2';
+    }
+  }
+
+  function saveDefaults() {
+    try {
+      const t = sel_type.value || '';
+      const p = sel_priority.value || '';
+      if (t.length > 0) {
+        window.localStorage.setItem('beads-ui.new.type', t);
+      }
+      if (p.length > 0) {
+        window.localStorage.setItem('beads-ui.new.priority', p);
+      }
+    } catch {
+      // ignore persistence errors
+    }
+  }
+
+  /**
+   * Extract numeric suffix from an id like "UI-123"; return -1 when absent.
+   * @param {string} id
+   */
+  function idNumeric(id) {
+    const m = /-(\d+)$/.exec(String(id || ''));
+    return m && m[1] ? Number(m[1]) : -1;
+  }
+
+  /**
+   * Submit handler: validate, create, then open the created issue details.
+   * @returns {Promise<void>}
+   */
+  async function createNow() {
+    clearError();
+    /** @type {string} */
+    const title = String(input_title.value || '').trim();
+    if (title.length === 0) {
+      setError('Title is required');
+      input_title.focus();
+      return;
+    }
+    /** @type {number} */
+    const prio = Number(sel_priority.value || '2');
+    if (!(prio >= 0 && prio <= 4)) {
+      setError('Priority must be 0..4');
+      sel_priority.focus();
+      return;
+    }
+    /** @type {string} */
+    const type = String(sel_type.value || '');
+    /** @type {string} */
+    const desc = String(input_description.value || '');
+    /** @type {string[]} */
+    const labels = String(input_labels.value || '')
+      .split(',')
+      .map((s) => s.trim())
+      .filter((s) => s.length > 0);
+
+    /** @type {{ title: string, type?: string, priority?: number, description?: string }} */
+    const payload = { title };
+    if (type.length > 0) {
+      payload.type = type;
+    }
+    if (String(prio).length > 0) {
+      payload.priority = prio;
+    }
+    if (desc.length > 0) {
+      payload.description = desc;
+    }
+
+    setBusy(true);
+    try {
+      await sendFn('create-issue', payload);
+    } catch {
+      setBusy(false);
+      setError('Failed to create issue');
+      return;
+    }
+
+    saveDefaults();
+
+    // Best-effort: find the created id by matching title among open issues and picking the highest numeric id
+    /** @type {any} */
+    let list = null;
+    try {
+      list = await sendFn('list-issues', {
+        filters: { status: 'open', limit: 50 }
+      });
+    } catch {
+      list = null;
+    }
+    /** @type {string} */
+    let created_id = '';
+    if (Array.isArray(list)) {
+      /** @type {any[]} */
+      const matches = list.filter((it) => String(it.title || '') === title);
+      if (matches.length > 0) {
+        /** @type {any} */
+        let best = matches[0];
+        for (const it of matches) {
+          const ai = idNumeric(best.id || '');
+          const bi = idNumeric(it.id || '');
+          if (bi > ai) {
+            best = it;
+          }
+        }
+        created_id = String(best.id || '');
+      }
+    }
+
+    // Apply labels if any
+    if (created_id && labels.length > 0) {
+      for (const label of labels) {
+        try {
+          await sendFn('label-add', { id: created_id, label });
+        } catch {
+          // ignore label failures
+        }
+      }
+    }
+
+    // Navigate to created issue if found
+    if (created_id) {
+      try {
+        router.gotoIssue(created_id);
+      } catch {
+        // ignore routing errors
+      }
+      // Also set state directly to ensure dialog opens even if hash routing is suppressed in tests
+      try {
+        if (store) {
+          store.setState({ selected_id: created_id });
+        }
+      } catch {
+        // ignore
+      }
+    }
+
+    setBusy(false);
+    requestClose();
+  }
+
+  // Events
+  dialog.addEventListener('cancel', (ev) => {
+    ev.preventDefault();
+    requestClose();
+  });
+  btn_close.addEventListener('click', () => requestClose());
+  btn_cancel.addEventListener('click', () => requestClose());
+  dialog.addEventListener('keydown', (ev) => {
+    if (ev.key === 'Enter' && (ev.ctrlKey || ev.metaKey)) {
+      ev.preventDefault();
+      void createNow();
+    }
+  });
+  form.addEventListener('submit', (ev) => {
+    ev.preventDefault();
+    void createNow();
+  });
+
+  return {
+    open() {
+      form.reset();
+      clearError();
+      loadDefaults();
+      try {
+        if (
+          'showModal' in dialog &&
+          typeof (/** @type {any} */ (dialog).showModal) === 'function'
+        ) {
+          /** @type {any} */ (dialog).showModal();
+        } else {
+          dialog.setAttribute('open', '');
+        }
+      } catch {
+        dialog.setAttribute('open', '');
+      }
+      setTimeout(() => {
+        try {
+          input_title.focus();
+        } catch {
+          // ignore
+        }
+      }, 0);
+    },
+    close() {
+      requestClose();
+    }
+  };
+}

package/app/ws.js

@@ -73,12 +73,28 @@ export function createWsClient(options = {}) {
   const queue = [];
   /** @type {Map<string, Set<(payload: any) => void>>} */
   const handlers = new Map();
+  /** @type {Set<(s: ConnectionState) => void>} */
+  const connection_handlers = new Set();
+
+  /**
+   * @param {ConnectionState} s
+   */
+  function notifyConnection(s) {
+    for (const fn of Array.from(connection_handlers)) {
+      try {
+        fn(s);
+      } catch {
+        // ignore listener errors
+      }
+    }
+  }
 
   function scheduleReconnect() {
     if (!should_reconnect || reconnect_timer) {
       return;
     }
     state = 'reconnecting';
+    notifyConnection(state);
     const base = Math.min(
       backoff.maxMs || 0,
       (backoff.initialMs || 0) * Math.pow(backoff.factor || 1, attempts)
@@ -105,6 +121,7 @@ export function createWsClient(options = {}) {
 
   function onOpen() {
     state = 'open';
+    notifyConnection(state);
     attempts = 0;
     // subscribe first
     sendRaw(makeRequest('subscribe-updates', {}));
@@ -160,6 +177,7 @@ export function createWsClient(options = {}) {
 
   function onClose() {
     state = 'closed';
+    notifyConnection(state);
     // fail all pending
     for (const [id, p] of pending.entries()) {
       p.reject(new Error('ws disconnected'));
@@ -177,6 +195,7 @@ export function createWsClient(options = {}) {
     try {
       ws = /** @type {any} */ (new WebSocket(url));
       state = 'connecting';
+      notifyConnection(state);
       const s = /** @type {any} */ (ws);
       s.addEventListener('open', onOpen);
       s.addEventListener('message', onMessage);
@@ -231,6 +250,17 @@ export function createWsClient(options = {}) {
         set?.delete(handler);
       };
     },
+    /**
+     * Subscribe to connection state changes.
+     * @param {(state: ConnectionState) => void} handler
+     * @returns {() => void}
+     */
+    onConnection(handler) {
+      connection_handlers.add(handler);
+      return () => {
+        connection_handlers.delete(handler);
+      };
+    },
     /** Close and stop reconnecting. */
     close() {
       should_reconnect = false;

package/docs/architecture.md

@@ -147,7 +147,7 @@ Error reply
 - Update status: `bd update <id> --status <open|in_progress|closed>`
 - Update priority: `bd update <id> --priority <0..4>`
 - Edit title: `bd update <id> --title <text>`
-- Edit description: not supported (immutable after create)
+- Edit description: `bd update <id> --description <text>`
 - Edit acceptance: `bd update <id> --acceptance-criteria <text>`
 - Link dependency: `bd dep add <a> <b>` (a depends on b)
 - Unlink dependency: `bd dep remove <a> <b>`

package/package.json

@@ -1,6 +1,8 @@
 {
   "name": "beads-ui",
-  "version": "0.1.1",
+  "version": "0.2.0",
+  "description": "Local‑first UI for Beads — a fast issue tracker for your coding agent.",
+  "homepage": "https://github.com/mantoni/beads-ui",
   "type": "module",
   "bin": {
     "bdui": "bin/bdui.js"
@@ -44,5 +46,19 @@
     "express": "^5.1.0",
     "lit-html": "^3.3.1",
     "ws": "^8.18.3"
+  },
+  "files": [
+    "app",
+    "bin",
+    "docs",
+    "server",
+    "CHANGES.md",
+    "LICENSE",
+    "README.md",
+    "!**/*.test.js"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mantoni/beads-ui.git"
   }
 }

package/server/cli/commands.js

@@ -19,7 +19,8 @@ import { openUrl, waitForServer } from './open.js';
  * @param {{ no_open?: boolean }} [options]
  */
 export async function handleStart(options) {
-  const no_open = options?.no_open === true;
+  // Default behavior: do not open a browser unless explicitly requested.
+  const no_open = options?.no_open !== false;
   const existing_pid = readPidFile();
   if (existing_pid && isProcessRunning(existing_pid)) {
     printServerUrl();
@@ -80,12 +81,19 @@ export async function handleStop() {
  * Handle `restart` command: stop (ignore not-running) then start.
  * @returns {Promise<number>} Exit code (0 on success)
  */
-export async function handleRestart() {
+/**
+ * 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]
+ * @returns {Promise<number>}
+ */
+export async function handleRestart(options) {
   const stop_code = await handleStop();
   // 0 = stopped, 2 = not running; both are acceptable to proceed
   if (stop_code !== 0 && stop_code !== 2) {
     return 1;
   }
-  const start_code = await handleStart();
+  const start_code = await handleStart(options);
   return start_code === 0 ? 0 : 1;
 }

package/server/cli/index.js

@@ -17,6 +17,10 @@ export function parseArgs(args) {
       flags.push('help');
       continue;
     }
+    if (token === '--open') {
+      flags.push('open');
+      continue;
+    }
     if (token === '--no-open') {
       flags.push('no-open');
       continue;
@@ -53,19 +57,46 @@ 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.
+     */
     /** @type {{ no_open: boolean }} */
     const options = {
-      no_open:
-        flags.includes('no-open') ||
-        String(process.env.BDUI_NO_OPEN || '') === '1'
+      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;
+    }
     return await handleStart(options);
   }
   if (command === 'stop') {
     return await handleStop();
   }
   if (command === 'restart') {
-    return await handleRestart();
+    /** @type {{ no_open: boolean }} */
+    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;
+    }
+    return await handleRestart(options);
   }
 
   // Unknown command path (should not happen due to parseArgs guard)

package/server/cli/usage.js

@@ -13,7 +13,7 @@ export function printUsage(out_stream) {
     '',
     'Options:',
     '  -h, --help   Show this help message',
-    '      --no-open  Do not open the browser on start',
+    '      --open   Open the browser after start/restart',
     ''
   ];
   for (const line of lines) {

package/server/watcher.js

@@ -6,11 +6,11 @@ import { resolveDbPath } from './db.js';
  * Watch the resolved beads SQLite DB file and invoke a callback after a debounce window.
  * The DB path is resolved following beads precedence and can be overridden via options.
  * @param {string} root_dir - Project root directory (starting point for resolution).
- * @param {(payload: { ts: number }) => void} on_change - Called when changes are detected.
+ * @param {(payload: { ts: number }) => void} onChange - Called when changes are detected.
  * @param {{ debounce_ms?: number, explicit_db?: string }} [options]
  * @returns {{ close: () => void, rebind: (opts?: { root_dir?: string, explicit_db?: string }) => void, path: string }}
  */
-export function watchDb(root_dir, on_change, options = {}) {
+export function watchDb(root_dir, onChange, options = {}) {
   const debounce_ms = options.debounce_ms ?? 250;
 
   /** @type {ReturnType<typeof setTimeout> | undefined} */
@@ -29,7 +29,7 @@ export function watchDb(root_dir, on_change, options = {}) {
       clearTimeout(timer);
     }
     timer = setTimeout(() => {
-      on_change({ ts: Date.now() });
+      onChange({ ts: Date.now() });
     }, debounce_ms);
     timer.unref?.();
   };

package/server/ws.js

@@ -10,7 +10,7 @@ import { isRequest, makeError, makeOk } from './protocol.js';
 /**
  * @typedef {{
  *   subscribed: boolean,
- *   list_filters?: { status?: 'open'|'in_progress'|'closed', ready?: boolean, limit?: number },
+ *   list_filters?: { status?: 'open'|'in_progress'|'closed', ready?: boolean, blocked?: boolean, limit?: number },
  *   show_id?: string | null
  * }} ConnectionSubs
  */
@@ -74,8 +74,8 @@ export function notifyIssuesChanged(payload, options = {}) {
         continue;
       }
       if (s.list_filters) {
-        // Ready lists are conservatively invalidated on any change
-        if (s.list_filters.ready === true) {
+        // Ready/Blocked lists are conservatively invalidated on any change
+        if (s.list_filters.ready === true || s.list_filters.blocked === true) {
           recipients.add(ws);
           continue;
         }
@@ -268,6 +268,25 @@ export async function handleMessage(ws, data) {
       return;
     }
 
+    // When "blocked" is requested, use the dedicated bd subcommand
+    if (filters && typeof filters === 'object' && filters.blocked === true) {
+      const res = await runBdJson(['blocked', '--json']);
+      if (res.code !== 0) {
+        const err = makeError(req, 'bd_error', res.stderr || 'bd failed');
+        ws.send(JSON.stringify(err));
+        return;
+      }
+      // Remember subscription scope for this connection
+      try {
+        const s = getSubs(ws);
+        s.list_filters = { blocked: true };
+      } catch {
+        // ignore tracking errors
+      }
+      ws.send(JSON.stringify(makeOk(req, res.stdoutJson)));
+      return;
+    }
+
     /** @type {string[]} */
     const args = ['list', '--json'];
     if (filters && typeof filters === 'object') {
@@ -498,7 +517,9 @@ export async function handleMessage(ws, data) {
       id.length === 0 ||
       (field !== 'title' &&
         field !== 'description' &&
-        field !== 'acceptance') ||
+        field !== 'acceptance' &&
+        field !== 'notes' &&
+        field !== 'design') ||
       typeof value !== 'string'
     ) {
       ws.send(
@@ -506,20 +527,7 @@ export async function handleMessage(ws, data) {
           makeError(
             req,
             'bad_request',
-            "payload requires { id: string, field: 'title'|'description'|'acceptance', value: string }"
-          )
-        )
-      );
-      return;
-    }
-    // Description updates are currently not supported by bd
-    if (field === 'description') {
-      ws.send(
-        JSON.stringify(
-          makeError(
-            req,
-            'bd_error',
-            'editing description is not supported by bd'
+            "payload requires { id: string, field: 'title'|'description'|'acceptance'|'notes'|'design', value: string }"
           )
         )
       );
@@ -527,8 +535,20 @@ export async function handleMessage(ws, data) {
     }
     // Map UI fields to bd CLI flags
     // title       → --title
+    // description → --description
     // acceptance  → --acceptance-criteria
-    const flag = field === 'title' ? '--title' : '--acceptance-criteria';
+    // notes       → --notes
+    // design      → --design
+    const flag =
+      field === 'title'
+        ? '--title'
+        : field === 'description'
+          ? '--description'
+          : field === 'acceptance'
+            ? '--acceptance-criteria'
+            : field === 'notes'
+              ? '--notes'
+              : '--design';
     const res = await runBd(['update', id, flag, value]);
     if (res.code !== 0) {
       ws.send(