@cliangdev/flux-plugin 0.0.0-dev.cbdf207 → 0.0.0-dev.df3e9bb

package/src/server/db/refs.ts

@@ -0,0 +1,60 @@
+import type { Database } from "./sqlite.js";
+
+/**
+ * Generate a project prefix from project name.
+ * Uses acronym for multi-word names, or truncated uppercase for single words.
+ *
+ * @example
+ * generatePrefix("my-saas-app") // -> "MSA"
+ * generatePrefix("flux")        // -> "FLUX"
+ * generatePrefix("my app")      // -> "MA"
+ */
+export function generatePrefix(projectName: string): string {
+  const words = projectName
+    .replace(/[^a-zA-Z0-9]/g, " ")
+    .split(/\s+/)
+    .filter((w) => w.length > 0);
+
+  if (words.length >= 2) {
+    return words
+      .map((w) => w[0])
+      .join("")
+      .toUpperCase()
+      .slice(0, 10);
+  }
+  return projectName
+    .replace(/[^a-zA-Z0-9]/g, "")
+    .toUpperCase()
+    .slice(0, 10);
+}
+
+/**
+ * Generate a sequential reference for an entity.
+ * Refs follow pattern: PREFIX-TYPE{NUMBER}
+ *
+ * @param db - Database instance
+ * @param type - Entity type: "P" (PRD), "E" (Epic), "T" (Task)
+ * @param prefix - Project prefix
+ * @returns Sequential ref like "MSA-P1", "MSA-E1", "MSA-T1"
+ */
+export function generateRef(
+  db: Database,
+  type: "P" | "E" | "T",
+  prefix: string,
+): string {
+  const table = type === "P" ? "prds" : type === "E" ? "epics" : "tasks";
+  const pattern = `${prefix}-${type}%`;
+  const result = db
+    .query(
+      `SELECT ref FROM ${table} WHERE ref LIKE ? ORDER BY CAST(SUBSTR(ref, LENGTH(?) + 1) AS INTEGER) DESC LIMIT 1`,
+    )
+    .get(pattern, `${prefix}-${type}`) as { ref: string } | null;
+
+  if (!result) {
+    return `${prefix}-${type}1`;
+  }
+
+  const match = result.ref.match(new RegExp(`${prefix}-${type}(\\d+)$`));
+  const maxNum = match ? parseInt(match[1], 10) : 0;
+  return `${prefix}-${type}${maxNum + 1}`;
+}

package/src/server/db/schema.ts

