@cliangdev/flux-plugin 0.2.0-dev.dc5e2c4 → 0.2.0-dev.f718bcf

package/src/dashboard/server.ts

@@ -0,0 +1,296 @@
+/**
+ * Flux Dashboard Server
+ *
+ * HTTP + WebSocket server for the Flux Dashboard.
+ * Serves static files and API endpoints for viewing PRD/Epic/Task data.
+ */
+
+import { getAdapter } from "../server/adapters/index.js";
+import type { Epic, Prd, Task } from "../server/adapters/types.js";
+import { initDb } from "../server/db/index.js";
+import { openBrowser } from "./browser.js";
+import { startWatchers, stopWatchers } from "./watchers.js";
+
+const DEFAULT_PORT = 3333;
+const MAX_PORT_ATTEMPTS = 10;
+
+interface DashboardServer {
+  server: ReturnType<typeof Bun.serve>;
+  port: number;
+  stop: () => void;
+}
+
+function getPort(): number {
+  const envPort = process.env.FLUX_DASHBOARD_PORT;
+  if (envPort) {
+    const parsed = Number.parseInt(envPort, 10);
+    if (!Number.isNaN(parsed) && parsed > 0 && parsed < 65536) {
+      return parsed;
+    }
+  }
+  return DEFAULT_PORT;
+}
+
+async function findAvailablePort(startPort: number): Promise<number> {
+  for (let port = startPort; port < startPort + MAX_PORT_ATTEMPTS; port++) {
+    try {
+      const testServer = Bun.serve({
+        port,
+        fetch: () => new Response("test"),
+      });
+      testServer.stop();
+      return port;
+    } catch {}
+  }
+  throw new Error(
+    `No available port found between ${startPort} and ${startPort + MAX_PORT_ATTEMPTS - 1}`,
+  );
+}
+
+function getContentType(path: string): string {
+  if (path.endsWith(".html")) return "text/html";
+  if (path.endsWith(".css")) return "text/css";
+  if (path.endsWith(".js")) return "application/javascript";
+  if (path.endsWith(".json")) return "application/json";
+  if (path.endsWith(".svg")) return "image/svg+xml";
+  return "application/octet-stream";
+}
+
+export async function startDashboard(): Promise<DashboardServer> {
+  const preferredPort = getPort();
+  const port = await findAvailablePort(preferredPort);
+
+  const publicDir = new URL("./public/", import.meta.url).pathname;
+
+  const server = Bun.serve({
+    port,
+
+    async fetch(req, server) {
+      const url = new URL(req.url);
+      const path = url.pathname;
+
+      // WebSocket upgrade
+      if (path === "/ws") {
+        const upgraded = server.upgrade(req);
+        return upgraded
+          ? undefined
+          : new Response("WebSocket upgrade failed", { status: 400 });
+      }
+
+      // API endpoints
+      if (path.startsWith("/api/")) {
+        return handleApiRequest(path, url);
+      }
+
+      // Static files
+      const filePath = path === "/" ? "/index.html" : path;
+      const fullPath = `${publicDir}${filePath}`;
+
+      try {
+        const file = Bun.file(fullPath);
+        if (await file.exists()) {
+          return new Response(file, {
+            headers: { "Content-Type": getContentType(fullPath) },
+          });
+        }
+      } catch {}
+
+      return new Response("Not found", { status: 404 });
+    },
+
+    websocket: {
+      open(ws) {
+        ws.subscribe("updates");
+      },
+      message(_ws, _message) {
+        // Client messages not needed for read-only dashboard
+      },
+      close(ws) {
+        ws.unsubscribe("updates");
+      },
+    },
+  });
+
+  // Start file watchers
+  startWatchers(server);
+
+  // Graceful shutdown
+  const cleanup = () => {
+    console.log("\nShutting down dashboard...");
+    stopWatchers();
+    server.stop();
+    process.exit(0);
+  };
+
+  process.on("SIGINT", cleanup);
+  process.on("SIGTERM", cleanup);
+
+  return {
+    server,
+    port,
+    stop: () => {
+      stopWatchers();
+      server.stop();
+    },
+  };
+}
+
+interface TreePrd extends Prd {
+  epics: TreeEpic[];
+}
+
+interface TreeEpic extends Epic {
+  tasks: Task[];
+}
+
+async function handleApiRequest(path: string, _url: URL): Promise<Response> {
+  try {
+    const adapter = getAdapter();
+
+    // GET /api/tree
+    if (path === "/api/tree") {
+      const prds = await adapter.listPrds({}, { limit: 100, offset: 0 });
+      const tree: TreePrd[] = await Promise.all(
+        prds.items.map(async (prd) => {
+          const epics = await adapter.listEpics(
+            { prdRef: prd.ref },
+            { limit: 100, offset: 0 },
+          );
+          const epicsWithTasks: TreeEpic[] = await Promise.all(
+            epics.items.map(async (epic) => {
+              const tasks = await adapter.listTasks(
+                { epicRef: epic.ref },
+                { limit: 100, offset: 0 },
+              );
+              return { ...epic, tasks: tasks.items };
+            }),
+          );
+          return { ...prd, epics: epicsWithTasks };
+        }),
+      );
+      return Response.json(tree);
+    }
+
+    // GET /api/prd/:ref
+    if (path.startsWith("/api/prd/")) {
+      const ref = path.slice("/api/prd/".length);
+      const prd = await adapter.getPrd(ref);
+      if (!prd) {
+        return Response.json({ error: "PRD not found" }, { status: 404 });
+      }
+
+      let markdown = prd.description || "";
+      if (prd.folderPath) {
+        try {
+          const prdPath = `${prd.folderPath}/prd.md`;
+          const file = Bun.file(prdPath);
+          if (await file.exists()) {
+            markdown = await file.text();
+          }
+        } catch {}
+      }
+
+      return Response.json({ ...prd, markdown });
+    }
+
+    // GET /api/epic/:ref
+    if (path.startsWith("/api/epic/")) {
+      const ref = path.slice("/api/epic/".length);
+      const epic = await adapter.getEpic(ref);
+      if (!epic) {
+        return Response.json({ error: "Epic not found" }, { status: 404 });
+      }
+      const criteria = await adapter.getCriteria(ref);
+      return Response.json({ ...epic, criteria });
+    }
+
+    // GET /api/task/:ref
+    if (path.startsWith("/api/task/")) {
+      const ref = path.slice("/api/task/".length);
+      const task = await adapter.getTask(ref);
+      if (!task) {
+        return Response.json({ error: "Task not found" }, { status: 404 });
+      }
+      const criteria = await adapter.getCriteria(ref);
+      const deps = await adapter.getDependencies(ref);
+      return Response.json({ ...task, criteria, dependencies: deps });
+    }
+
+    // GET /api/tags
+    if (path === "/api/tags") {
+      const prds = await adapter.listPrds({}, { limit: 1000, offset: 0 });
+      const tagCounts = new Map<string, number>();
+      let total = 0;
+
+      for (const prd of prds.items) {
+        total++;
+        if (prd.tag) {
+          tagCounts.set(prd.tag, (tagCounts.get(prd.tag) || 0) + 1);
+        }
+      }
+
+      const tags = [
+        { tag: "All", count: total },
+        ...Array.from(tagCounts.entries())
+          .map(([tag, count]) => ({ tag, count }))
+          .sort((a, b) => a.tag.localeCompare(b.tag)),
+      ];
+
+      return Response.json(tags);
+    }
+
+    // GET /api/dependencies
+    if (path === "/api/dependencies") {
+      const edges: Array<{ from: string; to: string; type: string }> = [];
+
+      const prds = await adapter.listPrds({}, { limit: 1000, offset: 0 });
+      for (const prd of prds.items) {
+        const deps = await adapter.getDependencies(prd.ref);
+        for (const depRef of deps) {
+          edges.push({ from: prd.ref, to: depRef, type: "prd" });
+        }
+      }
+
+      const epics = await adapter.listEpics({}, { limit: 1000, offset: 0 });
+      for (const epic of epics.items) {
+        const deps = await adapter.getDependencies(epic.ref);
+        for (const depRef of deps) {
+          edges.push({ from: epic.ref, to: depRef, type: "epic" });
+        }
+      }
+
+      const tasks = await adapter.listTasks({}, { limit: 1000, offset: 0 });
+      for (const task of tasks.items) {
+        const deps = await adapter.getDependencies(task.ref);
+        for (const depRef of deps) {
+          edges.push({ from: task.ref, to: depRef, type: "task" });
+        }
+      }
+
+      return Response.json({ edges });
+    }
+
+    return Response.json({ error: "Unknown endpoint" }, { status: 404 });
+  } catch (error) {
+    console.error("API error:", error);
+    return Response.json(
+      { error: error instanceof Error ? error.message : "Internal error" },
+      { status: 500 },
+    );
+  }
+}
+
+// Main entry point
+if (import.meta.main) {
+  try {
+    // Initialize local database (no-op if using external adapter like Linear)
+    initDb();
+    const { port } = await startDashboard();
+    const url = `http://localhost:${port}`;
+    console.log(`\n  Flux Dashboard running at ${url}\n`);
+    await openBrowser(url);
+  } catch (error) {
+    console.error("Failed to start dashboard:", error);
+    process.exit(1);
+  }
+}

