heartbeads 0.4.0

package/app/api/oauth/client-metadata.json/route.ts

@@ -0,0 +1,33 @@
+import { NextResponse } from "next/server";
+import { env } from "@/lib/env";
+
+export const dynamic = "force-dynamic";
+
+export async function GET() {
+  const publicUrl = env.PUBLIC_URL;
+  const url = publicUrl || `http://127.0.0.1:${env.PORT}`;
+  const isConfidential = !!publicUrl && !!env.ATPROTO_JWK_PRIVATE;
+
+  const metadata: Record<string, unknown> = {
+    client_name: "Beads Map",
+    client_uri: url,
+    dpop_bound_access_tokens: true,
+    grant_types: ["authorization_code", "refresh_token"],
+    response_types: ["code"],
+    scope: "atproto transition:generic",
+    application_type: "web",
+    redirect_uris: [`${url}/api/oauth/callback`],
+  };
+
+  if (isConfidential) {
+    metadata.client_id = `${publicUrl}/api/oauth/client-metadata.json`;
+    metadata.token_endpoint_auth_method = "private_key_jwt";
+    metadata.token_endpoint_auth_signing_alg = "ES256";
+    metadata.jwks_uri = `${publicUrl}/api/oauth/jwks.json`;
+  } else {
+    metadata.client_id = `http://localhost?redirect_uri=${encodeURIComponent(`${url}/api/oauth/callback`)}&scope=${encodeURIComponent("atproto transition:generic")}`;
+    metadata.token_endpoint_auth_method = "none";
+  }
+
+  return NextResponse.json(metadata);
+}

package/app/api/oauth/jwks.json/route.ts

@@ -0,0 +1,32 @@
+import { NextResponse } from "next/server";
+import { getJwks } from "@/lib/auth/client";
+
+export const dynamic = "force-dynamic";
+
+export async function GET() {
+  try {
+    const jwks = await getJwks();
+
+    if (!jwks) {
+      return NextResponse.json(
+        { keys: [] },
+        {
+          headers: {
+            "Content-Type": "application/json",
+            "Cache-Control": "public, max-age=3600",
+          },
+        }
+      );
+    }
+
+    return NextResponse.json(jwks, {
+      headers: {
+        "Content-Type": "application/json",
+        "Cache-Control": "public, max-age=3600",
+      },
+    });
+  } catch (error) {
+    console.error("Failed to get JWKS:", error);
+    return NextResponse.json({ keys: [] }, { status: 500 });
+  }
+}

package/app/api/records/route.ts

