@rsktash/beads-ui 0.1.0

package/server/validators.js

@@ -0,0 +1,124 @@
+/**
+ * Validation helpers for protocol payloads.
+ *
+ * Provides schema checks for subscription specs and selected mutations.
+ */
+
+/**
+ * Known subscription types supported by the server.
+ *
+ * @type {Set<string>}
+ */
+const SUBSCRIPTION_TYPES = new Set([
+  'all-issues',
+  'epics',
+  'blocked-issues',
+  'ready-issues',
+  'in-progress-issues',
+  'closed-issues',
+  'search-issues',
+  'issue-detail'
+]);
+
+/**
+ * Validate a subscribe-list payload and normalize to a SubscriptionSpec.
+ *
+ * @param {unknown} payload
+ * @returns {{ ok: true, id: string, spec: { type: string, params?: Record<string, string|number|boolean> } } | { ok: false, code: 'bad_request', message: string }}
+ */
+export function validateSubscribeListPayload(payload) {
+  if (!payload || typeof payload !== 'object') {
+    return {
+      ok: false,
+      code: 'bad_request',
+      message: 'payload must be an object'
+    };
+  }
+  const any =
+    /** @type {{ id?: unknown, type?: unknown, params?: unknown }} */ (payload);
+
+  const id = typeof any.id === 'string' ? any.id : '';
+  if (id.length === 0) {
+    return {
+      ok: false,
+      code: 'bad_request',
+      message: 'payload.id must be a non-empty string'
+    };
+  }
+
+  const type = typeof any.type === 'string' ? any.type : '';
+  if (type.length === 0 || !SUBSCRIPTION_TYPES.has(type)) {
+    return {
+      ok: false,
+      code: 'bad_request',
+      message: `payload.type must be one of: ${Array.from(SUBSCRIPTION_TYPES).join(', ')}`
+    };
+  }
+
+  /** @type {Record<string, string|number|boolean> | undefined} */
+  let params;
+  if (any.params !== undefined) {
+    if (
+      !any.params ||
+      typeof any.params !== 'object' ||
+      Array.isArray(any.params)
+    ) {
+      return {
+        ok: false,
+        code: 'bad_request',
+        message: 'payload.params must be an object when provided'
+      };
+    }
+    params = /** @type {Record<string, string|number|boolean>} */ (any.params);
+  }
+
+  // Per-type param schemas
+  if (type === 'issue-detail') {
+    const id = String(params?.id ?? '').trim();
+    if (id.length === 0) {
+      return {
+        ok: false,
+        code: 'bad_request',
+        message: 'params.id must be a non-empty string'
+      };
+    }
+    params = { id };
+  } else if (type === 'search-issues') {
+    /** @type {Record<string, string|number|boolean>} */
+    const cleaned = {};
+    if (params && typeof params.q === 'string') cleaned.q = params.q;
+    if (params && typeof params.status === 'string') cleaned.status = params.status;
+    if (params && typeof params.type === 'string') cleaned.type = params.type;
+    if (params && typeof params.limit === 'number') cleaned.limit = params.limit;
+    if (params && typeof params.offset === 'number') cleaned.offset = params.offset;
+    params = Object.keys(cleaned).length > 0 ? cleaned : undefined;
+  } else if (type === 'closed-issues') {
+    /** @type {Record<string, string|number|boolean>} */
+    const cleaned = {};
+    if (params && 'since' in params) {
+      const since = params.since;
+      const n = typeof since === 'number' ? since : Number.NaN;
+      if (!Number.isFinite(n) || n < 0) {
+        return {
+          ok: false,
+          code: 'bad_request',
+          message: 'params.since must be a non-negative number (epoch ms)'
+        };
+      }
+      cleaned.since = n;
+    }
+    // Allow pagination params
+    if (params && typeof params.limit === 'number') cleaned.limit = params.limit;
+    if (params && typeof params.offset === 'number') cleaned.offset = params.offset;
+    params = Object.keys(cleaned).length > 0 ? cleaned : undefined;
+  } else {
+    // Allow pagination params (limit, offset) for all list types
+    /** @type {Record<string, string|number|boolean>} */
+    const cleaned = {};
+    if (params && typeof params.limit === 'number') cleaned.limit = params.limit;
+    if (params && typeof params.offset === 'number') cleaned.offset = params.offset;
+    params = Object.keys(cleaned).length > 0 ? cleaned : undefined;
+  }
+
+  return { ok: true, id, spec: { type, params } };
+}

