@rsktash/beads-ui 0.1.51 → 0.10.3

package/server/queries.js

@@ -0,0 +1,247 @@
+// SQL used by the read-only Hono routes. Schema is owned by the Go CLI; we
+// only SELECT + the occasional mutation. Both engines accept the same ANSI
+// SQL we use here (LIKE patterns, IN clauses, parameterised values).
+//
+// Placeholders are `?` style. The pg adapter rewrites them to $N at runtime.
+
+import { rowToComment, rowToDependency, rowToIssue } from './types.js';
+
+export async function getConfigValue(db, key) {
+  const r = await db.one('SELECT value FROM config WHERE key = ?', [key]);
+  return r ? String(r.value) : '';
+}
+
+// Computed columns shared by list/ready/detail. Keeps the JSON shape stable
+// across endpoints (parent_id, parent_title, total_children, closed_children,
+// blocked_by_count, comment_count).
+const ENRICHED_COMPUTED = `
+  (SELECT depends_on_id FROM dependencies d
+    WHERE d.issue_id = i.id AND d.type = 'parent-child' LIMIT 1) AS parent_id,
+  (SELECT p.title FROM dependencies d JOIN issues p ON p.id = d.depends_on_id
+    WHERE d.issue_id = i.id AND d.type = 'parent-child' LIMIT 1) AS parent_title,
+  (SELECT COUNT(*) FROM dependencies d
+    WHERE d.depends_on_id = i.id AND d.type = 'parent-child') AS total_children,
+  (SELECT COUNT(*) FROM dependencies d JOIN issues c ON c.id = d.issue_id
+    WHERE d.depends_on_id = i.id AND d.type = 'parent-child'
+      AND c.status = 'closed') AS closed_children,
+  (SELECT COUNT(*) FROM dependencies d JOIN issues b ON b.id = d.depends_on_id
+    WHERE d.issue_id = i.id AND d.type = 'blocks'
+      AND b.status NOT IN ('closed', 'pinned')) AS blocked_by_count,
+  (SELECT COUNT(*) FROM comments c WHERE c.issue_id = i.id) AS comment_count
+`;
+
+// Full row + enrichment — used by getIssue (detail page wants everything).
+const ENRICHED_FULL = `i.*, ${ENRICHED_COMPUTED}`;
+
+// Slim row + enrichment — used by listIssues and readyIssues. Drops the heavy
+// markdown bodies (description/design/acceptance_criteria/notes) and the JSON
+// blobs (metadata/payload) which the board, list, and search dialog never
+// render. On epic-heavy projects this cuts the polled response by 50–80%.
+// rowToIssue (server/types.js) defaults missing fields to '' so the public
+// JSON shape stays the same — clients still see those keys, just empty.
+const ENRICHED_SLIM = `
+  i.id, i.title, i.status, i.priority, i.issue_type,
+  i.assignee, i.estimated_minutes, i.content_hash,
+  i.created_at, i.created_by, i.owner,
+  i.updated_at, i.started_at, i.closed_at, i.due_at, i.defer_until,
+  i.closed_by_session, i.close_reason,
+  i.external_ref, i.spec_id, i.source_repo, i.source_system,
+  i.sender, i.ephemeral, i.pinned, i.is_template,
+  i.wisp_type, i.mol_type, i.role_type, i.event_kind,
+  i.actor, i.target,
+  ${ENRICHED_COMPUTED}
+`;
+
+export async function listIssues(db, filters = {}, limit = 0) {
+  const where = [];
+  const args = [];
+  if (filters.status) {
+    where.push('i.status = ?');
+    args.push(filters.status);
+  }
+  if (filters.status_in) {
+    const list = String(filters.status_in)
+      .split(',')
+      .map((s) => s.trim())
+      .filter(Boolean);
+    if (list.length) {
+      where.push(`i.status IN (${list.map(() => '?').join(',')})`);
+      args.push(...list);
+    }
+  }
+  if (filters.type) {
+    where.push('i.issue_type = ?');
+    args.push(filters.type);
+  }
+  if (filters.assignee) {
+    where.push('i.assignee = ?');
+    args.push(filters.assignee);
+  }
+  if (filters.priority !== undefined && filters.priority !== null && filters.priority !== '') {
+    where.push('i.priority = ?');
+    args.push(Number(filters.priority));
+  }
+  let sql = `SELECT ${ENRICHED_SLIM} FROM issues i`;
+  if (where.length) sql += ' WHERE ' + where.join(' AND ');
+  // ORDER BY: priority is irrelevant once an issue is closed — caller can ask
+  // for closed_at_desc to get a "recently finished" feed. Default keeps
+  // priority primary with updated_at DESC as tiebreaker so stale work sinks.
+  // NULLS LAST handles postgres (defaults to NULLS FIRST on DESC); sqlite
+  // already places NULLs last by default but accepts the keyword.
+  if (filters.order === 'closed_at_desc') {
+    sql += ' ORDER BY i.closed_at DESC NULLS LAST, i.created_at DESC';
+  } else {
+    sql += ' ORDER BY i.priority ASC, i.updated_at DESC NULLS LAST';
+  }
+  if (limit > 0) sql += ` LIMIT ${Number(limit) | 0}`;
+  const rows = await db.all(sql, args);
+  return rows.map(rowToIssue);
+}
+
+export async function getIssue(db, id) {
+  const sql = `SELECT ${ENRICHED_FULL} FROM issues i WHERE i.id = ?`;
+  const r = await db.one(sql, [id]);
+  return r ? rowToIssue(r) : null;
+}
+
+export async function listLabels(db, issueId) {
+  const rows = await db.all(
+    'SELECT label FROM labels WHERE issue_id = ? ORDER BY label',
+    [issueId],
+  );
+  return rows.map((r) => r.label);
+}
+
+// listBlockedBy returns up to `limit` issue ids/titles that currently block
+// the given issue. Used by the IssueCard "blocked by" badges.
+export async function listBlockedBy(db, issueId, limit = 5) {
+  const rows = await db.all(
+    `SELECT b.id, b.title FROM dependencies d
+       JOIN issues b ON b.id = d.depends_on_id
+       WHERE d.issue_id = ? AND d.type = 'blocks'
+         AND b.status NOT IN ('closed', 'pinned')
+       ORDER BY b.created_at
+       LIMIT ${Number(limit) | 0}`,
+    [issueId],
+  );
+  return rows;
+}
+
+// listBlocks returns up to `limit` issue ids/titles currently blocked BY the
+// given issue (i.e., rows where this issue is depends_on_id, type='blocks').
+// Mirror of listBlockedBy with reversed direction; powers the "Blocks" card
+// in the issue-detail sidebar.
+export async function listBlocks(db, issueId, limit = 10) {
+  const rows = await db.all(
+    `SELECT b.id, b.title FROM dependencies d
+       JOIN issues b ON b.id = d.issue_id
+       WHERE d.depends_on_id = ? AND d.type = 'blocks'
+         AND b.status NOT IN ('closed', 'pinned')
+       ORDER BY b.created_at
+       LIMIT ${Number(limit) | 0}`,
+    [issueId],
+  );
+  return rows;
+}
+
+// listChildren returns the parent-child children of an issue (where THIS
+// issue is the depends_on_id, type='parent-child'). Used by the metadata
+// sidebar's Children card.
+export async function listChildren(db, parentId) {
+  const rows = await db.all(
+    `SELECT c.id, c.title, c.status, c.priority, c.issue_type
+       FROM dependencies d
+       JOIN issues c ON c.id = d.issue_id
+       WHERE d.depends_on_id = ? AND d.type = 'parent-child'
+       ORDER BY c.priority ASC, c.created_at ASC`,
+    [parentId],
+  );
+  return rows;
+}
+
+export async function listDependencies(db, issueId) {
+  const rows = await db.all(
+    'SELECT * FROM dependencies WHERE issue_id = ? OR depends_on_id = ? ORDER BY created_at',
+    [issueId, issueId],
+  );
+  return rows.map(rowToDependency);
+}
+
+export async function listComments(db, issueId) {
+  const rows = await db.all(
+    'SELECT * FROM comments WHERE issue_id = ? ORDER BY created_at',
+    [issueId],
+  );
+  return rows.map(rowToComment);
+}
+
+export async function readyIssues(db) {
+  const sql = `
+    SELECT ${ENRICHED_SLIM} FROM issues i
+    WHERE i.status = 'open'
+      AND i.ephemeral = 0
+      AND i.is_template = 0
+      AND (i.defer_until IS NULL OR i.defer_until <= ?)
+      AND NOT EXISTS (
+          SELECT 1 FROM dependencies d
+          JOIN issues blocker ON blocker.id = d.depends_on_id
+          WHERE d.issue_id = i.id
+            AND d.type = 'blocks'
+            AND blocker.status NOT IN ('closed', 'pinned')
+      )
+    ORDER BY i.priority ASC, i.updated_at DESC NULLS LAST`;
+  const now = new Date().toISOString();
+  const rows = await db.all(sql, [now]);
+  return rows.map(rowToIssue);
+}
+
+// ---------- mutations (subset: comments + labels only) ----------
+
+export async function addComment(db, { id, issueId, author, text }) {
+  const now = new Date().toISOString();
+  await db.exec(
+    `INSERT INTO comments (id, issue_id, author, text, created_at)
+     VALUES (?, ?, ?, ?, ?)`,
+    [id, issueId, author, text, now],
+  );
+  return { id, issue_id: issueId, author, text, created_at: now };
+}
+
+export async function deleteComment(db, commentId) {
+  await db.exec('DELETE FROM comments WHERE id = ?', [commentId]);
+}
+
+export async function addLabel(db, issueId, label) {
+  // idempotent — re-adding the same (issue, label) is a no-op
+  try {
+    await db.exec(
+      'INSERT INTO labels (issue_id, label) VALUES (?, ?)',
+      [issueId, label],
+    );
+  } catch (err) {
+    if (!/UNIQUE|duplicate/i.test(String(err?.message))) throw err;
+  }
+}
+
+export async function removeLabel(db, issueId, label) {
+  await db.exec(
+    'DELETE FROM labels WHERE issue_id = ? AND label = ?',
+    [issueId, label],
+  );
+}
+
+export async function listProjects(db) {
+  if (db.driver !== 'postgres') return [];
+  const sql = `
+    SELECT s.schema_name AS prefix
+    FROM information_schema.schemata s
+    WHERE s.schema_name NOT IN ('pg_catalog', 'information_schema', 'pg_toast', 'public')
+      AND s.schema_name NOT LIKE 'pg_%'
+      AND EXISTS (
+        SELECT 1 FROM information_schema.tables t
+        WHERE t.table_schema = s.schema_name AND t.table_name = 'config'
+      )
+    ORDER BY s.schema_name`;
+  const rows = await db.all(sql);
+  return rows.map((r) => ({ prefix: r.prefix }));
+}

