@cliangdev/flux-plugin 0.2.0 → 0.3.0

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/__tests__/config.test.ts

@@ -0,0 +1,163 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import {
+  existsSync,
+  mkdirSync,
+  realpathSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+
+describe("config", () => {
+  const originalEnv = process.env.FLUX_PROJECT_ROOT;
+  const originalCwd = process.cwd();
+  // Use os.tmpdir() to get the real temp path (handles /tmp -> /private/tmp on macOS)
+  const TEST_DIR = `${realpathSync(tmpdir())}/flux-config-test-${Date.now()}`;
+  const NESTED_DIR = `${TEST_DIR}/subdir/nested`;
+
+  beforeEach(async () => {
+    // Clean up any previous test directory
+    if (existsSync(TEST_DIR)) {
+      rmSync(TEST_DIR, { recursive: true });
+    }
+
+    // Create test directory structure
+    mkdirSync(NESTED_DIR, { recursive: true });
+
+    // Clear the config cache before each test
+    const { config } = await import("../config.js");
+    config.clearCache();
+  });
+
+  afterEach(async () => {
+    // Restore original env
+    if (originalEnv !== undefined) {
+      process.env.FLUX_PROJECT_ROOT = originalEnv;
+    } else {
+      delete process.env.FLUX_PROJECT_ROOT;
+    }
+
+    // Restore original cwd
+    process.chdir(originalCwd);
+
+    // Clear the config cache
+    const { config } = await import("../config.js");
+    config.clearCache();
+
+    // Clean up test directory
+    if (existsSync(TEST_DIR)) {
+      rmSync(TEST_DIR, { recursive: true });
+    }
+  });
+
+  test("uses env var when properly set", async () => {
+    process.env.FLUX_PROJECT_ROOT = "/some/valid/path";
+
+    const { config } = await import("../config.js");
+    config.clearCache();
+
+    expect(config.projectRoot).toBe("/some/valid/path");
+  });
+
+  test("ignores unresolved template variable and walks up directories", async () => {
+    // Create a .flux folder at TEST_DIR
+    mkdirSync(`${TEST_DIR}/.flux`, { recursive: true });
+    writeFileSync(
+      `${TEST_DIR}/.flux/project.json`,
+      JSON.stringify({ name: "test" }),
+    );
+
+    // Simulate Claude Code passing unresolved template variable
+    // biome-ignore lint/suspicious/noTemplateCurlyInString: intentionally testing literal template string
+    process.env.FLUX_PROJECT_ROOT = "${CLAUDE_PROJECT_DIR}";
+
+    // Change to nested directory
+    process.chdir(NESTED_DIR);
+
+    const { config } = await import("../config.js");
+    config.clearCache();
+
+    // Should walk up and find TEST_DIR, not use the literal "${CLAUDE_PROJECT_DIR}"
+    expect(config.projectRoot).not.toContain("${");
+    expect(config.projectRoot).toBe(TEST_DIR);
+  });
+
+  test("walks up directories to find .flux folder", async () => {
+    // Create a .flux folder at TEST_DIR (parent of NESTED_DIR)
+    mkdirSync(`${TEST_DIR}/.flux`, { recursive: true });
+    writeFileSync(
+      `${TEST_DIR}/.flux/project.json`,
+      JSON.stringify({ name: "test" }),
+    );
+
+    // No env var set
+    delete process.env.FLUX_PROJECT_ROOT;
+
+    // Change to nested directory
+    process.chdir(NESTED_DIR);
+
+    const { config } = await import("../config.js");
+    config.clearCache();
+
+    // Should walk up and find TEST_DIR
+    expect(config.projectRoot).toBe(TEST_DIR);
+  });
+
+  test("falls back to cwd when no .flux folder found", async () => {
+    // No .flux folder anywhere in TEST_DIR hierarchy
+    // No env var set
+    delete process.env.FLUX_PROJECT_ROOT;
+
+    // Change to test directory (which has no .flux)
+    process.chdir(TEST_DIR);
+
+    const { config } = await import("../config.js");
+    config.clearCache();
+
+    // Should fall back to cwd
+    expect(config.projectRoot).toBe(TEST_DIR);
+  });
+
+  test("projectExists returns true when project.json exists", async () => {
+    mkdirSync(`${TEST_DIR}/.flux`, { recursive: true });
+    writeFileSync(
+      `${TEST_DIR}/.flux/project.json`,
+      JSON.stringify({ name: "test" }),
+    );
+
+    process.env.FLUX_PROJECT_ROOT = TEST_DIR;
+
+    const { config } = await import("../config.js");
+    config.clearCache();
+
+    expect(config.projectExists).toBe(true);
+  });
+
+  test("projectExists returns false when project.json does not exist", async () => {
+    // No .flux folder
+    process.env.FLUX_PROJECT_ROOT = TEST_DIR;
+
+    const { config } = await import("../config.js");
+    config.clearCache();
+
+    expect(config.projectExists).toBe(false);
+  });
+
+  test("caches project root for performance", async () => {
+    process.env.FLUX_PROJECT_ROOT = "/first/path";
+
+    const { config } = await import("../config.js");
+    config.clearCache();
+
+    // First call caches the value
+    expect(config.projectRoot).toBe("/first/path");
+
+    // Changing env var should not affect cached value
+    process.env.FLUX_PROJECT_ROOT = "/second/path";
+    expect(config.projectRoot).toBe("/first/path");
+
+    // After clearing cache, should use new env var
+    config.clearCache();
+    expect(config.projectRoot).toBe("/second/path");
+  });
+});