package/src/dashboard/watchers.ts

@@ -0,0 +1,83 @@
+/**
+ * File Watchers for Real-time Updates
+ *
+ * Watches .flux/flux.db and .flux/prds/ for changes and broadcasts
+ * updates to connected WebSocket clients.
+ */
+
+import { type FSWatcher, watch } from "node:fs";
+import { resolve } from "node:path";
+
+let dbWatcher: FSWatcher | null = null;
+let prdsWatcher: FSWatcher | null = null;
+let debounceTimer: Timer | null = null;
+
+const DEBOUNCE_MS = 500;
+
+export function startWatchers(server: ReturnType<typeof Bun.serve>): void {
+  const projectRoot = process.env.FLUX_PROJECT_ROOT || process.cwd();
+  const fluxDir = resolve(projectRoot, ".flux");
+  const dbPath = resolve(fluxDir, "flux.db");
+  const prdsDir = resolve(fluxDir, "prds");
+
+  const broadcast = (type: "db" | "file", path?: string) => {
+    if (debounceTimer) {
+      clearTimeout(debounceTimer);
+    }
+
+    debounceTimer = setTimeout(() => {
+      server.publish(
+        "updates",
+        JSON.stringify({
+          type: "update",
+          source: type,
+          path,
+          timestamp: Date.now(),
+        }),
+      );
+    }, DEBOUNCE_MS);
+  };
+
+  // Watch database file
+  try {
+    dbWatcher = watch(dbPath, (eventType) => {
+      if (eventType === "change") {
+        broadcast("db");
+      }
+    });
+  } catch (error) {
+    console.warn("Could not watch database file:", error);
+  }
+
+  // Watch PRDs directory recursively
+  try {
+    prdsWatcher = watch(
+      prdsDir,
+      { recursive: true },
+      (_eventType, filename) => {
+        if (filename?.endsWith(".md")) {
+          broadcast("file", filename);
+        }
+      },
+    );
+  } catch (error) {
+    console.warn("Could not watch PRDs directory:", error);
+  }
+}
+
+export function stopWatchers(): void {
+  if (debounceTimer) {
+    clearTimeout(debounceTimer);
+    debounceTimer = null;
+  }
+
+  if (dbWatcher) {
+    dbWatcher.close();
+    dbWatcher = null;
+  }
+
+  if (prdsWatcher) {
+    prdsWatcher.close();
+    prdsWatcher = null;
+  }
+}

