@cliangdev/flux-plugin 0.2.0 → 0.3.0

package/src/utils/__tests__/status-renderer.test.ts

@@ -0,0 +1,310 @@
+import { describe, expect, test } from "bun:test";
+import { renderFullTreeView, renderSummaryView } from "../status-renderer.js";
+
+describe("renderSummaryView", () => {
+  const mockProjectContext = {
+    name: "flux plugin",
+    vision: "AI-first workflow orchestration",
+    ref_prefix: "FP",
+  };
+
+  const mockStats = {
+    prds: { total: 2, draft: 1, approved: 1, completed: 0, archived: 0 },
+    epics: { total: 4, pending: 1, in_progress: 2, completed: 1 },
+    tasks: { total: 10, pending: 3, in_progress: 2, completed: 5 },
+  };
+
+  const mockPrds = [
+    {
+      ref: "FP-P1",
+      title: "MCP Tool Implementation",
+      status: "COMPLETED",
+      epics: [
+        {
+          ref: "FP-E1",
+          title: "Core CRUD Tools",
+          status: "COMPLETED",
+          task_count: 3,
+          tasks_completed: 3,
+        },
+        {
+          ref: "FP-E2",
+          title: "Query Tools",
+          status: "COMPLETED",
+          task_count: 2,
+          tasks_completed: 2,
+        },
+      ],
+    },
+    {
+      ref: "FP-P5",
+      title: "Status Display Feature",
+      status: "DRAFT",
+      epics: [
+        {
+          ref: "FP-E4",
+          title: "Terminal UI",
+          status: "IN_PROGRESS",
+          task_count: 4,
+          tasks_completed: 1,
+        },
+      ],
+    },
+  ];
+
+  test("shows version and project name in header", () => {
+    const result = renderSummaryView(
+      mockProjectContext,
+      mockStats,
+      mockPrds,
+      "0.1.0",
+    );
+    expect(result).toContain("Flux v0.1.0 • flux plugin");
+  });
+
+  test("shows only project name when version is not provided", () => {
+    const result = renderSummaryView(mockProjectContext, mockStats, mockPrds);
+    expect(result).toContain("flux plugin");
+    expect(result).not.toContain("Flux v");
+  });
+
+  test("shows project name header", () => {
+    const result = renderSummaryView(mockProjectContext, mockStats, mockPrds);
+    expect(result).toContain("flux plugin");
+  });
+
+  test("shows overall progress bar with percentage", () => {
+    const result = renderSummaryView(mockProjectContext, mockStats, mockPrds);
+    // 5 completed out of 10 = 50%
+    expect(result).toContain("50%");
+    expect(result).toMatch(/[━·]+/);
+  });
+
+  test("shows task summary counts", () => {
+    const result = renderSummaryView(mockProjectContext, mockStats, mockPrds);
+    expect(result).toContain("5 done");
+    expect(result).toContain("2 active");
+    expect(result).toContain("3 pending");
+  });
+
+  test("lists PRDs with status badges", () => {
+    const result = renderSummaryView(mockProjectContext, mockStats, mockPrds);
+    expect(result).toContain("FP-P1");
+    expect(result).toContain("MCP Tool Implementation");
+    expect(result).toContain("FP-P5");
+    expect(result).toContain("Status Display Feature");
+    // Status badges
+    expect(result).toContain("COMPLETED");
+    expect(result).toContain("DRAFT");
+  });
+
+  test("shows epic progress bars under each PRD", () => {
+    const result = renderSummaryView(mockProjectContext, mockStats, mockPrds);
+    expect(result).toContain("FP-E1");
+    expect(result).toContain("Core CRUD Tools");
+    expect(result).toContain("FP-E4");
+    expect(result).toContain("Terminal UI");
+    // Progress indicators
+    expect(result).toContain("3/3");
+    expect(result).toContain("1/4");
+  });
+
+  test("handles empty project", () => {
+    const emptyStats = {
+      prds: { total: 0, draft: 0, approved: 0, completed: 0, archived: 0 },
+      epics: { total: 0, pending: 0, in_progress: 0, completed: 0 },
+      tasks: { total: 0, pending: 0, in_progress: 0, completed: 0 },
+    };
+    const result = renderSummaryView(mockProjectContext, emptyStats, []);
+    expect(result).toContain("flux plugin");
+    expect(result).toContain("0%");
+  });
+
+  test("sorts PRDs by status with APPROVED first, DRAFT last", () => {
+    const unsortedPrds = [
+      {
+        ref: "FP-P1",
+        title: "Draft PRD",
+        status: "DRAFT",
+        epics: [],
+      },
+      {
+        ref: "FP-P2",
+        title: "Approved PRD",
+        status: "APPROVED",
+        epics: [],
+      },
+      {
+        ref: "FP-P3",
+        title: "Pending Review PRD",
+        status: "PENDING_REVIEW",
+        epics: [],
+      },
+    ];
+    const result = renderSummaryView(
+      mockProjectContext,
+      mockStats,
+      unsortedPrds,
+    );
+    const lines = result.split("\n");
+    const prdLines = lines.filter((line) => line.includes("FP-P"));
+    // APPROVED should come first, then PENDING_REVIEW, then DRAFT
+    expect(prdLines[0]).toContain("FP-P2"); // APPROVED
+    expect(prdLines[1]).toContain("FP-P3"); // PENDING_REVIEW
+    expect(prdLines[2]).toContain("FP-P1"); // DRAFT
+  });
+
+  test("shows '(no tasks)' indicator for epics with zero tasks", () => {
+    const prdsWithEmptyEpic = [
+      {
+        ref: "FP-P1",
+        title: "PRD with empty epic",
+        status: "DRAFT",
+        epics: [
+          {
+            ref: "FP-E1",
+            title: "Empty Epic",
+            status: "PENDING",
+            task_count: 0,
+            tasks_completed: 0,
+          },
+        ],
+      },
+    ];
+    const result = renderSummaryView(
+      mockProjectContext,
+      mockStats,
+      prdsWithEmptyEpic,
+    );
+    expect(result).toContain("(no tasks)");
+    expect(result).toContain("··········");
+    // Should NOT show "0/0"
+    expect(result).not.toMatch(/FP-E1.*0\/0/);
+  });
+});
+
+describe("renderFullTreeView", () => {
+  const mockPrdsWithTasks = [
+    {
+      ref: "FP-P5",
+      title: "Status Display Feature",
+      status: "DRAFT",
+      epics: [
+        {
+          ref: "FP-E4",
+          title: "Terminal UI",
+          status: "IN_PROGRESS",
+          tasks: [
+            { ref: "FP-T6", title: "Design mockups", status: "COMPLETED" },
+            {
+              ref: "FP-T7",
+              title: "Implement tree view",
+              status: "IN_PROGRESS",
+            },
+            { ref: "FP-T8", title: "Add color support", status: "PENDING" },
+            { ref: "FP-T9", title: "Write tests", status: "PENDING" },
+          ],
+        },
+      ],
+    },
+  ];
+
+  test("shows full PRD→Epic→Task hierarchy", () => {
+    const result = renderFullTreeView(mockPrdsWithTasks);
+    // PRD level
+    expect(result).toContain("FP-P5");
+    expect(result).toContain("Status Display Feature");
+    // Epic level
+    expect(result).toContain("FP-E4");
+    expect(result).toContain("Terminal UI");
+    // Task level
+    expect(result).toContain("FP-T6");
+    expect(result).toContain("Design mockups");
+    expect(result).toContain("FP-T7");
+    expect(result).toContain("FP-T8");
+    expect(result).toContain("FP-T9");
+  });
+
+  test("each item has status icon", () => {
+    const result = renderFullTreeView(mockPrdsWithTasks);
+    // Status icons: ✓ for completed, ⟳ for in progress, ○ for pending
+    expect(result).toContain("✓");
+    expect(result).toContain("⟳");
+    expect(result).toContain("○");
+  });
+
+  test("current task is highlighted with ← CURRENT", () => {
+    const result = renderFullTreeView(mockPrdsWithTasks);
+    // IN_PROGRESS task should be marked as current
+    expect(result).toContain("CURRENT");
+    // The line with FP-T7 should have the CURRENT marker
+    const lines = result.split("\n");
+    const currentLine = lines.find((line) => line.includes("FP-T7"));
+    expect(currentLine).toContain("CURRENT");
+  });
+
+  test("handles PRD with no epics", () => {
+    const prdsNoEpics = [
+      {
+        ref: "FP-P1",
+        title: "Empty PRD",
+        status: "DRAFT",
+        epics: [],
+      },
+    ];
+    const result = renderFullTreeView(prdsNoEpics);
+    expect(result).toContain("FP-P1");
+    expect(result).toContain("Empty PRD");
+  });
+
+  test("handles epic with no tasks", () => {
+    const epicNoTasks = [
+      {
+        ref: "FP-P1",
+        title: "PRD",
+        status: "APPROVED",
+        epics: [
+          {
+            ref: "FP-E1",
+            title: "Empty Epic",
+            status: "PENDING",
+            tasks: [],
+          },
+        ],
+      },
+    ];
+    const result = renderFullTreeView(epicNoTasks);
+    expect(result).toContain("FP-E1");
+    expect(result).toContain("Empty Epic");
+  });
+
+  test("sorts PRDs by status with APPROVED first, DRAFT last", () => {
+    const unsortedPrds = [
+      {
+        ref: "FP-P1",
+        title: "Draft PRD",
+        status: "DRAFT",
+        epics: [],
+      },
+      {
+        ref: "FP-P2",
+        title: "Approved PRD",
+        status: "APPROVED",
+        epics: [],
+      },
+      {
+        ref: "FP-P3",
+        title: "Pending Review PRD",
+        status: "PENDING_REVIEW",
+        epics: [],
+      },
+    ];
+    const result = renderFullTreeView(unsortedPrds);
+    const lines = result.split("\n");
+    const prdLines = lines.filter((line) => line.includes("FP-P"));
+    // APPROVED should come first, then PENDING_REVIEW, then DRAFT
+    expect(prdLines[0]).toContain("FP-P2"); // APPROVED
+    expect(prdLines[1]).toContain("FP-P3"); // PENDING_REVIEW
+    expect(prdLines[2]).toContain("FP-P1"); // DRAFT
+  });
+});

