beads-kanban-ui 0.1.0

package/src/lib/epic-parser.ts

@@ -0,0 +1,242 @@
+/**
+ * Epic parser utility for beads kanban
+ *
+ * Provides functions to separate epics from tasks, build epic trees,
+ * compute progress metrics, and identify blocking relationships.
+ */
+
+import type { Bead, Epic, EpicProgress } from "@/types";
+
+/**
+ * Separates epics from standalone tasks
+ *
+ * @param beads - Array of all beads
+ * @returns Object with separate arrays for epics and standalone tasks
+ *
+ * @example
+ * ```typescript
+ * const { epics, tasks } = parseEpicsAndTasks(allBeads);
+ * console.log(`Found ${epics.length} epics and ${tasks.length} standalone tasks`);
+ * ```
+ */
+export function parseEpicsAndTasks(beads: Bead[]): {
+  epics: Epic[];
+  tasks: Bead[];
+} {
+  if (!beads || beads.length === 0) {
+    return { epics: [], tasks: [] };
+  }
+
+  const epics: Epic[] = [];
+  const tasks: Bead[] = [];
+
+  for (const bead of beads) {
+    // Bead is an epic if issue_type is 'epic' OR if it has children
+    if (bead.issue_type === 'epic' || (bead.children && bead.children.length > 0)) {
+      epics.push({
+        ...bead,
+        issue_type: 'epic',
+        children: bead.children ?? [],
+      } as Epic);
+    } else if (!bead.parent_id) {
+      // Only include tasks that are NOT children of epics (standalone tasks)
+      tasks.push(bead);
+    }
+  }
+
+  return { epics, tasks };
+}
+
+/**
+ * Attaches child beads to their parent epics
+ *
+ * @param epics - Array of epic beads
+ * @param allBeads - Array of all beads (including children)
+ * @returns Array of epics with resolved children attached
+ *
+ * @example
+ * ```typescript
+ * const epicsWithChildren = buildEpicTree(epics, allBeads);
+ * epicsWithChildren.forEach(epic => {
+ *   console.log(`Epic ${epic.id} has ${epic.children.length} children`);
+ * });
+ * ```
+ */
+export function buildEpicTree(epics: Epic[], allBeads: Bead[]): Epic[] {
+  if (!epics || epics.length === 0) {
+    return [];
+  }
+
+  if (!allBeads || allBeads.length === 0) {
+    return epics;
+  }
+
+  // Create a lookup map for fast child access
+  const beadMap = new Map<string, Bead>();
+  for (const bead of allBeads) {
+    beadMap.set(bead.id, bead);
+  }
+
+  // Build epic tree with resolved children
+  return epics.map((epic) => {
+    const children = (epic.children ?? [])
+      .map((childId) => beadMap.get(childId))
+      .filter((child): child is Bead => child !== undefined);
+
+    return {
+      ...epic,
+      children: children.map((c) => c.id),
+    };
+  });
+}
+
+/**
+ * Computes progress metrics for an epic based on its children
+ *
+ * @param epic - Epic bead with children
+ * @param allBeads - Array of all beads to resolve children from
+ * @returns EpicProgress object with computed metrics
+ *
+ * @example
+ * ```typescript
+ * const progress = computeEpicProgress(epic, allBeads);
+ * console.log(`${progress.completed}/${progress.total} children completed`);
+ * console.log(`${progress.blocked} children blocked`);
+ * ```
+ */
+export function computeEpicProgress(epic: Epic, allBeads: Bead[]): EpicProgress {
+  if (!epic.children || epic.children.length === 0) {
+    return {
+      total: 0,
+      completed: 0,
+      inProgress: 0,
+      blocked: 0,
+    };
+  }
+
+  if (!allBeads || allBeads.length === 0) {
+    return {
+      total: epic.children.length,
+      completed: 0,
+      inProgress: 0,
+      blocked: 0,
+    };
+  }
+
+  // Create lookup map for children
+  const beadMap = new Map<string, Bead>();
+  for (const bead of allBeads) {
+    beadMap.set(bead.id, bead);
+  }
+
+  // Resolve child beads
+  const children = epic.children
+    .map((childId) => beadMap.get(childId))
+    .filter((child): child is Bead => child !== undefined);
+
+  // Count statuses
+  const completed = children.filter((c) => c.status === 'closed').length;
+  const inProgress = children.filter((c) => c.status === 'in_progress').length;
+
+  // Count blocked children (those with unresolved deps)
+  const blocked = children.filter((child) => {
+    if (!child.deps || child.deps.length === 0) {
+      return false;
+    }
+
+    // Check if any dependency is not yet completed
+    return child.deps.some((depId) => {
+      const depBead = beadMap.get(depId);
+      return depBead && depBead.status !== 'closed';
+    });
+  }).length;
+
+  return {
+    total: children.length,
+    completed,
+    inProgress,
+    blocked,
+  };
+}
+
+/**
+ * Identifies tasks that are blocked by unresolved dependencies
+ *
+ * @param beads - Array of all beads to check
+ * @returns Array of beads that have blocking dependencies
+ *
+ * @example
+ * ```typescript
+ * const blockedTasks = getBlockedTasks(allBeads);
+ * console.log(`${blockedTasks.length} tasks are currently blocked`);
+ * blockedTasks.forEach(task => {
+ *   console.log(`${task.id} blocked by: ${task.deps?.join(', ')}`);
+ * });
+ * ```
+ */
+export function getBlockedTasks(beads: Bead[]): Bead[] {
+  if (!beads || beads.length === 0) {
+    return [];
+  }
+
+  // Create lookup map for fast access
+  const beadMap = new Map<string, Bead>();
+  for (const bead of beads) {
+    beadMap.set(bead.id, bead);
+  }
+
+  // Filter beads with unresolved dependencies
+  return beads.filter((bead) => {
+    if (!bead.deps || bead.deps.length === 0) {
+      return false;
+    }
+
+    // Check if any dependency is not yet completed
+    return bead.deps.some((depId) => {
+      const depBead = beadMap.get(depId);
+      // Blocked if dependency exists and is not closed
+      return depBead && depBead.status !== 'closed';
+    });
+  });
+}
+
+/**
+ * Computes which beads the given bead blocks (inverse of deps)
+ *
+ * @param bead - The bead to check
+ * @param allBeads - Array of all beads to search for dependents
+ * @returns Array of bead IDs that depend on this bead
+ *
+ * @example
+ * ```typescript
+ * const blockers = computeBlockers(someBead, allBeads);
+ * if (blockers.length > 0) {
+ *   console.log(`Completing this task will unblock: ${blockers.join(', ')}`);
+ * }
+ * ```
+ */
+export function computeBlockers(bead: Bead, allBeads: Bead[]): string[] {
+  if (!bead || !bead.id) {
+    return [];
+  }
+
+  if (!allBeads || allBeads.length === 0) {
+    return [];
+  }
+
+  // Find all beads that list this bead in their deps array
+  const blockers: string[] = [];
+
+  for (const otherBead of allBeads) {
+    if (!otherBead.deps || otherBead.deps.length === 0) {
+      continue;
+    }
+
+    // If this bead is in the other bead's deps, then this bead blocks it
+    if (otherBead.deps.includes(bead.id)) {
+      blockers.push(otherBead.id);
+    }
+  }
+
+  return blockers;
+}

