heartbeads 0.4.0

package/lib/types.ts

@@ -0,0 +1,271 @@
+// ============================================================================
+// Core data types matching .beads/issues.jsonl schema
+// ============================================================================
+
+export interface BeadDependency {
+  issue_id: string;
+  depends_on_id: string;
+  type: "blocks" | "parent-child" | "relates_to";
+  created_at: string;
+  created_by?: string;
+  metadata?: string;
+}
+
+export interface BeadIssue {
+  id: string;
+  title: string;
+  description?: string;
+  status: "open" | "in_progress" | "blocked" | "deferred" | "closed";
+  priority: number; // 0 (critical) to 4 (backlog)
+  issue_type: "task" | "bug" | "feature" | "chore" | "epic";
+  owner?: string;
+  assignee?: string;
+  labels?: string[];
+  created_at: string;
+  created_by?: string;
+  updated_at: string;
+  closed_at?: string;
+  close_reason?: string;
+  dependencies?: BeadDependency[];
+}
+
+// ============================================================================
+// Graph data types for visualization
+// ============================================================================
+
+export interface GraphNode {
+  [key: string]: unknown; // index signature for react-force-graph compatibility
+  id: string;
+  title: string;
+  description?: string;
+  status: BeadIssue["status"];
+  priority: number;
+  issueType: BeadIssue["issue_type"];
+  owner?: string;
+  assignee?: string;
+  createdBy?: string;
+  createdAt: string;
+  updatedAt: string;
+  closedAt?: string;
+  closeReason?: string;
+  prefix: string; // e.g. "my-app", "backend", "frontend"
+
+  // Computed
+  blockerCount: number;    // issues this blocks
+  dependentCount: number;  // issues that depend on this
+  blockerIds: string[];    // IDs of issues this blocks
+  dependentIds: string[];  // IDs of issues blocking this
+
+  // Force-graph position (set by simulation)
+  x?: number;
+  y?: number;
+  fx?: number;
+  fy?: number;
+
+  // Animation metadata (set by live-update merge logic, consumed by paintNode)
+  _spawnTime?: number;    // Date.now() when this node first appeared (for pop-in animation)
+  _removeTime?: number;   // Date.now() when this node was marked for removal (for shrink-out)
+  _changedAt?: number;    // Date.now() when status/priority changed (for ripple animation)
+  _prevStatus?: string;   // Previous status value before the change (for color transition)
+}
+
+// ============================================================================
+// Color mode for legend/node fill switching
+// ============================================================================
+
+export type ColorMode = "status" | "priority" | "owner" | "assignee" | "prefix";
+
+export const COLOR_MODE_LABELS: Record<ColorMode, string> = {
+  status: "Status",
+  priority: "Priority",
+  owner: "Owner",
+  assignee: "Assignee",
+  prefix: "Prefix",
+};
+
+export interface GraphLink {
+  source: string;
+  target: string;
+  type: "blocks" | "parent-child" | "relates_to";
+  createdAt?: string;     // ISO 8601 from BeadDependency.created_at (for timeline replay)
+
+  // Animation metadata (set by live-update merge logic, consumed by paintLink)
+  _spawnTime?: number;    // Date.now() when this link first appeared (for fade-in animation)
+  _removeTime?: number;   // Date.now() when this link was marked for removal (for fade-out)
+}
+
+export interface GraphData {
+  nodes: GraphNode[];
+  links: GraphLink[];
+}
+
+export interface BeadsApiResponse {
+  issues: BeadIssue[];
+  dependencies: BeadDependency[];
+  graphData: GraphData;
+  stats: {
+    total: number;
+    open: number;
+    inProgress: number;
+    blocked: number;
+    closed: number;
+    actionable: number;
+    edges: number;
+    prefixes: string[];
+  };
+}
+
+// ============================================================================
+// Status and priority display helpers
+// ============================================================================
+
+export const STATUS_COLORS: Record<string, string> = {
+  open: "#10b981",       // emerald-500
+  in_progress: "#f59e0b", // amber-500
+  blocked: "#ef4444",     // red-500
+  deferred: "#8b5cf6",    // violet-500
+  closed: "#a1a1aa",      // zinc-400
+};
+
+export const STATUS_LABELS: Record<string, string> = {
+  open: "Open",
+  in_progress: "In Progress",
+  blocked: "Blocked",
+  deferred: "Deferred",
+  closed: "Closed",
+};
+
+export const PRIORITY_LABELS: Record<number, string> = {
+  0: "P0 - Critical",
+  1: "P1 - High",
+  2: "P2 - Medium",
+  3: "P3 - Low",
+  4: "P4 - Backlog",
+};
+
+export const PRIORITY_COLORS: Record<number, string> = {
+  0: "#ef4444", // red
+  1: "#f97316", // orange
+  2: "#3b82f6", // blue
+  3: "#a1a1aa", // zinc
+  4: "#d4d4d8", // zinc-300
+};
+
+// ============================================================================
+// Catppuccin Latte accent palette
+// ============================================================================
+
+/** Catppuccin Latte accent colors — 14 visually distinct, reordered for max contrast between adjacent indices */
+export const CATPPUCCIN_ACCENTS: string[] = [
+  "#d20f39", // Red
+  "#179299", // Teal
+  "#fe640b", // Peach
+  "#1e66f5", // Blue
+  "#40a02b", // Green
+  "#8839ef", // Mauve
+  "#df8e1d", // Yellow
+  "#209fb5", // Sapphire
+  "#ea76cb", // Pink
+  "#04a5e5", // Sky
+  "#e64553", // Maroon
+  "#7287fd", // Lavender
+  "#dd7878", // Flamingo
+  "#dc8a78", // Rosewater
+];
+
+export const CATPPUCCIN_ACCENT_NAMES: string[] = [
+  "Red", "Teal", "Peach", "Blue", "Green", "Mauve", "Yellow",
+  "Sapphire", "Pink", "Sky", "Maroon", "Lavender", "Flamingo", "Rosewater",
+];
+
+/** Catppuccin Latte Surface2 — used for "unassigned" / unknown values */
+export const CATPPUCCIN_UNASSIGNED = "#acb0be";
+
+export const TYPE_ICONS: Record<string, string> = {
+  bug: "\uD83D\uDC1B",
+  feature: "\u2728",
+  task: "\uD83D\uDCDD",
+  epic: "\uD83C\uDFAF",
+  chore: "\uD83D\uDD27",
+};
+
+// ============================================================================
+// Dynamic prefix label and color generation
+// ============================================================================
+
+/**
+ * Generate a deterministic color from a string using a hash-based hue.
+ * Uses FNV-1a for better distribution across the hue wheel.
+ */
+function hashColor(str: string): string {
+  let hash = 2166136261; // FNV offset basis
+  for (let i = 0; i < str.length; i++) {
+    hash ^= str.charCodeAt(i);
+    hash = (hash * 16777619) >>> 0; // FNV prime, keep as uint32
+  }
+  const hue = hash % 360;
+  return `hsl(${hue}, 65%, 55%)`;
+}
+
+/**
+ * Humanize a prefix string into a display label.
+ * "my-lib" -> "My Lib", "backend" -> "Backend"
+ */
+function humanizePrefix(prefix: string): string {
+  return prefix
+    .split(/[-_]/)
+    .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+    .join(" ");
+}
+
+/**
+ * Get a display label for a prefix. Returns a human-readable name
+ * auto-generated from the prefix string.
+ */
+export function getPrefixLabel(prefix: string): string {
+  return humanizePrefix(prefix);
+}
+
+/**
+ * Get a color for a prefix. Generates a deterministic color
+ * from the prefix string using hash-based hue.
+ */
+export function getPrefixColor(prefix: string): string {
+  return hashColor(prefix);
+}
+
+/**
+ * Deterministically map a person handle/name to a Catppuccin Latte accent color.
+ * Uses FNV-1a hash modulo 14 to index into CATPPUCCIN_ACCENTS.
+ * Returns CATPPUCCIN_UNASSIGNED for undefined/null/empty strings.
+ */
+export function getPersonColor(person: string | undefined): string {
+  if (!person) return CATPPUCCIN_UNASSIGNED;
+  let hash = 2166136261; // FNV offset basis
+  for (let i = 0; i < person.length; i++) {
+    hash ^= person.charCodeAt(i);
+    hash = (hash * 16777619) >>> 0;
+  }
+  return CATPPUCCIN_ACCENTS[hash % CATPPUCCIN_ACCENTS.length];
+}
+
+/**
+ * Deterministically map a prefix string to a Catppuccin Latte accent color.
+ * Same approach as getPersonColor but for project prefixes.
+ */
+export function getCatppuccinPrefixColor(prefix: string): string {
+  return getPersonColor(prefix);
+}
+
+// Backward-compatible exports — delegates to dynamic functions
+// so existing code using PREFIX_COLORS[prefix] || fallback still works.
+// Prefer using getPrefixColor() / getPrefixLabel() directly.
+export const PREFIX_LABELS = new Proxy({} as Record<string, string>, {
+  get: (_target, prop: string) => getPrefixLabel(prop),
+  has: () => true,
+});
+
+export const PREFIX_COLORS = new Proxy({} as Record<string, string>, {
+  get: (_target, prop: string) => getPrefixColor(prop),
+  has: () => true,
+});

