beads-kanban-ui 0.1.0

package/.designs/beads-kanban-ui-bj0.md

@@ -0,0 +1,73 @@
+# Main Page Design Overhaul
+
+## Epic ID: beads-kanban-ui-bj0
+
+## Overview
+
+Modernize the main projects page with an animated beam background, custom typography, and improved layout structure. Remove navbar, add centered heading, create a visually appealing project grid.
+
+## Requirements
+
+1. **Background**: Animated Beams component from @react-bits registry
+   - Full-screen, fixed position, behind all content
+   - Config: beamWidth=8, beamHeight=14, beamNumber=20, lightColor="#f0c7ff", speed=2, noiseIntensity=1.75, scale=0.2, rotation=30
+
+2. **Typography**: Space Grotesk font family
+   - Imported via next/font/google
+   - Applied to headings
+
+3. **Layout**:
+   - Remove navbar/header completely
+   - Add centered heading: "Manage Your Beads Projects"
+   - Center the 3-column grid with max-width constraint (~1200px)
+   - Keep FAB button for adding projects
+   - Move settings icon to top-right corner (fixed position)
+
+## Visual Layout
+
+```
++--------------------------------------------------+
+|  [Settings Icon]                          (fixed)|
+|                                                  |
+|        "Manage Your Beads Projects"              |
+|        (Space Grotesk, centered)                 |
+|                                                  |
+|    +-------+  +-------+  +-------+               |
+|    | Card  |  | Card  |  | Card  |               |
+|    +-------+  +-------+  +-------+               |
+|                                                  |
+|                              [+ FAB]     (fixed) |
++--------------------------------------------------+
+  * Animated Beams fill entire viewport behind *
+```
+
+## Z-Index Layering
+
+| Layer | z-index | Component |
+|-------|---------|-----------|
+| Background | 0 | Beams |
+| Content | 10 | Main container, grid, cards |
+| Controls | 20 | FAB, Settings icon |
+| Dialogs | 50 | AddProjectDialog |
+
+## Implementation Tasks
+
+1. **beads-kanban-ui-bj0.1**: Install Beams component
+   - `npx shadcn@latest add @react-bits/Beams-JS-CSS`
+
+2. **beads-kanban-ui-bj0.2**: Configure Space Grotesk font
+   - Add to layout.tsx via next/font/google
+   - Add .font-heading utility class
+
+3. **beads-kanban-ui-bj0.3**: Restructure main page layout
+   - Remove header, add Beams background, add heading, center grid
+   - Depends on tasks 1 and 2
+
+## File Changes
+
+| File | Change |
+|------|--------|
+| src/app/page.tsx | Remove navbar, add Beams, add heading, center layout |
+| src/app/layout.tsx | Add Space Grotesk font |
+| src/app/globals.css | Add .font-heading class |
+| src/components/ui/beams.tsx | New file (from registry) |

package/.designs/beads-kanban-ui-qxq.md