package/src/lib/git.ts

@@ -0,0 +1,102 @@
+/**
+ * Git utilities for branch status via HTTP API
+ *
+ * Provides functions to check branch existence and ahead/behind status
+ * relative to the main branch.
+ */
+
+import * as api from './api';
+
+/**
+ * Branch status relative to main
+ */
+export interface BranchStatus {
+  /** Whether the branch exists locally */
+  exists: boolean;
+  /** Number of commits ahead of main */
+  ahead: number;
+  /** Number of commits behind main */
+  behind: number;
+}
+
+/**
+ * Get branch status (exists, ahead, behind) relative to main
+ *
+ * @param projectPath - Absolute path to the git repository
+ * @param branchName - Name of the branch to check status for
+ * @returns Promise resolving to BranchStatus
+ *
+ * @example
+ * ```typescript
+ * const status = await getBranchStatus('/path/to/repo', 'bd-BD-001');
+ * if (status.exists) {
+ *   console.log(`Branch is ${status.ahead} ahead, ${status.behind} behind main`);
+ * }
+ * ```
+ */
+export async function getBranchStatus(
+  projectPath: string,
+  branchName: string
+): Promise<BranchStatus> {
+  return api.git.branchStatus(projectPath, branchName);
+}
+
+/**
+ * Check if a branch exists locally
+ *
+ * @param projectPath - Absolute path to the git repository
+ * @param branchName - Name of the branch to check
+ * @returns Promise resolving to true if branch exists
+ *
+ * @example
+ * ```typescript
+ * const exists = await branchExists('/path/to/repo', 'bd-BD-001');
+ * ```
+ */
+export async function branchExists(
+  projectPath: string,
+  branchName: string
+): Promise<boolean> {
+  const status = await getBranchStatus(projectPath, branchName);
+  return status.exists;
+}
+
+/**
+ * Get branch statuses for multiple branches in batch
+ *
+ * Runs checks in parallel for efficiency.
+ *
+ * @param projectPath - Absolute path to the git repository
+ * @param branchNames - Array of branch names to check
+ * @returns Promise resolving to a map of branch name to status
+ *
+ * @example
+ * ```typescript
+ * const statuses = await getBatchBranchStatus('/path/to/repo', [
+ *   'bd-BD-001',
+ *   'bd-BD-002',
+ *   'bd-BD-003'
+ * ]);
+ * ```
+ */
+export async function getBatchBranchStatus(
+  projectPath: string,
+  branchNames: string[]
+): Promise<Record<string, BranchStatus>> {
+  const results: Record<string, BranchStatus> = {};
+
+  // Run all checks in parallel
+  const promises = branchNames.map(async (branchName) => {
+    try {
+      const status = await getBranchStatus(projectPath, branchName);
+      results[branchName] = status;
+    } catch {
+      // If there's an error, assume branch doesn't exist
+      results[branchName] = { exists: false, ahead: 0, behind: 0 };
+    }
+  });
+
+  await Promise.all(promises);
+
+  return results;
+}