package/server/watcher.js

@@ -0,0 +1,139 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { resolveWorkspaceDatabase } from './db.js';
+import { debug } from './logging.js';
+
+/**
+ * Watch the resolved workspace database target and invoke a callback after a
+ * debounce window.
+ *
+ * For SQLite workspaces this watches the DB file's parent directory and filters
+ * by file name. For non-SQLite backends (for example Dolt), this watches the
+ * workspace `.beads` directory.
+ *
+ * @param {string} root_dir - Project root directory (starting point for resolution).
+ * @param {() => void} onChange - Called when changes are detected.
+ * @param {{ debounce_ms?: number, cooldown_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, onChange, options = {}) {
+  const debounce_ms = options.debounce_ms ?? 250;
+  const cooldown_ms = options.cooldown_ms ?? 1000;
+  const log = debug('watcher');
+
+  /** @type {ReturnType<typeof setTimeout> | undefined} */
+  let timer;
+  /** @type {fs.FSWatcher | undefined} */
+  let watcher;
+  let cooldown_until = 0;
+  let current_path = '';
+  let current_dir = '';
+  let current_file = '';
+
+  /**
+   * Schedule the debounced onChange callback.
+   */
+  const schedule = () => {
+    if (timer) {
+      clearTimeout(timer);
+    }
+    timer = setTimeout(() => {
+      onChange();
+      cooldown_until = Date.now() + cooldown_ms;
+    }, debounce_ms);
+    timer.unref();
+  };
+
+  /**
+   * Attach a watcher to the directory containing the resolved DB path.
+   *
+   * @param {string} base_dir
+   * @param {string | undefined} explicit_db
+   */
+  const bind = (base_dir, explicit_db) => {
+    const resolved = resolveWorkspaceDatabase({ cwd: base_dir, explicit_db });
+    current_path = resolved.path;
+    if (pathIsDirectory(current_path)) {
+      current_dir = current_path;
+      current_file = '';
+    } else {
+      current_dir = path.dirname(current_path);
+      current_file = path.basename(current_path);
+    }
+    if (!resolved.exists) {
+      log(
+        'resolved workspace database missing: %s – Hint: set --db, export BEADS_DB, or run `bd init` in your workspace.',
+        current_path
+      );
+    }
+
+    // (Re)create watcher
+    try {
+      watcher = fs.watch(
+        current_dir,
+        { persistent: true },
+        (event_type, filename) => {
+          if (current_file && filename && String(filename) !== current_file) {
+            return;
+          }
+          if (event_type === 'change' || event_type === 'rename') {
+            if (Date.now() < cooldown_until) {
+              return;
+            }
+            log('fs %s %s', event_type, filename || '');
+            schedule();
+          }
+        }
+      );
+    } catch (err) {
+      log('unable to watch directory %s %o', current_dir, err);
+    }
+  };
+
+  // initial bind
+  bind(root_dir, options.explicit_db);
+
+  return {
+    get path() {
+      return current_path;
+    },
+    close() {
+      if (timer) {
+        clearTimeout(timer);
+        timer = undefined;
+      }
+      watcher?.close();
+    },
+    /**
+     * Re-resolve and reattach watcher when root_dir or explicit_db changes.
+     *
+     * @param {{ root_dir?: string, explicit_db?: string }} [opts]
+     */
+    rebind(opts = {}) {
+      const next_root = opts.root_dir ? String(opts.root_dir) : root_dir;
+      const next_explicit = opts.explicit_db ?? options.explicit_db;
+      const next_resolved = resolveWorkspaceDatabase({
+        cwd: next_root,
+        explicit_db: next_explicit
+      });
+      const next_path = next_resolved.path;
+      if (next_path !== current_path) {
+        // swap watcher
+        watcher?.close();
+        cooldown_until = 0;
+        bind(next_root, next_explicit);
+      }
+    }
+  };
+}
+
+/**
+ * @param {string} file_path
+ */
+function pathIsDirectory(file_path) {
+  try {
+    return fs.statSync(file_path).isDirectory();
+  } catch {
+    return false;
+  }
+}