@@ -0,0 +1,168 @@
+import { NextRequest, NextResponse } from "next/server";
+import { getAuthenticatedAgent } from "@/lib/agent";
+import { getSession } from "@/lib/session";
+
+export const dynamic = "force-dynamic";
+
+/**
+ * POST /api/records — Create a new record
+ * Body: { collection, rkey?, record }
+ */
+export async function POST(request: NextRequest) {
+  try {
+    const session = await getSession();
+    if (!session.did) {
+      return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+    }
+
+    const agent = await getAuthenticatedAgent();
+    if (!agent) {
+      return NextResponse.json(
+        { error: "Failed to authenticate" },
+        { status: 401 }
+      );
+    }
+
+    const body = await request.json();
+    const { collection, rkey, record } = body;
+
+    if (!collection || typeof collection !== "string") {
+      return NextResponse.json(
+        { error: "Collection is required" },
+        { status: 400 }
+      );
+    }
+    if (!record || typeof record !== "object") {
+      return NextResponse.json(
+        { error: "Record is required" },
+        { status: 400 }
+      );
+    }
+
+    const res = await agent.com.atproto.repo.createRecord({
+      repo: session.did,
+      collection,
+      rkey: rkey || undefined,
+      record,
+    });
+
+    return NextResponse.json({
+      success: true,
+      uri: res.data.uri,
+      cid: res.data.cid,
+    });
+  } catch (error) {
+    console.error("Failed to create record:", error);
+    const message =
+      error instanceof Error ? error.message : "Failed to create record";
+    return NextResponse.json({ error: message }, { status: 500 });
+  }
+}
+
+/**
+ * PUT /api/records — Update an existing record
+ * Body: { collection, rkey, record }
+ */
+export async function PUT(request: NextRequest) {
+  try {
+    const session = await getSession();
+    if (!session.did) {
+      return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+    }
+
+    const agent = await getAuthenticatedAgent();
+    if (!agent) {
+      return NextResponse.json(
+        { error: "Failed to authenticate" },
+        { status: 401 }
+      );
+    }
+
+    const body = await request.json();
+    const { collection, rkey, record } = body;
+
+    if (!collection || typeof collection !== "string") {
+      return NextResponse.json(
+        { error: "Collection is required" },
+        { status: 400 }
+      );
+    }
+    if (!rkey || typeof rkey !== "string") {
+      return NextResponse.json(
+        { error: "Record key is required" },
+        { status: 400 }
+      );
+    }
+    if (!record || typeof record !== "object") {
+      return NextResponse.json(
+        { error: "Record is required" },
+        { status: 400 }
+      );
+    }
+
+    await agent.com.atproto.repo.putRecord({
+      repo: session.did,
+      collection,
+      rkey,
+      record,
+    });
+
+    return NextResponse.json({ success: true });
+  } catch (error) {
+    console.error("Failed to update record:", error);
+    const message =
+      error instanceof Error ? error.message : "Failed to update record";
+    return NextResponse.json({ error: message }, { status: 500 });
+  }
+}
+
+/**
+ * DELETE /api/records?collection=...&rkey=...
+ * Deletes a record from the authenticated user's repo.
+ */
+export async function DELETE(request: NextRequest) {
+  try {
+    const session = await getSession();
+    if (!session.did) {
+      return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+    }
+
+    const agent = await getAuthenticatedAgent();
+    if (!agent) {
+      return NextResponse.json(
+        { error: "Failed to authenticate" },
+        { status: 401 }
+      );
+    }
+
+    const { searchParams } = new URL(request.url);
+    const collection = searchParams.get("collection");
+    const rkey = searchParams.get("rkey");
+
+    if (!collection) {
+      return NextResponse.json(
+        { error: "Collection is required" },
+        { status: 400 }
+      );
+    }
+    if (!rkey) {
+      return NextResponse.json(
+        { error: "Record key is required" },
+        { status: 400 }
+      );
+    }
+
+    await agent.com.atproto.repo.deleteRecord({
+      repo: session.did,
+      collection,
+      rkey,
+    });
+
+    return NextResponse.json({ success: true });
+  } catch (error) {
+    console.error("Failed to delete record:", error);
+    const message =
+      error instanceof Error ? error.message : "Failed to delete record";
+    return NextResponse.json({ error: message }, { status: 500 });
+  }
+}

package/app/api/status/route.ts

@@ -0,0 +1,25 @@
+import { NextResponse } from "next/server";
+import { getSession } from "@/lib/session";
+
+export const dynamic = "force-dynamic";
+
+export async function GET() {
+  try {
+    const session = await getSession();
+
+    if (!session.did) {
+      return NextResponse.json({ authenticated: false });
+    }
+
+    return NextResponse.json({
+      authenticated: true,
+      did: session.did,
+      handle: session.handle,
+      displayName: session.displayName,
+      avatar: session.avatar,
+    });
+  } catch (error) {
+    console.error("Status check failed:", error);
+    return NextResponse.json({ authenticated: false });
+  }
+}

package/app/api/v1/graph/route.ts

