@cliangdev/flux-plugin 0.2.0 → 0.3.0

package/src/server/db/__tests__/queries.test.ts

@@ -0,0 +1,473 @@
+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-db-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+const FLUX_DIR = join(TEST_DIR, ".flux");
+process.env.FLUX_PROJECT_ROOT = TEST_DIR;
+
+// Now import modules
+import { config } from "../../config.js";
+import {
+  closeDb,
+  count,
+  findAll,
+  findById,
+  findByRef,
+  generateId,
+  generateRef,
+  getDb,
+  initDb,
+  insert,
+  remove,
+  update,
+} from "../index.js";
+
+describe("Database Queries", () => {
+  let projectId: string;
+
+  beforeEach(() => {
+    closeDb();
+    config.clearCache();
+    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();
+
+    // Create a project for foreign key constraints
+    projectId = generateId("proj");
+    const db = getDb();
+    insert(db, "projects", {
+      id: projectId,
+      name: "test-project",
+      ref_prefix: "TEST",
+    });
+  });
+
+  afterEach(() => {
+    closeDb();
+    config.clearCache();
+    if (existsSync(TEST_DIR)) {
+      rmSync(TEST_DIR, { recursive: true, force: true });
+    }
+  });
+
+  describe("generateId", () => {
+    test("generates unique IDs with prefix", () => {
+      const id1 = generateId("test");
+      const id2 = generateId("test");
+
+      expect(id1).toMatch(/^test_/);
+      expect(id2).toMatch(/^test_/);
+      expect(id1).not.toBe(id2);
+    });
+
+    test("generates IDs with different prefixes", () => {
+      const prdId = generateId("prd");
+      const epicId = generateId("epic");
+      const taskId = generateId("task");
+
+      expect(prdId).toMatch(/^prd_/);
+      expect(epicId).toMatch(/^epic_/);
+      expect(taskId).toMatch(/^task_/);
+    });
+  });
+
+  describe("insert and findById", () => {
+    test("inserts and retrieves record", () => {
+      const db = getDb();
+      const id = generateId("prd");
+
+      insert(db, "prds", {
+        id,
+        project_id: projectId,
+        ref: "TEST-P1",
+        title: "Test PRD",
+        status: "DRAFT",
+      });
+
+      const result = findById<{ id: string; title: string }>(db, "prds", id);
+      expect(result).toBeDefined();
+      expect(result?.id).toBe(id);
+      expect(result?.title).toBe("Test PRD");
+    });
+
+    test("findById returns null for non-existent record", () => {
+      const db = getDb();
+      const result = findById(db, "prds", "nonexistent_id");
+      expect(result).toBeNull();
+    });
+  });
+
+  describe("findByRef", () => {
+    test("finds record by ref", () => {
+      const db = getDb();
+      const id = generateId("prd");
+
+      insert(db, "prds", {
+        id,
+        project_id: projectId,
+        ref: "TEST-P99",
+        title: "Test PRD",
+        status: "DRAFT",
+      });
+
+      const result = findByRef<{ ref: string; title: string }>(
+        db,
+        "prds",
+        "TEST-P99",
+      );
+      expect(result).toBeDefined();
+      expect(result?.ref).toBe("TEST-P99");
+    });
+
+    test("findByRef returns null for non-existent ref", () => {
+      const db = getDb();
+      const result = findByRef(db, "prds", "NONEXISTENT-P999");
+      expect(result).toBeNull();
+    });
+  });
+
+  describe("findAll", () => {
+    test("finds all records without filter", () => {
+      const db = getDb();
+
+      insert(db, "prds", {
+        id: generateId("prd"),
+        project_id: projectId,
+        ref: "TEST-P1",
+        title: "PRD 1",
+        status: "DRAFT",
+      });
+      insert(db, "prds", {
+        id: generateId("prd"),
+        project_id: projectId,
+        ref: "TEST-P2",
+        title: "PRD 2",
+        status: "APPROVED",
+      });
+
+      const results = findAll<{ title: string }>(db, "prds");
+      expect(results.length).toBe(2);
+    });
+
+    test("finds records with where filter", () => {
+      const db = getDb();
+
+      insert(db, "prds", {
+        id: generateId("prd"),
+        project_id: projectId,
+        ref: "TEST-P1",
+        title: "PRD 1",
+        status: "DRAFT",
+      });
+      insert(db, "prds", {
+        id: generateId("prd"),
+        project_id: projectId,
+        ref: "TEST-P2",
+        title: "PRD 2",
+        status: "APPROVED",
+      });
+
+      const results = findAll<{ status: string }>(db, "prds", {
+        status: "DRAFT",
+      });
+      expect(results.length).toBe(1);
+      expect(results[0].status).toBe("DRAFT");
+    });
+
+    test("supports pagination with limit", () => {
+      const db = getDb();
+
+      for (let i = 1; i <= 5; i++) {
+        insert(db, "prds", {
+          id: generateId("prd"),
+          project_id: projectId,
+          ref: `TEST-P${i}`,
+          title: `PRD ${i}`,
+          status: "DRAFT",
+        });
+      }
+
+      const results = findAll<{ title: string }>(db, "prds", { limit: 3 });
+      expect(results.length).toBe(3);
+    });
+
+    test("supports pagination with limit and offset", () => {
+      const db = getDb();
+
+      for (let i = 1; i <= 5; i++) {
+        insert(db, "prds", {
+          id: generateId("prd"),
+          project_id: projectId,
+          ref: `TEST-P${i}`,
+          title: `PRD ${i}`,
+          status: "DRAFT",
+        });
+      }
+
+      const page1 = findAll<{ title: string }>(db, "prds", {
+        limit: 2,
+        offset: 0,
+      });
+      expect(page1.length).toBe(2);
+
+      const page2 = findAll<{ title: string }>(db, "prds", {
+        limit: 2,
+        offset: 2,
+      });
+      expect(page2.length).toBe(2);
+
+      const page3 = findAll<{ title: string }>(db, "prds", {
+        limit: 2,
+        offset: 4,
+      });
+      expect(page3.length).toBe(1);
+    });
+
+    test("supports where filter with pagination", () => {
+      const db = getDb();
+
+      for (let i = 1; i <= 3; i++) {
+        insert(db, "prds", {
+          id: generateId("prd"),
+          project_id: projectId,
+          ref: `TEST-P${i}`,
+          title: `Draft PRD ${i}`,
+          status: "DRAFT",
+        });
+      }
+      for (let i = 4; i <= 5; i++) {
+        insert(db, "prds", {
+          id: generateId("prd"),
+          project_id: projectId,
+          ref: `TEST-P${i}`,
+          title: `Approved PRD ${i}`,
+          status: "APPROVED",
+        });
+      }
+
+      const results = findAll<{ status: string }>(db, "prds", {
+        where: { status: "DRAFT" },
+        limit: 2,
+      });
+      expect(results.length).toBe(2);
+      expect(results.every((r) => r.status === "DRAFT")).toBe(true);
+    });
+  });
+
+  describe("update", () => {
+    test("updates record fields", () => {
+      const db = getDb();
+      const id = generateId("prd");
+
+      insert(db, "prds", {
+        id,
+        project_id: projectId,
+        ref: "TEST-P1",
+        title: "Original Title",
+        status: "DRAFT",
+      });
+
+      update(db, "prds", id, { title: "Updated Title", status: "APPROVED" });
+
+      const result = findById<{ title: string; status: string }>(
+        db,
+        "prds",
+        id,
+      );
+      expect(result?.title).toBe("Updated Title");
+      expect(result?.status).toBe("APPROVED");
+    });
+
+    test("update sets updated_at timestamp", () => {
+      const db = getDb();
+      const id = generateId("prd");
+
+      insert(db, "prds", {
+        id,
+        project_id: projectId,
+        ref: "TEST-P1",
+        title: "Test",
+        status: "DRAFT",
+      });
+
+      const before = findById<{ updated_at: string }>(db, "prds", id);
+      const _beforeTime = before?.updated_at;
+
+      // Small delay to ensure timestamp changes
+      update(db, "prds", id, { title: "Updated" });
+
+      const after = findById<{ updated_at: string }>(db, "prds", id);
+      expect(after?.updated_at).toBeDefined();
+      // updated_at should be set (may or may not be different from before due to speed)
+    });
+  });
+
+  describe("remove", () => {
+    test("deletes record by id", () => {
+      const db = getDb();
+      const id = generateId("prd");
+
+      insert(db, "prds", {
+        id,
+        project_id: projectId,
+        ref: "TEST-P1",
+        title: "Test PRD",
+        status: "DRAFT",
+      });
+
+      expect(findById(db, "prds", id)).toBeDefined();
+
+      remove(db, "prds", id);
+
+      expect(findById(db, "prds", id)).toBeNull();
+    });
+  });
+
+  describe("count", () => {
+    test("counts all records without filter", () => {
+      const db = getDb();
+
+      insert(db, "prds", {
+        id: generateId("prd"),
+        project_id: projectId,
+        ref: "TEST-P1",
+        title: "PRD 1",
+        status: "DRAFT",
+      });
+      insert(db, "prds", {
+        id: generateId("prd"),
+        project_id: projectId,
+        ref: "TEST-P2",
+        title: "PRD 2",
+        status: "APPROVED",
+      });
+
+      expect(count(db, "prds")).toBe(2);
+    });
+
+    test("counts records with filter", () => {
+      const db = getDb();
+
+      insert(db, "prds", {
+        id: generateId("prd"),
+        project_id: projectId,
+        ref: "TEST-P1",
+        title: "PRD 1",
+        status: "DRAFT",
+      });
+      insert(db, "prds", {
+        id: generateId("prd"),
+        project_id: projectId,
+        ref: "TEST-P2",
+        title: "PRD 2",
+        status: "APPROVED",
+      });
+
+      expect(count(db, "prds", { status: "DRAFT" })).toBe(1);
+      expect(count(db, "prds", { status: "APPROVED" })).toBe(1);
+      expect(count(db, "prds", { status: "COMPLETED" })).toBe(0);
+    });
+  });
+
+  describe("generateRef", () => {
+    test("generates sequential refs starting from 1", () => {
+      const db = getDb();
+      const ref = generateRef(db, "P", "TEST");
+      expect(ref).toBe("TEST-P1");
+    });
+
+    test("generates next sequential ref based on existing records", () => {
+      const db = getDb();
+
+      insert(db, "prds", {
+        id: generateId("prd"),
+        project_id: projectId,
+        ref: "TEST-P1",
+        title: "PRD 1",
+        status: "DRAFT",
+      });
+
+      const ref = generateRef(db, "P", "TEST");
+      expect(ref).toBe("TEST-P2");
+    });
+
+    test("handles gaps in ref sequence by using max ref number", () => {
+      const db = getDb();
+
+      const prdId = generateId("prd");
+      insert(db, "prds", {
+        id: prdId,
+        project_id: projectId,
+        ref: "TEST-P1",
+        title: "PRD",
+        status: "DRAFT",
+      });
+      const epicId = generateId("epic");
+      insert(db, "epics", {
+        id: epicId,
+        prd_id: prdId,
+        ref: "TEST-E1",
+        title: "Epic",
+        status: "PENDING",
+      });
+
+      insert(db, "tasks", {
+        id: generateId("task"),
+        epic_id: epicId,
+        ref: "TEST-T1",
+        title: "Task 1",
+        status: "PENDING",
+        priority: "MEDIUM",
+      });
+      insert(db, "tasks", {
+        id: generateId("task"),
+        epic_id: epicId,
+        ref: "TEST-T5",
+        title: "Task 5",
+        status: "PENDING",
+        priority: "MEDIUM",
+      });
+      insert(db, "tasks", {
+        id: generateId("task"),
+        epic_id: epicId,
+        ref: "TEST-T10",
+        title: "Task 10",
+        status: "PENDING",
+        priority: "MEDIUM",
+      });
+
+      const ref = generateRef(db, "T", "TEST");
+      expect(ref).toBe("TEST-T11");
+    });
+
+    test("handles different prefixes independently", () => {
+      const db = getDb();
+
+      insert(db, "prds", {
+        id: generateId("prd"),
+        project_id: projectId,
+        ref: "ABC-P5",
+        title: "PRD",
+        status: "DRAFT",
+      });
+      insert(db, "prds", {
+        id: generateId("prd"),
+        project_id: projectId,
+        ref: "XYZ-P10",
+        title: "PRD",
+        status: "DRAFT",
+      });
+
+      expect(generateRef(db, "P", "ABC")).toBe("ABC-P6");
+      expect(generateRef(db, "P", "XYZ")).toBe("XYZ-P11");
+      expect(generateRef(db, "P", "NEW")).toBe("NEW-P1");
+    });
+  });
+});