package/src/lib/utils.ts

@@ -0,0 +1,12 @@
+import { clsx, type ClassValue } from 'clsx';
+import { twMerge } from 'tailwind-merge';
+
+/**
+ * Merges Tailwind class names, resolving any conflicts.
+ *
+ * @param inputs - An array of class names to merge.
+ * @returns A string of merged and optimized class names.
+ */
+export function cn(...inputs: ClassValue[]): string {
+  return twMerge(clsx(inputs));
+}

package/src/types/index.ts

@@ -0,0 +1,107 @@
+/**
+ * Bead counts by status for a project
+ */
+export interface BeadCounts {
+  open: number;
+  in_progress: number;
+  inreview: number;
+  closed: number;
+}
+
+/**
+ * Project stored in local SQLite
+ */
+export interface Project {
+  id: string;
+  name: string;
+  path: string;
+  tags: Tag[];
+  lastOpened: string;
+  createdAt: string;
+  beadCounts?: BeadCounts;
+}
+
+/**
+ * Tag stored in local SQLite
+ */
+export interface Tag {
+  id: string;
+  name: string;
+  color: string;
+}
+
+/**
+ * Bead status types
+ */
+export type BeadStatus = 'open' | 'in_progress' | 'inreview' | 'closed';
+
+/**
+ * Bead from .beads/issues.jsonl
+ */
+export interface Bead {
+  id: string;
+  title: string;
+  description?: string;
+  status: BeadStatus;
+  priority: number;
+  issue_type: string;
+  owner: string;
+  created_at: string;
+  updated_at: string;
+  comments: Comment[];
+  // Epic support fields
+  parent_id?: string;         // ID of parent epic (for child tasks)
+  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)
+}
+
+/**
+ * Comment from .beads/issues.jsonl
+ */
+export interface Comment {
+  id: number;
+  issue_id: string;
+  author: string;
+  text: string;
+  created_at: string;
+}
+
+/**
+ * Kanban column configuration
+ */
+export interface KanbanColumn {
+  id: BeadStatus;
+  title: string;
+  beads: Bead[];
+}
+
+/**
+ * GitHub PR info (for future integration)
+ */
+export interface PRInfo {
+  url: string;
+  state: 'OPEN' | 'MERGED' | 'CLOSED';
+  reviewDecision: 'APPROVED' | 'CHANGES_REQUESTED' | 'REVIEW_REQUIRED' | null;
+  statusCheckRollup: { state: 'SUCCESS' | 'FAILURE' | 'PENDING' } | null;
+}
+
+/**
+ * Epic progress metrics (computed from children)
+ */
+export interface EpicProgress {
+  total: number;       // Total number of child tasks
+  completed: number;   // Number of children with status 'closed'
+  inProgress: number;  // Number of children with status 'in_progress'
+  blocked: number;     // Number of children with unresolved dependencies
+}
+
+/**
+ * Epic-specific bead type
+ */
+export interface Epic extends Bead {
+  issue_type: 'epic';
+  children: string[];     // Epics always have children (required, not optional)
+  progress?: EpicProgress; // Computed progress metrics
+}

