heartbeads 0.4.0

package/README.md

@@ -0,0 +1,389 @@
+# heartbeads
+
+**Interactive dependency graph viewer for [beads](https://github.com/GainForest/beads) (bd) issues.**
+
+![heartbeads showing a multi-project dependency graph](public/image.png)
+
+See your entire project's issues, epics, and dependencies as a live, explorable graph. heartbeads auto-discovers your `.beads/` directory and renders everything instantly -- no configuration needed.
+
+---
+
+## Features
+
+### Graph Visualization
+
+- **5 graph layouts** -- Switch between layout modes via the toolbar:
+  - **Force** -- Organic force simulation with collision avoidance and variable link distances
+  - **DAG** -- Clean top-down directed acyclic graph with topological layering
+  - **Radial** -- Concentric rings by dependency depth. Root nodes (no blockers) sit at center, deeper dependencies on outer rings. Ring spacing scales with node count.
+  - **Cluster** -- Groups nodes spatially by project prefix. Each prefix gets its own cluster center arranged in a circle. Cross-project dependencies stretch visibly between clusters.
+  - **Spread** -- Like Force but maximally spaced for readability and screenshots. Stronger repulsion, wider link distances.
+- **Collapse / Expand** -- Collapse all epics at once with a single button, or right-click individual epics to collapse/uncollapse them. Shows collapsed task count on each epic node.
+- **Visual encoding** -- Node size = dependency importance (connection count), fill color = configurable via legend (see below), ring color = project prefix ([Catppuccin Latte](https://github.com/catppuccin/palette) palette). Larger nodes are more connected; epics get a size boost.
+- **Legend color modes** -- Switch node fill color between 5 modes via the bottom-right legend panel:
+  - **Status** (default) -- Open (green), In Progress (amber), Blocked (red), Deferred (zinc), Closed (emerald)
+  - **Priority** -- P0 Critical (red), P1 High (orange), P2 Medium (blue), P3 Low (zinc), P4 Backlog (zinc-300)
+  - **Owner** -- Color by `createdBy` field using Catppuccin Latte accent palette (14 colors)
+  - **Assignee** -- Color by `assignee` field using Catppuccin Latte accent palette
+  - **Prefix** -- Color by project prefix using Catppuccin Latte accent palette
+- **Catppuccin Latte palette** -- All prefix-colored elements (node rings, cluster circles, tooltip accent bars, prefix fill mode) use the [Catppuccin Latte](https://github.com/catppuccin/palette) accent palette (14 saturated colors optimized for light backgrounds). Person/prefix mapping is deterministic via FNV-1a hash.
+- **Dependency arrows** -- Solid emerald arrows with flow particles for blocking relationships, dashed zinc lines for parent-child hierarchy. Curved links with configurable curvature.
+- **Semantic zoom** -- When zooming out, individual nodes smoothly fade and are replaced by epic cluster labels at each cluster's centroid. Clusters show the epic title, ID, and member count, surrounded by a dashed circle in the project's prefix color. Cluster visibility can be toggled with the "Clusters" button in the top-left toolbar.
+- **Spawn & exit animations** -- New nodes pop in with an overshoot easing (easeOutBack), removed nodes shrink out, and status changes trigger a ripple animation. New links flash bright emerald on arrival.
+- **Hover tooltips** -- Hover over any node to see a tooltip card with the project prefix, issue ID, title, creation date, blocker list, priority, owner, and assignee. Smart viewport clamping (prefers above cursor, flips below).
+- **Resizable minimap** -- Always-visible minimap (bottom-left) showing all nodes, links, claimed avatars, and the current viewport rectangle. Click to navigate. Drag the top, right, or top-right corner handles to resize (100-500px wide, 80-400px tall).
+
+### Live Updates
+
+- **SSE streaming** -- File watchers detect changes to `issues.jsonl` (and all additional repo JSONL files) and push updates via Server-Sent Events. No refresh needed.
+- **Diff/merge pipeline** -- Incoming data is diffed against current state (`diffBeadsData`) and merged with position preservation (`mergeBeadsData`) so the graph layout doesn't reset. Animation metadata (`_spawnTime`, `_removeTime`, `_changedAt`) is stamped during merge.
+
+### Timeline Replay
+
+- **Step-based playback** -- Replay the entire history of your project as a step-by-step animation. Each step corresponds to one temporal event (issue creation, dependency addition).
+- **Play/pause controls** -- Play, pause, and scrub through the timeline with a slider.
+- **Speed toggle** -- 1x, 2x, 4x playback speed (2 seconds per event at 1x).
+- **Uses the same diff/merge pipeline** as live updates, so nodes get proper positions and spawn animations during replay.
+
+### Search
+
+- **Smart search** -- `Cmd/Ctrl+F` to fuzzy search across all issues by ID, title, project prefix, owner, assignee, or commenter username. Keyboard navigation through results.
+
+### Right-Click Context Menu
+
+- **Multi-action menu** -- Right-click any node to open a context menu with actions:
+  - **Show description** -- Opens a full-screen modal with the issue's markdown description
+  - **Add comment** -- Opens the comment tooltip for posting
+  - **Claim task** -- Posts a claim comment (`@handle`) to mark yourself as working on the issue (only shown when authenticated and node is unclaimed)
+  - **Unclaim task** -- Removes your claim from the node (only shown when you are the claimant)
+  - **Collapse/Uncollapse epic** -- Toggle individual epic collapse on right-click (only shown on epic nodes)
+
+### Mobile Responsive
+
+- **Hamburger menu** -- On mobile viewports (<=768px), the nav pills are replaced with a hamburger menu that opens a slide-in drawer from the right with all navigation items.
+- **Double-tap context menu** -- Since right-click doesn't exist on mobile, double-tap a node to open a bottom action sheet with the same actions as the desktop context menu.
+- **Touch-optimized** -- Hover tooltips suppressed on mobile (no flicker), comment tooltips render as bottom sheets, text-selection TTS tooltip disabled, activity overlay compact mode (3 events).
+- **Bottom drawer** -- Node detail slides up as a bottom drawer instead of a sidebar on mobile.
+
+### Task Claiming
+
+- **Claim tasks** -- Right-click a node and select "Claim task" to mark yourself as working on it. Posts a special `@handle` comment via ATProto.
+- **Avatar badges** -- Claimed nodes display the claimant's circular avatar at the bottom-right of the node on the graph canvas. Avatars are drawn at constant screen-space size and also appear on the minimap.
+- **Avatar hover tooltip** -- Hover over a claimed node's avatar to see the claimant's profile picture, handle, and when they claimed it (relative time).
+- **Optimistic UI** -- Claims and unclaims update immediately in the UI before the server round-trip completes. Optimistic claims show the avatar instantly; optimistic unclaims suppress it instantly.
+- **Unclaim** -- Remove your claim via the context menu. Deletes the underlying ATProto comment record.
+
+### Node Detail Sidebar
+
+- **Click-to-inspect** -- Click any node to open a detail sidebar with:
+  - Issue ID, title, type icon, status/priority/prefix badges
+  - GitHub repository link (auto-detected from git remote, shown as clickable badge + URL)
+  - Metrics grid: blocks count, dependent count
+  - Blocker and dependent lists with clickable navigation
+  - Dates: created, updated, closed (with hour:minute precision)
+  - Owner attribution
+  - Full description rendered as Markdown (with GFM support)
+  - Copy-to-clipboard button for descriptions (copies raw markdown with a header showing project prefix, issue ID, and GitHub repo URL)
+  - Threaded comment section (see below)
+- **Description modal** -- "View in window" opens a full-screen modal with the rendered description and a copy button. Also accessible via right-click context menu "Show description".
+- **Mobile drawer** -- On small screens, the detail panel slides up as a bottom drawer instead of a sidebar.
+
+### ATProto Authentication & Comments
+
+- **OAuth 2.0 login** -- Sign in with your Bluesky/ATProto account via OAuth 2.0 with PKCE. Avatar and handle shown in the header. Dual mode: public client for dev, confidential (ES256 JWK) for production.
+- **Comment annotations** -- Right-click any node to post a comment via ATProto (`org.impactindexer.review.comment` lexicon). Comments stored on the AT Protocol, fetched from the Hypergoat GraphQL indexer.
+- **Threaded replies** -- Comments support nested replies (`replyTo` field). Root comments sorted newest-first, replies sorted chronologically. Rendered with indentation (`ml-4 pl-3 border-l`).
+- **Likes** -- Heart-toggle likes on comments (`org.impactindexer.review.like` lexicon). Rose-colored when liked by the current user.
+- **Delete** -- Delete your own comments and likes.
+- **Comment badges** -- Nodes with comments show a red notification badge with the comment count on the graph canvas.
+- **All Comments panel** -- Slide-in sidebar showing all comments across all nodes with threaded replies, clickable node navigation pills, and like/delete actions.
+
+### Multi-Repo Support
+
+- **Automatic aggregation** -- If your `.beads/config.yaml` lists additional repositories, heartbeads loads all of them into a unified graph.
+- **Per-project colors** -- Each project prefix gets a deterministic color from the Catppuccin Latte palette (14 accent colors). Shown as node rings, prefix badges, cluster borders, and tooltip accent bars.
+- **GitHub repo links** -- Auto-detects git remote URLs for each repository (primary + additional). Shown in the node detail card as a clickable GitHub link. Also included in copied description text.
+
+### Header / Navbar
+
+- **Frosted glass header** -- `bg-white/95 backdrop-blur-sm` sticky header inspired by [plresearch.org](https://plresearch.org).
+- **Animated heartbeat logo** -- An animated ECG/heartbeat trace SVG that continuously pulses — representing the living heartbeat of your project.
+- **Pill navigation** -- Replay and Comments toggle buttons styled as rounded-full pill items. Auth button with rounded avatar dropdown.
+- **Centered search** -- Rounded-full search bar with keyboard shortcut hint and dropdown results panel.
+- **Mobile hamburger menu** -- On small screens, nav pills collapse into a hamburger menu with a slide-in drawer.
+
+### Info Panel & Legend
+
+- **Bottom-right info panel** -- Shows issue count, dependency count, project count, color mode selector (Status / Priority / Owner / Assignee / Prefix), dynamic legend dots for the active mode, and visual encoding hints. Hidden during timeline replay. Legend shows only items present in visible nodes for owner/assignee/prefix modes.
+
+---
+
+## Quick Start
+
+```bash
+cd ~/my-project
+npx heartbeads@latest
+```
+
+heartbeads walks up from your current directory to find `.beads/`, just like `git` finds `.git/`.
+
+### With an explicit path
+
+```bash
+npx heartbeads@latest --beads-dir ~/projects/my-project/.beads
+```
+
+### Multi-repo aggregation
+
+If your `.beads/config.yaml` lists additional repositories, heartbeads automatically loads all of them:
+
+```yaml
+# .beads/config.yaml
+repos:
+  additional:
+    - ../backend
+    - ../frontend
+    - ../shared-lib
+```
+
+---
+
+## CLI Reference
+
+```
+heartbeads [options]
+
+Options:
+  --port <number>       Port to serve on (default: 3000)
+  --beads-dir <path>    Explicit .beads/ directory path
+  --password <string>   Require a password to access the dashboard and API
+  --dev                 Run in development mode (hot reload)
+  --help, -h            Show this help message
+
+Environment:
+  BEADS_DIR             Override .beads/ discovery (same as --beads-dir)
+  HEARTBEADS_PASSWORD   Require a password (same as --password)
+
+Examples:
+  npx heartbeads@latest                                    # Auto-discover from cwd
+  npx heartbeads@latest --port 4000                        # Custom port
+  npx heartbeads@latest --beads-dir ~/projects/hub/.beads  # Explicit path
+  npx heartbeads@latest --password secret                  # Password-protected
+  BEADS_DIR=../.beads npx heartbeads@latest --dev          # Dev mode with env var
+```
+
+---
+
+## Public API
+
+Heartbeads exposes a read-only REST API for AI agents, CI/CD bots, and integrations. All endpoints return JSON with CORS headers (`Access-Control-Allow-Origin: *`).
+
+When running with `--password`, API requests require authentication via one of:
+- **Bearer token:** `curl -H "Authorization: Bearer <password>" ...`
+- **Query param:** `curl "...?token=<password>"`
+
+Without `--password`, all endpoints are open (no auth required).
+
+### `GET /api/v1/graph` -- Full project snapshot
+
+Returns the entire beads graph with issues, dependencies, comments, claims, and recent activity in a single response.
+
+```bash
+# Full snapshot (issues + comments + activity)
+curl http://localhost:3000/api/v1/graph
+
+# Only open issues, skip comments for speed
+curl "http://localhost:3000/api/v1/graph?status=open&include="
+
+# Open + in_progress with activity feed capped at 20
+curl "http://localhost:3000/api/v1/graph?status=open,in_progress&include=comments,activity&limit=20"
+
+# Filter by repo prefix
+curl "http://localhost:3000/api/v1/graph?prefix=beads-map"
+```
+
+| Param | Description | Example |
+|-------|-------------|---------|
+| `status` | Filter by status (comma-separated) | `open,in_progress` |
+| `priority` | Filter by priority (comma-separated) | `0,1` |
+| `prefix` | Filter by repo prefix | `beads-map` |
+| `include` | Opt-in expensive fields (default: all) | `comments,activity` |
+| `limit` | Activity feed cap (default 50, max 200) | `20` |
+
+Response includes: `project` metadata, `issues[]` with comments and claims, `dependencies[]`, `stats`, `activity[]`, and `_meta`.
+
+### `GET /api/v1/issues/:id` -- Single issue detail
+
+Returns one issue with full description, threaded comments, and enriched blockers/dependents (with title + status).
+
+```bash
+curl http://localhost:3000/api/v1/issues/beads-map-abc
+
+# Returns 404 with hint if not found
+curl http://localhost:3000/api/v1/issues/nonexistent
+```
+
+### `GET /api/v1/ready` -- Actionable issues
+
+Returns issues ready to work on: open or in_progress with no unresolved blockers. Sorted by priority (critical first), then by age (oldest first).
+
+```bash
+# All actionable issues
+curl http://localhost:3000/api/v1/ready
+
+# Only unclaimed bugs
+curl "http://localhost:3000/api/v1/ready?unclaimed=true&type=bug"
+
+# Limit to top 10
+curl "http://localhost:3000/api/v1/ready?limit=10"
+```
+
+| Param | Description | Example |
+|-------|-------------|---------|
+| `unclaimed` | Only unclaimed issues | `true` |
+| `type` | Filter by issue type (comma-separated) | `bug,feature` |
+| `assignee` | Filter by assignee | `alice` |
+| `prefix` | Filter by repo prefix | `beads-map` |
+| `limit` | Max issues returned | `20` |
+
+Response includes: `issues[]` with comments and claims, `stats` summary (total_ready, unclaimed, by_priority, by_type), and `_meta`.
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/GainForest/heartbeads.git
+cd heartbeads
+pnpm install
+
+# Run in dev mode against a beads project
+BEADS_DIR=~/path/to/.beads pnpm dev
+
+# Build for production
+pnpm build
+```
+
+### Quality gate
+
+`pnpm build` must pass with zero errors before committing. There are no tests yet -- the build is the sole gate.
+
+---
+
+## Architecture
+
+```
+heartbeads/
+├── middleware.ts                  # Password gate: auth check on every request (Edge Runtime)
+├── app/
+│   ├── page.tsx                  # Main page: SSE wiring, merge logic, search, layout, comments, claims
+│   ├── layout.tsx                # Root layout, wraps in AuthProvider
+│   ├── not-found.tsx             # Custom 404 page with heartbeat logo
+│   ├── login/page.tsx            # Password login page (shown when --password flag is set)
+│   ├── globals.css               # Timeline slider styles, markdown prose, scrollbar
+│   └── api/
+│       ├── beads/
+│       │   ├── route.ts          # GET /api/beads -- one-shot full data load
+│       │   └── stream/route.ts   # GET /api/beads/stream -- SSE live updates
+│       ├── auth/route.ts          # GET/POST/DELETE /api/auth -- dashboard password gate
+│       ├── v1/
+│       │   ├── graph/route.ts    # GET /api/v1/graph -- full project snapshot for AI agents
+│       │   ├── issues/[id]/      # GET /api/v1/issues/:id -- single issue detail
+│       │   └── ready/route.ts    # GET /api/v1/ready -- actionable issues
+│       ├── config/route.ts       # GET /api/config -- project name, repo count, repo URLs
+│       ├── login/route.ts        # POST /api/login -- initiate ATProto OAuth
+│       ├── logout/route.ts       # POST /api/logout -- clear session
+│       ├── status/route.ts       # GET /api/status -- current auth state
+│       ├── records/route.ts      # POST/PUT/DELETE /api/records -- ATProto record CRUD
+│       └── oauth/
+│           ├── callback/route.ts         # OAuth callback handler
+│           ├── client-metadata.json/     # OAuth client metadata
+│           └── jwks.json/route.ts        # JSON Web Key Set
+├── components/
+│   ├── AllCommentsPanel.tsx      # Slide-in panel: all comments across nodes, threaded
+│   ├── AuthButton.tsx            # Sign-in modal + avatar dropdown (rounded-full pill style)
+│   ├── BeadsGraph.tsx            # Force graph: paintNode/paintLink, minimap, semantic zoom, avatars
+│   ├── BeadsLogo.tsx             # Animated heartbeat (ECG) SVG logo
+│   ├── BeadTooltip.tsx           # Hover tooltip: prefix, ID, title, date, blockers, priority, owner
+│   ├── CommentTooltip.tsx        # Floating right-click comment tooltip (bottom sheet on mobile)
+│   ├── ContextMenu.tsx           # Right-click context menu: description, comment, claim/unclaim
+│   ├── DescriptionModal.tsx      # Full-screen markdown description modal with copy button
+│   ├── HeartIcon.tsx             # Shared heart SVG (outline/filled)
+│   ├── MobileActionSheet.tsx     # Mobile bottom action sheet (double-tap context menu)
+│   ├── NodeDetail.tsx            # Sidebar detail: metadata, deps, comments, repo link
+│   ├── TimelineBar.tsx           # Timeline replay: play/pause, scrubber, speed toggle
+│   ├── GraphStats.tsx            # Issue count statistics widget (unused, inlined in BeadsGraph)
+│   └── StatusLegend.tsx          # Color legend for statuses (unused, inlined in BeadsGraph)
+├── hooks/
+│   ├── useBeadsComments.ts       # React hook wrapper for lib/comments.ts
+│   └── useIsMobile.ts            # Mobile viewport detection hook (<=768px)
+├── lib/
+│   ├── comments.ts               # Shared comment fetching, threading, claim detection
+│   ├── gate.ts                   # Password gate: HMAC token generation/validation
+│   ├── api-helpers.ts            # CORS headers, JSON response builders for /api/v1/*
+│   ├── auth.tsx                  # AuthProvider context + useAuth hook
+│   ├── auth/client.ts            # OAuth client factory (public/confidential mode)
+│   ├── agent.ts                  # Authenticated ATProto agent from session
+│   ├── session.ts                # iron-session encrypted cookie setup
+│   ├── env.ts                    # Environment variable validation
+│   ├── discover.ts               # .beads/ auto-discovery + git remote URL detection
+│   ├── parse-beads.ts            # JSONL parser, multi-repo hydration, graph builder
+│   ├── types.ts                  # GraphNode, GraphLink, ColorMode, Catppuccin palette, color helpers
+│   ├── diff-beads.ts             # Diff engine for detecting added/removed/changed nodes/links
+│   ├── watch-beads.ts            # fs.watch wrapper with debounce for JSONL file changes
+│   ├── settings.ts               # ElevenLabs TTS settings (localStorage)
+│   ├── tts.ts                    # Text-to-speech with ElevenLabs API, alignment cache
+│   ├── activity.ts               # Activity feed event types and builders
+│   ├── timeline.ts               # buildTimelineEvents + filterDataAtTime for replay
+│   └── utils.ts                  # formatRelativeTime, buildDescriptionCopyText, shared utilities
+├── bin/
+│   └── heartbeads.mjs            # CLI entry point
+├── scripts/
+│   └── generate-jwk.js           # ES256 JWK key generation for OAuth
+└── public/
+    └── image.png                 # Screenshot for README
+```
+
+### Data flow
+
+1. **Discovery** -- `lib/discover.ts` walks up from `cwd` (or reads `BEADS_DIR`) to find `.beads/`. Also detects git remote URLs for all repos.
+2. **Parsing** -- `lib/parse-beads.ts` reads `issues.jsonl` from the primary repo and any additional repos in `config.yaml`, deduplicates, extracts dependencies, and builds a graph structure with computed fields (blocker/dependent counts, prefix colors).
+3. **Rendering** -- `components/BeadsGraph.tsx` uses `react-force-graph-2d` with fully custom canvas rendering (`paintNode`, `paintLink`). All transient state (hover, selection, comments, claimed avatars) stored in refs to avoid re-rendering the force simulation.
+4. **Live updates** -- `app/api/beads/stream/route.ts` opens an SSE connection, watches all JSONL files, and pushes full data on each change. The client diffs and merges with position preservation.
+5. **Timeline** -- `lib/timeline.ts` extracts sorted temporal events from the data. During replay, `filterDataAtTime()` produces a time-slice that flows through the same diff/merge pipeline as live updates.
+6. **Comments** -- `lib/comments.ts` fetches from the Hypergoat GraphQL indexer, resolves Bluesky profiles, and builds threaded trees. Used by both the React hook (`hooks/useBeadsComments.ts`) and the public API routes (`/api/v1/*`).
+7. **Public API** -- `/api/v1/graph`, `/api/v1/issues/:id`, and `/api/v1/ready` combine beads data + comments + activity into enriched JSON for AI agents. No auth required, CORS enabled.
+7. **Claims** -- A claim is a comment with text `@handle` (starts with `@`, no spaces). The `claimedNodeAvatars` useMemo in `page.tsx` scans all comments to build a `Map<nodeId, claimInfo>`. Avatars are drawn on canvas nodes and the minimap by `paintNode` via `claimedNodeAvatarsRef`.
+
+### Key design decisions
+
+- **paintNode/paintLink use refs, not props** -- Callbacks have `[]` dependencies and read from `selectedNodeRef`, `hoveredNodeRef`, `claimedNodeAvatarsRef`, etc. This prevents re-creating the ForceGraph component on every interaction.
+- **Position preservation is critical** -- `react-force-graph-2d` mutates node objects in-place (`x`, `y`, `vx`, `vy`). The merge logic copies these from old nodes to new nodes to prevent layout resets.
+- **Animation metadata convention** -- Fields prefixed with `_` on nodes/links (`_spawnTime`, `_removeTime`, `_changedAt`, `_prevStatus`) are transient, set by `mergeBeadsData()`, consumed by `paintNode`/`paintLink`, and garbage-collected after 600ms.
+- **Bootstrap trick** -- The graph starts in DAG mode for 15ms to spread nodes into good positions, then auto-switches to Force mode. This gives the organic layout a clean starting arrangement.
+- **Link source/target normalization** -- `filterDataAtTime()` must spread new link objects with string `source`/`target` (not the original mutated object refs from d3-force). Without this, links draw to wrong positions during timeline replay.
+- **Optimistic claim/unclaim** -- Two state variables: `optimisticClaims` (Map) for immediate avatar display, `optimisticUnclaims` (Set) for immediate avatar suppression. Both reconciled with comment-derived data in `claimedNodeAvatars` useMemo.
+- **Avatar image cache** -- Module-level `avatarImageCache` in `BeadsGraph.tsx`. No `crossOrigin` attribute on Image elements (Bluesky CDN CORS issue). `getAvatarImage()` returns cached `HTMLImageElement` or starts loading and returns null.
+- **Portal for modals** -- `DescriptionModal` uses `createPortal(jsx, document.body)` with `z-[100]` to escape any parent stacking contexts.
+
+---
+
+## Tech Stack
+
+- [Next.js 14](https://nextjs.org/) (App Router)
+- [react-force-graph-2d](https://github.com/vasturiano/react-force-graph) for canvas-based graph rendering
+- [d3-force](https://github.com/d3/d3-force) (forceCollide, forceRadial, forceX, forceY for layout modes)
+- [Catppuccin Latte](https://github.com/catppuccin/palette) accent palette for prefix/person coloring (14 colors)
+- [Tailwind CSS](https://tailwindcss.com/) for styling
+- [TypeScript](https://www.typescriptlang.org/) throughout
+- [@atproto/oauth-client-node](https://github.com/bluesky-social/atproto) + [@atproto/api](https://github.com/bluesky-social/atproto) for ATProto authentication and record CRUD
+- [iron-session](https://github.com/vvo/iron-session) for encrypted cookie session management
+- [react-markdown](https://github.com/remarkjs/react-markdown) + [remark-gfm](https://github.com/remarkjs/remark-gfm) for description rendering
+- Node.js `fs.watch` for file change detection
+- Server-Sent Events for real-time streaming
+
+---
+
+## License
+
+MIT

package/app/api/auth/route.ts

@@ -0,0 +1,103 @@
+/**
+ * Dashboard password authentication API.
+ *
+ * GET  /api/auth — Check if password protection is active and if the request is authenticated
+ * POST /api/auth — Validate password and set auth cookie
+ * DELETE /api/auth — Clear auth cookie (lock dashboard)
+ *
+ * This is separate from ATProto OAuth (Sign In button in navbar).
+ * ATProto is for identity (comments, likes, claims).
+ * This gate controls who can view the dashboard and access the API.
+ */
+
+import { NextResponse } from "next/server";
+import { cookies } from "next/headers";
+import { env } from "@/lib/env";
+import {
+  COOKIE_NAME,
+  generateGateToken,
+  validateGateToken,
+  comparePassword,
+} from "@/lib/gate";
+
+export const dynamic = "force-dynamic";
+
+const isProduction = process.env.NODE_ENV === "production";
+
+export async function GET() {
+  const password = env.HEARTBEADS_PASSWORD;
+
+  if (!password) {
+    return NextResponse.json({ protected: false });
+  }
+
+  const cookieStore = await cookies();
+  const token = cookieStore.get(COOKIE_NAME)?.value;
+  const authenticated = token ? validateGateToken(token, password) : false;
+
+  return NextResponse.json({ protected: true, authenticated });
+}
+
+export async function POST(request: Request) {
+  const password = env.HEARTBEADS_PASSWORD;
+
+  if (!password) {
+    return NextResponse.json(
+      { error: "Password protection is not enabled" },
+      { status: 400 }
+    );
+  }
+
+  let body: { password?: string };
+  try {
+    body = await request.json();
+  } catch {
+    return NextResponse.json(
+      { error: "Invalid request body" },
+      { status: 400 }
+    );
+  }
+
+  const provided = body.password;
+  if (!provided || typeof provided !== "string") {
+    return NextResponse.json(
+      { error: "Password is required" },
+      { status: 400 }
+    );
+  }
+
+  if (!comparePassword(provided, password)) {
+    return NextResponse.json(
+      { error: "Invalid password" },
+      { status: 401 }
+    );
+  }
+
+  // Password matches — set the gate cookie
+  const token = generateGateToken(password);
+  const response = NextResponse.json({ success: true });
+
+  response.cookies.set(COOKIE_NAME, token, {
+    httpOnly: true,
+    sameSite: "lax",
+    secure: isProduction,
+    path: "/",
+    // Session cookie — no maxAge, expires when browser closes
+  });
+
+  return response;
+}
+
+export async function DELETE() {
+  const response = NextResponse.json({ success: true });
+
+  response.cookies.set(COOKIE_NAME, "", {
+    httpOnly: true,
+    sameSite: "lax",
+    secure: isProduction,
+    path: "/",
+    maxAge: 0, // Expire immediately
+  });
+
+  return response;
+}

package/app/api/beads/route.ts

@@ -0,0 +1,27 @@
+import { NextResponse } from "next/server";
+import { loadBeadsData } from "@/lib/parse-beads";
+import { discoverBeadsDir } from "@/lib/discover";
+
+export async function GET() {
+  try {
+    const { beadsDir } = discoverBeadsDir();
+    const data = loadBeadsData(beadsDir);
+    return NextResponse.json(data);
+  } catch (error: any) {
+    // Distinguish discovery errors (404) from data loading errors (500)
+    if (error?.message?.includes("No .beads/ directory found")) {
+      return NextResponse.json(
+        {
+          error: "No .beads directory found",
+          hint: "Run bd init in your project, then start heartbeads from that directory",
+        },
+        { status: 404 }
+      );
+    }
+    console.error("Failed to load beads data:", error);
+    return NextResponse.json(
+      { error: "Failed to load beads data" },
+      { status: 500 }
+    );
+  }
+}

package/app/api/beads/stream/route.ts

@@ -0,0 +1,83 @@
+import { discoverBeadsDir } from "@/lib/discover";
+import { loadBeadsData } from "@/lib/parse-beads";
+import { watchBeadsFiles } from "@/lib/watch-beads";
+
+// Prevent Next.js from statically optimizing this route
+export const dynamic = "force-dynamic";
+
+export async function GET(request: Request) {
+  let cleanup: (() => void) | null = null;
+
+  const stream = new ReadableStream({
+    start(controller) {
+      const encoder = new TextEncoder();
+
+      function send(data: unknown) {
+        try {
+          controller.enqueue(
+            encoder.encode(`data: ${JSON.stringify(data)}\n\n`)
+          );
+        } catch {
+          // Stream closed — cleanup will handle
+        }
+      }
+
+      try {
+        const { beadsDir } = discoverBeadsDir();
+
+        // Send initial data
+        const initialData = loadBeadsData(beadsDir);
+        send(initialData);
+
+        // Watch for changes and push updates
+        cleanup = watchBeadsFiles(beadsDir, () => {
+          try {
+            const newData = loadBeadsData(beadsDir);
+            send(newData);
+          } catch (err) {
+            console.error("Failed to reload beads data:", err);
+          }
+        });
+
+        // Heartbeat every 30s to keep connection alive through proxies/firewalls
+        const heartbeat = setInterval(() => {
+          try {
+            controller.enqueue(encoder.encode(": heartbeat\n\n"));
+          } catch {
+            clearInterval(heartbeat);
+          }
+        }, 30000);
+
+        // Clean up when client disconnects
+        request.signal.addEventListener("abort", () => {
+          clearInterval(heartbeat);
+          if (cleanup) cleanup();
+          try {
+            controller.close();
+          } catch {
+            /* already closed */
+          }
+        });
+      } catch (err: unknown) {
+        // Discovery failed — send error and close
+        const message =
+          err instanceof Error ? err.message : "Unknown error";
+        send({ error: message });
+        controller.close();
+      }
+    },
+
+    cancel() {
+      if (cleanup) cleanup();
+    },
+  });
+
+  return new Response(stream, {
+    headers: {
+      "Content-Type": "text/event-stream",
+      "Cache-Control": "no-cache, no-transform",
+      Connection: "keep-alive",
+      "X-Accel-Buffering": "no", // Disable Nginx buffering
+    },
+  });
+}

package/app/api/config/route.ts

@@ -0,0 +1,48 @@
+import { NextResponse } from "next/server";
+import { discoverBeadsDir, getRepoUrls } from "@/lib/discover";
+import { readFileSync, existsSync } from "fs";
+import { join } from "path";
+import { parse as parseYaml } from "yaml";
+
+export const dynamic = "force-dynamic";
+
+export async function GET() {
+  try {
+    const discovery = discoverBeadsDir();
+
+    // Read repos list from config.yaml
+    let repos: string[] = ["."];
+    const configPath = join(discovery.beadsDir, "config.yaml");
+    try {
+      if (existsSync(configPath)) {
+        const content = readFileSync(configPath, "utf-8");
+        const config = parseYaml(content);
+        const additional = config?.repos?.additional;
+        if (Array.isArray(additional)) {
+          repos = [config?.repos?.primary || ".", ...additional];
+        }
+      }
+    } catch {
+      // config.yaml unreadable — use defaults
+    }
+
+    // Build prefix → GitHub URL mapping from git remotes
+    const repoUrls = getRepoUrls(discovery.beadsDir);
+
+    return NextResponse.json({
+      name: discovery.issuePrefix || discovery.repoName,
+      prefix: discovery.issuePrefix || null,
+      repoCount: 1 + discovery.additionalRepos,
+      repos,
+      repoUrls,
+    });
+  } catch {
+    // No .beads/ found — return safe defaults
+    return NextResponse.json({
+      name: "Beads",
+      prefix: null,
+      repoCount: 0,
+      repos: [],
+    });
+  }
+}