package/src/server/db/ids.ts

@@ -0,0 +1,17 @@
+/**
+ * Generate a unique ID with optional type prefix.
+ * IDs are sortable by creation time and include randomness for uniqueness.
+ *
+ * @param prefix - Optional type prefix (e.g., "prd", "epic", "task")
+ * @returns Unique ID string
+ *
+ * @example
+ * generateId("prd")  // -> "prd_m1abc123xyz"
+ * generateId("epic") // -> "epic_m1abc456def"
+ * generateId("task") // -> "task_m1abc789ghi"
+ */
+export function generateId(prefix: string = ""): string {
+  const timestamp = Date.now().toString(36);
+  const random = Math.random().toString(36).substring(2, 10);
+  return prefix ? `${prefix}_${timestamp}${random}` : `${timestamp}${random}`;
+}

package/src/server/db/index.ts

@@ -0,0 +1,69 @@
+import { existsSync, mkdirSync } from "node:fs";
+import { config } from "../config.js";
+import { logger } from "../utils/logger.js";
+import { SCHEMA } from "./schema.js";
+import { Database } from "./sqlite.js";
+
+let db: Database | null = null;
+
+/**
+ * Initialize the database, creating the .flux directory and schema if needed.
+ * Returns a singleton database instance.
+ */
+export function initDb(): Database {
+  if (db) {
+    return db;
+  }
+
+  // Create .flux directory if it doesn't exist
+  if (!existsSync(config.fluxPath)) {
+    logger.info(`Creating flux directory: ${config.fluxPath}`);
+    mkdirSync(config.fluxPath, { recursive: true });
+  }
+
+  // Open or create database
+  logger.info(`Opening database: ${config.dbPath}`);
+  db = new Database(config.dbPath);
+
+  // Enable foreign keys
+  db.run("PRAGMA foreign_keys = ON");
+
+  // Initialize schema
+  db.exec(SCHEMA);
+
+  logger.info("Database initialized successfully");
+  return db;
+}
+
+/**
+ * Get the database instance. Throws if not initialized.
+ */
+export function getDb(): Database {
+  if (!db) {
+    throw new Error("Database not initialized. Call initDb() first.");
+  }
+  return db;
+}
+
+/**
+ * Close the database connection.
+ */
+export function closeDb(): void {
+  if (db) {
+    db.close();
+    db = null;
+    logger.info("Database connection closed");
+  }
+}
+
+/**
+ * Check if a Flux project exists in the current directory.
+ */
+export function fluxProjectExists(): boolean {
+  return existsSync(config.fluxPath) && existsSync(config.dbPath);
+}
+
+// Re-export utilities for convenience
+export { generateId } from "./ids.js";
+export * from "./queries.js";
+export { generatePrefix, generateRef } from "./refs.js";