package/src/server/adapters/__tests__/dependency-ops.test.ts

@@ -194,8 +194,12 @@ describe("LinearAdapter - Dependency Operations", () => {
       const mockRelation = {
         id: "relation_1",
         type: "blocks",
-        issue: { id: "issue_epic_1", identifier: "ENG-42" },
-        relatedIssue: { id: "issue_epic_2", identifier: "ENG-43" },
+        // Linear SDK returns promises for lazy-loaded related objects
+        issue: Promise.resolve({ id: "issue_epic_1", identifier: "ENG-42" }),
+        relatedIssue: Promise.resolve({
+          id: "issue_epic_2",
+          identifier: "ENG-43",
+        }),
         delete: mockDelete,
       };
 
@@ -208,7 +212,7 @@ describe("LinearAdapter - Dependency Operations", () => {
         id: "issue_epic_2",
         identifier: "ENG-43",
         _raw: {
-          relations: mock(async () => ({
+          inverseRelations: mock(async () => ({
             nodes: [mockRelation],
           })),
         },
@@ -235,7 +239,7 @@ describe("LinearAdapter - Dependency Operations", () => {
         id: "issue_epic_1",
         identifier: "ENG-42",
         _raw: {
-          relations: mock(async () => ({ nodes: [] })),
+          inverseRelations: mock(async () => ({ nodes: [] })),
         },
       });
 
@@ -265,7 +269,7 @@ describe("LinearAdapter - Dependency Operations", () => {
         id: "issue_epic_2",
         identifier: "ENG-43",
         _raw: {
-          relations: mock(async () => ({
+          inverseRelations: mock(async () => ({
             nodes: [], // No relations
           })),
         },
@@ -294,19 +298,31 @@ describe("LinearAdapter - Dependency Operations", () => {
         id: "issue_epic_1",
         identifier: "ENG-43",
         _raw: {
-          relations: mock(async () => ({
+          inverseRelations: mock(async () => ({
             nodes: [
               {
                 id: "relation_1",
                 type: "blocks",
-                issue: { id: "issue_epic_2", identifier: "ENG-42" },
-                relatedIssue: { id: "issue_epic_1", identifier: "ENG-43" },
+                issue: Promise.resolve({
+                  id: "issue_epic_2",
+                  identifier: "ENG-42",
+                }),
+                relatedIssue: Promise.resolve({
+                  id: "issue_epic_1",
+                  identifier: "ENG-43",
+                }),
               },
               {
                 id: "relation_2",
                 type: "blocks",
-                issue: { id: "issue_epic_3", identifier: "ENG-44" },
-                relatedIssue: { id: "issue_epic_1", identifier: "ENG-43" },
+                issue: Promise.resolve({
+                  id: "issue_epic_3",
+                  identifier: "ENG-44",
+                }),
+                relatedIssue: Promise.resolve({
+                  id: "issue_epic_1",
+                  identifier: "ENG-43",
+                }),
               },
             ],
           })),
@@ -328,7 +344,7 @@ describe("LinearAdapter - Dependency Operations", () => {
         id: "issue_epic_1",
         identifier: "ENG-42",
         _raw: {
-          relations: mock(async () => ({
+          inverseRelations: mock(async () => ({
             nodes: [],
           })),
         },
@@ -349,25 +365,43 @@ describe("LinearAdapter - Dependency Operations", () => {
         id: "issue_epic_1",
         identifier: "ENG-43",
         _raw: {
-          relations: mock(async () => ({
+          inverseRelations: mock(async () => ({
             nodes: [
               {
                 id: "relation_1",
                 type: "blocks",
-                issue: { id: "issue_epic_2", identifier: "ENG-42" },
-                relatedIssue: { id: "issue_epic_1", identifier: "ENG-43" },
+                issue: Promise.resolve({
+                  id: "issue_epic_2",
+                  identifier: "ENG-42",
+                }),
+                relatedIssue: Promise.resolve({
+                  id: "issue_epic_1",
+                  identifier: "ENG-43",
+                }),
               },
               {
                 id: "relation_2",
                 type: "duplicate",
-                issue: { id: "issue_epic_3", identifier: "ENG-44" },
-                relatedIssue: { id: "issue_epic_1", identifier: "ENG-43" },
+                issue: Promise.resolve({
+                  id: "issue_epic_3",
+                  identifier: "ENG-44",
+                }),
+                relatedIssue: Promise.resolve({
+                  id: "issue_epic_1",
+                  identifier: "ENG-43",
+                }),
               },
               {
                 id: "relation_3",
                 type: "related",
-                issue: { id: "issue_epic_4", identifier: "ENG-45" },
-                relatedIssue: { id: "issue_epic_1", identifier: "ENG-43" },
+                issue: Promise.resolve({
+                  id: "issue_epic_4",
+                  identifier: "ENG-45",
+                }),
+                relatedIssue: Promise.resolve({
+                  id: "issue_epic_1",
+                  identifier: "ENG-43",
+                }),
               },
             ],
           })),

package/src/server/adapters/linear/adapter.ts

@@ -887,16 +887,22 @@ export class LinearAdapter implements BackendAdapter {
     if (!blockedIssue) throw new Error(`Issue not found: ${ref}`);
     if (!blockerIssue) throw new Error(`Issue not found: ${dependsOnRef}`);
 
+    // Use inverseRelations to find relations where blockedIssue is the target
     const relations = await this.client.execute<any>(() =>
-      blockedIssue._raw.relations(),
+      blockedIssue._raw.inverseRelations(),
     );
 
-    const relationToDelete = relations.nodes.find(
-      (rel: any) =>
-        rel.type === "blocks" &&
-        rel.issue.id === blockerIssue.id &&
-        rel.relatedIssue.id === blockedIssue.id,
-    );
+    // Find the relation to delete - need to await rel.issue since it's lazy-loaded
+    let relationToDelete: any = null;
+    for (const rel of relations.nodes) {
+      if (rel.type === "blocks") {
+        const relIssue = await rel.issue;
+        if (relIssue?.id === blockerIssue.id) {
+          relationToDelete = rel;
+          break;
+        }
+      }
+    }
 
     if (!relationToDelete) {
       throw new Error(
@@ -911,18 +917,17 @@ export class LinearAdapter implements BackendAdapter {
     const issue = await this.fetchIssue(ref);
     if (!issue) throw new Error(`Issue not found: ${ref}`);
 
+    // Use inverseRelations to get relations where this issue is the target (relatedIssueId)
+    // This finds issues that block this one
     const relations = await this.client.execute<any>(() =>
-      issue._raw.relations(),
+      issue._raw.inverseRelations(),
     );
 
     const blockingRefs: string[] = [];
     for (const rel of relations.nodes) {
-      if (
-        rel.type === "blocks" &&
-        rel.relatedIssue &&
-        (rel.relatedIssue as any).id === issue.id
-      ) {
-        const blockerIssue = rel.issue as any;
+      if (rel.type === "blocks") {
+        // Linear SDK returns lazy-loaded promises for related objects
+        const blockerIssue = await rel.issue;
         if (blockerIssue?.identifier) {
           blockingRefs.push(blockerIssue.identifier);
         }

package/src/server/adapters/local-adapter.ts

@@ -12,7 +12,7 @@ import {
   rmSync,
   writeFileSync,
 } from "node:fs";
-import { join } from "node:path";
+import { isAbsolute, join } from "node:path";
 import { config } from "../config.js";
 import {
   count,
@@ -108,6 +108,12 @@ interface ProjectRow {
 // =============================================================================
 
 function toPrd(row: PrdRow): Prd {
+  // Normalize folderPath to absolute path for consistency
+  let folderPath = row.folder_path ?? undefined;
+  if (folderPath && !isAbsolute(folderPath)) {
+    folderPath = join(config.projectRoot, folderPath);
+  }
+
   return {
     id: row.id,
     projectId: row.project_id,
@@ -116,7 +122,7 @@ function toPrd(row: PrdRow): Prd {
     description: row.description ?? undefined,
     status: row.status as Prd["status"],
     tag: row.tag ?? undefined,
-    folderPath: row.folder_path ?? undefined,
+    folderPath,
     createdAt: row.created_at,
     updatedAt: row.updated_at,
   };
@@ -312,6 +318,14 @@ export class LocalAdapter implements BackendAdapter {
       cascade.epics++;
     }
 
+    // Delete PRD dependencies
+    const deletedDeps = db
+      .query(
+        "DELETE FROM prd_dependencies WHERE prd_id = ? OR depends_on_prd_id = ?",
+      )
+      .run(prd.id, prd.id);
+    cascade.dependencies += deletedDeps.changes;
+
     remove(db, "prds", prd.id);
 
     return { deleted: ref, cascade };
@@ -710,7 +724,15 @@ export class LocalAdapter implements BackendAdapter {
       throw new Error("Dependencies must be between entities of the same type");
     }
 
-    if (entityType === "E") {
+    if (entityType === "P") {
+      const prd = findByRef<PrdRow>(db, "prds", ref);
+      const dependsOnPrd = findByRef<PrdRow>(db, "prds", dependsOnRef);
+      if (!prd || !dependsOnPrd) throw new Error("PRD not found");
+
+      db.query(
+        "INSERT OR IGNORE INTO prd_dependencies (prd_id, depends_on_prd_id) VALUES (?, ?)",
+      ).run(prd.id, dependsOnPrd.id);
+    } else if (entityType === "E") {
       const epic = findByRef<EpicRow>(db, "epics", ref);
       const dependsOnEpic = findByRef<EpicRow>(db, "epics", dependsOnRef);
       if (!epic || !dependsOnEpic) throw new Error("Epic not found");
@@ -726,8 +748,6 @@ export class LocalAdapter implements BackendAdapter {
       db.query(
         "INSERT OR IGNORE INTO task_dependencies (task_id, depends_on_task_id) VALUES (?, ?)",
       ).run(task.id, dependsOnTask.id);
-    } else {
-      throw new Error("Dependencies can only be added to Epics or Tasks");
     }
   }
 
@@ -735,7 +755,15 @@ export class LocalAdapter implements BackendAdapter {
     const db = getDb();
     const entityType = getEntityType(ref);
 
-    if (entityType === "E") {
+    if (entityType === "P") {
+      const prd = findByRef<PrdRow>(db, "prds", ref);
+      const dependsOnPrd = findByRef<PrdRow>(db, "prds", dependsOnRef);
+      if (!prd || !dependsOnPrd) throw new Error("PRD not found");
+
+      db.query(
+        "DELETE FROM prd_dependencies WHERE prd_id = ? AND depends_on_prd_id = ?",
+      ).run(prd.id, dependsOnPrd.id);
+    } else if (entityType === "E") {
       const epic = findByRef<EpicRow>(db, "epics", ref);
       const dependsOnEpic = findByRef<EpicRow>(db, "epics", dependsOnRef);
       if (!epic || !dependsOnEpic) throw new Error("Epic not found");
@@ -758,7 +786,20 @@ export class LocalAdapter implements BackendAdapter {
     const db = getDb();
     const entityType = getEntityType(ref);
 
-    if (entityType === "E") {
+    if (entityType === "P") {
+      const prd = findByRef<PrdRow>(db, "prds", ref);
+      if (!prd) return [];
+
+      const deps = db
+        .query(
+          `SELECT p.ref FROM prd_dependencies pd
+           JOIN prds p ON pd.depends_on_prd_id = p.id
+           WHERE pd.prd_id = ?`,
+        )
+        .all(prd.id) as { ref: string }[];
+
+      return deps.map((d) => d.ref);
+    } else if (entityType === "E") {
       const epic = findByRef<EpicRow>(db, "epics", ref);
       if (!epic) return [];
 

package/src/server/db/__tests__/queries.test.ts

@@ -3,7 +3,7 @@ import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 
 // Set up test environment BEFORE any imports
-const TEST_DIR = `/tmp/flux-test-db-${Date.now()}`;
+const TEST_DIR = `/tmp/flux-test-db-${Date.now()}-${Math.random().toString(36).slice(2)}`;
 const FLUX_DIR = join(TEST_DIR, ".flux");
 process.env.FLUX_PROJECT_ROOT = TEST_DIR;
 
@@ -28,6 +28,7 @@ describe("Database Queries", () => {
   let projectId: string;
 
   beforeEach(() => {
+    closeDb();
     config.clearCache();
     process.env.FLUX_PROJECT_ROOT = TEST_DIR;