@@ -0,0 +1,251 @@
+/**
+ * GET /api/v1/graph — Full project snapshot for AI agents.
+ *
+ * Returns the entire beads graph with issues, dependencies, comments,
+ * claims, and activity in a single JSON response. No auth required.
+ *
+ * Query params:
+ *   ?status=open,in_progress   Filter issues by status (comma-separated)
+ *   ?priority=0,1              Filter by priority (comma-separated)
+ *   ?prefix=beads-map          Filter by repo prefix
+ *   ?include=comments,activity Opt-in fields (default: all)
+ *   ?limit=50                  Activity feed cap (default 50, max 200)
+ */
+
+import { loadBeadsData } from "@/lib/parse-beads";
+import { discoverBeadsDir, getRepoUrls } from "@/lib/discover";
+import { fetchBeadsComments, getClaimedNodes } from "@/lib/comments";
+import type { BeadsComment, ClaimInfo } from "@/lib/comments";
+import { buildHistoricalFeed } from "@/lib/activity";
+import type { GraphNode } from "@/lib/types";
+import { jsonResponse, errorResponse, OPTIONS } from "@/lib/api-helpers";
+import { readFileSync, existsSync } from "fs";
+import { join } from "path";
+import { parse as parseYaml } from "yaml";
+
+export const dynamic = "force-dynamic";
+export { OPTIONS };
+
+// Read version from package.json at module load time
+let heartbeadsVersion = "0.0.0";
+try {
+  const pkg = JSON.parse(
+    readFileSync(join(process.cwd(), "package.json"), "utf-8")
+  );
+  heartbeadsVersion = pkg.version || heartbeadsVersion;
+} catch {
+  // ignore
+}
+
+/** Serialize a BeadsComment tree for API output */
+function serializeComment(c: BeadsComment): Record<string, unknown> {
+  return {
+    author: {
+      handle: c.handle,
+      did: c.did,
+      ...(c.displayName ? { displayName: c.displayName } : {}),
+    },
+    text: c.text,
+    createdAt: c.createdAt,
+    likes: c.likes.length,
+    replies: c.replies.map(serializeComment),
+  };
+}
+
+/** Serialize a claim for API output */
+function serializeClaim(claim: ClaimInfo) {
+  return {
+    handle: claim.handle,
+    did: claim.did,
+    ...(claim.displayName ? { displayName: claim.displayName } : {}),
+    claimed_at: claim.claimedAt,
+  };
+}
+
+export async function GET(request: Request) {
+  try {
+    const discovery = discoverBeadsDir();
+    const url = new URL(request.url);
+    const params = url.searchParams;
+
+    // Parse query params
+    const statusFilter = params.get("status")?.split(",").filter(Boolean);
+    const priorityFilter = params
+      .get("priority")
+      ?.split(",")
+      .map(Number)
+      .filter((n) => !isNaN(n));
+    const prefixFilter = params.get("prefix") || null;
+    const includeParam = params.get("include");
+    const limit = Math.min(
+      Math.max(parseInt(params.get("limit") || "50") || 50, 1),
+      200
+    );
+
+    // Determine what to include (default: everything)
+    let includeComments = true;
+    let includeActivity = true;
+    if (includeParam !== null) {
+      const includes = includeParam.split(",").filter(Boolean);
+      includeComments = includes.includes("comments");
+      includeActivity = includes.includes("activity");
+    }
+
+    // Load beads data + config in parallel with optional comments
+    const beadsPromise = Promise.resolve(loadBeadsData(discovery.beadsDir));
+    const commentsPromise = includeComments
+      ? fetchBeadsComments().catch((err) => {
+          console.error("[api/v1/graph] Failed to fetch comments:", err);
+          return null;
+        })
+      : Promise.resolve(null);
+
+    const [beadsData, commentsResult] = await Promise.all([
+      beadsPromise,
+      commentsPromise,
+    ]);
+
+    // Build project metadata
+    let repos: string[] = ["."];
+    const configPath = join(discovery.beadsDir, "config.yaml");
+    try {
+      if (existsSync(configPath)) {
+        const content = readFileSync(configPath, "utf-8");
+        const config = parseYaml(content);
+        const additional = config?.repos?.additional;
+        if (Array.isArray(additional)) {
+          repos = [config?.repos?.primary || ".", ...additional];
+        }
+      }
+    } catch {
+      // ignore
+    }
+
+    const repoUrls = getRepoUrls(discovery.beadsDir);
+    const claims = commentsResult
+      ? getClaimedNodes(commentsResult.allComments)
+      : new Map<string, ClaimInfo>();
+
+    // Build node map for enrichment
+    const nodeMap = new Map<string, GraphNode>(
+      beadsData.graphData.nodes.map((n) => [n.id, n])
+    );
+
+    // Filter and enrich issues
+    let issues = beadsData.graphData.nodes;
+
+    if (statusFilter) {
+      issues = issues.filter((n) => statusFilter.includes(n.status));
+    }
+    if (priorityFilter) {
+      issues = issues.filter((n) => priorityFilter.includes(n.priority));
+    }
+    if (prefixFilter) {
+      issues = issues.filter((n) => n.prefix === prefixFilter);
+    }
+
+    const enrichedIssues = issues.map((node) => {
+      const nodeComments =
+        commentsResult?.commentsByNode.get(node.id) || [];
+      const claim = claims.get(node.id) || null;
+
+      return {
+        id: node.id,
+        title: node.title,
+        description: node.description || null,
+        status: node.status,
+        priority: node.priority,
+        issue_type: node.issueType,
+        owner: node.owner || null,
+        assignee: node.assignee || null,
+        labels: [] as string[], // labels not on GraphNode, could extend later
+        created_at: node.createdAt,
+        updated_at: node.updatedAt,
+        closed_at: node.closedAt || null,
+        close_reason: node.closeReason || null,
+        prefix: node.prefix,
+        blockers: node.dependentIds,   // issues that block this one (upstream)
+        dependents: node.blockerIds,   // issues this one blocks (downstream)
+        ...(includeComments
+          ? { comments: nodeComments.map(serializeComment) }
+          : {}),
+        claimed_by: claim ? serializeClaim(claim) : null,
+      };
+    });
+
+    // Build dependencies
+    const dependencies = beadsData.graphData.links.map((link) => {
+      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;
+      return { from: src, to: tgt, type: link.type };
+    });
+
+    // Build activity feed
+    let activity: Record<string, unknown>[] = [];
+    if (includeActivity) {
+      const feed = buildHistoricalFeed(
+        beadsData.graphData.nodes,
+        beadsData.graphData.links,
+        commentsResult?.allComments || null
+      );
+      activity = feed.slice(0, limit).map((event) => ({
+        type: event.type,
+        time: new Date(event.time).toISOString(),
+        issue_id: event.nodeId,
+        ...(event.nodeTitle ? { issue_title: event.nodeTitle } : {}),
+        ...(event.actor ? { actor: { handle: event.actor.handle } } : {}),
+        ...(event.detail ? { detail: event.detail } : {}),
+      }));
+    }
+
+    // Warnings for partial data
+    const warnings: string[] = [];
+    if (includeComments && !commentsResult) {
+      warnings.push("Failed to fetch comments from indexer");
+    }
+
+    return jsonResponse({
+      project: {
+        name: discovery.issuePrefix || discovery.repoName,
+        prefix: discovery.issuePrefix || null,
+        repos,
+        repoUrls,
+      },
+      issues: enrichedIssues,
+      dependencies,
+      stats: {
+        total: beadsData.stats.total,
+        open: beadsData.stats.open,
+        in_progress: beadsData.stats.inProgress,
+        blocked: beadsData.stats.blocked,
+        closed: beadsData.stats.closed,
+        actionable: beadsData.stats.actionable,
+      },
+      ...(includeActivity ? { activity } : {}),
+      _meta: {
+        generated_at: new Date().toISOString(),
+        api_version: "v1" as const,
+        heartbeads_version: heartbeadsVersion,
+        ...(warnings.length ? { warnings } : {}),
+      },
+    });
+  } catch (error: unknown) {
+    const message =
+      error instanceof Error ? error.message : "Unknown error";
+    if (message.includes("No .beads/ directory found")) {
+      return errorResponse(
+        "No .beads directory found",
+        404,
+        "Run bd init in your project first, or set BEADS_DIR."
+      );
+    }
+    console.error("[api/v1/graph] Error:", error);
+    return errorResponse("Internal server error", 500);
+  }
+}