package/src/server/db/queries.ts

@@ -0,0 +1,142 @@
+import type { Database, SQLQueryBindings } from "./sqlite.js";
+
+/**
+ * Find a record by its ref field.
+ */
+export function findByRef<T>(
+  db: Database,
+  table: string,
+  ref: string,
+): T | null {
+  return db.query(`SELECT * FROM ${table} WHERE ref = ?`).get(ref) as T | null;
+}
+
+/**
+ * Find a record by its id field.
+ */
+export function findById<T>(db: Database, table: string, id: string): T | null {
+  return db.query(`SELECT * FROM ${table} WHERE id = ?`).get(id) as T | null;
+}
+
+interface FindAllOptions {
+  where?: Record<string, unknown>;
+  limit?: number;
+  offset?: number;
+}
+
+/**
+ * Find all records in a table, optionally filtered with pagination.
+ */
+export function findAll<T>(
+  db: Database,
+  table: string,
+  whereOrOptions?: Record<string, unknown> | FindAllOptions,
+): T[] {
+  // Handle both old signature (where object) and new signature (options object)
+  let where: Record<string, unknown> | undefined;
+  let limit: number | undefined;
+  let offset: number | undefined;
+
+  if (whereOrOptions) {
+    if (
+      "where" in whereOrOptions ||
+      "limit" in whereOrOptions ||
+      "offset" in whereOrOptions
+    ) {
+      const opts = whereOrOptions as FindAllOptions;
+      where = opts.where;
+      limit = opts.limit;
+      offset = opts.offset;
+    } else {
+      where = whereOrOptions as Record<string, unknown>;
+    }
+  }
+
+  let sql = `SELECT * FROM ${table}`;
+  const values: SQLQueryBindings[] = [];
+
+  if (where && Object.keys(where).length > 0) {
+    const conditions = Object.keys(where)
+      .map((k) => `${k} = ?`)
+      .join(" AND ");
+    sql += ` WHERE ${conditions}`;
+    values.push(...(Object.values(where) as SQLQueryBindings[]));
+  }
+
+  if (limit !== undefined) {
+    sql += ` LIMIT ?`;
+    values.push(limit);
+  }
+
+  if (offset !== undefined && offset > 0) {
+    sql += ` OFFSET ?`;
+    values.push(offset);
+  }
+
+  return db.query(sql).all(...values) as T[];
+}
+
+/**
+ * Insert a new record into a table.
+ */
+export function insert(
+  db: Database,
+  table: string,
+  data: Record<string, unknown>,
+): void {
+  const keys = Object.keys(data);
+  const placeholders = keys.map(() => "?").join(", ");
+  const sql = `INSERT INTO ${table} (${keys.join(", ")}) VALUES (${placeholders})`;
+  const values = Object.values(data) as SQLQueryBindings[];
+  db.query(sql).run(...values);
+}
+
+/**
+ * Update an existing record by id.
+ */
+export function update(
+  db: Database,
+  table: string,
+  id: string,
+  data: Record<string, unknown>,
+): void {
+  const sets = Object.keys(data)
+    .map((k) => `${k} = ?`)
+    .join(", ");
+  const sql = `UPDATE ${table} SET ${sets}, updated_at = CURRENT_TIMESTAMP WHERE id = ?`;
+  const values = [...Object.values(data), id] as SQLQueryBindings[];
+  db.query(sql).run(...values);
+}
+
+/**
+ * Delete a record by id.
+ */
+export function remove(db: Database, table: string, id: string): void {
+  db.query(`DELETE FROM ${table} WHERE id = ?`).run(id);
+}
+
+/**
+ * Count records in a table, optionally filtered.
+ */
+export function count(
+  db: Database,
+  table: string,
+  where?: Record<string, unknown>,
+): number {
+  if (!where || Object.keys(where).length === 0) {
+    const result = db.query(`SELECT COUNT(*) as count FROM ${table}`).get() as {
+      count: number;
+    };
+    return result.count;
+  }
+
+  const conditions = Object.keys(where)
+    .map((k) => `${k} = ?`)
+    .join(" AND ");
+  const sql = `SELECT COUNT(*) as count FROM ${table} WHERE ${conditions}`;
+  const values = Object.values(where) as SQLQueryBindings[];
+  const result = db.query(sql).get(...values) as {
+    count: number;
+  };
+  return result.count;
+}