package/server/routes/auth.js

@@ -0,0 +1,27 @@
+import { Hono } from 'hono';
+import { login, logout } from '../auth.js';
+
+export function authRouter(auth) {
+  const r = new Hono();
+
+  r.post('/login', async (c) => {
+    if (!auth.enabled) return c.json({ error: 'auth disabled' }, 400);
+    const body = await c.req.json().catch(() => ({}));
+    const { username, password } = body;
+    if (!username || !password) {
+      return c.json({ error: 'username and password are required' }, 400);
+    }
+    const result = login(auth, username, password);
+    if (!result) return c.json({ error: 'invalid credentials' }, 401);
+    return c.json(result);
+  });
+
+  r.post('/logout', async (c) => {
+    if (!auth.enabled) return c.json({ ok: true });
+    const token = c.get('token');
+    if (token) logout(auth, token);
+    return c.json({ ok: true });
+  });
+
+  return r;
+}

package/server/routes/issues.js

@@ -0,0 +1,120 @@
+import { Hono } from 'hono';
+import { etag } from 'hono/etag';
+import { randomUUID } from 'node:crypto';
+import {
+  addComment,
+  addLabel,
+  deleteComment,
+  getIssue,
+  listBlockedBy,
+  listBlocks,
+  listChildren,
+  listComments,
+  listDependencies,
+  listIssues,
+  listLabels,
+  readyIssues,
+  removeLabel,
+} from '../queries.js';
+
+// Reads the per-request project db from c.get('db'). Set by the project-
+// scope middleware in index.js. No db is captured at registration time so
+// the same router serves every project.
+export function issuesRouter() {
+  const r = new Hono();
+
+  // ETag for GET responses: the board and detail pages poll every 5s, so
+  // most refetches return identical bodies. The middleware hashes the
+  // serialized response and replies 304 with an empty body when the
+  // client's If-None-Match header matches — saves bandwidth and the
+  // client-side parse/render. Skipped for mutations.
+  //
+  // Cache-Control "private, no-cache" tells the browser to keep the body
+  // in the per-origin disk cache and always revalidate via If-None-Match.
+  // Without this header the browser may not cache JSON responses at all,
+  // which would mean ETag is set but never sent back — neutering the 304
+  // path. "private" prevents shared caches from storing the data.
+  const etagMiddleware = etag();
+  r.use('/*', async (c, next) => {
+    if (c.req.method !== 'GET') return next();
+    await etagMiddleware(c, next);
+    if (c.res.status === 200 || c.res.status === 304) {
+      c.res.headers.set('Cache-Control', 'private, no-cache');
+    }
+  });
+
+  r.get('/', async (c) => {
+    const db = c.get('db');
+    const q = c.req.query();
+    const limit = q.limit ? Number(q.limit) : 0;
+    const issues = await listIssues(db, q, limit);
+    return c.json({ issues });
+  });
+
+  r.get('/ready', async (c) => {
+    const db = c.get('db');
+    const issues = await readyIssues(db);
+    return c.json({ issues });
+  });
+
+  r.get('/:id', async (c) => {
+    const db = c.get('db');
+    const id = c.req.param('id');
+    const issue = await getIssue(db, id);
+    if (!issue) return c.json({ error: 'not found' }, 404);
+    const [labels, deps, comments, blockedBy, blocks, children] = await Promise.all([
+      listLabels(db, id),
+      listDependencies(db, id),
+      listComments(db, id),
+      listBlockedBy(db, id, 5),
+      listBlocks(db, id, 10),
+      listChildren(db, id),
+    ]);
+    return c.json({
+      issue, labels, dependencies: deps, comments,
+      blocked_by: blockedBy,
+      blocks,
+      children,
+    });
+  });
+
+  r.post('/:id/comments', async (c) => {
+    const db = c.get('db');
+    const issueId = c.req.param('id');
+    const body = await c.req.json().catch(() => ({}));
+    const text = String(body.text || '').trim();
+    if (!text) return c.json({ error: 'text is required' }, 400);
+    const user = c.get('user') || { username: 'anon' };
+    const comment = await addComment(db, {
+      id: randomUUID(),
+      issueId,
+      author: user.username,
+      text,
+    });
+    return c.json({ comment });
+  });
+
+  r.delete('/:id/comments/:commentId', async (c) => {
+    const db = c.get('db');
+    await deleteComment(db, c.req.param('commentId'));
+    return c.json({ ok: true });
+  });
+
+  r.post('/:id/labels', async (c) => {
+    const db = c.get('db');
+    const issueId = c.req.param('id');
+    const body = await c.req.json().catch(() => ({}));
+    const label = String(body.label || '').trim();
+    if (!label) return c.json({ error: 'label is required' }, 400);
+    await addLabel(db, issueId, label);
+    return c.json({ ok: true, label });
+  });
+
+  r.delete('/:id/labels/:label', async (c) => {
+    const db = c.get('db');
+    await removeLabel(db, c.req.param('id'), c.req.param('label'));
+    return c.json({ ok: true });
+  });
+
+  return r;
+}