@@ -0,0 +1,144 @@
+# Dark Minimalist Theme for Kanban and Settings Pages
+
+## Epic ID: beads-kanban-ui-qxq
+
+## Overview
+
+Apply the dark minimalist aesthetic from the home page to the Kanban board (project page) and Settings page. The goal is visual consistency across all pages: dark backgrounds, glass-morphism cards, subtle borders, and refined typography.
+
+## Reference Implementation
+
+The home page (`src/app/page.tsx`) establishes the target aesthetic:
+- Root container: `dark min-h-dvh bg-[#0a0a0a]`
+- Nav: `border-zinc-800 bg-[#0a0a0a]/80 backdrop-blur-sm`
+- Cards: roiui glass effect with `backdrop-filter: blur(12px)`
+
+---
+
+## 1. Color Palette
+
+### Background Colors
+
+| Usage | Value | Tailwind Class |
+|-------|-------|----------------|
+| Page background | `#0a0a0a` | `bg-[#0a0a0a]` |
+| Column background | - | `bg-zinc-900/50` |
+
+### Border Colors
+
+| Usage | Tailwind Class |
+|-------|----------------|
+| Default border | `border-zinc-800` |
+| Hover border | `border-zinc-700` |
+| Focus ring | `ring-zinc-400` |
+
+### Text Colors
+
+| Usage | Tailwind Class |
+|-------|----------------|
+| Primary text | `text-white` or `text-foreground` |
+| Secondary text | `text-zinc-400` |
+| Muted text | `text-zinc-500` |
+
+---
+
+## 2. Card Styling (Glass Effect)
+
+```tsx
+<div className={cn(
+  "rounded-lg",
+  "bg-zinc-900/70 backdrop-blur-md",
+  "border border-zinc-800/60",
+  "shadow-sm shadow-black/20",
+  "transition-all duration-200",
+  "hover:-translate-y-0.5 hover:shadow-lg hover:shadow-black/30",
+  "hover:border-zinc-700"
+)}>
+```
+
+### Selected State
+```tsx
+isSelected && "ring-2 ring-zinc-400 ring-offset-2 ring-offset-[#0a0a0a]"
+```
+
+### Blocked State
+```tsx
+blocked ? "border-l-4 border-l-red-500" : "border-l-4 border-l-transparent"
+```
+
+---
+
+## 3. Column Differentiation
+
+Use subtle colored accent bars at the top of each column header instead of colored backgrounds.
+
+### Column Container
+```tsx
+<div className="flex flex-col h-full min-h-0 rounded-lg bg-zinc-900/30 border border-zinc-800/50">
+```
+
+### Column Color Mapping
+
+| Status | Accent Border | Header Text | Badge BG | Badge Text |
+|--------|---------------|-------------|----------|------------|
+| Open | `border-t-blue-500/60` | `text-blue-400` | `bg-blue-500/20` | `text-blue-400` |
+| In Progress | `border-t-amber-500/60` | `text-amber-400` | `bg-amber-500/20` | `text-amber-400` |
+| In Review | `border-t-purple-500/60` | `text-purple-400` | `bg-purple-500/20` | `text-purple-400` |
+| Closed | `border-t-green-500/60` | `text-green-400` | `bg-green-500/20` | `text-green-400` |
+
+---
+
+## 4. Badge Colors (Dark Theme)
+
+### Priority Badges
+
+| Priority | Background | Text |
+|----------|------------|------|
+| P0 (Critical) | `bg-red-500/20` | `text-red-400` |
+| P1 (High) | `bg-orange-500/20` | `text-orange-400` |
+| P2 (Medium) | `bg-zinc-500/20` | `text-zinc-400` |
+| P3/P4 (Low) | `bg-zinc-600/20` | `text-zinc-500` |
+
+### Status Badges
+
+| Status | Background | Text |
+|--------|------------|------|
+| BLOCKED | `bg-red-500/20` | `text-red-400` |
+| Open | `bg-blue-500/20` | `text-blue-400` |
+| In Progress | `bg-amber-500/20` | `text-amber-400` |
+| In Review | `bg-purple-500/20` | `text-purple-400` |
+| Closed | `bg-green-500/20` | `text-green-400` |
+
+---
+
+## 5. Page Wrapper Pattern
+
+### Kanban Page
+```tsx
+<div className="dark min-h-dvh bg-[#0a0a0a]">
+  <header className="sticky top-0 z-30 border-b border-zinc-800 bg-[#0a0a0a]/80 backdrop-blur-sm px-4 py-3">
+  </header>
+  <main className="flex-1 overflow-hidden p-4">
+  </main>
+</div>
+```
+
+### Settings Page
+```tsx
+<div className="dark min-h-dvh bg-[#0a0a0a]">
+  <header className="sticky top-0 z-30 border-b border-zinc-800 bg-[#0a0a0a]/80 backdrop-blur-sm px-6 py-4">
+  </header>
+  <main className="mx-auto max-w-2xl p-6">
+  </main>
+</div>
+```
+
+---
+
+## 6. Button Variants
+
+| Variant | Classes |
+|---------|---------|
+| Primary | `bg-zinc-100 text-zinc-900 hover:bg-white` |
+| Ghost | `text-zinc-400 hover:bg-zinc-800/50 hover:text-zinc-100` |
+| Destructive | `bg-red-900/30 text-red-400 border-red-800/50 hover:bg-red-900/50` |

package/.designs/epic-support.md