@@ -0,0 +1,88 @@
+export const SCHEMA = `
+-- Projects table (for multi-project support later)
+CREATE TABLE IF NOT EXISTS projects (
+  id TEXT PRIMARY KEY,
+  name TEXT NOT NULL,
+  ref_prefix TEXT NOT NULL,
+  created_at DATETIME DEFAULT CURRENT_TIMESTAMP
+);
+
+-- PRDs
+CREATE TABLE IF NOT EXISTS prds (
+  id TEXT PRIMARY KEY,
+  project_id TEXT NOT NULL,
+  ref TEXT UNIQUE NOT NULL,
+  title TEXT NOT NULL,
+  description TEXT,
+  status TEXT DEFAULT 'DRAFT',
+  tag TEXT,
+  folder_path TEXT,
+  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+  FOREIGN KEY (project_id) REFERENCES projects(id)
+);
+
+-- Epics
+CREATE TABLE IF NOT EXISTS epics (
+  id TEXT PRIMARY KEY,
+  prd_id TEXT NOT NULL,
+  ref TEXT UNIQUE NOT NULL,
+  title TEXT NOT NULL,
+  description TEXT,
+  status TEXT DEFAULT 'PENDING',
+  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+  FOREIGN KEY (prd_id) REFERENCES prds(id)
+);
+
+-- Tasks
+CREATE TABLE IF NOT EXISTS tasks (
+  id TEXT PRIMARY KEY,
+  epic_id TEXT NOT NULL,
+  ref TEXT UNIQUE NOT NULL,
+  title TEXT NOT NULL,
+  description TEXT,
+  status TEXT DEFAULT 'PENDING',
+  priority TEXT DEFAULT 'MEDIUM',
+  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+  FOREIGN KEY (epic_id) REFERENCES epics(id)
+);
+
+-- Acceptance Criteria (for both epics and tasks)
+CREATE TABLE IF NOT EXISTS acceptance_criteria (
+  id TEXT PRIMARY KEY,
+  parent_type TEXT NOT NULL,
+  parent_id TEXT NOT NULL,
+  criteria TEXT NOT NULL,
+  is_met BOOLEAN DEFAULT FALSE,
+  created_at DATETIME DEFAULT CURRENT_TIMESTAMP
+);
+
+-- Epic Dependencies
+CREATE TABLE IF NOT EXISTS epic_dependencies (
+  epic_id TEXT NOT NULL,
+  depends_on_epic_id TEXT NOT NULL,
+  PRIMARY KEY (epic_id, depends_on_epic_id),
+  FOREIGN KEY (epic_id) REFERENCES epics(id),
+  FOREIGN KEY (depends_on_epic_id) REFERENCES epics(id)
+);
+
+-- Task Dependencies
+CREATE TABLE IF NOT EXISTS task_dependencies (
+  task_id TEXT NOT NULL,
+  depends_on_task_id TEXT NOT NULL,
+  PRIMARY KEY (task_id, depends_on_task_id),
+  FOREIGN KEY (task_id) REFERENCES tasks(id),
+  FOREIGN KEY (depends_on_task_id) REFERENCES tasks(id)
+);
+
+-- Indexes for common queries
+CREATE INDEX IF NOT EXISTS idx_prds_project ON prds(project_id);
+CREATE INDEX IF NOT EXISTS idx_prds_status ON prds(status);
+CREATE INDEX IF NOT EXISTS idx_epics_prd ON epics(prd_id);
+CREATE INDEX IF NOT EXISTS idx_epics_status ON epics(status);
+CREATE INDEX IF NOT EXISTS idx_tasks_epic ON tasks(epic_id);
+CREATE INDEX IF NOT EXISTS idx_tasks_status ON tasks(status);
+CREATE INDEX IF NOT EXISTS idx_criteria_parent ON acceptance_criteria(parent_type, parent_id);
+`;

package/src/server/db/sqlite.ts

@@ -0,0 +1,10 @@
+/**
+ * SQLite adapter using bun:sqlite.
+ * This plugin requires Bun runtime.
+ */
+
+import type { SQLQueryBindings } from "bun:sqlite";
+import { Database } from "bun:sqlite";
+
+export { Database };
+export type { SQLQueryBindings };

package/src/server/index.ts

@@ -0,0 +1,83 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { config } from "./config.js";
+import { fluxProjectExists, initDb } from "./db/index.js";
+import {
+  addCriteriaTool,
+  addDependencyTool,
+  configureLinearTool,
+  createEpicTool,
+  createPrdTool,
+  createTaskTool,
+  deleteEntityTool,
+  getEntityTool,
+  getProjectContextTool,
+  getStatsTool,
+  getVersionTool,
+  initProjectTool,
+  markCriteriaMetTool,
+  queryEntitiesTool,
+  registerTools,
+  removeDependencyTool,
+  renderStatusTool,
+  type ToolDefinition,
+  updateEntityTool,
+  updateStatusTool,
+} from "./tools/index.js";
+import { logger } from "./utils/logger.js";
+
+const server = new Server(
+  { name: "flux", version: "0.1.0" },
+  { capabilities: { tools: {} } },
+);
+
+// All tools
+const tools: ToolDefinition[] = [
+  // CRUD tools
+  createPrdTool,
+  createEpicTool,
+  createTaskTool,
+  updateEntityTool,
+  deleteEntityTool,
+  addDependencyTool,
+  removeDependencyTool,
+  addCriteriaTool,
+  markCriteriaMetTool,
+  updateStatusTool,
+  // Query tools
+  getEntityTool,
+  queryEntitiesTool,
+  getProjectContextTool,
+  initProjectTool,
+  getStatsTool,
+  getVersionTool,
+  // Configuration tools
+  configureLinearTool,
+  // Display tools
+  renderStatusTool,
+];
+
+registerTools(server, tools);
+
+async function main() {
+  logger.info("Flux MCP server starting...");
+  logger.info(`  Project root: ${config.projectRoot}`);
+  logger.info(`  Flux path: ${config.fluxPath}`);
+
+  // Initialize database if flux project exists
+  if (fluxProjectExists()) {
+    logger.info("Flux project found, initializing database...");
+    initDb();
+  } else {
+    logger.info("No flux project found. Use init_project to create one.");
+  }
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  logger.info("Flux MCP server running");
+}
+
+main().catch((err) => {
+  logger.error("Server failed to start", err);
+  process.exit(1);
+});

