@rsktash/beads-ui 0.1.0

package/.github/workflows/publish.yml

@@ -0,0 +1,28 @@
+name: Publish to npm
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          registry-url: https://registry.npmjs.org
+
+      - run: npm ci
+
+      - run: npm run build
+
+      - run: npm publish --provenance --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/app/protocol.js

@@ -0,0 +1,216 @@
+/**
+ * Protocol definitions for beads-ui WebSocket communication.
+ *
+ * Conventions
+ * - All messages are JSON objects.
+ * - Client → Server uses RequestEnvelope.
+ * - Server → Client uses ReplyEnvelope.
+ * - Every request is correlated by `id` in replies.
+ * - Server can also send unsolicited events (e.g., subscription `snapshot`).
+ */
+
+/** @typedef {'list-issues'|'update-status'|'edit-text'|'update-priority'|'create-issue'|'list-ready'|'dep-add'|'dep-remove'|'epic-status'|'update-assignee'|'label-add'|'label-remove'|'subscribe-list'|'unsubscribe-list'|'snapshot'|'upsert'|'delete'|'get-comments'|'add-comment'|'delete-issue'|'list-workspaces'|'set-workspace'|'get-workspace'|'workspace-changed'} MessageType */
+
+/**
+ * @typedef {Object} RequestEnvelope
+ * @property {string} id - Unique id to correlate request/response.
+ * @property {MessageType} type - Message type.
+ * @property {unknown} [payload] - Message payload.
+ */
+
+/**
+ * @typedef {Object} ErrorObject
+ * @property {string} code - Stable error code.
+ * @property {string} message - Human-readable message.
+ * @property {unknown} [details] - Optional extra info for debugging.
+ */
+
+/**
+ * @typedef {Object} ReplyEnvelope
+ * @property {string} id - Correlates to the originating request.
+ * @property {boolean} ok - True when request succeeded; false on error.
+ * @property {MessageType} type - Echoes request type (or event type).
+ * @property {unknown} [payload] - Response payload.
+ * @property {ErrorObject} [error] - Present when ok=false.
+ */
+
+/** @type {MessageType[]} */
+export const MESSAGE_TYPES = /** @type {const} */ ([
+  'list-issues',
+  'update-status',
+  'edit-text',
+  'update-priority',
+  'create-issue',
+  'list-ready',
+  'dep-add',
+  'dep-remove',
+  'epic-status',
+  'update-assignee',
+  'label-add',
+  'label-remove',
+  'subscribe-list',
+  'unsubscribe-list',
+  // vNext per-subscription full-issue push events
+  'snapshot',
+  'upsert',
+  'delete',
+  // Comments
+  'get-comments',
+  'add-comment',
+  // Delete issue
+  'delete-issue',
+  // Workspace management
+  'list-workspaces',
+  'set-workspace',
+  'get-workspace',
+  'workspace-changed'
+]);
+
+/**
+ * Generate a lexically sortable request id.
+ *
+ * @returns {string}
+ */
+export function nextId() {
+  const now = Date.now().toString(36);
+  const rand = Math.random().toString(36).slice(2, 8);
+  return `${now}-${rand}`;
+}
+
+/**
+ * Create a request envelope.
+ *
+ * @param {MessageType} type - Message type.
+ * @param {unknown} [payload] - Message payload.
+ * @param {string} [id] - Optional id; generated if omitted.
+ * @returns {RequestEnvelope}
+ */
+export function makeRequest(type, payload, id = nextId()) {
+  return { id, type, payload };
+}
+
+/**
+ * Create a successful reply envelope for a given request.
+ *
+ * @param {RequestEnvelope} req - Original request.
+ * @param {unknown} [payload] - Reply payload.
+ * @returns {ReplyEnvelope}
+ */
+export function makeOk(req, payload) {
+  return { id: req.id, ok: true, type: req.type, payload };
+}
+
+/**
+ * Create an error reply envelope for a given request.
+ *
+ * @param {RequestEnvelope} req - Original request.
+ * @param {string} code
+ * @param {string} message
+ * @param {unknown} [details]
+ * @returns {ReplyEnvelope}
+ */
+export function makeError(req, code, message, details) {
+  return {
+    id: req.id,
+    ok: false,
+    type: req.type,
+    error: { code, message, details }
+  };
+}
+
+/**
+ * Check if a value is a plain object.
+ *
+ * @param {unknown} value
+ * @returns {value is Record<string, unknown>}
+ */
+function isRecord(value) {
+  return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+
+/**
+ * Type guard for MessageType values.
+ *
+ * @param {unknown} value
+ * @returns {value is MessageType}
+ */
+export function isMessageType(value) {
+  return (
+    typeof value === 'string' &&
+    MESSAGE_TYPES.includes(/** @type {MessageType} */ (value))
+  );
+}
+
+/**
+ * Type guard for RequestEnvelope.
+ *
+ * @param {unknown} value
+ * @returns {value is RequestEnvelope}
+ */
+export function isRequest(value) {
+  if (!isRecord(value)) {
+    return false;
+  }
+  return (
+    typeof value.id === 'string' &&
+    typeof value.type === 'string' &&
+    (value.payload === undefined || 'payload' in value)
+  );
+}
+
+/**
+ * Type guard for ReplyEnvelope.
+ *
+ * @param {unknown} value
+ * @returns {value is ReplyEnvelope}
+ */
+export function isReply(value) {
+  if (!isRecord(value)) {
+    return false;
+  }
+  if (
+    typeof value.id !== 'string' ||
+    typeof value.ok !== 'boolean' ||
+    !isMessageType(value.type)
+  ) {
+    return false;
+  }
+  if (value.ok === false) {
+    const err = value.error;
+    if (
+      !isRecord(err) ||
+      typeof err.code !== 'string' ||
+      typeof err.message !== 'string'
+    ) {
+      return false;
+    }
+  }
+  return true;
+}
+
+/**
+ * Normalize and validate an incoming JSON value as a RequestEnvelope.
+ * Throws a user-friendly error if invalid.
+ *
+ * @param {unknown} json
+ * @returns {RequestEnvelope}
+ */
+export function decodeRequest(json) {
+  if (!isRequest(json)) {
+    throw new Error('Invalid request envelope');
+  }
+  return json;
+}
+
+/**
+ * Normalize and validate an incoming JSON value as a ReplyEnvelope.
+ *
+ * @param {unknown} json
+ * @returns {ReplyEnvelope}
+ */
+export function decodeReply(json) {
+  if (!isReply(json)) {
+    throw new Error('Invalid reply envelope');
+  }
+  return json;
+}

package/bin/bdui

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const serverDir = resolve(__dirname, "..");
+
+// Set static dir for serving the Vite build output
+process.env.BEADS_UI_STATIC = resolve(serverDir, "dist");
+
+// Default to port 3333 to avoid conflicts with common dev servers on 3000
+if (!process.env.PORT) {
+  process.env.PORT = "3333";
+}
+
+// Preserve the caller's working directory — the server uses cwd() to
+// resolve the beads database, so we must NOT chdir.
+
+import("../server/index.js");

package/client/index.html

@@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Beads UI</title>
+  </head>
+  <body style="background: #FDFBF7; color: #1A1A1A;">
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/client/postcss.config.js

@@ -0,0 +1,11 @@
+import path from "path";
+import { fileURLToPath } from "url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+export default {
+  plugins: {
+    tailwindcss: { config: path.resolve(__dirname, "tailwind.config.ts") },
+    autoprefixer: {},
+  },
+};