package/server/routes/stream.js

@@ -0,0 +1,111 @@
+// SSE: per-project change stream. Server polls a cheap "fingerprint" query
+// every WATCH_MS and broadcasts a `tick` event when it changes. Clients open
+// an EventSource and invalidate their cached queries on tick.
+//
+// Why poll-and-broadcast: bd is mutated by the CLI, agents, and the web
+// server. Postgres LISTEN/NOTIFY would catch all of them but only on pg, and
+// requires triggers. A 1.5s SQL fingerprint (max(updated_at), count(*)) is
+// cheap enough for the polling rate we want, works on both engines, and
+// scales: N connected browsers per project share one watcher.
+//
+// Fingerprint covers issues, dependencies, comments, and labels — anything
+// the board / list / detail page renders.
+
+const WATCH_MS = 1500;        // server poll cadence
+const HEARTBEAT_MS = 25000;   // SSE ping to keep proxies from killing the stream
+
+// project prefix -> { db, hash, timer, subs:Set<{enqueue,close}> }
+const watchers = new Map();
+
+// stamp normalises whatever the driver returns for a timestamp column
+// (string from sqlite, Date from pg) into a stable string for hashing.
+const stamp = (v) => {
+  if (v == null) return '';
+  if (v instanceof Date) return v.toISOString();
+  return String(v);
+};
+
+async function fingerprint(db) {
+  // Cheap "did anything change?" probe: max-of-mutable-timestamp + row count
+  // for each table the UI cares about. Portable across sqlite/postgres.
+  const i = await db.one(`SELECT MAX(updated_at) AS m, COUNT(*) AS c FROM issues`);
+  const d = await db.one(`SELECT MAX(created_at) AS m, COUNT(*) AS c FROM dependencies`);
+  const cm = await db.one(`SELECT MAX(created_at) AS m, COUNT(*) AS c FROM comments`);
+  const l = await db.one(`SELECT COUNT(*) AS c FROM labels`);
+  return [
+    `i:${stamp(i?.m)}/${i?.c ?? 0}`,
+    `d:${stamp(d?.m)}/${d?.c ?? 0}`,
+    `c:${stamp(cm?.m)}/${cm?.c ?? 0}`,
+    `l:${l?.c ?? 0}`,
+  ].join('|');
+}
+
+function startWatcher(prefix, db) {
+  const w = { db, hash: '', subs: new Set(), timer: null };
+  watchers.set(prefix, w);
+  const tick = async () => {
+    if (w.subs.size === 0) {
+      // No subscribers — stop polling and let the watcher idle out.
+      clearInterval(w.timer);
+      watchers.delete(prefix);
+      return;
+    }
+    let next;
+    try { next = await fingerprint(db); } catch (err) {
+      // Don't kill the watcher on transient db errors.
+      if (process.env.DEBUG) console.error('stream fingerprint failed:', err.message);
+      return;
+    }
+    if (next !== w.hash) {
+      w.hash = next;
+      const payload = `event: tick\ndata: ${next}\n\n`;
+      for (const sub of w.subs) {
+        try { sub.enqueue(payload); } catch {}
+      }
+    }
+  };
+  w.timer = setInterval(tick, WATCH_MS);
+  // prime hash so the first real change emits, but the initial open doesn't
+  fingerprint(db).then((h) => { w.hash = h; }).catch(() => {});
+  return w;
+}
+
+export function streamHandler(c) {
+  const prefix = c.get('project');
+  const db = c.get('db');
+  if (!prefix || !db) return c.json({ error: 'no project' }, 400);
+
+  const w = watchers.get(prefix) || startWatcher(prefix, db);
+
+  const stream = new ReadableStream({
+    start(controller) {
+      const enc = new TextEncoder();
+      const sub = {
+        enqueue: (s) => controller.enqueue(enc.encode(s)),
+        close: () => { try { controller.close(); } catch {} },
+      };
+      w.subs.add(sub);
+      // Initial hello + heartbeat loop.
+      sub.enqueue(`event: hello\ndata: ${w.hash}\n\n`);
+      const hb = setInterval(() => {
+        try { sub.enqueue(`: ping\n\n`); } catch {}
+      }, HEARTBEAT_MS);
+      // Cleanup when the client disconnects.
+      const onClose = () => {
+        clearInterval(hb);
+        w.subs.delete(sub);
+        sub.close();
+      };
+      c.req.raw.signal?.addEventListener('abort', onClose);
+    },
+  });
+
+  return new Response(stream, {
+    headers: {
+      'Content-Type': 'text/event-stream; charset=utf-8',
+      'Cache-Control': 'no-cache, no-transform',
+      'Connection': 'keep-alive',
+      'X-Accel-Buffering': 'no', // disable nginx buffering
+    },
+  });
+}