@@ -0,0 +1,282 @@
+# Epic Support for Beads Kanban UI
+
+## Codebase Analysis Summary
+
+### Technology Stack
+- **Frontend**: Next.js 14, React 18, TypeScript, Tailwind CSS, shadcn/ui (Radix UI primitives)
+- **Backend**: Rust with Axum, SQLite for project metadata
+- **Data Source**: `.beads/issues.jsonl` files (JSONL format)
+- **Real-time**: Server-Sent Events (SSE) for file watching
+- **Icons**: Lucide React
+
+### Current Data Model (`/src/types/index.ts`)
+```typescript
+interface Bead {
+  id: string;
+  title: string;
+  description?: string;
+  status: BeadStatus; // 'open' | 'in_progress' | 'inreview' | 'closed'
+  priority: number;
+  issue_type: string;
+  owner: string;
+  created_at: string;
+  updated_at: string;
+  comments: Comment[];
+}
+```
+
+**Missing fields for epic support**:
+- `parent_id?: string` - For child tasks
+- `children?: string[]` - For epic tasks
+- `issue_type: 'task' | 'epic'` - Already exists but not leveraged
+- `design_doc?: string` - Path to design doc (e.g., `.designs/{EPIC_ID}.md`)
+- `deps?: string[]` - Dependencies for sequencing
+
+**Important Notes**:
+- Existing beads without `issue_type` should default to `'task'`
+- `blockers` is a **computed field** derived from `deps` relationships (not stored in data)
+
+### Current Component Structure
+- `KanbanColumn` - Renders a single column with list of `BeadCard` components
+- `BeadCard` - Individual task card with priority, status, branch info
+- `BeadDetail` - Sheet panel showing full bead details
+- `kanban-board.tsx` - Main board orchestrating columns and detail panel
+
+### API Layer
+- Beads read via `GET /api/beads?path=`
+- CLI commands via `POST /api/bd/command` (whitelisted: list, show, comment, update, close, create)
+- File watching via SSE at `/api/watch/beads`
+- Design doc reading would need new endpoint: `GET /api/fs/read?path=`
+
+---
+
+## Implementation Plan
+
+### Phase 1: Backend Extensions (Rust Struct + Endpoints + CLI)
+
+**1.1 Extend Rust Bead struct** (`/server/src/routes/beads.rs`)
+```rust
+pub struct Bead {
+    // ... existing fields
+    #[serde(default)]
+    pub parent_id: Option<String>,
+    #[serde(default)]
+    pub children: Option<Vec<String>>,
+    #[serde(default)]
+    pub design_doc: Option<String>,
+    #[serde(default)]
+    pub deps: Option<Vec<String>>,
+    // NOTE: blockers is NOT stored - computed client-side from deps relationships
+}
+```
+
+**1.2 Update CLI whitelist** (`/server/src/routes/bd.rs`)
+```rust
+const ALLOWED_COMMANDS: &[&str] = &[
+    "list", "show", "comment", "update", "close", "create",
+    "ready", "epic"  // NEW: for bd ready and bd epic status
+];
+```
+
+**1.3 Add design doc read endpoint** (`/server/src/routes/fs.rs`)
+```rust
+// GET /api/fs/read?path=.designs/{EPIC_ID}.md
+pub async fn read_file(Query(params): Query<FsReadParams>) -> impl IntoResponse
+
+// Security constraints:
+// - Max file size: 100KB
+// - Only .md extension allowed
+// - Path must be within project directory
+// - Path must start with ".designs/"
+```
+
+---
+
+### Phase 2: Frontend Types & Data Layer
+
+**2.1 Extend TypeScript Types** (`/src/types/index.ts`)
+```typescript
+// Extended Bead interface
+interface Bead {
+  // ... existing fields
+  parent_id?: string;         // ID of parent epic (for children)
+  children?: string[];        // IDs of child tasks (for epics)
+  design_doc?: string;        // Path like ".designs/{EPIC_ID}.md"
+  deps?: string[];            // Dependency IDs (blocking this task)
+  blockers?: string[];        // COMPUTED: Tasks this blocks (derived from deps relationships)
+}
+
+// New Epic-specific types
+interface Epic extends Bead {
+  issue_type: 'epic';
+  children: string[];
+  progress?: EpicProgress;
+}
+
+interface EpicProgress {
+  total: number;
+  completed: number;
+  inProgress: number;
+  blocked: number;
+}
+```
+
+**Note on blockers field**: The `blockers` field is **computed client-side** from analyzing the `deps` relationships of all beads. It should NOT be stored in the data model. When processing beads, compute blockers dynamically based on which beads list the current bead in their `deps` array.
+
+**2.2 Create epic-parser utility** (`/src/lib/epic-parser.ts`)
+- `parseEpicsAndTasks(beads)` - Separate epics from standalone tasks
+- `buildEpicTree(epics, tasks)` - Attach children to parent epics
+- `computeEpicProgress(epic)` - Calculate completion percentages
+- `getBlockedTasks(tasks)` - Identify tasks with unresolved deps
+- `computeBlockers(bead, allBeads)` - Compute which beads this task blocks
+
+**2.3 Extend beads-parser** (`/src/lib/beads-parser.ts`)
+- Add `groupByEpicStatus()` for epic-specific grouping
+- Add `getEpicChildren(epicId, beads)` helper
+- Add `isEpicCompleted(epic)` check
+
+---
+
+### Phase 3: UI Components (EpicCard, SubtaskList, DesignDocViewer, DependencyBadge)
+
+**3.1 EpicCard Component** (`/src/components/epic-card.tsx`)
+- Larger card with distinctive styling (gradient border, icon)
+- Progress bar showing children completion (3/5)
+- Collapsed children preview (first 2-3 titles)
+- Expand/collapse toggle
+- Design doc indicator badge
+- Different visual treatment from regular BeadCard
+
+**3.2 SubtaskList Component** (`/src/components/subtask-list.tsx`)
+- Compact list of child tasks within epic card
+- Checkbox-style status indicators
+- Click to open child detail
+- Drag-to-reorder (future enhancement)
+
+**3.3 DesignDocViewer Component** (`/src/components/design-doc-viewer.tsx`)
+- Markdown renderer for `.designs/{EPIC_ID}.md`
+- Collapsible sections
+- Code syntax highlighting
+- Full-screen toggle
+- **Dependencies**: Requires `react-markdown` and `rehype-highlight` (or similar syntax highlighting library) packages
+
+**3.4 EpicDetailPanel Component** (`/src/components/epic-detail.tsx`)
+- Extended BeadDetail with:
+  - Design doc tab/section
+  - Children list with status
+  - Dependency graph visualization
+  - Progress metrics
+  - Epic-level timeline
+
+**3.5 DependencyBadge Component** (`/src/components/dependency-badge.tsx`)
+- Shows blocked/blocking status
+- Tooltip with dependency names
+- Click to navigate to blocker
+
+---
+
+### Phase 4: Board Integration (KanbanColumn filtering, useEpics hook, kanban-board updates)
+
+**4.1 Update kanban-board.tsx** (`/src/app/project/kanban-board.tsx`)
+- Filter child tasks before rendering columns:
+```typescript
+// In kanban-board.tsx before passing to KanbanColumn
+const topLevelBeads = beads.filter(b => !b.parent_id);
+```
+- Render `EpicCard` for `issue_type: 'epic'`
+- Keep `BeadCard` for standalone tasks
+- Hide child tasks from top-level (they show inside epics)
+- Add filter: "Show: All | Epics Only | Tasks Only"
+- Add grouping: "Group by: Status | Epic"
+- Handle epic expansion state
+- Route to EpicDetailPanel or BeadDetail based on type
+
+**4.2 Update KanbanColumn** (`/src/components/kanban-column.tsx`)
+- Render `EpicCard` for `issue_type: 'epic'`
+- Keep `BeadCard` for non-epic tasks
+- Only receives top-level beads (already filtered)
+
+**4.3 New useEpics hook** (`/src/hooks/use-epics.ts`)
+- Derived from useBeads
+- Separates epics and tasks
+- Computes progress for each epic
+- Handles expansion state
+- Filters to only top-level beads
+
+---
+
+### Phase 5: Enhanced Features (Optional)
+
+**5.1 Epic Progress Indicator**
+- Circular progress ring or horizontal bar
+- Color-coded: green (done), amber (in progress), gray (pending), red (blocked)
+- Fraction display: "3/5 children"
+
+**5.2 Dependency Visualization**
+- Mini dependency graph in epic detail
+- Lines connecting dependent children
+- Blocked tasks highlighted in red
+- Topological ordering display
+
+**5.3 Design Doc Editing** (Future)
+- Inline Markdown editor
+- Auto-save on blur
+- Version history via git
+
+**5.4 Epic Timeline/Burndown View**
+- Gantt-style timeline for children
+- Burndown chart showing completion over time
+- Estimated vs actual completion
+
+**5.5 Enhanced Filtering**
+- Filter by epic vs standalone
+- Filter by dependency status (blocked/unblocked)
+- Filter by epic parent
+- "Ready to work" view (bd ready equivalent)
+
+**5.6 UX Improvements**
+- Keyboard shortcut: `E` to toggle epic filter
+- Drag children between epics
+- Bulk operations on epic children
+- Epic templates for common patterns
+
+---
+
+## Implementation Sequence
+
+| Phase | Description | Dependencies |
+|-------|-------------|--------------|
+| 1 | Backend Extensions (Rust struct, GET /api/fs/read, CLI whitelist) | None |
+| 2 | Frontend Types & Data Layer (TypeScript types, epic-parser, beads-parser) | Phase 1 |
+| 3 | UI Components (EpicCard, SubtaskList, DesignDocViewer, DependencyBadge) | Phase 2 |
+| 4 | Board Integration (KanbanColumn filtering, useEpics hook, kanban-board updates) | Phase 3 |
+| 5 | Enhanced Features (progress indicators, dependency visualization, filtering) | Phase 4 |
+
+---
+
+## Critical Files for Implementation
+
+| File | Purpose |
+|------|---------|
+| `/src/types/index.ts` | Core type extensions for epic/parent/children |
+| `/src/components/bead-card.tsx` | Pattern to follow for EpicCard |
+| `/src/app/project/kanban-board.tsx` | Main integration point |
+| `/server/src/routes/beads.rs` | Backend bead struct to extend |
+| `/src/lib/beads-parser.ts` | Data processing utilities to extend |
+
+---
+
+## Required Deliverables
+
+1. **Kanban board clearly separates epics/tasks** - EpicCard vs BeadCard rendering
+2. **Epic item has design document viewer** - DesignDocViewer component
+3. **Epic items contain all sub tasks** - SubtaskList within EpicCard
+4. **User can open sub tasks through epic** - Click handler to BeadDetail
+
+## Bonus Features
+
+- Progress indicators (3/5 children done)
+- Dependency visualization
+- "Ready to work" filter
+- Epic timeline view
+- Blocked status badges