package/tailwind.config.ts

@@ -0,0 +1,85 @@
+import type { Config } from 'tailwindcss';
+
+const config: Config = {
+  darkMode: ['class'],
+  content: [
+    './src/pages/**/*.{js,ts,jsx,tsx,mdx}',
+    './src/components/**/*.{js,ts,jsx,tsx,mdx}',
+    './src/app/**/*.{js,ts,jsx,tsx,mdx}',
+  ],
+  theme: {
+    extend: {
+      colors: {
+        background: 'hsl(var(--background))',
+        foreground: 'hsl(var(--foreground))',
+        card: {
+          DEFAULT: 'hsl(var(--card))',
+          foreground: 'hsl(var(--card-foreground))',
+        },
+        popover: {
+          DEFAULT: 'hsl(var(--popover))',
+          foreground: 'hsl(var(--popover-foreground))',
+        },
+        primary: {
+          DEFAULT: 'hsl(var(--primary))',
+          foreground: 'hsl(var(--primary-foreground))',
+        },
+        secondary: {
+          DEFAULT: 'hsl(var(--secondary))',
+          foreground: 'hsl(var(--secondary-foreground))',
+        },
+        muted: {
+          DEFAULT: 'hsl(var(--muted))',
+          foreground: 'hsl(var(--muted-foreground))',
+        },
+        accent: {
+          DEFAULT: 'hsl(var(--accent))',
+          foreground: 'hsl(var(--accent-foreground))',
+        },
+        destructive: {
+          DEFAULT: 'hsl(var(--destructive))',
+          foreground: 'hsl(var(--destructive-foreground))',
+        },
+        border: 'hsl(var(--border))',
+        input: 'hsl(var(--input))',
+        ring: 'hsl(var(--ring))',
+        chart: {
+          '1': 'hsl(var(--chart-1))',
+          '2': 'hsl(var(--chart-2))',
+          '3': 'hsl(var(--chart-3))',
+          '4': 'hsl(var(--chart-4))',
+          '5': 'hsl(var(--chart-5))',
+        },
+        // Beads Status colors
+        status: {
+          open: 'hsl(var(--status-open))',
+          inprogress: 'hsl(var(--status-inprogress))',
+          inreview: 'hsl(var(--status-inreview))',
+          done: 'hsl(var(--status-done))',
+        },
+        // Beads Priority colors
+        priority: {
+          p0: 'hsl(var(--priority-p0))',
+          p1: 'hsl(var(--priority-p1))',
+          p2: 'hsl(var(--priority-p2))',
+          p3: 'hsl(var(--priority-p3))',
+          p4: 'hsl(var(--priority-p4))',
+        },
+        // Beads Accents
+        blocked: 'hsl(var(--blocked))',
+        branch: 'hsl(var(--branch))',
+      },
+      borderRadius: {
+        lg: 'var(--radius)',
+        md: 'calc(var(--radius) - 2px)',
+        sm: 'calc(var(--radius) - 4px)',
+      },
+    },
+  },
+  plugins: [
+    require('tailwindcss-animate'),
+    require('@tailwindcss/typography'),
+  ],
+};
+
+export default config;

package/tsconfig.json

@@ -0,0 +1,26 @@
+{
+  "compilerOptions": {
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "preserve",
+    "incremental": true,
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ],
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  },
+  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
+  "exclude": ["node_modules"]
+}