package/client/src/App.tsx

@@ -0,0 +1,35 @@
+import { WsProvider } from "./lib/ws-context";
+import { Layout } from "./components/Layout";
+import { Board } from "./views/Board";
+import { List } from "./views/List";
+import { Detail } from "./views/Detail";
+import { SearchDialog } from "./components/SearchDialog";
+
+export function App() {
+  return (
+    <WsProvider>
+      <SearchDialog />
+      <Layout>
+        {(route) => {
+          if (route.startsWith("#/detail/")) {
+            const id = route.replace("#/detail/", "");
+            return <Detail key={id} issueId={id} />;
+          }
+          if (route.startsWith("#/list")) return <List />;
+          if (
+            route.startsWith("#/board") ||
+            route === "" ||
+            route === "#/" ||
+            route === "#"
+          )
+            return <Board />;
+          return (
+            <div className="p-6 text-stone-400">
+              View not implemented yet
+            </div>
+          );
+        }}
+      </Layout>
+    </WsProvider>
+  );
+}

package/client/src/components/IssueCard.tsx

@@ -0,0 +1,73 @@
+import { PriorityBadge } from "./PriorityBadge";
+import { TypeBadge } from "./TypeBadge";
+import { getInitials, getAvatarColor } from "../lib/avatar";
+import type { Issue } from "../lib/types";
+
+const TYPE_BORDER_COLORS: Record<string, string> = {
+  epic: "#7C3AED",
+  feature: "#6366F1",
+  bug: "#EF4444",
+  task: "#16A34A",
+  chore: "#78716C",
+};
+
+export function IssueCard({
+  issue,
+  onClick,
+  dimmed = false,
+}: {
+  issue: Issue;
+  onClick: () => void;
+  dimmed?: boolean;
+}) {
+  const borderColor = TYPE_BORDER_COLORS[issue.issue_type] ?? "#78716C";
+
+  return (
+    <button
+      onClick={onClick}
+      className={`issue-card group w-full text-left relative cursor-pointer ${dimmed ? "issue-card--dimmed" : ""}`}
+      style={{ borderLeft: `3px solid ${borderColor}` }}
+    >
+      <div className="px-3.5 py-3">
+        {/* Issue ID */}
+        <div className="mb-1">
+          <span
+            className="font-mono text-xs"
+            style={{ color: "var(--text-tertiary)" }}
+          >
+            {issue.id}
+          </span>
+        </div>
+
+        {/* Title */}
+        <p
+          className="text-sm font-medium line-clamp-2 mb-2.5"
+          style={{ color: "var(--text-primary)" }}
+        >
+          {issue.title}
+        </p>
+
+        {/* Type badge + Priority badge + Assignee avatar */}
+        <div className="flex items-center gap-1.5">
+          <TypeBadge type={issue.issue_type} />
+          <PriorityBadge priority={issue.priority} />
+          <div className="flex-1" />
+          {issue.assignee && (
+            <div
+              className="flex items-center justify-center rounded-full text-[10px] font-bold shrink-0"
+              style={{
+                width: "24px",
+                height: "24px",
+                backgroundColor: getAvatarColor(issue.assignee),
+                color: "var(--text-inverse)",
+              }}
+              title={issue.assignee}
+            >
+              {getInitials(issue.assignee)}
+            </div>
+          )}
+        </div>
+      </div>
+    </button>
+  );
+}