package/.env.local.example

@@ -0,0 +1,2 @@
+# Backend URL (optional, defaults to http://localhost:3008)
+NEXT_PUBLIC_BACKEND_URL=http://localhost:3008

package/.eslintrc.json

@@ -0,0 +1,3 @@
+{
+  "extends": "next/core-web-vitals"
+}

package/.gitattributes

@@ -0,0 +1,3 @@
+
+# Use bd merge for beads JSONL files
+.beads/issues.jsonl merge=beads

package/.github/workflows/release.yml

@@ -0,0 +1,123 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Version to release (e.g., v1.0.0)'
+        required: true
+        type: string
+
+jobs:
+  build:
+    strategy:
+      matrix:
+        include:
+          - os: macos-latest
+            target: aarch64-apple-darwin
+            artifact: beads-server-darwin-arm64
+          - os: macos-latest
+            target: x86_64-apple-darwin
+            artifact: beads-server-darwin-x64
+          - os: ubuntu-latest
+            target: x86_64-unknown-linux-gnu
+            artifact: beads-server-linux-x64
+          - os: windows-latest
+            target: x86_64-pc-windows-msvc
+            artifact: beads-server-win32-x64.exe
+
+    runs-on: ${{ matrix.os }}
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+
+      - name: Install frontend dependencies
+        run: npm ci
+
+      - name: Build frontend
+        run: npm run build
+
+      - name: Setup Rust
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          targets: ${{ matrix.target }}
+
+      - name: Build server
+        run: cargo build --release --target ${{ matrix.target }}
+        working-directory: server
+
+      - name: Copy binary (Unix)
+        if: runner.os != 'Windows'
+        run: cp server/target/${{ matrix.target }}/release/beads-server ${{ matrix.artifact }}
+
+      - name: Copy binary (Windows)
+        if: runner.os == 'Windows'
+        run: copy server\target\${{ matrix.target }}\release\beads-server.exe ${{ matrix.artifact }}
+
+      - name: Upload artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: ${{ matrix.artifact }}
+          path: ${{ matrix.artifact }}
+
+  release:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - name: Download all artifacts
+        uses: actions/download-artifact@v4
+        with:
+          path: artifacts
+
+      - name: Prepare release assets
+        run: |
+          mkdir -p release
+          find artifacts -type f -exec mv {} release/ \;
+          ls -la release/
+
+      - name: Create Release
+        uses: softprops/action-gh-release@v1
+        with:
+          name: ${{ github.ref_name || inputs.version }}
+          tag_name: ${{ github.ref_name || inputs.version }}
+          files: release/*
+          generate_release_notes: true
+
+  publish-npm:
+    needs: release
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Update package version
+        run: |
+          VERSION="${{ github.ref_name || inputs.version }}"
+          VERSION="${VERSION#v}"  # Remove 'v' prefix
+          cd npm
+          npm version $VERSION --no-git-tag-version --allow-same-version
+
+      - name: Publish to npm
+        run: npm publish
+        working-directory: npm
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}