package/server/watcher.test.js

@@ -0,0 +1,120 @@
+import { beforeEach, describe, expect, test, vi } from 'vitest';
+import { watchDb } from './watcher.js';
+
+/** @type {{ dir: string, cb: (event: string, filename?: string) => void, w: { close: () => void } }[]} */
+const watchers = [];
+
+vi.mock('node:fs', () => {
+  const watch = vi.fn((dir, _opts, cb) => {
+    // Minimal event emitter interface for FSWatcher
+    const handlers = /** @type {{ close: Array<() => void> }} */ ({
+      close: []
+    });
+    const w = {
+      close: () => handlers.close.forEach((fn) => fn())
+    };
+    watchers.push({ dir, cb, w });
+    return /** @type {any} */ (w);
+  });
+  return { default: { watch }, watch };
+});
+
+beforeEach(() => {
+  watchers.length = 0;
+  vi.useFakeTimers();
+  vi.spyOn(console, 'warn').mockImplementation(() => {});
+});
+
+describe('watchDb', () => {
+  test('debounces rapid change events', () => {
+    const calls = [];
+    const handle = watchDb('/repo', () => calls.push(null), {
+      debounce_ms: 100,
+      explicit_db: '/repo/.beads/ui.db'
+    });
+    expect(watchers.length).toBe(1);
+    const { cb } = watchers[0];
+
+    // Fire multiple changes in quick succession
+    cb('change', 'ui.db');
+    cb('change', 'ui.db');
+    cb('rename', 'ui.db');
+
+    // Nothing yet until debounce passes
+    expect(calls.length).toBe(0);
+    vi.advanceTimersByTime(99);
+    expect(calls.length).toBe(0);
+    vi.advanceTimersByTime(1);
+    expect(calls.length).toBe(1);
+
+    // Cleanup
+    handle.close();
+  });
+
+  test('ignores other filenames', () => {
+    const calls = [];
+    const handle = watchDb('/repo', () => calls.push(null), {
+      debounce_ms: 50,
+      explicit_db: '/repo/.beads/ui.db'
+    });
+    const { cb } = watchers[0];
+    cb('change', 'something-else.db');
+    vi.advanceTimersByTime(60);
+    expect(calls.length).toBe(0);
+    handle.close();
+  });
+
+  test('rebind attaches to new db path', () => {
+    const calls = [];
+    const handle = watchDb('/repo', () => calls.push(null), {
+      debounce_ms: 50,
+      explicit_db: '/repo/.beads/ui.db'
+    });
+    expect(watchers.length).toBe(1);
+    const first = watchers[0];
+
+    // Rebind to a different DB path
+    handle.rebind({ explicit_db: '/other/.beads/alt.db' });
+
+    // A new watcher is created
+    expect(watchers.length).toBe(2);
+    const second = watchers[1];
+
+    // Old watcher should ignore new file name
+    first.cb('change', 'ui.db');
+    vi.advanceTimersByTime(60);
+    expect(calls.length).toBe(0);
+
+    // New watcher reacts
+    second.cb('change', 'alt.db');
+    vi.advanceTimersByTime(60);
+    expect(calls.length).toBe(1);
+
+    handle.close();
+  });
+
+  test('ignores changes during cooldown window', () => {
+    const calls = [];
+    const handle = watchDb('/repo', () => calls.push(null), {
+      debounce_ms: 10,
+      cooldown_ms: 100,
+      explicit_db: '/repo/.beads/ui.db'
+    });
+    const { cb } = watchers[0];
+
+    cb('change', 'ui.db');
+    vi.advanceTimersByTime(10);
+    expect(calls.length).toBe(1);
+
+    cb('change', 'ui.db');
+    vi.advanceTimersByTime(10);
+    expect(calls.length).toBe(1);
+
+    vi.advanceTimersByTime(100);
+    cb('change', 'ui.db');
+    vi.advanceTimersByTime(10);
+    expect(calls.length).toBe(2);
+
+    handle.close();
+  });
+});

package/server/ws.comments.test.js