package/client/src/components/Layout.tsx

@@ -0,0 +1,175 @@
+import { useState, useEffect, type ReactNode } from "react";
+import { useWs } from "../lib/ws-context";
+
+function useHashRoute(): string {
+  const [hash, setHash] = useState(window.location.hash || "#/board");
+  useEffect(() => {
+    const handler = () => setHash(window.location.hash || "#/board");
+    window.addEventListener("hashchange", handler);
+    return () => window.removeEventListener("hashchange", handler);
+  }, []);
+  return hash;
+}
+
+function NavLink({ href, label, icon, active }: { href: string; label: string; icon: ReactNode; active: boolean }) {
+  return (
+    <a
+      href={href}
+      className="flex items-center gap-2.5 px-3 py-2 rounded-md text-sm transition-colors"
+      style={{
+        background: active ? "var(--bg-hover)" : "transparent",
+        color: active ? "var(--text-primary)" : "var(--text-secondary)",
+        fontWeight: active ? 500 : 400,
+      }}
+      onMouseEnter={(e) => {
+        if (!active) e.currentTarget.style.background = "var(--bg-hover)";
+      }}
+      onMouseLeave={(e) => {
+        if (!active) e.currentTarget.style.background = "transparent";
+      }}
+    >
+      {icon}
+      {label}
+    </a>
+  );
+}
+
+const BoardIcon = () => (
+  <svg width="16" height="16" viewBox="0 0 16 16" fill="none" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round">
+    <rect x="1" y="1" width="5" height="6" rx="1" />
+    <rect x="10" y="1" width="5" height="9" rx="1" />
+    <rect x="1" y="9" width="5" height="6" rx="1" />
+    <rect x="10" y="12" width="5" height="3" rx="1" />
+  </svg>
+);
+
+const ListIcon = () => (
+  <svg width="16" height="16" viewBox="0 0 16 16" fill="none" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round">
+    <line x1="5" y1="4" x2="14" y2="4" />
+    <line x1="5" y1="8" x2="14" y2="8" />
+    <line x1="5" y1="12" x2="14" y2="12" />
+    <circle cx="2" cy="4" r="0.75" fill="currentColor" stroke="none" />
+    <circle cx="2" cy="8" r="0.75" fill="currentColor" stroke="none" />
+    <circle cx="2" cy="12" r="0.75" fill="currentColor" stroke="none" />
+  </svg>
+);
+
+export function Layout({
+  children,
+}: {
+  children: (route: string) => ReactNode;
+}) {
+  const route = useHashRoute();
+  const ws = useWs();
+  const [projectName, setProjectName] = useState("");
+
+  useEffect(() => {
+    ws.getWorkspace().then((res: any) => {
+      if (res?.db_path) {
+        // db_path is like /path/to/project/.beads — parent is the project
+        const parts = res.db_path.split("/").filter(Boolean);
+        const beadsIdx = parts.lastIndexOf(".beads");
+        if (beadsIdx > 0) {
+          setProjectName(parts[beadsIdx - 1]);
+          return;
+        }
+      }
+      if (res?.root_dir) {
+        setProjectName(res.root_dir.split("/").pop() || "");
+      }
+    }).catch(() => {});
+  }, [ws]);
+
+  return (
+    <div className="flex h-screen" style={{ background: "var(--bg-base)" }}>
+      <nav
+        className="flex flex-col"
+        style={{
+          width: "200px",
+          borderRight: "1px solid var(--border-subtle)",
+          background: "var(--bg-base)",
+        }}
+      >
+        {/* Logo */}
+        <div className="flex items-center gap-2.5 px-4 py-5">
+          <div
+            className="flex items-center justify-center rounded-md"
+            style={{
+              width: "28px",
+              height: "28px",
+              background: "var(--accent)",
+            }}
+          >
+            <svg width="14" height="14" viewBox="0 0 14 14" fill="white">
+              <circle cx="7" cy="4" r="2.5" />
+              <circle cx="4" cy="10" r="2.5" />
+              <circle cx="10" cy="10" r="2.5" />
+            </svg>
+          </div>
+          <span
+            className="font-bold"
+            style={{
+              fontSize: "16px",
+              color: "var(--text-primary)",
+            }}
+          >
+            Beads
+          </span>
+        </div>
+
+        {/* Project name */}
+        {projectName && (
+          <div className="px-4 pb-3 mb-1" style={{ borderBottom: "1px solid var(--border-subtle)" }}>
+            <span className="text-xs font-mono" style={{ color: "var(--text-tertiary)" }}>
+              {projectName}
+            </span>
+          </div>
+        )}
+
+        {/* Nav links */}
+        <div className="px-2 space-y-0.5">
+          <NavLink
+            href="#/board"
+            label="Board"
+            icon={<BoardIcon />}
+            active={route.startsWith("#/board") || route === "" || route === "#/" || route === "#"}
+          />
+          <NavLink
+            href="#/list"
+            label="List"
+            icon={<ListIcon />}
+            active={route.startsWith("#/list")}
+          />
+        </div>
+
+        {/* Spacer */}
+        <div className="flex-1" />
+
+        {/* User card */}
+        <div
+          className="mx-3 mb-3 px-3 py-2.5 rounded-md flex items-center gap-2.5"
+          style={{
+            border: "1px solid var(--border-subtle)",
+          }}
+        >
+          <div
+            className="flex items-center justify-center rounded-full text-xs font-bold shrink-0"
+            style={{
+              width: "28px",
+              height: "28px",
+              background: "var(--accent)",
+              color: "white",
+            }}
+          >
+            R
+          </div>
+          <div>
+            <div className="text-sm font-medium" style={{ color: "var(--text-primary)" }}>Rustam</div>
+            <div style={{ fontSize: "11px", color: "var(--text-tertiary)" }}>Developer</div>
+          </div>
+        </div>
+      </nav>
+      <main className="flex-1 overflow-auto">{children(route)}</main>
+    </div>
+  );
+}