package/app/api/v1/issues/[id]/route.ts

@@ -0,0 +1,158 @@
+/**
+ * GET /api/v1/issues/:id — Single issue detail for AI agents.
+ *
+ * Returns one issue with full description, threaded comments,
+ * claim info, and enriched blockers/dependents (with title + status).
+ * No auth required.
+ */
+
+import { loadBeadsData } from "@/lib/parse-beads";
+import { discoverBeadsDir } from "@/lib/discover";
+import { fetchBeadsComments, getClaimedNodes } from "@/lib/comments";
+import type { BeadsComment, ClaimInfo } from "@/lib/comments";
+import type { GraphNode } from "@/lib/types";
+import { jsonResponse, errorResponse, OPTIONS } from "@/lib/api-helpers";
+import { readFileSync } from "fs";
+import { join } from "path";
+
+export const dynamic = "force-dynamic";
+export { OPTIONS };
+
+let heartbeadsVersion = "0.0.0";
+try {
+  const pkg = JSON.parse(
+    readFileSync(join(process.cwd(), "package.json"), "utf-8")
+  );
+  heartbeadsVersion = pkg.version || heartbeadsVersion;
+} catch {
+  // ignore
+}
+
+function serializeComment(c: BeadsComment): Record<string, unknown> {
+  return {
+    author: {
+      handle: c.handle,
+      did: c.did,
+      ...(c.displayName ? { displayName: c.displayName } : {}),
+    },
+    text: c.text,
+    createdAt: c.createdAt,
+    likes: c.likes.length,
+    replies: c.replies.map(serializeComment),
+  };
+}
+
+export async function GET(
+  request: Request,
+  { params }: { params: { id: string } }
+) {
+  try {
+    const discovery = discoverBeadsDir();
+    const issueId = params.id;
+
+    // Load beads data + comments in parallel
+    const [beadsData, commentsResult] = await Promise.all([
+      Promise.resolve(loadBeadsData(discovery.beadsDir)),
+      fetchBeadsComments().catch((err) => {
+        console.error("[api/v1/issues] Failed to fetch comments:", err);
+        return null;
+      }),
+    ]);
+
+    // Find the issue
+    const nodeMap = new Map<string, GraphNode>(
+      beadsData.graphData.nodes.map((n) => [n.id, n])
+    );
+    const node = nodeMap.get(issueId);
+
+    if (!node) {
+      return errorResponse(
+        "Issue not found",
+        404,
+        `No issue with id "${issueId}". Use GET /api/v1/graph to list all issues.`
+      );
+    }
+
+    // Build enriched blockers/dependents with title + status
+    // dependentIds = issues that block this one (upstream)
+    // blockerIds = issues this one blocks (downstream)
+    const enrichedBlockers = node.dependentIds
+      .map((id) => {
+        const n = nodeMap.get(id);
+        return n
+          ? { id: n.id, title: n.title, status: n.status }
+          : { id, title: null, status: null };
+      });
+
+    const enrichedDependents = node.blockerIds
+      .map((id) => {
+        const n = nodeMap.get(id);
+        return n
+          ? { id: n.id, title: n.title, status: n.status }
+          : { id, title: null, status: null };
+      });
+
+    // Comments and claims
+    const nodeComments =
+      commentsResult?.commentsByNode.get(issueId) || [];
+    const claims = commentsResult
+      ? getClaimedNodes(commentsResult.allComments)
+      : new Map<string, ClaimInfo>();
+    const claim = claims.get(issueId) || null;
+
+    const warnings: string[] = [];
+    if (!commentsResult) {
+      warnings.push("Failed to fetch comments from indexer");
+    }
+
+    return jsonResponse({
+      issue: {
+        id: node.id,
+        title: node.title,
+        description: node.description || null,
+        status: node.status,
+        priority: node.priority,
+        issue_type: node.issueType,
+        owner: node.owner || null,
+        assignee: node.assignee || null,
+        labels: [] as string[],
+        created_at: node.createdAt,
+        updated_at: node.updatedAt,
+        closed_at: node.closedAt || null,
+        close_reason: node.closeReason || null,
+        prefix: node.prefix,
+        blockers: enrichedBlockers,
+        dependents: enrichedDependents,
+        comments: nodeComments.map(serializeComment),
+        claimed_by: claim
+          ? {
+              handle: claim.handle,
+              did: claim.did,
+              ...(claim.displayName
+                ? { displayName: claim.displayName }
+                : {}),
+              claimed_at: claim.claimedAt,
+            }
+          : null,
+      },
+      _meta: {
+        generated_at: new Date().toISOString(),
+        api_version: "v1" as const,
+        heartbeads_version: heartbeadsVersion,
+        ...(warnings.length ? { warnings } : {}),
+      },
+    });
+  } catch (error: unknown) {
+    const message =
+      error instanceof Error ? error.message : "Unknown error";
+    if (message.includes("No .beads/ directory found")) {
+      return errorResponse(
+        "No .beads directory found",
+        404,
+        "Run bd init in your project first, or set BEADS_DIR."
+      );
+    }
+    console.error("[api/v1/issues] Error:", error);
+    return errorResponse("Internal server error", 500);
+  }
+}