heartbeads 0.4.0

package/lib/discover.ts

@@ -0,0 +1,228 @@
+import { existsSync, readFileSync, realpathSync, statSync } from "fs";
+import { join, resolve, dirname, basename, parse as pathParse } from "path";
+import { execSync } from "child_process";
+import { parse as parseYaml } from "yaml";
+
+export interface BeadsDiscovery {
+  beadsDir: string; // Absolute path to the .beads/ directory
+  repoRoot: string; // Parent directory of .beads/
+  repoName: string; // Directory name of repoRoot (e.g. 'my-project')
+  issuePrefix?: string; // From config.yaml issue-prefix field, if set
+  additionalRepos: number; // Count of repos.additional entries (0 for single-repo)
+}
+
+/**
+ * Read config.yaml from a .beads directory and extract metadata.
+ */
+function readBeadsConfig(beadsDir: string): {
+  issuePrefix?: string;
+  additionalRepos: number;
+} {
+  const configPath = join(beadsDir, "config.yaml");
+  try {
+    if (!existsSync(configPath)) return { additionalRepos: 0 };
+    const content = readFileSync(configPath, "utf-8");
+    const config = parseYaml(content);
+
+    const issuePrefix = config?.["issue-prefix"] || undefined;
+    const additional = config?.repos?.additional;
+    const additionalRepos = Array.isArray(additional) ? additional.length : 0;
+
+    return { issuePrefix, additionalRepos };
+  } catch {
+    return { additionalRepos: 0 };
+  }
+}
+
+/**
+ * Auto-discover the .beads/ directory by walking up from a starting directory,
+ * similar to how git finds .git/ or how bd itself finds .beads/.
+ *
+ * Resolution order:
+ * 1. BEADS_DIR environment variable (if set)
+ * 2. Walk up from startDir (or process.cwd()) looking for .beads/issues.jsonl
+ *
+ * @param startDir - Directory to start searching from (defaults to process.cwd())
+ * @throws Error if no .beads/ directory is found
+ */
+export function discoverBeadsDir(startDir?: string): BeadsDiscovery {
+  // 1. Check BEADS_DIR env var
+  const envDir = process.env.BEADS_DIR;
+  if (envDir) {
+    const resolved = resolve(envDir);
+
+    // Accept both /path/to/.beads and /path/to/repo (auto-append .beads/)
+    let beadsDir: string;
+    if (basename(resolved) === ".beads") {
+      beadsDir = resolved;
+    } else if (existsSync(join(resolved, ".beads"))) {
+      beadsDir = join(resolved, ".beads");
+    } else {
+      // Treat as .beads dir directly even if it doesn't exist yet
+      beadsDir = resolved;
+    }
+
+    try {
+      beadsDir = realpathSync(beadsDir);
+    } catch {
+      // realpathSync fails if path doesn't exist — use as-is
+    }
+
+    const repoRoot = dirname(beadsDir);
+    const repoName = basename(repoRoot);
+    const configData = readBeadsConfig(beadsDir);
+
+    return {
+      beadsDir,
+      repoRoot,
+      repoName,
+      ...configData,
+    };
+  }
+
+  // 2. Walk up directory tree from startDir or cwd
+  let current = resolve(startDir || process.cwd());
+  const { root } = pathParse(current);
+
+  while (true) {
+    const candidate = join(current, ".beads");
+
+    // Check for .beads/ directory (with or without issues.jsonl — empty projects are valid)
+    if (existsSync(candidate) && statSync(candidate).isDirectory()) {
+      let beadsDir: string;
+      try {
+        beadsDir = realpathSync(candidate);
+      } catch {
+        beadsDir = candidate;
+      }
+
+      const repoRoot = dirname(beadsDir);
+      const repoName = basename(repoRoot);
+      const configData = readBeadsConfig(beadsDir);
+
+      return {
+        beadsDir,
+        repoRoot,
+        repoName,
+        ...configData,
+      };
+    }
+
+    // Reached filesystem root without finding .beads/
+    if (current === root) {
+      throw new Error(
+        `No .beads/ directory found.\n` +
+          `Searched from: ${resolve(startDir || process.cwd())}\n\n` +
+          `To initialize beads in your project, run:\n` +
+          `  bd init\n\n` +
+          `Or set the BEADS_DIR environment variable:\n` +
+          `  BEADS_DIR=/path/to/project/.beads heartbeads`
+      );
+    }
+
+    // Move up one level
+    current = dirname(current);
+  }
+}
+
+/**
+ * Convert a raw git remote URL to a browser-friendly HTTPS URL.
+ * Handles: git@github.com:Org/repo.git, https://github.com/Org/repo.git, etc.
+ */
+function gitUrlToHttps(rawUrl: string): string | null {
+  let url = rawUrl.trim().replace(/\.git$/, "");
+
+  // SSH format: git@github.com:Org/repo
+  const sshMatch = url.match(/^git@([^:]+):(.+)$/);
+  if (sshMatch) {
+    return `https://${sshMatch[1]}/${sshMatch[2]}`;
+  }
+
+  // Already HTTPS
+  if (url.startsWith("https://") || url.startsWith("http://")) {
+    return url;
+  }
+
+  return null;
+}
+
+/**
+ * Get the git remote origin URL for a directory, if it's a git repo.
+ */
+function getGitRemoteUrl(dir: string): string | null {
+  try {
+    const raw = execSync("git config --get remote.origin.url", {
+      cwd: dir,
+      encoding: "utf-8",
+      timeout: 3000,
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+    return gitUrlToHttps(raw);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Build a mapping of repo prefix → GitHub HTTPS URL for all discovered repos.
+ * Uses the primary repo + any additional repos from config.yaml.
+ */
+export function getRepoUrls(beadsDir: string): Record<string, string> {
+  const urls: Record<string, string> = {};
+
+  // Primary repo
+  const repoRoot = dirname(beadsDir);
+  const primaryUrl = getGitRemoteUrl(repoRoot);
+
+  // Read config to get issue-prefix and additional repos
+  const configPath = join(beadsDir, "config.yaml");
+  let issuePrefix: string | undefined;
+  let additionalPaths: string[] = [];
+
+  try {
+    if (existsSync(configPath)) {
+      const content = readFileSync(configPath, "utf-8");
+      const config = parseYaml(content);
+      issuePrefix = config?.["issue-prefix"] || undefined;
+      const additional = config?.repos?.additional;
+      if (Array.isArray(additional)) {
+        additionalPaths = additional
+          .map((p: string) => resolve(repoRoot, p))
+          .filter((p: string) => existsSync(join(p, ".beads")));
+      }
+    }
+  } catch {
+    // config.yaml unreadable
+  }
+
+  // Primary repo: use issue-prefix or directory name as key
+  const primaryPrefix = issuePrefix || basename(repoRoot);
+  if (primaryUrl) {
+    urls[primaryPrefix] = primaryUrl;
+  }
+
+  // Additional repos
+  for (const repoPath of additionalPaths) {
+    const url = getGitRemoteUrl(repoPath);
+    if (!url) continue;
+
+    // Read that repo's .beads/config.yaml for its issue-prefix
+    const subConfigPath = join(repoPath, ".beads", "config.yaml");
+    let prefix = basename(repoPath); // fallback: directory name
+    try {
+      if (existsSync(subConfigPath)) {
+        const content = readFileSync(subConfigPath, "utf-8");
+        const config = parseYaml(content);
+        if (config?.["issue-prefix"]) {
+          prefix = config["issue-prefix"];
+        }
+      }
+    } catch {
+      // use directory name fallback
+    }
+
+    urls[prefix] = url;
+  }
+
+  return urls;
+}

package/lib/env.ts

@@ -0,0 +1,33 @@
+/**
+ * Environment variable validation and defaults for ATProto OAuth.
+ * Allows missing values in dev mode (defaults kick in).
+ */
+export const env = {
+  /** iron-session encryption key (32+ chars) */
+  get COOKIE_SECRET(): string {
+    return (
+      process.env.COOKIE_SECRET ||
+      "development-secret-at-least-32-chars!!"
+    );
+  },
+
+  /** App's public URL (empty = localhost dev mode with public OAuth client) */
+  get PUBLIC_URL(): string {
+    return process.env.PUBLIC_URL || "";
+  },
+
+  /** Dev server port */
+  get PORT(): number {
+    return parseInt(process.env.PORT || "3000", 10);
+  },
+
+  /** ES256 JWK private key JSON (empty = public client mode) */
+  get ATPROTO_JWK_PRIVATE(): string {
+    return process.env.ATPROTO_JWK_PRIVATE || "";
+  },
+
+  /** Dashboard password (empty = no auth, open access) */
+  get HEARTBEADS_PASSWORD(): string {
+    return process.env.HEARTBEADS_PASSWORD || "";
+  },
+};

package/lib/gate.ts

@@ -0,0 +1,55 @@
+/**
+ * Password gate helpers for dashboard access control.
+ *
+ * The gate cookie is an HMAC-SHA256 signature of the string "heartbeads-gate"
+ * keyed by the dashboard password. This produces a static token that can be
+ * validated by both Node.js (API routes) and Edge Runtime (middleware).
+ *
+ * Used by:
+ * - app/api/auth/route.ts — generates and validates the cookie
+ * - middleware.ts — validates cookie, Bearer token, and query param
+ */
+
+import { createHmac, timingSafeEqual } from "crypto";
+
+export const COOKIE_NAME = "heartbeads_gate";
+const HMAC_MESSAGE = "heartbeads-gate";
+
+/**
+ * Generate the gate token (HMAC-SHA256 of a fixed message, keyed by password).
+ * This is the value stored in the httpOnly cookie.
+ */
+export function generateGateToken(password: string): string {
+  return createHmac("sha256", password).update(HMAC_MESSAGE).digest("hex");
+}
+
+/**
+ * Validate a gate token against the password (Node.js crypto, constant-time).
+ */
+export function validateGateToken(
+  token: string,
+  password: string
+): boolean {
+  const expected = generateGateToken(password);
+  if (token.length !== expected.length) return false;
+  try {
+    return timingSafeEqual(Buffer.from(token), Buffer.from(expected));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Constant-time password comparison (Node.js crypto).
+ */
+export function comparePassword(
+  provided: string,
+  expected: string
+): boolean {
+  if (provided.length !== expected.length) return false;
+  try {
+    return timingSafeEqual(Buffer.from(provided), Buffer.from(expected));
+  } catch {
+    return false;
+  }
+}

package/lib/parse-beads.ts

@@ -0,0 +1,234 @@
+import { readFileSync, existsSync } from "fs";
+import { join, resolve } from "path";
+import { parse as parseYaml } from "yaml";
+import { discoverBeadsDir } from "./discover";
+import type {
+  BeadIssue,
+  BeadDependency,
+  GraphNode,
+  GraphLink,
+  GraphData,
+  BeadsApiResponse,
+} from "./types";
+
+/**
+ * Extract the prefix from a bead ID (e.g. "my-app-5gw" -> "my-app")
+ */
+export function extractPrefix(id: string): string {
+  const lastDash = id.lastIndexOf("-");
+  if (lastDash === -1) return id;
+  return id.substring(0, lastDash);
+}
+
+/**
+ * Read repos.additional paths from .beads/config.yaml
+ */
+export function getAdditionalRepoPaths(beadsDir: string): string[] {
+  const configPath = join(beadsDir, "config.yaml");
+  try {
+    const content = readFileSync(configPath, "utf-8");
+    const config = parseYaml(content);
+    const additional = config?.repos?.additional;
+    if (Array.isArray(additional)) {
+      return additional
+        .map((p: string) => resolve(beadsDir, "..", p))
+        .filter((p: string) => existsSync(join(p, ".beads", "issues.jsonl")));
+    }
+  } catch (err) {
+    console.error("Failed to read config.yaml:", err);
+  }
+  return [];
+}
+
+/**
+ * Parse a single issues.jsonl file and return issues
+ */
+function parseJsonlFile(filePath: string): BeadIssue[] {
+  try {
+    const content = readFileSync(filePath, "utf-8");
+    const lines = content.split("\n").filter((line) => line.trim().length > 0);
+    return lines.map((line) => JSON.parse(line) as BeadIssue);
+  } catch (err) {
+    console.error(`Failed to parse ${filePath}:`, err);
+    return [];
+  }
+}
+
+/**
+ * Parse issues.jsonl from the primary .beads directory and all additional repos
+ */
+export function parseIssuesJsonl(beadsDir?: string): BeadIssue[] {
+  const dir = beadsDir || discoverBeadsDir().beadsDir;
+
+  // Load primary repo issues
+  const primaryPath = join(dir, "issues.jsonl");
+  const issues = parseJsonlFile(primaryPath);
+
+  // Load additional repo issues from config.yaml
+  const additionalRepos = getAdditionalRepoPaths(dir);
+  for (const repoPath of additionalRepos) {
+    const repoJsonl = join(repoPath, ".beads", "issues.jsonl");
+    const repoIssues = parseJsonlFile(repoJsonl);
+    issues.push(...repoIssues);
+  }
+
+  // Deduplicate by issue ID (primary repo wins) and filter out tombstones.
+  // bd delete marks issues with status "tombstone" rather than removing them
+  // from the JSONL file — we must exclude these from the graph.
+  const seen = new Set<string>();
+  return issues.filter((issue) => {
+    if (seen.has(issue.id)) return false;
+    seen.add(issue.id);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    if ((issue as any).status === "tombstone") return false;
+    return true;
+  });
+}
+
+/**
+ * Extract all dependencies from issues (they're embedded in each issue)
+ */
+export function extractDependencies(issues: BeadIssue[]): BeadDependency[] {
+  const deps: BeadDependency[] = [];
+  const seen = new Set<string>();
+
+  for (const issue of issues) {
+    if (issue.dependencies) {
+      for (const dep of issue.dependencies) {
+        const key = `${dep.issue_id}->${dep.depends_on_id}:${dep.type}`;
+        if (!seen.has(key)) {
+          seen.add(key);
+          deps.push(dep);
+        }
+      }
+    }
+  }
+
+  return deps;
+}
+
+/**
+ * Build graph data from issues and dependencies
+ */
+export function buildGraphData(
+  issues: BeadIssue[],
+  dependencies: BeadDependency[]
+): GraphData {
+  const issueMap = new Map(issues.map((i) => [i.id, i]));
+
+  // Count blockers and dependents for each issue
+  const blockerCounts = new Map<string, string[]>(); // issue -> issues it blocks
+  const dependentCounts = new Map<string, string[]>(); // issue -> issues that block it
+
+  for (const dep of dependencies) {
+    if (dep.type === "blocks" || dep.type === "parent-child") {
+      // For blocks: depends_on_id blocks issue_id
+      // For parent-child: depends_on_id is parent of issue_id
+      // Both count as connections for node sizing
+      if (!blockerCounts.has(dep.depends_on_id)) {
+        blockerCounts.set(dep.depends_on_id, []);
+      }
+      blockerCounts.get(dep.depends_on_id)!.push(dep.issue_id);
+
+      if (!dependentCounts.has(dep.issue_id)) {
+        dependentCounts.set(dep.issue_id, []);
+      }
+      dependentCounts.get(dep.issue_id)!.push(dep.depends_on_id);
+    }
+  }
+
+  const nodes: GraphNode[] = issues.map((issue) => ({
+    id: issue.id,
+    title: issue.title,
+    description: issue.description,
+    status: issue.status,
+    priority: issue.priority,
+    issueType: issue.issue_type,
+    owner: issue.owner,
+    assignee: issue.assignee,
+    createdBy: issue.created_by,
+    createdAt: issue.created_at,
+    updatedAt: issue.updated_at,
+    closedAt: issue.closed_at,
+    closeReason: issue.close_reason,
+    prefix: extractPrefix(issue.id),
+
+    blockerCount: blockerCounts.get(issue.id)?.length || 0,
+    dependentCount: dependentCounts.get(issue.id)?.length || 0,
+    blockerIds: blockerCounts.get(issue.id) || [],
+    dependentIds: dependentCounts.get(issue.id) || [],
+  }));
+
+  // Build links: include blocking AND parent-child dependencies where both nodes exist
+  const links: GraphLink[] = dependencies
+    .filter(
+      (d) =>
+        (d.type === "blocks" || d.type === "parent-child") &&
+        issueMap.has(d.issue_id) &&
+        issueMap.has(d.depends_on_id)
+    )
+    .map((d) => ({
+      // For both types: depends_on_id is the "upstream" node (blocker or parent)
+      // blocks: blocker -> blocked
+      // parent-child: parent -> child
+      source: d.depends_on_id,
+      target: d.issue_id,
+      type: d.type,
+      createdAt: d.created_at,
+    }));
+
+  return { nodes, links };
+}
+
+/**
+ * Compute stats from issues and dependencies
+ */
+export function computeStats(
+  issues: BeadIssue[],
+  dependencies: BeadDependency[],
+  graphData: GraphData
+) {
+  const prefixes = [...new Set(issues.map((i) => extractPrefix(i.id)))];
+
+  // An issue is "actionable" if it's open and has no open blockers
+  const openIssueIds = new Set(
+    issues.filter((i) => i.status !== "closed").map((i) => i.id)
+  );
+
+  const blockedByOpen = new Set<string>();
+  for (const dep of dependencies) {
+    if (dep.type === "blocks" && openIssueIds.has(dep.depends_on_id)) {
+      // issue_id is blocked by depends_on_id which is still open
+      blockedByOpen.add(dep.issue_id);
+    }
+  }
+
+  const actionable = issues.filter(
+    (i) =>
+      (i.status === "open" || i.status === "in_progress") &&
+      !blockedByOpen.has(i.id)
+  ).length;
+
+  return {
+    total: issues.length,
+    open: issues.filter((i) => i.status === "open").length,
+    inProgress: issues.filter((i) => i.status === "in_progress").length,
+    blocked: issues.filter((i) => i.status === "blocked").length,
+    closed: issues.filter((i) => i.status === "closed").length,
+    actionable,
+    edges: graphData.links.length,
+    prefixes,
+  };
+}
+
+/**
+ * Full pipeline: parse, extract, build, compute
+ */
+export function loadBeadsData(beadsDir?: string): BeadsApiResponse {
+  const issues = parseIssuesJsonl(beadsDir);
+  const dependencies = extractDependencies(issues);
+  const graphData = buildGraphData(issues, dependencies);
+  const stats = computeStats(issues, dependencies, graphData);
+
+  return { issues, dependencies, graphData, stats };
+}

package/lib/session.ts

@@ -0,0 +1,52 @@
+import { env } from "./env";
+import { getIronSession, type SessionOptions } from "iron-session";
+import { cookies } from "next/headers";
+
+/**
+ * Session data stored in the encrypted cookie.
+ */
+export interface Session {
+  did?: string;
+  handle?: string;
+  displayName?: string;
+  avatar?: string;
+  returnTo?: string;
+  // OAuth session data (serialized) - persisted across serverless invocations
+  oauthSession?: string;
+}
+
+const isProduction = process.env.NODE_ENV === "production";
+
+const sessionOptions: SessionOptions = {
+  cookieName: "beads_map_sid",
+  password: env.COOKIE_SECRET,
+  cookieOptions: {
+    secure: isProduction,
+    maxAge: 60 * 60 * 24 * 30, // 30 days
+  },
+};
+
+/**
+ * Get the current user's session from their encrypted cookie.
+ */
+export async function getSession(): Promise<Session> {
+  const cookieStore = await cookies();
+  const session = await getIronSession<Session>(cookieStore, sessionOptions);
+  return session;
+}
+
+/**
+ * Get the raw iron-session object for direct manipulation (save/destroy).
+ */
+export async function getRawSession() {
+  const cookieStore = await cookies();
+  return await getIronSession<Session>(cookieStore, sessionOptions);
+}
+
+/**
+ * Clear the current user's session.
+ */
+export async function clearSession(): Promise<void> {
+  const session = await getRawSession();
+  session.destroy();
+}

package/lib/settings.ts

@@ -0,0 +1,42 @@
+// ============================================================================
+// User settings — persisted in localStorage
+// ============================================================================
+
+export interface BeadsMapSettings {
+  elevenLabsApiKey?: string;
+  elevenLabsVoiceId: string;
+  elevenLabsModel: string;
+}
+
+const STORAGE_KEY = "heartbeads-settings";
+
+const DEFAULTS: BeadsMapSettings = {
+  elevenLabsVoiceId: "UgBBYS2sOqTuMpoF3BR0", // Mark - Natural Conversations
+  elevenLabsModel: "eleven_flash_v2_5",
+};
+
+/** Read settings from localStorage, merged with defaults */
+export function getSettings(): BeadsMapSettings {
+  if (typeof window === "undefined") return { ...DEFAULTS };
+  try {
+    const raw = localStorage.getItem(STORAGE_KEY);
+    if (!raw) return { ...DEFAULTS };
+    return { ...DEFAULTS, ...JSON.parse(raw) };
+  } catch {
+    return { ...DEFAULTS };
+  }
+}
+
+/** Write settings to localStorage */
+export function saveSettings(settings: Partial<BeadsMapSettings>): void {
+  if (typeof window === "undefined") return;
+  const current = getSettings();
+  const merged = { ...current, ...settings };
+  localStorage.setItem(STORAGE_KEY, JSON.stringify(merged));
+}
+
+/** Check if ElevenLabs API key is configured */
+export function hasApiKey(): boolean {
+  const s = getSettings();
+  return !!s.elevenLabsApiKey && s.elevenLabsApiKey.trim().length > 0;
+}