package/src/utils/display.ts

@@ -0,0 +1,62 @@
+/**
+ * Renders a progress bar with filled and empty portions.
+ *
+ * @param percentage - Progress percentage (0-100)
+ * @param width - Total width of the progress bar in characters
+ * @returns String representation of the progress bar
+ *
+ * @example
+ * renderProgressBar(0, 10)   // "··········"
+ * renderProgressBar(50, 10)  // "━━━━━·····"
+ * renderProgressBar(100, 10) // "━━━━━━━━━━"
+ */
+export function renderProgressBar(percentage: number, width: number): string {
+  const filledCount = Math.floor((percentage / 100) * width);
+  const emptyCount = width - filledCount;
+
+  const filledChar = "━";
+  const emptyChar = "·";
+
+  return filledChar.repeat(filledCount) + emptyChar.repeat(emptyCount);
+}
+
+/**
+ * Status icons for different entity states.
+ */
+const STATUS_ICONS: Record<string, string> = {
+  COMPLETED: "✓",
+  IN_PROGRESS: "⟳",
+  PENDING: "○",
+  DRAFT: "◇",
+  APPROVED: "●",
+};
+
+/**
+ * Returns the appropriate icon for a given status.
+ *
+ * @param status - Entity status (COMPLETED, IN_PROGRESS, PENDING, DRAFT, APPROVED)
+ * @returns Unicode icon character representing the status
+ *
+ * @example
+ * getStatusIcon("COMPLETED")   // "✓"
+ * getStatusIcon("IN_PROGRESS") // "⟳"
+ * getStatusIcon("PENDING")     // "○"
+ */
+export function getStatusIcon(status: string): string {
+  return STATUS_ICONS[status] ?? "?";
+}
+
+/**
+ * Returns a badge for the given status.
+ *
+ * @param status - Entity status
+ * @returns String with the status in brackets
+ *
+ * @example
+ * getStatusBadge("COMPLETED")   // "[COMPLETED]"
+ * getStatusBadge("IN_PROGRESS") // "[IN_PROGRESS]"
+ * getStatusBadge("DRAFT")       // "[DRAFT]"
+ */
+export function getStatusBadge(status: string): string {
+  return `[${status}]`;
+}

