@cliangdev/flux-plugin 0.2.0 → 0.3.0

package/src/server/utils/status-transitions.ts

@@ -0,0 +1,160 @@
+/**
+ * Status Transition Validation
+ *
+ * Defines valid status transitions for PRDs, Epics, and Tasks.
+ * Prevents skipping workflow stages.
+ */
+
+import type { EpicStatus, PrdStatus, TaskStatus } from "../adapters/types.js";
+
+// =============================================================================
+// PRD Status Transitions
+// =============================================================================
+
+/**
+ * Valid PRD status transitions.
+ * Users cannot skip steps in the workflow.
+ */
+const PRD_TRANSITIONS: Record<PrdStatus, PrdStatus[]> = {
+  DRAFT: ["PENDING_REVIEW"],
+  PENDING_REVIEW: ["REVIEWED", "DRAFT"], // Can go back to DRAFT for revisions
+  REVIEWED: ["APPROVED", "DRAFT"], // Can reject back to DRAFT
+  APPROVED: ["BREAKDOWN_READY"],
+  BREAKDOWN_READY: ["COMPLETED"],
+  COMPLETED: ["ARCHIVED"], // Can archive completed PRDs
+  ARCHIVED: [], // Terminal state
+};
+
+/**
+ * Check if a PRD status transition is valid.
+ */
+export function isValidPrdTransition(from: PrdStatus, to: PrdStatus): boolean {
+  return PRD_TRANSITIONS[from]?.includes(to) ?? false;
+}
+
+/**
+ * Get valid next statuses for a PRD.
+ */
+export function getValidPrdTransitions(status: PrdStatus): PrdStatus[] {
+  return PRD_TRANSITIONS[status] ?? [];
+}
+
+// =============================================================================
+// Epic Status Transitions
+// =============================================================================
+
+/**
+ * Valid Epic status transitions.
+ */
+const EPIC_TRANSITIONS: Record<EpicStatus, EpicStatus[]> = {
+  PENDING: ["IN_PROGRESS"],
+  IN_PROGRESS: ["COMPLETED", "PENDING"], // Can pause back to PENDING
+  COMPLETED: [], // Terminal state
+};
+
+/**
+ * Check if an Epic status transition is valid.
+ */
+export function isValidEpicTransition(
+  from: EpicStatus,
+  to: EpicStatus,
+): boolean {
+  return EPIC_TRANSITIONS[from]?.includes(to) ?? false;
+}
+
+/**
+ * Get valid next statuses for an Epic.
+ */
+export function getValidEpicTransitions(status: EpicStatus): EpicStatus[] {
+  return EPIC_TRANSITIONS[status] ?? [];
+}
+
+// =============================================================================
+// Task Status Transitions
+// =============================================================================
+
+/**
+ * Valid Task status transitions.
+ */
+const TASK_TRANSITIONS: Record<TaskStatus, TaskStatus[]> = {
+  PENDING: ["IN_PROGRESS"],
+  IN_PROGRESS: ["COMPLETED", "PENDING"], // Can pause back to PENDING
+  COMPLETED: [], // Terminal state
+};
+
+/**
+ * Check if a Task status transition is valid.
+ */
+export function isValidTaskTransition(
+  from: TaskStatus,
+  to: TaskStatus,
+): boolean {
+  return TASK_TRANSITIONS[from]?.includes(to) ?? false;
+}
+
+/**
+ * Get valid next statuses for a Task.
+ */
+export function getValidTaskTransitions(status: TaskStatus): TaskStatus[] {
+  return TASK_TRANSITIONS[status] ?? [];
+}
+
+// =============================================================================
+// Generic Helpers
+// =============================================================================
+
+export type EntityType = "prd" | "epic" | "task";
+
+/**
+ * Get valid transitions for any entity type.
+ */
+export function getValidTransitions(
+  entityType: EntityType,
+  status: string,
+): string[] {
+  switch (entityType) {
+    case "prd":
+      return getValidPrdTransitions(status as PrdStatus);
+    case "epic":
+      return getValidEpicTransitions(status as EpicStatus);
+    case "task":
+      return getValidTaskTransitions(status as TaskStatus);
+    default:
+      return [];
+  }
+}
+
+/**
+ * Check if a status transition is valid for any entity type.
+ */
+export function isValidTransition(
+  entityType: EntityType,
+  from: string,
+  to: string,
+): boolean {
+  switch (entityType) {
+    case "prd":
+      return isValidPrdTransition(from as PrdStatus, to as PrdStatus);
+    case "epic":
+      return isValidEpicTransition(from as EpicStatus, to as EpicStatus);
+    case "task":
+      return isValidTaskTransition(from as TaskStatus, to as TaskStatus);
+    default:
+      return false;
+  }
+}
+
+/**
+ * Get a human-readable error message for invalid transitions.
+ */
+export function getTransitionErrorMessage(
+  entityType: EntityType,
+  from: string,
+  to: string,
+): string {
+  const validNext = getValidTransitions(entityType, from);
+  if (validNext.length === 0) {
+    return `Cannot transition from ${from}: it is a terminal state`;
+  }
+  return `Invalid transition from ${from} to ${to}. Valid next statuses: ${validNext.join(", ")}`;
+}

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

