@cliangdev/flux-plugin 0.2.0 → 0.3.0

package/src/server/utils/__tests__/mcp-response.test.ts

@@ -0,0 +1,331 @@
+import { describe, expect, test } from "bun:test";
+import type {
+  AcceptanceCriterion,
+  CascadeResult,
+  Epic,
+  PaginatedResult,
+  Prd,
+  Stats,
+  Task,
+} from "../../adapters/types.js";
+import {
+  toMcpCascadeResult,
+  toMcpCriterion,
+  toMcpEpic,
+  toMcpPaginatedEpics,
+  toMcpPaginatedPrds,
+  toMcpPaginatedTasks,
+  toMcpPrd,
+  toMcpStats,
+  toMcpTask,
+} from "../mcp-response.js";
+
+describe("MCP Response Transformations", () => {
+  describe("toMcpPrd", () => {
+    test("transforms PRD with all fields", () => {
+      const prd: Prd = {
+        id: "prd_123",
+        projectId: "proj_456",
+        ref: "TEST-P1",
+        title: "Test PRD",
+        description: "A description",
+        status: "DRAFT",
+        tag: "mvp",
+        folderPath: ".flux/prds/test",
+        createdAt: "2024-01-01T00:00:00Z",
+        updatedAt: "2024-01-02T00:00:00Z",
+      };
+
+      const result = toMcpPrd(prd);
+
+      expect(result.id).toBe("prd_123");
+      expect(result.project_id).toBe("proj_456");
+      expect(result.ref).toBe("TEST-P1");
+      expect(result.title).toBe("Test PRD");
+      expect(result.description).toBe("A description");
+      expect(result.status).toBe("DRAFT");
+      expect(result.tag).toBe("mvp");
+      expect(result.folder_path).toBe(".flux/prds/test");
+      expect(result.created_at).toBe("2024-01-01T00:00:00Z");
+      expect(result.updated_at).toBe("2024-01-02T00:00:00Z");
+    });
+
+    test("transforms PRD with optional fields undefined", () => {
+      const prd: Prd = {
+        id: "prd_123",
+        projectId: "proj_456",
+        ref: "TEST-P1",
+        title: "Test PRD",
+        status: "DRAFT",
+        createdAt: "2024-01-01T00:00:00Z",
+        updatedAt: "2024-01-02T00:00:00Z",
+      };
+
+      const result = toMcpPrd(prd);
+
+      expect(result.description).toBeUndefined();
+      expect(result.tag).toBeUndefined();
+      expect(result.folder_path).toBeUndefined();
+    });
+  });
+
+  describe("toMcpEpic", () => {
+    test("transforms Epic with all fields", () => {
+      const epic: Epic = {
+        id: "epic_123",
+        prdId: "prd_456",
+        ref: "TEST-E1",
+        title: "Test Epic",
+        description: "Epic description",
+        status: "IN_PROGRESS",
+        createdAt: "2024-01-01T00:00:00Z",
+        updatedAt: "2024-01-02T00:00:00Z",
+      };
+
+      const result = toMcpEpic(epic);
+
+      expect(result.id).toBe("epic_123");
+      expect(result.prd_id).toBe("prd_456");
+      expect(result.ref).toBe("TEST-E1");
+      expect(result.title).toBe("Test Epic");
+      expect(result.description).toBe("Epic description");
+      expect(result.status).toBe("IN_PROGRESS");
+      expect(result.created_at).toBe("2024-01-01T00:00:00Z");
+      expect(result.updated_at).toBe("2024-01-02T00:00:00Z");
+    });
+  });
+
+  describe("toMcpTask", () => {
+    test("transforms Task with all fields", () => {
+      const task: Task = {
+        id: "task_123",
+        epicId: "epic_456",
+        ref: "TEST-T1",
+        title: "Test Task",
+        description: "Task description",
+        status: "PENDING",
+        priority: "HIGH",
+        createdAt: "2024-01-01T00:00:00Z",
+        updatedAt: "2024-01-02T00:00:00Z",
+      };
+
+      const result = toMcpTask(task);
+
+      expect(result.id).toBe("task_123");
+      expect(result.epic_id).toBe("epic_456");
+      expect(result.ref).toBe("TEST-T1");
+      expect(result.title).toBe("Test Task");
+      expect(result.description).toBe("Task description");
+      expect(result.status).toBe("PENDING");
+      expect(result.priority).toBe("HIGH");
+      expect(result.created_at).toBe("2024-01-01T00:00:00Z");
+      expect(result.updated_at).toBe("2024-01-02T00:00:00Z");
+    });
+  });
+
+  describe("toMcpCriterion", () => {
+    test("transforms AcceptanceCriterion", () => {
+      const criterion: AcceptanceCriterion = {
+        id: "ac_123",
+        parentType: "epic",
+        parentId: "epic_456",
+        criteria: "Should work correctly",
+        isMet: true,
+        createdAt: "2024-01-01T00:00:00Z",
+      };
+
+      const result = toMcpCriterion(criterion);
+
+      expect(result.id).toBe("ac_123");
+      expect(result.parent_type).toBe("epic");
+      expect(result.parent_id).toBe("epic_456");
+      expect(result.criteria).toBe("Should work correctly");
+      expect(result.is_met).toBe(true);
+      expect(result.created_at).toBe("2024-01-01T00:00:00Z");
+    });
+
+    test("transforms criterion with is_met false", () => {
+      const criterion: AcceptanceCriterion = {
+        id: "ac_123",
+        parentType: "task",
+        parentId: "task_456",
+        criteria: "Not done yet",
+        isMet: false,
+        createdAt: "2024-01-01T00:00:00Z",
+      };
+
+      const result = toMcpCriterion(criterion);
+
+      expect(result.is_met).toBe(false);
+      expect(result.parent_type).toBe("task");
+    });
+  });
+
+  describe("toMcpStats", () => {
+    test("transforms Stats with all status counts", () => {
+      const stats: Stats = {
+        prds: {
+          total: 10,
+          draft: 3,
+          pendingReview: 2,
+          reviewed: 1,
+          approved: 2,
+          breakdownReady: 1,
+          completed: 1,
+          archived: 2,
+        },
+        epics: {
+          total: 20,
+          pending: 10,
+          inProgress: 5,
+          completed: 5,
+        },
+        tasks: {
+          total: 50,
+          pending: 25,
+          inProgress: 15,
+          completed: 10,
+        },
+      };
+
+      const result = toMcpStats(stats);
+
+      // PRD stats
+      expect(result.prds.total).toBe(10);
+      expect(result.prds.draft).toBe(3);
+      expect(result.prds.pending_review).toBe(2);
+      expect(result.prds.reviewed).toBe(1);
+      expect(result.prds.approved).toBe(2);
+      expect(result.prds.breakdown_ready).toBe(1);
+      expect(result.prds.completed).toBe(1);
+      expect(result.prds.archived).toBe(2);
+
+      // Epic stats
+      expect(result.epics.total).toBe(20);
+      expect(result.epics.pending).toBe(10);
+      expect(result.epics.in_progress).toBe(5);
+      expect(result.epics.completed).toBe(5);
+
+      // Task stats
+      expect(result.tasks.total).toBe(50);
+      expect(result.tasks.pending).toBe(25);
+      expect(result.tasks.in_progress).toBe(15);
+      expect(result.tasks.completed).toBe(10);
+    });
+  });
+
+  describe("toMcpPaginatedPrds", () => {
+    test("transforms paginated PRD result", () => {
+      const paginatedResult: PaginatedResult<Prd> = {
+        items: [
+          {
+            id: "prd_1",
+            projectId: "proj_1",
+            ref: "TEST-P1",
+            title: "PRD 1",
+            status: "DRAFT",
+            createdAt: "2024-01-01T00:00:00Z",
+            updatedAt: "2024-01-02T00:00:00Z",
+          },
+          {
+            id: "prd_2",
+            projectId: "proj_1",
+            ref: "TEST-P2",
+            title: "PRD 2",
+            status: "APPROVED",
+            createdAt: "2024-01-01T00:00:00Z",
+            updatedAt: "2024-01-02T00:00:00Z",
+          },
+        ],
+        total: 5,
+        limit: 2,
+        offset: 0,
+        hasMore: true,
+      };
+
+      const result = toMcpPaginatedPrds(paginatedResult);
+
+      expect(result.items.length).toBe(2);
+      expect(result.items[0].project_id).toBe("proj_1"); // camelCase -> snake_case
+      expect(result.total).toBe(5);
+      expect(result.limit).toBe(2);
+      expect(result.offset).toBe(0);
+      expect(result.has_more).toBe(true); // hasMore -> has_more
+    });
+  });
+
+  describe("toMcpPaginatedEpics", () => {
+    test("transforms paginated Epic result", () => {
+      const paginatedResult: PaginatedResult<Epic> = {
+        items: [
+          {
+            id: "epic_1",
+            prdId: "prd_1",
+            ref: "TEST-E1",
+            title: "Epic 1",
+            status: "PENDING",
+            createdAt: "2024-01-01T00:00:00Z",
+            updatedAt: "2024-01-02T00:00:00Z",
+          },
+        ],
+        total: 1,
+        limit: 10,
+        offset: 0,
+        hasMore: false,
+      };
+
+      const result = toMcpPaginatedEpics(paginatedResult);
+
+      expect(result.items.length).toBe(1);
+      expect(result.items[0].prd_id).toBe("prd_1");
+      expect(result.has_more).toBe(false);
+    });
+  });
+
+  describe("toMcpPaginatedTasks", () => {
+    test("transforms paginated Task result", () => {
+      const paginatedResult: PaginatedResult<Task> = {
+        items: [
+          {
+            id: "task_1",
+            epicId: "epic_1",
+            ref: "TEST-T1",
+            title: "Task 1",
+            status: "IN_PROGRESS",
+            priority: "MEDIUM",
+            createdAt: "2024-01-01T00:00:00Z",
+            updatedAt: "2024-01-02T00:00:00Z",
+          },
+        ],
+        total: 1,
+        limit: 10,
+        offset: 0,
+        hasMore: false,
+      };
+
+      const result = toMcpPaginatedTasks(paginatedResult);
+
+      expect(result.items.length).toBe(1);
+      expect(result.items[0].epic_id).toBe("epic_1");
+      expect(result.has_more).toBe(false);
+    });
+  });
+
+  describe("toMcpCascadeResult", () => {
+    test("transforms cascade deletion result", () => {
+      const cascade: CascadeResult = {
+        criteria: 5,
+        tasks: 10,
+        epics: 2,
+        dependencies: 3,
+      };
+
+      const result = toMcpCascadeResult(cascade);
+
+      expect(result.criteria).toBe(5);
+      expect(result.tasks).toBe(10);
+      expect(result.epics).toBe(2);
+      expect(result.dependencies).toBe(3);
+    });
+  });
+});

