@cliangdev/flux-plugin 0.2.0-dev.2b9c207 → 0.2.0-dev.359209a

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/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,
   };

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;
 

package/src/server/tools/__tests__/crud.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-${Date.now()}`;
+const TEST_DIR = `/tmp/flux-test-${Date.now()}-${Math.random().toString(36).slice(2)}`;
 const FLUX_DIR = join(TEST_DIR, ".flux");
 process.env.FLUX_PROJECT_ROOT = TEST_DIR;
 
@@ -22,6 +22,7 @@ import { updateStatusTool } from "../update-status.js";
 
 describe("CRUD MCP Tools", () => {
   beforeEach(() => {
+    closeDb();
     config.clearCache();
     clearAdapterCache();
     process.env.FLUX_PROJECT_ROOT = TEST_DIR;

package/src/server/tools/__tests__/mcp-interface.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-mcp-${Date.now()}`;
+const TEST_DIR = `/tmp/flux-test-mcp-${Date.now()}-${Math.random().toString(36).slice(2)}`;
 const FLUX_DIR = join(TEST_DIR, ".flux");
 process.env.FLUX_PROJECT_ROOT = TEST_DIR;
 
@@ -19,6 +19,7 @@ import {
 
 describe("MCP Interface", () => {
   beforeEach(() => {
+    closeDb();
     config.clearCache();
     process.env.FLUX_PROJECT_ROOT = TEST_DIR;
 

package/src/server/tools/__tests__/query.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-query-${Date.now()}`;
+const TEST_DIR = `/tmp/flux-test-query-${Date.now()}-${Math.random().toString(36).slice(2)}`;
 const FLUX_DIR = join(TEST_DIR, ".flux");
 process.env.FLUX_PROJECT_ROOT = TEST_DIR;
 
@@ -22,6 +22,7 @@ import { queryEntitiesTool } from "../query-entities.js";
 
 describe("Query MCP Tools", () => {
   beforeEach(() => {
+    closeDb();
     config.clearCache();
     clearAdapterCache();
     process.env.FLUX_PROJECT_ROOT = TEST_DIR;
@@ -341,9 +342,10 @@ describe("Query MCP Tools", () => {
 });
 
 describe("init_project", () => {
-  const INIT_TEST_DIR = `/tmp/flux-init-test-${Date.now()}`;
+  const INIT_TEST_DIR = `/tmp/flux-init-test-${Date.now()}-${Math.random().toString(36).slice(2)}`;
 
   beforeEach(() => {
+    closeDb();
     config.clearCache();
     clearAdapterCache();
     process.env.FLUX_PROJECT_ROOT = INIT_TEST_DIR;

package/src/server/tools/__tests__/z-configure-linear.test.ts

@@ -2,7 +2,7 @@ import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
 import { existsSync, mkdirSync, readFileSync, rmSync } from "node:fs";
 import { join } from "node:path";
 
-const TEST_DIR = `/tmp/flux-test-${Date.now()}`;
+const TEST_DIR = `/tmp/flux-test-${Date.now()}-${Math.random().toString(36).slice(2)}`;
 const FLUX_DIR = join(TEST_DIR, ".flux");
 process.env.FLUX_PROJECT_ROOT = TEST_DIR;
 

package/src/server/tools/__tests__/z-get-linear-url.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-${Date.now()}`;
+const TEST_DIR = `/tmp/flux-test-${Date.now()}-${Math.random().toString(36).slice(2)}`;
 const FLUX_DIR = join(TEST_DIR, ".flux");
 process.env.FLUX_PROJECT_ROOT = TEST_DIR;
 

package/src/status-line/__tests__/status-line.test.ts

@@ -31,7 +31,7 @@ function setupTestProject(testDir: string, projectName = "test-project") {
 }
 
 describe("status-line script", () => {
-  const TEST_DIR = `/tmp/flux-status-line-test-${Date.now()}`;
+  const TEST_DIR = `/tmp/flux-status-line-test-${Date.now()}-${Math.random().toString(36).slice(2)}`;
 
   beforeEach(() => {
     if (existsSync(TEST_DIR)) {