package/src/utils/status-renderer.ts

@@ -0,0 +1,214 @@
+import { getStatusBadge, getStatusIcon, renderProgressBar } from "./display.js";
+
+interface ProjectContext {
+  name: string;
+  vision?: string;
+  ref_prefix: string;
+}
+
+interface Stats {
+  prds: {
+    total: number;
+    draft: number;
+    approved: 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;
+  };
+}
+
+interface Epic {
+  ref: string;
+  title: string;
+  status: string;
+  task_count: number;
+  tasks_completed: number;
+  dependencies?: string[];
+}
+
+interface Task {
+  ref: string;
+  title: string;
+  status: string;
+  dependencies?: string[];
+}
+
+interface EpicWithTasks {
+  ref: string;
+  title: string;
+  status: string;
+  tasks: Task[];
+  dependencies?: string[];
+}
+
+interface Prd {
+  ref: string;
+  title: string;
+  status: string;
+  epics: Epic[];
+  dependencies?: string[];
+}
+
+interface PrdWithTasks {
+  ref: string;
+  title: string;
+  status: string;
+  epics: EpicWithTasks[];
+  dependencies?: string[];
+}
+
+const STATUS_ORDER: Record<string, number> = {
+  APPROVED: 1,
+  BREAKDOWN_READY: 2,
+  PENDING_REVIEW: 3,
+  REVIEWED: 4,
+  DRAFT: 5,
+  COMPLETED: 6,
+};
+
+function sortPrdsByStatus<T extends { status: string; ref: string }>(
+  prds: T[],
+): T[] {
+  return [...prds].sort((a, b) => {
+    const orderA = STATUS_ORDER[a.status] ?? 99;
+    const orderB = STATUS_ORDER[b.status] ?? 99;
+    if (orderA !== orderB) return orderA - orderB;
+    return a.ref.localeCompare(b.ref);
+  });
+}
+
+/**
+ * Renders the summary view for /flux:status command.
+ */
+export function renderSummaryView(
+  project: ProjectContext,
+  stats: Stats,
+  prds: Prd[],
+  version?: string,
+): string {
+  const lines: string[] = [];
+
+  if (version) {
+    lines.push(`Flux v${version} • ${project.name}`);
+  } else {
+    lines.push(project.name);
+  }
+  lines.push("");
+
+  const totalTasks = stats.tasks.total;
+  const completedTasks = stats.tasks.completed;
+  const percentage =
+    totalTasks > 0 ? Math.round((completedTasks / totalTasks) * 100) : 0;
+  const progressBar = renderProgressBar(percentage, 40);
+
+  lines.push(`Progress   ${progressBar} ${percentage}%`);
+  lines.push(
+    `Tasks      ${completedTasks} done · ${stats.tasks.in_progress} active · ${stats.tasks.pending} pending`,
+  );
+  lines.push("");
+
+  const sortedPrds = sortPrdsByStatus(prds);
+
+  for (const prd of sortedPrds) {
+    const badge = getStatusBadge(prd.status);
+    const prdBlocked = prd.dependencies && prd.dependencies.length > 0;
+    const prdBlockedBy = prdBlocked
+      ? ` ⚠️ blocked by: ${prd.dependencies?.join(", ")}`
+      : "";
+    lines.push(`${prd.ref} ${prd.title}  ${badge}${prdBlockedBy}`);
+
+    for (const epic of prd.epics) {
+      const icon = getStatusIcon(epic.status);
+      const epicBlocked = epic.dependencies && epic.dependencies.length > 0;
+      const epicBlockedBy = epicBlocked
+        ? ` ⚠️ blocked by: ${epic.dependencies?.join(", ")}`
+        : "";
+
+      if (epic.task_count === 0) {
+        lines.push(
+          `  ${icon} ${epic.ref} ${epic.title}  ·········· (no tasks)${epicBlockedBy}`,
+        );
+      } else {
+        const epicProgress = renderProgressBar(
+          (epic.tasks_completed / epic.task_count) * 100,
+          10,
+        );
+        lines.push(
+          `  ${icon} ${epic.ref} ${epic.title}  ${epicProgress} ${epic.tasks_completed}/${epic.task_count}${epicBlockedBy}`,
+        );
+      }
+    }
+    lines.push("");
+  }
+
+  lines.push("─".repeat(50));
+  lines.push(
+    `✓ ${completedTasks} done  ⟳ ${stats.tasks.in_progress} active  ○ ${stats.tasks.pending} pending`,
+  );
+
+  return lines.join("\n");
+}
+
+/**
+ * Renders the full tree view for /flux:status --full command.
+ * Shows complete PRD → Epic → Task hierarchy with status icons.
+ */
+export function renderFullTreeView(prds: PrdWithTasks[]): string {
+  const lines: string[] = [];
+
+  const sortedPrds = sortPrdsByStatus(prds);
+
+  for (const prd of sortedPrds) {
+    const prdBadge = getStatusBadge(prd.status);
+    const prdBlocked = prd.dependencies && prd.dependencies.length > 0;
+    const prdBlockedBy = prdBlocked
+      ? `  ⚠️ blocked by: ${prd.dependencies?.join(", ")}`
+      : "";
+    lines.push(`${prd.ref} ${prd.title}`);
+    lines.push(`${prdBadge}${prdBlockedBy}`);
+    lines.push("");
+
+    for (const epic of prd.epics) {
+      const epicIcon = getStatusIcon(epic.status);
+      const epicBlocked = epic.dependencies && epic.dependencies.length > 0;
+      const epicBlockedBy = epicBlocked
+        ? `  ⚠️ blocked by: ${epic.dependencies?.join(", ")}`
+        : "";
+      lines.push(`  ${epicIcon} ${epic.ref} ${epic.title}${epicBlockedBy}`);
+
+      if (epic.tasks.length > 0) {
+        lines.push(`  ┌${"─".repeat(50)}┐`);
+
+        for (const task of epic.tasks) {
+          const taskIcon = getStatusIcon(task.status);
+          const taskBlocked = task.dependencies && task.dependencies.length > 0;
+          const taskBlockedBy = taskBlocked
+            ? `  ⚠️ blocked by: ${task.dependencies?.join(", ")}`
+            : "";
+          const currentMarker =
+            task.status === "IN_PROGRESS" ? "  ← CURRENT" : "";
+          lines.push(
+            `  │ ${taskIcon} ${task.ref} ${task.title}${currentMarker}${taskBlockedBy}`,
+          );
+        }
+
+        lines.push(`  └${"─".repeat(50)}┘`);
+      }
+
+      lines.push("");
+    }
+  }
+
+  return lines.join("\n");
+}

package/src/version.ts

@@ -0,0 +1,5 @@
+/**
+ * Package version.
+ * Keep in sync with package.json - updated automatically by version bump scripts.
+ */
+export const VERSION = "0.1.0";