@@ -0,0 +1,262 @@
+import { beforeEach, describe, expect, test, vi } from 'vitest';
+import { getGitUserName, runBd, runBdJson } from './bd.js';
+import { handleMessage } from './ws.js';
+
+vi.mock('./bd.js', () => ({
+  runBd: vi.fn(),
+  runBdJson: vi.fn(),
+  getGitUserName: vi.fn()
+}));
+
+function makeStubSocket() {
+  return {
+    sent: /** @type {string[]} */ ([]),
+    readyState: 1,
+    OPEN: 1,
+    /** @param {string} msg */
+    send(msg) {
+      this.sent.push(String(msg));
+    }
+  };
+}
+
+describe('get-comments handler', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  test('returns comments array on success', async () => {
+    const rj = /** @type {import('vitest').Mock} */ (runBdJson);
+    const comments = [
+      {
+        id: 1,
+        issue_id: 'UI-1',
+        author: 'alice',
+        text: 'First comment',
+        created_at: '2025-01-01T00:00:00Z'
+      },
+      {
+        id: 2,
+        issue_id: 'UI-1',
+        author: 'bob',
+        text: 'Second comment',
+        created_at: '2025-01-02T00:00:00Z'
+      }
+    ];
+    rj.mockResolvedValueOnce({ code: 0, stdoutJson: comments });
+
+    const ws = makeStubSocket();
+    await handleMessage(
+      /** @type {any} */ (ws),
+      Buffer.from(
+        JSON.stringify({
+          id: 'req-1',
+          type: /** @type {any} */ ('get-comments'),
+          payload: { id: 'UI-1' }
+        })
+      )
+    );
+
+    expect(ws.sent.length).toBe(1);
+    const reply = JSON.parse(ws.sent[0]);
+    expect(reply.ok).toBe(true);
+    expect(reply.payload).toEqual(comments);
+
+    // Verify bd was called with correct args
+    expect(rj).toHaveBeenCalledWith(['comments', 'UI-1', '--json']);
+  });
+
+  test('returns error when issue id missing', async () => {
+    const ws = makeStubSocket();
+    await handleMessage(
+      /** @type {any} */ (ws),
+      Buffer.from(
+        JSON.stringify({
+          id: 'req-2',
+          type: /** @type {any} */ ('get-comments'),
+          payload: {}
+        })
+      )
+    );
+
+    expect(ws.sent.length).toBe(1);
+    const reply = JSON.parse(ws.sent[0]);
+    expect(reply.ok).toBe(false);
+    expect(reply.error.code).toBe('bad_request');
+  });
+
+  test('returns error when bd command fails', async () => {
+    const rj = /** @type {import('vitest').Mock} */ (runBdJson);
+    rj.mockResolvedValueOnce({ code: 1, stderr: 'Issue not found' });
+
+    const ws = makeStubSocket();
+    await handleMessage(
+      /** @type {any} */ (ws),
+      Buffer.from(
+        JSON.stringify({
+          id: 'req-3',
+          type: /** @type {any} */ ('get-comments'),
+          payload: { id: 'UI-999' }
+        })
+      )
+    );
+
+    expect(ws.sent.length).toBe(1);
+    const reply = JSON.parse(ws.sent[0]);
+    expect(reply.ok).toBe(false);
+    expect(reply.error.code).toBe('bd_error');
+  });
+});
+
+describe('add-comment handler', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  test('adds comment with git author and returns updated comments', async () => {
+    const gitUser = /** @type {import('vitest').Mock} */ (getGitUserName);
+    const rb = /** @type {import('vitest').Mock} */ (runBd);
+    const rj = /** @type {import('vitest').Mock} */ (runBdJson);
+
+    // Mock git config user.name
+    gitUser.mockResolvedValueOnce('Test User');
+    // Mock bd comment command
+    rb.mockResolvedValueOnce({ code: 0, stdout: '', stderr: '' });
+    // Mock bd comments --json (returns updated list)
+    const updatedComments = [
+      {
+        id: 1,
+        issue_id: 'UI-1',
+        author: 'Test User',
+        text: 'New comment',
+        created_at: '2025-01-01T00:00:00Z'
+      }
+    ];
+    rj.mockResolvedValueOnce({ code: 0, stdoutJson: updatedComments });
+
+    const ws = makeStubSocket();
+    await handleMessage(
+      /** @type {any} */ (ws),
+      Buffer.from(
+        JSON.stringify({
+          id: 'req-4',
+          type: /** @type {any} */ ('add-comment'),
+          payload: { id: 'UI-1', text: 'New comment' }
+        })
+      )
+    );
+
+    expect(ws.sent.length).toBe(1);
+    const reply = JSON.parse(ws.sent[0]);
+    expect(reply.ok).toBe(true);
+    expect(reply.payload).toEqual(updatedComments);
+
+    // Verify bd was called with correct args including --author
+    expect(rb).toHaveBeenCalledWith([
+      'comment',
+      'UI-1',
+      'New comment',
+      '--author',
+      'Test User'
+    ]);
+  });
+
+  test('adds comment without author when git user name is empty', async () => {
+    const gitUser = /** @type {import('vitest').Mock} */ (getGitUserName);
+    const rb = /** @type {import('vitest').Mock} */ (runBd);
+    const rj = /** @type {import('vitest').Mock} */ (runBdJson);
+
+    // Mock empty git user name
+    gitUser.mockResolvedValueOnce('');
+    // Mock bd comment command
+    rb.mockResolvedValueOnce({ code: 0, stdout: '', stderr: '' });
+    // Mock bd comments --json
+    rj.mockResolvedValueOnce({ code: 0, stdoutJson: [] });
+
+    const ws = makeStubSocket();
+    await handleMessage(
+      /** @type {any} */ (ws),
+      Buffer.from(
+        JSON.stringify({
+          id: 'req-5',
+          type: /** @type {any} */ ('add-comment'),
+          payload: { id: 'UI-1', text: 'Anonymous comment' }
+        })
+      )
+    );
+
+    expect(ws.sent.length).toBe(1);
+    const reply = JSON.parse(ws.sent[0]);
+    expect(reply.ok).toBe(true);
+
+    // Verify bd was called without --author
+    expect(rb).toHaveBeenCalledWith(['comment', 'UI-1', 'Anonymous comment']);
+  });
+
+  test('returns error when text is empty', async () => {
+    const ws = makeStubSocket();
+    await handleMessage(
+      /** @type {any} */ (ws),
+      Buffer.from(
+        JSON.stringify({
+          id: 'req-6',
+          type: /** @type {any} */ ('add-comment'),
+          payload: { id: 'UI-1', text: '' }
+        })
+      )
+    );
+
+    expect(ws.sent.length).toBe(1);
+    const reply = JSON.parse(ws.sent[0]);
+    expect(reply.ok).toBe(false);
+    expect(reply.error.code).toBe('bad_request');
+  });
+
+  test('returns error when id is missing', async () => {
+    const ws = makeStubSocket();
+    await handleMessage(
+      /** @type {any} */ (ws),
+      Buffer.from(
+        JSON.stringify({
+          id: 'req-7',
+          type: /** @type {any} */ ('add-comment'),
+          payload: { text: 'Some text' }
+        })
+      )
+    );
+
+    expect(ws.sent.length).toBe(1);
+    const reply = JSON.parse(ws.sent[0]);
+    expect(reply.ok).toBe(false);
+    expect(reply.error.code).toBe('bad_request');
+  });
+
+  test('returns error when bd comment command fails', async () => {
+    const gitUser = /** @type {import('vitest').Mock} */ (getGitUserName);
+    const rb = /** @type {import('vitest').Mock} */ (runBd);
+
+    gitUser.mockResolvedValueOnce('Test User');
+    rb.mockResolvedValueOnce({
+      code: 1,
+      stdout: '',
+      stderr: 'Issue not found'
+    });
+
+    const ws = makeStubSocket();
+    await handleMessage(
+      /** @type {any} */ (ws),
+      Buffer.from(
+        JSON.stringify({
+          id: 'req-8',
+          type: /** @type {any} */ ('add-comment'),
+          payload: { id: 'UI-999', text: 'Comment' }
+        })
+      )
+    );
+
+    expect(ws.sent.length).toBe(1);
+    const reply = JSON.parse(ws.sent[0]);
+    expect(reply.ok).toBe(false);
+    expect(reply.error.code).toBe('bd_error');
+  });
+});