package/src/server/tools/__tests__/crud.test.ts

@@ -0,0 +1,301 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+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 FLUX_DIR = join(TEST_DIR, ".flux");
+process.env.FLUX_PROJECT_ROOT = TEST_DIR;
+
+// Now import modules
+import { clearAdapterCache } from "../../adapters/index.js";
+import { config } from "../../config.js";
+import { closeDb, initDb } from "../../db/index.js";
+import { createEpicTool } from "../create-epic.js";
+import { createPrdTool } from "../create-prd.js";
+import { createTaskTool } from "../create-task.js";
+import { addCriteriaTool, markCriteriaMetTool } from "../criteria.js";
+import { deleteEntityTool } from "../delete-entity.js";
+import { addDependencyTool, removeDependencyTool } from "../dependencies.js";
+import { updateEntityTool } from "../update-entity.js";
+import { updateStatusTool } from "../update-status.js";
+
+describe("CRUD MCP Tools", () => {
+  beforeEach(() => {
+    config.clearCache();
+    clearAdapterCache();
+    process.env.FLUX_PROJECT_ROOT = TEST_DIR;
+
+    mkdirSync(FLUX_DIR, { recursive: true });
+    writeFileSync(
+      join(FLUX_DIR, "project.json"),
+      JSON.stringify({ name: "test-project", ref_prefix: "TEST" }),
+    );
+    initDb();
+  });
+
+  afterEach(() => {
+    closeDb();
+    clearAdapterCache();
+    config.clearCache();
+    if (existsSync(TEST_DIR)) {
+      rmSync(TEST_DIR, { recursive: true, force: true });
+    }
+  });
+
+  describe("create_prd", () => {
+    test("creates PRD with required fields", async () => {
+      const result = (await createPrdTool.handler({
+        title: "Test PRD",
+      })) as any;
+      expect(result).toBeDefined();
+      expect(result.title).toBe("Test PRD");
+      expect(result.ref).toBeDefined();
+      expect(result.status).toBe("DRAFT");
+      expect(result.id).toBeDefined();
+    });
+
+    test("creates PRD with optional fields", async () => {
+      const result = (await createPrdTool.handler({
+        title: "Test PRD",
+        description: "A description",
+        tag: "mvp",
+      })) as any;
+      expect(result.description).toBe("A description");
+      expect(result.tag).toBe("mvp");
+    });
+  });
+
+  describe("create_epic", () => {
+    test("creates epic linked to PRD", async () => {
+      const prd = (await createPrdTool.handler({ title: "Test PRD" })) as any;
+      const epic = (await createEpicTool.handler({
+        prd_ref: prd.ref,
+        title: "Test Epic",
+      })) as any;
+
+      expect(epic.title).toBe("Test Epic");
+      expect(epic.ref).toBeDefined();
+      expect(epic.status).toBe("PENDING");
+    });
+
+    test("creates epic with acceptance criteria", async () => {
+      const prd = (await createPrdTool.handler({ title: "Test PRD" })) as any;
+      const epic = (await createEpicTool.handler({
+        prd_ref: prd.ref,
+        title: "Test Epic",
+        acceptance_criteria: ["Criterion 1", "Criterion 2"],
+      })) as any;
+      expect(epic.criteria_count).toBe(2);
+    });
+
+    test("fails with invalid PRD ref", async () => {
+      await expect(
+        createEpicTool.handler({ prd_ref: "INVALID-P999", title: "Test" }),
+      ).rejects.toThrow("PRD not found");
+    });
+  });
+
+  describe("create_task", () => {
+    test("creates task linked to epic", async () => {
+      const prd = (await createPrdTool.handler({ title: "Test PRD" })) as any;
+      const epic = (await createEpicTool.handler({
+        prd_ref: prd.ref,
+        title: "Test Epic",
+      })) as any;
+      const task = (await createTaskTool.handler({
+        epic_ref: epic.ref,
+        title: "Test Task",
+      })) as any;
+
+      expect(task.title).toBe("Test Task");
+      expect(task.ref).toBeDefined();
+      expect(task.priority).toBe("MEDIUM");
+    });
+
+    test("creates task with priority", async () => {
+      const prd = (await createPrdTool.handler({ title: "Test PRD" })) as any;
+      const epic = (await createEpicTool.handler({
+        prd_ref: prd.ref,
+        title: "Test Epic",
+      })) as any;
+      const task = (await createTaskTool.handler({
+        epic_ref: epic.ref,
+        title: "Test Task",
+        priority: "HIGH",
+      })) as any;
+      expect(task.priority).toBe("HIGH");
+    });
+  });
+
+  describe("update_entity", () => {
+    test("updates PRD fields", async () => {
+      const prd = (await createPrdTool.handler({ title: "Original" })) as any;
+      const updated = (await updateEntityTool.handler({
+        ref: prd.ref,
+        fields: { title: "Updated", status: "APPROVED" },
+      })) as any;
+
+      expect(updated.title).toBe("Updated");
+      expect(updated.status).toBe("APPROVED");
+    });
+
+    test("updates epic status", async () => {
+      const prd = (await createPrdTool.handler({ title: "Test PRD" })) as any;
+      const epic = (await createEpicTool.handler({
+        prd_ref: prd.ref,
+        title: "Test Epic",
+      })) as any;
+      const updated = (await updateEntityTool.handler({
+        ref: epic.ref,
+        fields: { status: "IN_PROGRESS" },
+      })) as any;
+
+      expect(updated.status).toBe("IN_PROGRESS");
+    });
+  });
+
+  describe("delete_entity", () => {
+    test("deletes task", async () => {
+      const prd = (await createPrdTool.handler({ title: "Test PRD" })) as any;
+      const epic = (await createEpicTool.handler({
+        prd_ref: prd.ref,
+        title: "Test Epic",
+      })) as any;
+      const task = (await createTaskTool.handler({
+        epic_ref: epic.ref,
+        title: "Test Task",
+      })) as any;
+
+      const result = (await deleteEntityTool.handler({ ref: task.ref })) as any;
+      expect(result.deleted).toBe(task.ref);
+    });
+
+    test("cascade deletes epic with tasks", async () => {
+      const prd = (await createPrdTool.handler({ title: "Test PRD" })) as any;
+      const epic = (await createEpicTool.handler({
+        prd_ref: prd.ref,
+        title: "Test Epic",
+      })) as any;
+      await createTaskTool.handler({ epic_ref: epic.ref, title: "Task 1" });
+      await createTaskTool.handler({ epic_ref: epic.ref, title: "Task 2" });
+
+      const result = (await deleteEntityTool.handler({ ref: epic.ref })) as any;
+      expect(result.cascade.tasks).toBe(2);
+    });
+  });
+
+  describe("dependencies", () => {
+    test("adds and removes epic dependency", async () => {
+      const prd = (await createPrdTool.handler({ title: "Test PRD" })) as any;
+      const epic1 = (await createEpicTool.handler({
+        prd_ref: prd.ref,
+        title: "Epic 1",
+      })) as any;
+      const epic2 = (await createEpicTool.handler({
+        prd_ref: prd.ref,
+        title: "Epic 2",
+      })) as any;
+
+      const addResult = (await addDependencyTool.handler({
+        ref: epic2.ref,
+        depends_on_ref: epic1.ref,
+      })) as any;
+      expect(addResult.success).toBe(true);
+
+      const removeResult = (await removeDependencyTool.handler({
+        ref: epic2.ref,
+        depends_on_ref: epic1.ref,
+      })) as any;
+      expect(removeResult.success).toBe(true);
+    });
+
+    test("prevents self-dependency", async () => {
+      const prd = (await createPrdTool.handler({ title: "Test PRD" })) as any;
+      const epic = (await createEpicTool.handler({
+        prd_ref: prd.ref,
+        title: "Epic",
+      })) as any;
+
+      await expect(
+        addDependencyTool.handler({ ref: epic.ref, depends_on_ref: epic.ref }),
+      ).rejects.toThrow("depend on itself");
+    });
+  });
+
+  describe("criteria", () => {
+    test("adds and marks criterion", async () => {
+      const prd = (await createPrdTool.handler({ title: "Test PRD" })) as any;
+      const epic = (await createEpicTool.handler({
+        prd_ref: prd.ref,
+        title: "Test Epic",
+      })) as any;
+
+      const criterion = (await addCriteriaTool.handler({
+        parent_ref: epic.ref,
+        criteria: "Test criterion",
+      })) as any;
+      expect(criterion.criteria).toBe("Test criterion");
+      expect(criterion.is_met).toBe(false);
+
+      const updated = (await markCriteriaMetTool.handler({
+        criteria_id: criterion.id,
+      })) as any;
+      expect(updated.is_met).toBe(true);
+    });
+  });
+
+  describe("update_status", () => {
+    test("updates PRD status with valid transition", async () => {
+      const prd = (await createPrdTool.handler({ title: "Test PRD" })) as any;
+      // DRAFT → PENDING_REVIEW is a valid transition
+      const updated = (await updateStatusTool.handler({
+        ref: prd.ref,
+        status: "PENDING_REVIEW",
+      })) as any;
+      expect(updated.status).toBe("PENDING_REVIEW");
+      expect(updated.available_transitions).toContain("REVIEWED");
+    });
+
+    test("rejects invalid status for entity type", async () => {
+      const prd = (await createPrdTool.handler({ title: "Test PRD" })) as any;
+      await expect(
+        updateStatusTool.handler({ ref: prd.ref, status: "IN_PROGRESS" }),
+      ).rejects.toThrow("Invalid status");
+    });
+
+    test("rejects invalid status transition", async () => {
+      const prd = (await createPrdTool.handler({ title: "Test PRD" })) as any;
+      // DRAFT → APPROVED is not a valid transition (must go through PENDING_REVIEW first)
+      await expect(
+        updateStatusTool.handler({ ref: prd.ref, status: "APPROVED" }),
+      ).rejects.toThrow("Invalid transition");
+    });
+
+    test("updates task status with valid transitions", async () => {
+      const prd = (await createPrdTool.handler({ title: "Test PRD" })) as any;
+      const epic = (await createEpicTool.handler({
+        prd_ref: prd.ref,
+        title: "Test Epic",
+      })) as any;
+      const task = (await createTaskTool.handler({
+        epic_ref: epic.ref,
+        title: "Test Task",
+      })) as any;
+
+      // PENDING → IN_PROGRESS is valid
+      const inProgress = (await updateStatusTool.handler({
+        ref: task.ref,
+        status: "IN_PROGRESS",
+      })) as any;
+      expect(inProgress.status).toBe("IN_PROGRESS");
+
+      // IN_PROGRESS → COMPLETED is valid
+      const completed = (await updateStatusTool.handler({
+        ref: task.ref,
+        status: "COMPLETED",
+      })) as any;
+      expect(completed.status).toBe("COMPLETED");
+    });
+  });
+});

package/src/server/tools/__tests__/get-version.test.ts

@@ -0,0 +1,27 @@
+import { describe, expect, test } from "bun:test";
+import { VERSION } from "../../../version.js";
+import { getVersionTool } from "../get-version.js";
+
+describe("get_version", () => {
+  test("returns version and name", async () => {
+    const result = (await getVersionTool.handler({})) as any;
+
+    expect(result.version).toBe(VERSION);
+    expect(result.name).toBe("flux-plugin");
+  });
+
+  test("requires no input parameters", async () => {
+    // Should work with empty object
+    const result = (await getVersionTool.handler({})) as any;
+    expect(result).toBeDefined();
+    expect(result.version).toBeDefined();
+    expect(result.name).toBeDefined();
+  });
+
+  test("has correct tool definition", () => {
+    expect(getVersionTool.name).toBe("get_version");
+    expect(getVersionTool.description).toContain("version");
+    expect(getVersionTool.inputSchema).toBeDefined();
+    expect(getVersionTool.handler).toBeDefined();
+  });
+});