beads-map 0.1.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 beads-map`
+      );
+    }
+
+    // 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,28 @@
+/**
+ * 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 || "";
+  },
+};

package/lib/parse-beads.ts

@@ -0,0 +1,232 @@
+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,
+    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/timeline.ts

@@ -0,0 +1,138 @@
+import type { GraphNode, GraphLink } from "./types";
+
+// ============================================================================
+// Timeline event types
+// ============================================================================
+
+export type TimelineEventType = "node-created" | "node-closed";
+
+export interface TimelineEvent {
+  time: number; // unix ms
+  type: TimelineEventType;
+  id: string; // node ID or "source->target"
+}
+
+export interface TimelineRange {
+  events: TimelineEvent[];
+  minTime: number; // earliest event (unix ms)
+  maxTime: number; // latest event (unix ms)
+}
+
+// ============================================================================
+// Event extraction
+// ============================================================================
+
+/**
+ * Extract all temporal events from nodes and links, sorted chronologically.
+ *
+ * Events:
+ * - node-created: from node.createdAt
+ * - node-closed: from node.closedAt (if present)
+ * - link-created: from link.createdAt (if present)
+ *
+ * Nodes/links missing timestamps are skipped.
+ */
+export function buildTimelineEvents(
+  nodes: GraphNode[],
+  links: GraphLink[]
+): TimelineRange {
+  const events: TimelineEvent[] = [];
+
+  for (const node of nodes) {
+    const createdMs = new Date(node.createdAt).getTime();
+    if (!isNaN(createdMs)) {
+      events.push({ time: createdMs, type: "node-created", id: node.id });
+    }
+    if (node.closedAt) {
+      const closedMs = new Date(node.closedAt).getTime();
+      if (!isNaN(closedMs)) {
+        events.push({ time: closedMs, type: "node-closed", id: node.id });
+      }
+    }
+  }
+
+  events.sort((a, b) => a.time - b.time);
+
+  const minTime = events.length > 0 ? events[0].time : Date.now();
+  const maxTime =
+    events.length > 0 ? events[events.length - 1].time : Date.now();
+
+  return { events, minTime, maxTime };
+}
+
+// ============================================================================
+// Time filtering
+// ============================================================================
+
+/**
+ * Filter nodes and links to only include items visible at `currentTime`.
+ *
+ * Node visibility: createdAt <= currentTime.
+ * Node status override: if closedAt <= currentTime, force status to "closed".
+ * Link visibility: both endpoints visible AND link.createdAt <= currentTime.
+ *   If link has no createdAt, it appears when both endpoints are visible.
+ *
+ * Returns shallow copies when status is overridden, original objects otherwise
+ * (preserves x/y positions from force simulation).
+ */
+export function filterDataAtTime(
+  allNodes: GraphNode[],
+  allLinks: GraphLink[],
+  currentTime: number
+): { nodes: GraphNode[]; links: GraphLink[] } {
+  const visibleNodeIds = new Set<string>();
+  const nodes: GraphNode[] = [];
+
+  for (const node of allNodes) {
+    const createdMs = new Date(node.createdAt).getTime();
+    if (isNaN(createdMs) || createdMs > currentTime) continue;
+
+    visibleNodeIds.add(node.id);
+
+    // Determine correct status at this point in time
+    let status = node.status;
+    if (node.closedAt) {
+      const closedMs = new Date(node.closedAt).getTime();
+      if (!isNaN(closedMs) && closedMs <= currentTime) {
+        status = "closed";
+      } else if (node.status === "closed") {
+        // Node is closed in current data but we're before closedAt — show as open
+        status = "open";
+      }
+    }
+
+    if (status !== node.status) {
+      nodes.push({ ...node, status } as GraphNode);
+    } else {
+      nodes.push(node);
+    }
+  }
+
+  // Filter visible links
+  const links: GraphLink[] = [];
+  for (const link of allLinks) {
+    const src =
+      typeof link.source === "object"
+        ? (link.source as { id: string }).id
+        : link.source;
+    const tgt =
+      typeof link.target === "object"
+        ? (link.target as { id: string }).id
+        : link.target;
+
+    // Both endpoints must be visible — link appears when both nodes are on canvas
+    if (!visibleNodeIds.has(src) || !visibleNodeIds.has(tgt)) continue;
+
+    // Normalize source/target to string IDs — d3-force mutates link objects
+    // in-place replacing strings with object refs to the main graph's nodes.
+    // We must return fresh objects with string IDs so ForceGraph2D resolves
+    // them against the timeline's node array, not the main graph's.
+    links.push({
+      ...link,
+      source: src,
+      target: tgt,
+    });
+  }
+
+  return { nodes, links };
+}