package/server/types.js

@@ -0,0 +1,83 @@
+// Row-shape helpers shared by the route handlers. Matches the public types
+// in the Go side (beads.Issue, beads.Dependency, beads.Comment).
+
+export function rowToIssue(r) {
+  if (!r) return null;
+  return {
+    id: r.id,
+    content_hash: r.content_hash || '',
+    title: r.title,
+    description: r.description || '',
+    design: r.design || '',
+    acceptance_criteria: r.acceptance_criteria || '',
+    notes: r.notes || '',
+    status: r.status,
+    priority: Number(r.priority),
+    issue_type: r.issue_type,
+    assignee: r.assignee || '',
+    estimated_minutes: Number(r.estimated_minutes || 0),
+    created_at: toISO(r.created_at),
+    created_by: r.created_by || '',
+    owner: r.owner || '',
+    updated_at: toISO(r.updated_at),
+    started_at: toISO(r.started_at),
+    closed_at: toISO(r.closed_at),
+    closed_by_session: r.closed_by_session || '',
+    external_ref: r.external_ref || '',
+    spec_id: r.spec_id || '',
+    metadata: r.metadata || '{}',
+    source_repo: r.source_repo || '',
+    source_system: r.source_system || '',
+    close_reason: r.close_reason || '',
+    sender: r.sender || '',
+    ephemeral: !!Number(r.ephemeral),
+    pinned: !!Number(r.pinned),
+    is_template: !!Number(r.is_template),
+    wisp_type: r.wisp_type || '',
+    mol_type: r.mol_type || '',
+    role_type: r.role_type || '',
+    event_kind: r.event_kind || '',
+    actor: r.actor || '',
+    target: r.target || '',
+    payload: r.payload || '',
+    due_at: toISO(r.due_at),
+    defer_until: toISO(r.defer_until),
+    // Enriched fields populated by ENRICHED SELECT (queries.js). Optional —
+    // detail/list endpoints set them; raw inserts won't have them.
+    parent_id: r.parent_id || '',
+    parent_title: r.parent_title || '',
+    total_children: r.total_children != null ? Number(r.total_children) : 0,
+    closed_children: r.closed_children != null ? Number(r.closed_children) : 0,
+    blocked_by_count: r.blocked_by_count != null ? Number(r.blocked_by_count) : 0,
+    comment_count: r.comment_count != null ? Number(r.comment_count) : 0,
+  };
+}
+
+export function rowToDependency(r) {
+  return {
+    issue_id: r.issue_id,
+    depends_on_id: r.depends_on_id,
+    type: r.type,
+    created_at: toISO(r.created_at),
+    created_by: r.created_by || '',
+    metadata: r.metadata || '{}',
+    thread_id: r.thread_id || '',
+  };
+}
+
+export function rowToComment(r) {
+  return {
+    id: r.id,
+    issue_id: r.issue_id,
+    author: r.author,
+    text: r.text,
+    created_at: toISO(r.created_at),
+  };
+}
+
+function toISO(v) {
+  if (!v) return null;
+  if (v instanceof Date) return v.toISOString();
+  // sqlite returns 'YYYY-MM-DD HH:MM:SS' or ISO already; postgres returns Date
+  return new Date(v).toISOString();
+}