beads-kanban-ui 0.1.0 → 0.1.1

package/.designs/epic-support.md

@@ -1,282 +0,0 @@
-# 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

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

package/.eslintrc.json

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

package/.gitattributes

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

package/.github/workflows/release.yml

@@ -1,123 +0,0 @@
-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 }}

package/.history/README_20260121193710.md

@@ -1,227 +0,0 @@
-# Beads Kanban UI
-
-**See all your tasks at a glance. Drag, organize, and track progress across projects—no CLI required.**
-
-A beautiful visual Kanban board for the [Beads CLI](https://github.com/steveyegge/beads) task tracker. Beads stores tasks as git-native files (`.beads/issues.jsonl`), and this UI gives you the dashboard and board you've been missing.
-
-> **Works great with [Beads Orchestration](https://github.com/AvivK5498/Claude-Code-Beads-Orchestration)** — A multi-agent orchestration framework for Claude Code that uses beads for git-native task tracking with mandatory code review gates.
-
-## See It in Action
-
-**Dashboard** — All your projects in one place with status at a glance:
-![Dashboard with multi-project view, status donuts, and tags](Screenshots/dashboard.png)
-
-**Kanban Board** — Organize tasks across Open → In Progress → In Review → Closed:
-![Kanban board showing epic groups and task cards with git branch info](Screenshots/kanban-board.png)
-
-**Bead Details** — Dive into any task with full context and subtasks:
-![Bead detail panel showing epic with progress bar and subtasks](Screenshots/bead-detail.png)
-
-## What You Get
-
-- **Multi-project dashboard** — Manage all your beads projects in one place with status donut charts
-- **Kanban board** — Drag-and-drop columns: Open → In Progress → In Review → Closed
-- **Epic support** — Group related tasks, track progress with bars, view all subtasks
-- **Real-time sync** — File watcher auto-updates when beads files change on disk
-- **Git integration** — See branch status for each task at a glance
-- **Search & filter** — Quick filters for status, priority, owner, and tags
-- **Project tagging** — Organize with colored tags and filter by them
-
-## Quick Start (3 steps)
-
-### 1. Prerequisites
-```bash
-# Install beads CLI
-brew install steveyegge/beads/bd
-
-# You'll also need Node.js 18+ and Rust
-```
-
-### 2. Install and Run
-```bash
-git clone https://github.com/AvivK5498/beads-kanban-ui
-cd beads-kanban-ui
-npm install
-npm run dev:full
-```
-
-### 3. Open in Browser
-Navigate to **`http://localhost:3007`** and add your beads projects.
-
-That's it! The app watches for file changes and syncs in real-time.
-
----
-
-## Detailed Setup
-
-### Development Mode
-
-Run both frontend and backend together:
-```bash
-npm run dev:full
-```
-
-Or run separately:
-```bash
-# Terminal 1: Frontend (http://localhost:3007)
-npm run dev
-
-# Terminal 2: Backend (http://localhost:3008)
-npm run server:dev
-```
-
-The Rust backend builds automatically on first run. If you need to rebuild it:
-```bash
-cd server && cargo build --release && cd ..
-```
-
-### Production Build
-
-For a single binary deployment:
-```bash
-npm run build
-npm run server:build
-./server/target/release/beads-server
-```
-
-The production server embeds the frontend and serves everything from a single binary on port 3008.
-
----
-
-## How It Works
-
-### Dashboard
-1. Click **+ Add Project** and select a directory with a `.beads/` folder
-2. See all projects with status donuts showing task distribution
-3. Click any project to view its Kanban board
-
-### Kanban Board
-1. Tasks are organized by status: Open, In Progress, In Review, Closed
-2. Drag cards between columns to update status
-3. Click any task to see full details, comments, and related subtasks (for epics)
-
-### Features in Detail
-
-**Search & Filter**
-- Quick filters for status, priority, and assigned owner
-- Project tags for organization
-
-**Real-time Sync**
-- The app watches `.beads/issues.jsonl` and updates automatically
-- No refresh needed—changes appear instantly
-
-**Git Integration**
-- Each task shows its git branch status
-- Useful for tracking which branch a task lives on
-
----
-
-## Architecture
-
-```
-┌─────────────────────────────────────────────────────────┐
-│                    Beads Kanban UI                      │
-├─────────────────────────────────────────────────────────┤
-│  Frontend (Next.js 14)          │  Backend (Rust/Axum) │
-│  ─────────────────────          │  ────────────────────│
-│  • React 18                     │  • SQLite (projects) │
-│  • shadcn/ui components         │  • beads CLI bridge  │
-│  • Tailwind CSS                 │  • File watcher      │
-│  • TypeScript                   │  • Git integration   │
-└─────────────────────────────────────────────────────────┘
-                           │
-                           ▼
-              ┌─────────────────────────┐
-              │   .beads/ directory     │
-              │   (issues.jsonl, etc.)  │
-              └─────────────────────────┘
-```
-
-### Tech Stack
-- **Frontend**: Next.js 14, React 18, Tailwind CSS, shadcn/ui
-- **Backend**: Rust with Axum framework
-- **Database**: SQLite for project metadata
-- **File Sync**: Real-time watcher for `.beads/` changes
-
-### Project Structure
-```
-beads-kanban-ui/
-├── src/
-│   ├── app/                 # Next.js pages and routes
-│   │   ├── page.tsx         # Projects dashboard
-│   │   ├── project/         # Kanban board view
-│   │   └── settings/        # Settings page
-│   ├── components/          # React components
-│   │   ├── ui/              # shadcn/ui components
-│   │   ├── kanban-column.tsx
-│   │   ├── bead-card.tsx
-│   │   └── bead-detail.tsx
-│   ├── hooks/               # Custom React hooks
-│   ├── lib/                 # Utilities and API client
-│   └── types/               # TypeScript type definitions
-├── server/
-│   └── src/
-│       ├── main.rs          # Axum server entry point
-│       ├── db.rs            # SQLite database layer
-│       └── routes/          # API route handlers
-└── package.json
-```
-
----
-
-## API Endpoints
-
-| Endpoint | Method | Description |
-|----------|--------|-------------|
-| `/api/health` | GET | Server health check |
-| `/api/projects` | GET/POST | List or create projects |
-| `/api/projects/:id` | GET/PUT/DELETE | Manage individual projects |
-| `/api/beads?path=` | GET | Read beads from a project path |
-| `/api/beads/comment` | POST | Add comment to a bead |
-| `/api/bd/command` | POST | Execute beads CLI commands |
-| `/api/git/branch-status` | GET | Get git branch status for a bead |
-| `/api/fs/list` | GET | List directory contents |
-| `/api/fs/exists` | GET | Check if a path exists |
-| `/api/watch/beads` | GET | Server-sent events for file changes |
-
-### Environment Variables
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `PORT` | `3008` | Backend server port |
-| `NEXT_PUBLIC_BACKEND_URL` | `http://localhost:3008` | Backend URL for frontend API calls |
-
----
-
-## Development Commands
-
-```bash
-# Run both frontend and backend
-npm run dev:full
-
-# Run frontend only
-npm run dev
-
-# Run backend only
-npm run server:dev
-
-# Build for production
-npm run build
-npm run server:build
-
-# Linting
-npm run lint
-```
-
----
-
-## Related Projects
-
-- **[Beads CLI](https://github.com/steveyegge/beads)** — Git-native issue tracker (the core tool this UI wraps)
-- **[Beads Orchestration](https://github.com/AvivK5498/Claude-Code-Beads-Orchestration)** — Multi-agent orchestration framework for Claude Code using beads
-
----
-
-## License
-
-MIT