@@ -0,0 +1,215 @@
+import { Database } from "bun:sqlite";
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const BUN_PATH = join(homedir(), ".bun", "bin", "bun");
+
+function setupTestProject(testDir: string, projectName = "test-project") {
+  const fluxDir = join(testDir, ".flux");
+  mkdirSync(fluxDir, { recursive: true });
+
+  writeFileSync(
+    join(fluxDir, "project.json"),
+    JSON.stringify({
+      name: projectName,
+      ref_prefix: "TEST",
+    }),
+  );
+
+  const db = new Database(join(fluxDir, "flux.db"));
+  db.run(`
+    CREATE TABLE IF NOT EXISTS tasks (
+      id TEXT PRIMARY KEY,
+      ref TEXT UNIQUE NOT NULL,
+      title TEXT NOT NULL,
+      status TEXT DEFAULT 'PENDING'
+    )
+  `);
+  return db;
+}
+
+describe("status-line script", () => {
+  const TEST_DIR = `/tmp/flux-status-line-test-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+
+  beforeEach(() => {
+    if (existsSync(TEST_DIR)) {
+      rmSync(TEST_DIR, { recursive: true, force: true });
+    }
+    mkdirSync(TEST_DIR, { recursive: true });
+  });
+
+  afterEach(() => {
+    if (existsSync(TEST_DIR)) {
+      rmSync(TEST_DIR, { recursive: true, force: true });
+    }
+  });
+
+  test("script is executable", async () => {
+    const scriptPath = join(import.meta.dir, "..", "index.ts");
+    expect(existsSync(scriptPath)).toBe(true);
+
+    const proc = Bun.spawn([BUN_PATH, scriptPath], {
+      stdin: "pipe",
+      stdout: "pipe",
+      stderr: "pipe",
+      cwd: TEST_DIR,
+    });
+
+    proc.stdin.write("{}");
+    proc.stdin.end();
+
+    await proc.exited;
+    expect(proc.exitCode).toBe(0);
+  });
+
+  test("script reads JSON from stdin", async () => {
+    const db = setupTestProject(TEST_DIR);
+    db.run(
+      "INSERT INTO tasks (id, ref, title, status) VALUES ('t1', 'TEST-T1', 'Active task', 'IN_PROGRESS')",
+    );
+    db.close();
+
+    const scriptPath = join(import.meta.dir, "..", "index.ts");
+    const proc = Bun.spawn([BUN_PATH, scriptPath], {
+      stdin: "pipe",
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+
+    proc.stdin.write(JSON.stringify({ cwd: TEST_DIR }));
+    proc.stdin.end();
+
+    await proc.exited;
+    const output = await new Response(proc.stdout).text();
+
+    expect(output).toContain("TEST-T1");
+    expect(output).toContain("Active task");
+  });
+
+  test("script outputs single line to stdout", async () => {
+    const db = setupTestProject(TEST_DIR);
+    db.run(
+      "INSERT INTO tasks (id, ref, title, status) VALUES ('t1', 'TEST-T1', 'Active task', 'IN_PROGRESS')",
+    );
+    db.run(
+      "INSERT INTO tasks (id, ref, title, status) VALUES ('t2', 'TEST-T2', 'Done task', 'COMPLETED')",
+    );
+    db.close();
+
+    const scriptPath = join(import.meta.dir, "..", "index.ts");
+    const proc = Bun.spawn([BUN_PATH, scriptPath], {
+      stdin: "pipe",
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+
+    proc.stdin.write(JSON.stringify({ cwd: TEST_DIR }));
+    proc.stdin.end();
+
+    await proc.exited;
+    const output = await new Response(proc.stdout).text();
+
+    const lines = output.trim().split("\n");
+    expect(lines.length).toBe(1);
+
+    expect(output).toContain("TEST-T1");
+    expect(output).toContain("Active task");
+    expect(output).toContain("⟳");
+  });
+
+  test("shows only active task without task counts", async () => {
+    const db = setupTestProject(TEST_DIR);
+    db.run(
+      "INSERT INTO tasks (id, ref, title, status) VALUES ('t1', 'TEST-T1', 'Done 1', 'COMPLETED')",
+    );
+    db.run(
+      "INSERT INTO tasks (id, ref, title, status) VALUES ('t2', 'TEST-T2', 'Done 2', 'COMPLETED')",
+    );
+    db.run(
+      "INSERT INTO tasks (id, ref, title, status) VALUES ('t3', 'TEST-T3', 'Active', 'IN_PROGRESS')",
+    );
+    db.close();
+
+    const scriptPath = join(import.meta.dir, "..", "index.ts");
+    const proc = Bun.spawn([BUN_PATH, scriptPath], {
+      stdin: "pipe",
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+
+    proc.stdin.write(JSON.stringify({ cwd: TEST_DIR }));
+    proc.stdin.end();
+
+    await proc.exited;
+    const output = await new Response(proc.stdout).text();
+
+    expect(output).toContain("TEST-T3");
+    expect(output).toContain("Active");
+    expect(output).not.toContain("tasks");
+  });
+
+  test("outputs nothing when no flux project found", async () => {
+    const scriptPath = join(import.meta.dir, "..", "index.ts");
+    const proc = Bun.spawn([BUN_PATH, scriptPath], {
+      stdin: "pipe",
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+
+    proc.stdin.write(JSON.stringify({ cwd: TEST_DIR }));
+    proc.stdin.end();
+
+    await proc.exited;
+    const output = await new Response(proc.stdout).text();
+
+    expect(output.trim()).toBe("");
+  });
+
+  test("includes model name from JSON input", async () => {
+    const db = setupTestProject(TEST_DIR);
+    db.run(
+      "INSERT INTO tasks (id, ref, title, status) VALUES ('t1', 'TEST-T1', 'Active task', 'IN_PROGRESS')",
+    );
+    db.close();
+
+    const scriptPath = join(import.meta.dir, "..", "index.ts");
+    const proc = Bun.spawn([BUN_PATH, scriptPath], {
+      stdin: "pipe",
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+
+    proc.stdin.write(JSON.stringify({ cwd: TEST_DIR, model: "Opus" }));
+    proc.stdin.end();
+
+    await proc.exited;
+    const output = await new Response(proc.stdout).text();
+
+    expect(output).toContain("[Opus]");
+  });
+
+  test("outputs nothing when no active task", async () => {
+    const db = setupTestProject(TEST_DIR);
+    db.run(
+      "INSERT INTO tasks (id, ref, title, status) VALUES ('t1', 'TEST-T1', 'Pending task', 'PENDING')",
+    );
+    db.close();
+
+    const scriptPath = join(import.meta.dir, "..", "index.ts");
+    const proc = Bun.spawn([BUN_PATH, scriptPath], {
+      stdin: "pipe",
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+
+    proc.stdin.write(JSON.stringify({ cwd: TEST_DIR }));
+    proc.stdin.end();
+
+    await proc.exited;
+    const output = await new Response(proc.stdout).text();
+
+    expect(output.trim()).toBe("");
+  });
+});

package/src/status-line/index.ts

@@ -0,0 +1,147 @@
+#!/usr/bin/env bun
+
+/**
+ * Flux Status Line Script
+ *
+ * This script is designed to be used with Claude Code's status line feature.
+ * It reads JSON context from stdin and outputs a single status line.
+ *
+ * Expected input format (JSON):
+ * { "cwd": "/path/to/project", ... }
+ *
+ * Output format:
+ * [Opus] | ⟳ FP-T7: Implement tree view
+ */
+
+import { Database } from "bun:sqlite";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+interface StdinContext {
+  cwd?: string;
+  workspace?: {
+    current_dir?: string;
+    project_dir?: string;
+  };
+  model?:
+    | {
+        display_name?: string;
+      }
+    | string;
+}
+
+interface TaskRow {
+  ref: string;
+  title: string;
+  status: string;
+}
+
+const STATUS_ICONS: Record<string, string> = {
+  COMPLETED: "✓",
+  IN_PROGRESS: "⟳",
+  PENDING: "○",
+  DRAFT: "◇",
+  APPROVED: "●",
+};
+
+function findFluxRoot(startDir: string): string | null {
+  let dir = startDir;
+  const root = "/";
+
+  while (dir !== root) {
+    if (existsSync(join(dir, ".flux", "project.json"))) {
+      return dir;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+
+  return null;
+}
+
+function getStatusLine(cwd: string, model?: string): string {
+  const projectRoot = findFluxRoot(cwd);
+  if (!projectRoot) {
+    return "";
+  }
+
+  const fluxDir = join(projectRoot, ".flux");
+  const projectJsonPath = join(fluxDir, "project.json");
+  const dbPath = join(fluxDir, "flux.db");
+
+  if (!existsSync(projectJsonPath) || !existsSync(dbPath)) {
+    return "";
+  }
+
+  try {
+    readFileSync(projectJsonPath, "utf-8");
+  } catch {
+    return "";
+  }
+
+  let db: Database;
+  try {
+    db = new Database(dbPath, { readonly: true });
+  } catch {
+    return "";
+  }
+
+  try {
+    const activeTask = db
+      .query<TaskRow, []>(
+        "SELECT ref, title, status FROM tasks WHERE status = 'IN_PROGRESS' LIMIT 1",
+      )
+      .get();
+
+    if (!activeTask) {
+      return "";
+    }
+
+    const parts: string[] = [];
+
+    if (model) {
+      parts.push(`[${model}]`);
+    }
+
+    const icon = STATUS_ICONS[activeTask.status] || "?";
+    const maxTitleLen = 30;
+    const title =
+      activeTask.title.length > maxTitleLen
+        ? `${activeTask.title.slice(0, maxTitleLen - 1)}…`
+        : activeTask.title;
+    parts.push(`${icon} ${activeTask.ref}: ${title}`);
+
+    return parts.join(" | ");
+  } finally {
+    db.close();
+  }
+}
+
+async function main() {
+  let context: StdinContext = {};
+
+  try {
+    const stdin = await Bun.stdin.text();
+    if (stdin.trim()) {
+      context = JSON.parse(stdin);
+    }
+  } catch {}
+
+  const cwd =
+    context.workspace?.current_dir ||
+    context.workspace?.project_dir ||
+    context.cwd ||
+    process.cwd();
+  const model =
+    typeof context.model === "object"
+      ? context.model?.display_name
+      : context.model;
+  const statusLine = getStatusLine(cwd, model);
+
+  if (statusLine) {
+    console.log(statusLine);
+  }
+}
+
+main().catch(() => {});

package/src/utils/__tests__/chalk-import.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, test } from "bun:test";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+describe("chalk dependency", () => {
+  test("chalk is listed in package.json dependencies", () => {
+    const packageJsonPath = join(process.cwd(), "package.json");
+    expect(existsSync(packageJsonPath)).toBe(true);
+
+    const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf-8"));
+    expect(packageJson.dependencies).toBeDefined();
+    expect(packageJson.dependencies.chalk).toBeDefined();
+    expect(typeof packageJson.dependencies.chalk).toBe("string");
+  });
+
+  test("chalk imports work in TypeScript", async () => {
+    // Dynamic import to verify chalk is available
+    const chalk = await import("chalk");
+
+    // Verify chalk has expected API
+    expect(chalk.default).toBeDefined();
+    expect(typeof chalk.default.red).toBe("function");
+    expect(typeof chalk.default.green).toBe("function");
+    expect(typeof chalk.default.blue).toBe("function");
+    expect(typeof chalk.default.yellow).toBe("function");
+
+    // Verify chalk can actually format text
+    const redText = chalk.default.red("test");
+    expect(typeof redText).toBe("string");
+    expect(redText).toContain("test");
+  });
+});

package/src/utils/__tests__/display.test.ts

@@ -0,0 +1,97 @@
+import { describe, expect, test } from "bun:test";
+import {
+  getStatusBadge,
+  getStatusIcon,
+  renderProgressBar,
+} from "../display.js";
+
+describe("renderProgressBar", () => {
+  test("returns empty bar for 0% progress", () => {
+    const result = renderProgressBar(0, 10);
+    expect(result).toBe("··········");
+  });
+
+  test("returns half-filled bar for 50% progress", () => {
+    const result = renderProgressBar(50, 10);
+    expect(result).toBe("━━━━━·····");
+  });
+
+  test("returns full bar for 100% progress", () => {
+    const result = renderProgressBar(100, 10);
+    expect(result).toBe("━━━━━━━━━━");
+  });
+
+  test("handles 33% progress correctly (rounds down)", () => {
+    const result = renderProgressBar(33, 10);
+    expect(result).toBe("━━━·······");
+  });
+
+  test("handles different widths", () => {
+    expect(renderProgressBar(0, 5)).toBe("·····");
+    expect(renderProgressBar(50, 5)).toBe("━━···");
+    expect(renderProgressBar(100, 5)).toBe("━━━━━");
+  });
+
+  test("handles edge case percentages", () => {
+    expect(renderProgressBar(1, 10)).toBe("··········");
+    expect(renderProgressBar(99, 10)).toBe("━━━━━━━━━·");
+  });
+});
+
+describe("getStatusIcon", () => {
+  test("returns checkmark for COMPLETED status", () => {
+    expect(getStatusIcon("COMPLETED")).toBe("✓");
+  });
+
+  test("returns spinner for IN_PROGRESS status", () => {
+    expect(getStatusIcon("IN_PROGRESS")).toBe("⟳");
+  });
+
+  test("returns circle for PENDING status", () => {
+    expect(getStatusIcon("PENDING")).toBe("○");
+  });
+
+  test("returns diamond for DRAFT status", () => {
+    expect(getStatusIcon("DRAFT")).toBe("◇");
+  });
+
+  test("returns diamond for APPROVED status (PRD-specific)", () => {
+    expect(getStatusIcon("APPROVED")).toBe("●");
+  });
+
+  test("returns question mark for unknown status", () => {
+    expect(getStatusIcon("UNKNOWN")).toBe("?");
+  });
+});
+
+describe("getStatusBadge", () => {
+  test("returns green badge for COMPLETED status", () => {
+    const badge = getStatusBadge("COMPLETED");
+    expect(badge).toContain("COMPLETED");
+  });
+
+  test("returns yellow badge for IN_PROGRESS status", () => {
+    const badge = getStatusBadge("IN_PROGRESS");
+    expect(badge).toContain("IN_PROGRESS");
+  });
+
+  test("returns gray badge for PENDING status", () => {
+    const badge = getStatusBadge("PENDING");
+    expect(badge).toContain("PENDING");
+  });
+
+  test("returns blue badge for DRAFT status", () => {
+    const badge = getStatusBadge("DRAFT");
+    expect(badge).toContain("DRAFT");
+  });
+
+  test("returns cyan badge for APPROVED status", () => {
+    const badge = getStatusBadge("APPROVED");
+    expect(badge).toContain("APPROVED");
+  });
+
+  test("returns plain badge for unknown status", () => {
+    const badge = getStatusBadge("UNKNOWN");
+    expect(badge).toContain("UNKNOWN");
+  });
+});