package/lib/utils.ts

@@ -0,0 +1,48 @@
+/**
+ * Shared utilities for heartbeads.
+ */
+
+import { getPrefixLabel } from "@/lib/types";
+import type { GraphNode } from "@/lib/types";
+
+/**
+ * Formats an ISO date string as a human-readable relative time.
+ * - < 60s: "just now"
+ * - < 60m: "Xm ago"
+ * - < 24h: "Xh ago"
+ * - < 7d:  "Xd ago"
+ * - else:  "Mon DD" (e.g. "Feb 10")
+ */
+export function formatRelativeTime(isoString: string): string {
+  const date = new Date(isoString);
+  const now = new Date();
+  const seconds = Math.floor((now.getTime() - date.getTime()) / 1000);
+  if (seconds < 60) return "just now";
+  const minutes = Math.floor(seconds / 60);
+  if (minutes < 60) return `${minutes}m ago`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${hours}h ago`;
+  const days = Math.floor(hours / 24);
+  if (days < 7) return `${days}d ago`;
+  return date.toLocaleDateString("en-US", { month: "short", day: "numeric" });
+}
+
+/**
+ * Build a copy-pasteable text for a node's description with metadata header.
+ * Format:
+ *   [Project Name] issue-id
+ *   https://github.com/org/repo  (if available)
+ *
+ *   <description>
+ */
+export function buildDescriptionCopyText(
+  node: GraphNode,
+  repoUrl?: string,
+): string {
+  const lines: string[] = [];
+  lines.push(`[${getPrefixLabel(node.prefix)}] ${node.id}`);
+  if (repoUrl) lines.push(repoUrl);
+  lines.push("");
+  lines.push(node.description || "");
+  return lines.join("\n");
+}

package/lib/watch-beads.ts

@@ -0,0 +1,97 @@
+import { watch, existsSync } from "fs";
+import { join, dirname, basename } from "path";
+import { getAdditionalRepoPaths } from "./parse-beads";
+
+/**
+ * Get all issues.jsonl file paths that should be watched.
+ * Returns the primary path plus any additional repo paths from config.yaml.
+ */
+export function getWatchPaths(beadsDir: string): string[] {
+  const paths: string[] = [];
+
+  // Primary JSONL
+  const primary = join(beadsDir, "issues.jsonl");
+  if (existsSync(primary)) paths.push(primary);
+
+  // Additional repo JSONLs
+  const additionalRepos = getAdditionalRepoPaths(beadsDir);
+  for (const repoPath of additionalRepos) {
+    const jsonlPath = join(repoPath, ".beads", "issues.jsonl");
+    if (existsSync(jsonlPath)) paths.push(jsonlPath);
+  }
+
+  return paths;
+}
+
+/**
+ * Watch all issues.jsonl files for a beads project.
+ * Discovers files from the primary .beads dir and config.yaml repos.additional.
+ * Debounces rapid changes (bd often writes multiple times per command).
+ *
+ * @param beadsDir - Absolute path to the primary .beads/ directory
+ * @param onChange - Callback fired when any watched file changes (after debounce)
+ * @param debounceMs - Debounce interval in milliseconds (default: 300)
+ * @returns Cleanup function that closes all watchers
+ */
+export function watchBeadsFiles(
+  beadsDir: string,
+  onChange: () => void,
+  debounceMs = 300
+): () => void {
+  const filePaths = getWatchPaths(beadsDir);
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  const watchers: ReturnType<typeof watch>[] = [];
+
+  // Deduplicate directories — multiple files may share the same .beads/ dir
+  const dirToFiles = new Map<string, Set<string>>();
+  for (const filePath of filePaths) {
+    const dir = dirname(filePath);
+    const file = basename(filePath);
+    if (!dirToFiles.has(dir)) dirToFiles.set(dir, new Set());
+    dirToFiles.get(dir)!.add(file);
+  }
+
+  console.log(
+    `[heartbeads] Watching ${filePaths.length} file(s) in ${dirToFiles.size} dir(s) for changes`
+  );
+
+  const debouncedOnChange = () => {
+    if (timer) clearTimeout(timer);
+    timer = setTimeout(() => {
+      console.log("[heartbeads] File change detected, pushing update");
+      onChange();
+    }, debounceMs);
+  };
+
+  // Watch directories instead of individual files.
+  // This is far more reliable on macOS: fs.watch on a file breaks when the
+  // file is atomically replaced (write-tmp + rename), which is how bd and
+  // many editors write. Watching the directory catches renames reliably.
+  for (const [dir, fileNames] of dirToFiles) {
+    try {
+      const watcher = watch(dir, { persistent: true }, (_eventType, filename) => {
+        // Filter: only react to changes to our target files
+        if (filename && fileNames.has(filename)) {
+          debouncedOnChange();
+        }
+      });
+      watchers.push(watcher);
+      console.log(`[heartbeads]   Watching dir: ${dir} for [${[...fileNames].join(", ")}]`);
+    } catch (err) {
+      console.warn(`[heartbeads] Failed to watch ${dir}:`, err);
+    }
+  }
+
+  if (filePaths.length === 0) {
+    console.warn("[heartbeads] No issues.jsonl files found to watch");
+  }
+
+  // Return cleanup function
+  return () => {
+    if (timer) clearTimeout(timer);
+    for (const w of watchers) {
+      w.close();
+    }
+    console.log("[heartbeads] File watchers closed");
+  };
+}

package/next.config.mjs

@@ -0,0 +1,4 @@
+/** @type {import('next').NextConfig} */
+const nextConfig = {};
+
+export default nextConfig;

package/package.json

@@ -0,0 +1,81 @@
+{
+  "name": "heartbeads",
+  "version": "0.4.0",
+  "description": "Interactive dependency graph viewer for beads (bd) issues",
+  "keywords": [
+    "beads",
+    "bd",
+    "issue-tracking",
+    "dependency-graph",
+    "visualization"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/GainForest/heartbeads.git"
+  },
+  "license": "MIT",
+  "bin": {
+    "heartbeads": "./bin/heartbeads.mjs"
+  },
+  "files": [
+    "app",
+    "components",
+    "hooks",
+    "lib",
+    "bin",
+    "scripts",
+    "public",
+    ".next/server",
+    ".next/static",
+    ".next/BUILD_ID",
+    ".next/build-manifest.json",
+    ".next/app-build-manifest.json",
+    ".next/app-path-routes-manifest.json",
+    ".next/export-marker.json",
+    ".next/images-manifest.json",
+    ".next/package.json",
+    ".next/prerender-manifest.json",
+    ".next/react-loadable-manifest.json",
+    ".next/required-server-files.json",
+    ".next/routes-manifest.json",
+    ".next/next-minimal-server.js.nft.json",
+    ".next/next-server.js.nft.json",
+    "next.config.mjs",
+    "tailwind.config.ts",
+    "tsconfig.json",
+    "postcss.config.mjs",
+    "package.json"
+  ],
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start",
+    "lint": "next lint",
+    "prepublishOnly": "next build"
+  },
+  "dependencies": {
+    "@atproto/api": "^0.18.20",
+    "@atproto/jwk-jose": "^0.1.11",
+    "@atproto/oauth-client-node": "^0.3.16",
+    "@atproto/syntax": "^0.4.3",
+    "@types/d3-force": "^3.0.10",
+    "d3-force": "^3.0.0",
+    "iron-session": "^8.0.4",
+    "next": "^14.2.21",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "react-force-graph-2d": "^1.25.7",
+    "react-markdown": "^10.1.0",
+    "remark-gfm": "^4.0.1",
+    "yaml": "^2.8.2"
+  },
+  "devDependencies": {
+    "@types/node": "^20.17.0",
+    "@types/react": "^18.3.12",
+    "@types/react-dom": "^18.3.1",
+    "autoprefixer": "^10.4.20",
+    "postcss": "^8.4.49",
+    "tailwindcss": "^3.4.16",
+    "typescript": "^5.7.2"
+  }
+}

package/postcss.config.mjs

@@ -0,0 +1,9 @@
+/** @type {import('postcss-load-config').Config} */
+const config = {
+  plugins: {
+    tailwindcss: {},
+    autoprefixer: {},
+  },
+};
+
+export default config;

package/scripts/generate-jwk.js

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+
+/**
+ * Generate an ES256 JWK private key for ATProto OAuth confidential client authentication.
+ *
+ * Usage: node scripts/generate-jwk.js
+ *
+ * Copy the output and add it to your .env file as ATPROTO_JWK_PRIVATE
+ */
+
+const crypto = require('crypto')
+
+async function generateJWK() {
+  // Generate an EC key pair using P-256 curve (required for ES256)
+  const { privateKey } = await crypto.subtle.generateKey(
+    {
+      name: 'ECDSA',
+      namedCurve: 'P-256',
+    },
+    true, // extractable
+    ['sign', 'verify']
+  )
+
+  // Export as JWK
+  const jwk = await crypto.subtle.exportKey('jwk', privateKey)
+
+  // Add key ID and algorithm
+  jwk.kid = `key-${Date.now()}`
+  jwk.alg = 'ES256'
+  jwk.use = 'sig'
+
+  console.log('\n=== ES256 Private Key (JWK) ===\n')
+  console.log('Add this to your .env file as ATPROTO_JWK_PRIVATE:\n')
+  console.log(JSON.stringify(jwk))
+  console.log('\n')
+}
+
+generateJWK().catch(console.error)

package/tailwind.config.ts

@@ -0,0 +1,41 @@
+import type { Config } from "tailwindcss";
+
+const config: Config = {
+  content: [
+    "./app/**/*.{js,ts,jsx,tsx,mdx}",
+    "./components/**/*.{js,ts,jsx,tsx,mdx}",
+  ],
+  theme: {
+    extend: {
+      fontFamily: {
+        sans: [
+          "Inter",
+          "system-ui",
+          "-apple-system",
+          "BlinkMacSystemFont",
+          "Segoe UI",
+          "Roboto",
+          "sans-serif",
+        ],
+        mono: ["JetBrains Mono", "Fira Code", "monospace"],
+      },
+      colors: {
+        beads: {
+          50: "#ecfdf5",
+          100: "#d1fae5",
+          200: "#a7f3d0",
+          300: "#6ee7b7",
+          400: "#34d399",
+          500: "#10b981",
+          600: "#059669",
+          700: "#047857",
+          800: "#065f46",
+          900: "#064e3b",
+        },
+      },
+    },
+  },
+  plugins: [],
+};
+
+export default config;

package/tsconfig.json

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