package/src/server/utils/logger.ts

@@ -0,0 +1,9 @@
+export const logger = {
+  info: (msg: string, ...args: unknown[]) =>
+    console.error(`[INFO] ${msg}`, ...args),
+  error: (msg: string, ...args: unknown[]) =>
+    console.error(`[ERROR] ${msg}`, ...args),
+  debug: (msg: string, ...args: unknown[]) => {
+    if (process.env.DEBUG) console.error(`[DEBUG] ${msg}`, ...args);
+  },
+};

package/src/server/utils/mcp-response.ts

@@ -0,0 +1,254 @@
+/**
+ * MCP Response Utilities
+ *
+ * Transforms adapter responses (camelCase) to MCP format (snake_case).
+ * This ensures consistent API responses while keeping the adapter interface clean.
+ */
+
+import type {
+  AcceptanceCriterion,
+  CascadeResult,
+  Epic,
+  PaginatedResult,
+  Prd,
+  Stats,
+  Task,
+} from "../adapters/types.js";
+
+// =============================================================================
+// PRD Response Transformations
+// =============================================================================
+
+export interface McpPrd {
+  id: string;
+  project_id: string;
+  ref: string;
+  title: string;
+  description?: string;
+  status: string;
+  tag?: string;
+  folder_path?: string;
+  created_at: string;
+  updated_at: string;
+}
+
+export function toMcpPrd(prd: Prd): McpPrd {
+  return {
+    id: prd.id,
+    project_id: prd.projectId,
+    ref: prd.ref,
+    title: prd.title,
+    description: prd.description,
+    status: prd.status,
+    tag: prd.tag,
+    folder_path: prd.folderPath,
+    created_at: prd.createdAt,
+    updated_at: prd.updatedAt,
+  };
+}
+
+// =============================================================================
+// Epic Response Transformations
+// =============================================================================
+
+export interface McpEpic {
+  id: string;
+  prd_id: string;
+  ref: string;
+  title: string;
+  description?: string;
+  status: string;
+  created_at: string;
+  updated_at: string;
+}
+
+export function toMcpEpic(epic: Epic): McpEpic {
+  return {
+    id: epic.id,
+    prd_id: epic.prdId,
+    ref: epic.ref,
+    title: epic.title,
+    description: epic.description,
+    status: epic.status,
+    created_at: epic.createdAt,
+    updated_at: epic.updatedAt,
+  };
+}
+
+// =============================================================================
+// Task Response Transformations
+// =============================================================================
+
+export interface McpTask {
+  id: string;
+  epic_id: string;
+  ref: string;
+  title: string;
+  description?: string;
+  status: string;
+  priority: string;
+  created_at: string;
+  updated_at: string;
+}
+
+export function toMcpTask(task: Task): McpTask {
+  return {
+    id: task.id,
+    epic_id: task.epicId,
+    ref: task.ref,
+    title: task.title,
+    description: task.description,
+    status: task.status,
+    priority: task.priority,
+    created_at: task.createdAt,
+    updated_at: task.updatedAt,
+  };
+}
+
+// =============================================================================
+// Acceptance Criteria Response Transformations
+// =============================================================================
+
+export interface McpCriterion {
+  id: string;
+  parent_type: string;
+  parent_id: string;
+  criteria: string;
+  is_met: boolean;
+  created_at: string;
+}
+
+export function toMcpCriterion(criterion: AcceptanceCriterion): McpCriterion {
+  return {
+    id: criterion.id,
+    parent_type: criterion.parentType,
+    parent_id: criterion.parentId,
+    criteria: criterion.criteria,
+    is_met: criterion.isMet,
+    created_at: criterion.createdAt,
+  };
+}
+
+// =============================================================================
+// Stats Response Transformations
+// =============================================================================
+
+export interface McpStats {
+  prds: {
+    total: number;
+    draft: number;
+    pending_review: number;
+    reviewed: number;
+    approved: number;
+    breakdown_ready: number;
+    completed: number;
+    archived: number;
+  };
+  epics: {
+    total: number;
+    pending: number;
+    in_progress: number;
+    completed: number;
+  };
+  tasks: {
+    total: number;
+    pending: number;
+    in_progress: number;
+    completed: number;
+  };
+}
+
+export function toMcpStats(stats: Stats): McpStats {
+  return {
+    prds: {
+      total: stats.prds.total,
+      draft: stats.prds.draft,
+      pending_review: stats.prds.pendingReview,
+      reviewed: stats.prds.reviewed,
+      approved: stats.prds.approved,
+      breakdown_ready: stats.prds.breakdownReady,
+      completed: stats.prds.completed,
+      archived: stats.prds.archived,
+    },
+    epics: {
+      total: stats.epics.total,
+      pending: stats.epics.pending,
+      in_progress: stats.epics.inProgress,
+      completed: stats.epics.completed,
+    },
+    tasks: {
+      total: stats.tasks.total,
+      pending: stats.tasks.pending,
+      in_progress: stats.tasks.inProgress,
+      completed: stats.tasks.completed,
+    },
+  };
+}
+
+// =============================================================================
+// Paginated Response Transformations
+// =============================================================================
+
+export interface McpPaginatedResult<T> {
+  items: T[];
+  total: number;
+  limit: number;
+  offset: number;
+  has_more: boolean;
+}
+
+export function toMcpPaginatedPrds(
+  result: PaginatedResult<Prd>,
+): McpPaginatedResult<McpPrd> {
+  return {
+    items: result.items.map(toMcpPrd),
+    total: result.total,
+    limit: result.limit,
+    offset: result.offset,
+    has_more: result.hasMore,
+  };
+}
+
+export function toMcpPaginatedEpics(
+  result: PaginatedResult<Epic>,
+): McpPaginatedResult<McpEpic> {
+  return {
+    items: result.items.map(toMcpEpic),
+    total: result.total,
+    limit: result.limit,
+    offset: result.offset,
+    has_more: result.hasMore,
+  };
+}
+
+export function toMcpPaginatedTasks(
+  result: PaginatedResult<Task>,
+): McpPaginatedResult<McpTask> {
+  return {
+    items: result.items.map(toMcpTask),
+    total: result.total,
+    limit: result.limit,
+    offset: result.offset,
+    has_more: result.hasMore,
+  };
+}
+
+// =============================================================================
+// Cascade Result Transformation
+// =============================================================================
+
+export interface McpCascadeResult {
+  criteria: number;
+  tasks: number;
+  epics: number;
+  dependencies: number;
+}
+
+export function toMcpCascadeResult(cascade: CascadeResult): McpCascadeResult {
+  return {
+    criteria: cascade.criteria,
+    tasks: cascade.tasks,
+    epics: cascade.epics,
+    dependencies: cascade.dependencies,
+  };
+}