package/client/src/components/Markdown.tsx

@@ -0,0 +1,77 @@
+import { useEffect, useState } from "react";
+import { marked } from "marked";
+import DOMPurify from "dompurify";
+import { codeToHtml } from "shiki";
+
+export function Markdown({ content }: { content: string }) {
+  const [html, setHtml] = useState("");
+
+  useEffect(() => {
+    if (!content) {
+      setHtml("");
+      return;
+    }
+
+    let cancelled = false;
+
+    async function render() {
+      const tokens = marked.lexer(content);
+
+      // Collect code blocks for syntax highlighting
+      const codeBlocks: Array<{ code: string; lang: string }> = [];
+      marked.walkTokens(tokens, (token) => {
+        if (token.type === "code") {
+          codeBlocks.push({
+            code: (token as { text: string }).text,
+            lang: (token as { lang?: string }).lang || "text",
+          });
+        }
+      });
+
+      // Highlight all code blocks in parallel
+      const highlighted = await Promise.all(
+        codeBlocks.map(async (block) => {
+          try {
+            return await codeToHtml(block.code, {
+              lang: block.lang,
+              theme: "github-light",
+            });
+          } catch {
+            return `<pre><code>${DOMPurify.sanitize(block.code)}</code></pre>`;
+          }
+        }),
+      );
+
+      // Render markdown and replace code blocks with highlighted versions
+      let rendered = marked.parser(tokens) as string;
+      let i = 0;
+      rendered = rendered.replace(
+        /<pre><code[^>]*>[\s\S]*?<\/code><\/pre>/g,
+        () => highlighted[i++] || "",
+      );
+
+      const sanitized = DOMPurify.sanitize(rendered, {
+        ADD_TAGS: ["span"],
+        ADD_ATTR: ["style", "class"],
+      });
+
+      if (!cancelled) setHtml(sanitized);
+    }
+
+    render();
+    return () => {
+      cancelled = true;
+    };
+  }, [content]);
+
+  return (
+    <div
+      className="prose prose-stone prose-sm max-w-none
+        prose-pre:bg-stone-50 prose-pre:border prose-pre:border-stone-200 prose-pre:rounded
+        prose-code:text-sm prose-code:font-mono
+        prose-headings:font-semibold prose-headings:text-stone-900
+        prose-a:text-blue-600 prose-a:no-underline hover:prose-a:underline"
+      dangerouslySetInnerHTML={{ __html: html }}
+    />
+  );
+}

package/client/src/components/PriorityBadge.tsx

@@ -0,0 +1,26 @@
+const PRIORITY_CONFIG: Record<number, { bg: string; text: string }> = {
+  0: { bg: "rgba(239,68,68,0.12)", text: "#DC2626" },
+  1: { bg: "rgba(249,115,22,0.12)", text: "#EA580C" },
+  2: { bg: "rgba(59,130,246,0.12)", text: "#2563EB" },
+  3: { bg: "rgba(34,197,94,0.12)", text: "#16A34A" },
+  4: { bg: "rgba(156,163,175,0.1)", text: "#9CA3AF" },
+};
+
+export function PriorityBadge({ priority }: { priority: number }) {
+  const config = PRIORITY_CONFIG[priority] || PRIORITY_CONFIG[4];
+  return (
+    <span
+      className="inline-flex items-center justify-center font-mono font-bold"
+      style={{
+        fontSize: "11px",
+        lineHeight: 1,
+        padding: "3px 8px",
+        borderRadius: "var(--radius-sm)",
+        backgroundColor: config.bg,
+        color: config.text,
+      }}
+    >
+      P{priority}
+    </span>
+  );
+}