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

package/src/server/adapters/local-adapter.ts

@@ -0,0 +1,968 @@
+/**
+ * LocalAdapter - SQLite + filesystem implementation of BackendAdapter
+ *
+ * Wraps the existing db layer to provide the BackendAdapter interface.
+ * This is the default adapter for local development.
+ */
+
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+import { config } from "../config.js";
+import {
+  count,
+  findAll,
+  findById,
+  findByRef,
+  generateId,
+  generateRef,
+  getDb,
+  insert,
+  remove,
+  update,
+} from "../db/index.js";
+import type {
+  AcceptanceCriterion,
+  AddCriterionInput,
+  BackendAdapter,
+  CascadeResult,
+  CreateEpicInput,
+  CreatePrdInput,
+  CreateTaskInput,
+  Document,
+  Epic,
+  EpicFilters,
+  PaginatedResult,
+  PaginationOptions,
+  Prd,
+  PrdFilters,
+  Stats,
+  Task,
+  TaskFilters,
+  UpdateEpicInput,
+  UpdatePrdInput,
+  UpdateTaskInput,
+} from "./types.js";
+
+// =============================================================================
+// Database Row Types (snake_case from SQLite)
+// =============================================================================
+
+interface PrdRow {
+  id: string;
+  project_id: string;
+  ref: string;
+  title: string;
+  description: string | null;
+  status: string;
+  tag: string | null;
+  folder_path: string | null;
+  created_at: string;
+  updated_at: string;
+}
+
+interface EpicRow {
+  id: string;
+  prd_id: string;
+  ref: string;
+  title: string;
+  description: string | null;
+  status: string;
+  created_at: string;
+  updated_at: string;
+}
+
+interface TaskRow {
+  id: string;
+  epic_id: string;
+  ref: string;
+  title: string;
+  description: string | null;
+  status: string;
+  priority: string;
+  created_at: string;
+  updated_at: string;
+}
+
+interface CriterionRow {
+  id: string;
+  parent_type: string;
+  parent_id: string;
+  criteria: string;
+  is_met: number;
+  created_at: string;
+}
+
+interface ProjectRow {
+  id: string;
+  ref_prefix: string;
+}
+
+// =============================================================================
+// Helper Functions
+// =============================================================================
+
+function toPrd(row: PrdRow): Prd {
+  return {
+    id: row.id,
+    projectId: row.project_id,
+    ref: row.ref,
+    title: row.title,
+    description: row.description ?? undefined,
+    status: row.status as Prd["status"],
+    tag: row.tag ?? undefined,
+    folderPath: row.folder_path ?? undefined,
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+  };
+}
+
+function toEpic(row: EpicRow): Epic {
+  return {
+    id: row.id,
+    prdId: row.prd_id,
+    ref: row.ref,
+    title: row.title,
+    description: row.description ?? undefined,
+    status: row.status as Epic["status"],
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+  };
+}
+
+function toTask(row: TaskRow): Task {
+  return {
+    id: row.id,
+    epicId: row.epic_id,
+    ref: row.ref,
+    title: row.title,
+    description: row.description ?? undefined,
+    status: row.status as Task["status"],
+    priority: row.priority as Task["priority"],
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+  };
+}
+
+function toCriterion(row: CriterionRow): AcceptanceCriterion {
+  return {
+    id: row.id,
+    parentType: row.parent_type as "epic" | "task",
+    parentId: row.parent_id,
+    criteria: row.criteria,
+    isMet: Boolean(row.is_met),
+    createdAt: row.created_at,
+  };
+}
+
+function getEntityType(ref: string): "P" | "E" | "T" {
+  const match = ref.match(/-([PET])\d+$/);
+  if (!match) {
+    throw new Error(`Invalid reference format: ${ref}`);
+  }
+  return match[1] as "P" | "E" | "T";
+}
+
+function getProject(): ProjectRow {
+  const db = getDb();
+  let project = db
+    .query("SELECT * FROM projects LIMIT 1")
+    .get() as ProjectRow | null;
+
+  if (!project) {
+    // Create default project if none exists
+    const projectId = generateId("proj");
+    const prefix = getProjectPrefix();
+    insert(db, "projects", {
+      id: projectId,
+      name: "default",
+      ref_prefix: prefix,
+    });
+    project = { id: projectId, ref_prefix: prefix };
+  }
+
+  return project;
+}
+
+function getProjectPrefix(): string {
+  const projectJsonPath = config.projectJsonPath;
+  if (existsSync(projectJsonPath)) {
+    try {
+      const content = readFileSync(projectJsonPath, "utf-8");
+      const project = JSON.parse(content) as { ref_prefix?: string };
+      return project.ref_prefix || "FLUX";
+    } catch {
+      return "FLUX";
+    }
+  }
+  return "FLUX";
+}
+
+// =============================================================================
+// LocalAdapter Implementation
+// =============================================================================
+
+export class LocalAdapter implements BackendAdapter {
+  // ---------------------------------------------------------------------------
+  // PRD Operations
+  // ---------------------------------------------------------------------------
+
+  async createPrd(input: CreatePrdInput): Promise<Prd> {
+    const db = getDb();
+    const project = getProject();
+
+    const id = generateId("prd");
+    const ref = generateRef(db, "P", project.ref_prefix);
+
+    insert(db, "prds", {
+      id,
+      project_id: project.id,
+      ref,
+      title: input.title,
+      description: input.description ?? null,
+      status: "DRAFT",
+      tag: input.tag ?? null,
+      folder_path: input.folderPath ?? null,
+    });
+
+    const row = findById<PrdRow>(db, "prds", id);
+    if (!row) throw new Error("Failed to create PRD");
+    return toPrd(row);
+  }
+
+  async updatePrd(ref: string, input: UpdatePrdInput): Promise<Prd> {
+    const db = getDb();
+    const existing = findByRef<PrdRow>(db, "prds", ref);
+    if (!existing) throw new Error(`PRD not found: ${ref}`);
+
+    const updates: Record<string, unknown> = {};
+    if (input.title !== undefined) updates.title = input.title;
+    if (input.description !== undefined)
+      updates.description = input.description;
+    if (input.status !== undefined) updates.status = input.status;
+    if (input.tag !== undefined) updates.tag = input.tag;
+    if (input.folderPath !== undefined) updates.folder_path = input.folderPath;
+
+    if (Object.keys(updates).length > 0) {
+      update(db, "prds", existing.id, updates);
+    }
+
+    const row = findById<PrdRow>(db, "prds", existing.id);
+    if (!row) throw new Error("Failed to update PRD");
+    return toPrd(row);
+  }
+
+  async getPrd(ref: string): Promise<Prd | null> {
+    const db = getDb();
+    const row = findByRef<PrdRow>(db, "prds", ref);
+    return row ? toPrd(row) : null;
+  }
+
+  async listPrds(
+    filters?: PrdFilters,
+    pagination?: PaginationOptions,
+  ): Promise<PaginatedResult<Prd>> {
+    const db = getDb();
+    const where: Record<string, unknown> = {};
+
+    if (filters?.status) where.status = filters.status;
+    if (filters?.tag) where.tag = filters.tag;
+
+    const limit = pagination?.limit ?? 50;
+    const offset = pagination?.offset ?? 0;
+
+    const total = count(db, "prds", where);
+    const rows = findAll<PrdRow>(db, "prds", { where, limit, offset });
+
+    return {
+      items: rows.map(toPrd),
+      total,
+      limit,
+      offset,
+      hasMore: offset + rows.length < total,
+    };
+  }
+
+  async deletePrd(
+    ref: string,
+  ): Promise<{ deleted: string; cascade: CascadeResult }> {
+    const db = getDb();
+    const prd = findByRef<PrdRow>(db, "prds", ref);
+    if (!prd) throw new Error(`PRD not found: ${ref}`);
+
+    const cascade: CascadeResult = {
+      criteria: 0,
+      tasks: 0,
+      epics: 0,
+      dependencies: 0,
+    };
+
+    // Delete all epics under this PRD
+    const epics = findAll<EpicRow>(db, "epics", { prd_id: prd.id });
+    for (const epic of epics) {
+      const epicResult = await this.deleteEpic(epic.ref);
+      cascade.criteria += epicResult.cascade.criteria;
+      cascade.tasks += epicResult.cascade.tasks;
+      cascade.dependencies += epicResult.cascade.dependencies;
+      cascade.epics++;
+    }
+
+    remove(db, "prds", prd.id);
+
+    return { deleted: ref, cascade };
+  }
+
+  // ---------------------------------------------------------------------------
+  // Epic Operations
+  // ---------------------------------------------------------------------------
+
+  async createEpic(input: CreateEpicInput): Promise<Epic> {
+    const db = getDb();
+    const project = getProject();
+
+    const prd = findByRef<PrdRow>(db, "prds", input.prdRef);
+    if (!prd) throw new Error(`PRD not found: ${input.prdRef}`);
+
+    const id = generateId("epic");
+    const ref = generateRef(db, "E", project.ref_prefix);
+
+    insert(db, "epics", {
+      id,
+      prd_id: prd.id,
+      ref,
+      title: input.title,
+      description: input.description ?? null,
+      status: "PENDING",
+    });
+
+    // Add acceptance criteria if provided
+    if (input.acceptanceCriteria?.length) {
+      for (const criteria of input.acceptanceCriteria) {
+        const criteriaId = generateId("ac");
+        insert(db, "acceptance_criteria", {
+          id: criteriaId,
+          parent_type: "epic",
+          parent_id: id,
+          criteria,
+          is_met: 0,
+        });
+      }
+    }
+
+    const row = findById<EpicRow>(db, "epics", id);
+    if (!row) throw new Error("Failed to create Epic");
+    return toEpic(row);
+  }
+
+  async updateEpic(ref: string, input: UpdateEpicInput): Promise<Epic> {
+    const db = getDb();
+    const existing = findByRef<EpicRow>(db, "epics", ref);
+    if (!existing) throw new Error(`Epic not found: ${ref}`);
+
+    const updates: Record<string, unknown> = {};
+    if (input.title !== undefined) updates.title = input.title;
+    if (input.description !== undefined)
+      updates.description = input.description;
+    if (input.status !== undefined) updates.status = input.status;
+
+    if (Object.keys(updates).length > 0) {
+      update(db, "epics", existing.id, updates);
+    }
+
+    const row = findById<EpicRow>(db, "epics", existing.id);
+    if (!row) throw new Error("Failed to update Epic");
+    return toEpic(row);
+  }
+
+  async getEpic(ref: string): Promise<Epic | null> {
+    const db = getDb();
+    const row = findByRef<EpicRow>(db, "epics", ref);
+    return row ? toEpic(row) : null;
+  }
+
+  async listEpics(
+    filters?: EpicFilters,
+    pagination?: PaginationOptions,
+  ): Promise<PaginatedResult<Epic>> {
+    const db = getDb();
+    const where: Record<string, unknown> = {};
+
+    if (filters?.status) where.status = filters.status;
+    if (filters?.prdRef) {
+      const prd = findByRef<PrdRow>(db, "prds", filters.prdRef);
+      if (!prd)
+        return {
+          items: [],
+          total: 0,
+          limit: pagination?.limit ?? 50,
+          offset: pagination?.offset ?? 0,
+          hasMore: false,
+        };
+      where.prd_id = prd.id;
+    }
+
+    const limit = pagination?.limit ?? 50;
+    const offset = pagination?.offset ?? 0;
+
+    const total = count(db, "epics", where);
+    const rows = findAll<EpicRow>(db, "epics", { where, limit, offset });
+
+    return {
+      items: rows.map(toEpic),
+      total,
+      limit,
+      offset,
+      hasMore: offset + rows.length < total,
+    };
+  }
+
+  async deleteEpic(
+    ref: string,
+  ): Promise<{ deleted: string; cascade: CascadeResult }> {
+    const db = getDb();
+    const epic = findByRef<EpicRow>(db, "epics", ref);
+    if (!epic) throw new Error(`Epic not found: ${ref}`);
+
+    const cascade: CascadeResult = {
+      criteria: 0,
+      tasks: 0,
+      epics: 0,
+      dependencies: 0,
+    };
+
+    // Delete all tasks under this epic
+    const tasks = findAll<TaskRow>(db, "tasks", { epic_id: epic.id });
+    for (const task of tasks) {
+      const taskResult = await this.deleteTask(task.ref);
+      cascade.criteria += taskResult.cascade.criteria;
+      cascade.tasks++;
+    }
+
+    // Delete epic criteria
+    const epicCriteria = findAll<CriterionRow>(db, "acceptance_criteria", {
+      parent_type: "epic",
+      parent_id: epic.id,
+    });
+    for (const c of epicCriteria) {
+      remove(db, "acceptance_criteria", c.id);
+      cascade.criteria++;
+    }
+
+    // Delete epic dependencies
+    db.query(
+      "DELETE FROM epic_dependencies WHERE epic_id = ? OR depends_on_epic_id = ?",
+    ).run(epic.id, epic.id);
+
+    remove(db, "epics", epic.id);
+
+    return { deleted: ref, cascade };
+  }
+
+  // ---------------------------------------------------------------------------
+  // Task Operations
+  // ---------------------------------------------------------------------------
+
+  async createTask(input: CreateTaskInput): Promise<Task> {
+    const db = getDb();
+    const project = getProject();
+
+    const epic = findByRef<EpicRow>(db, "epics", input.epicRef);
+    if (!epic) throw new Error(`Epic not found: ${input.epicRef}`);
+
+    const id = generateId("task");
+    const ref = generateRef(db, "T", project.ref_prefix);
+
+    insert(db, "tasks", {
+      id,
+      epic_id: epic.id,
+      ref,
+      title: input.title,
+      description: input.description ?? null,
+      status: "PENDING",
+      priority: input.priority ?? "MEDIUM",
+    });
+
+    // Add acceptance criteria if provided
+    if (input.acceptanceCriteria?.length) {
+      for (const criteria of input.acceptanceCriteria) {
+        const criteriaId = generateId("ac");
+        insert(db, "acceptance_criteria", {
+          id: criteriaId,
+          parent_type: "task",
+          parent_id: id,
+          criteria,
+          is_met: 0,
+        });
+      }
+    }
+
+    const row = findById<TaskRow>(db, "tasks", id);
+    if (!row) throw new Error("Failed to create Task");
+    return toTask(row);
+  }
+
+  async updateTask(ref: string, input: UpdateTaskInput): Promise<Task> {
+    const db = getDb();
+    const existing = findByRef<TaskRow>(db, "tasks", ref);
+    if (!existing) throw new Error(`Task not found: ${ref}`);
+
+    const updates: Record<string, unknown> = {};
+    if (input.title !== undefined) updates.title = input.title;
+    if (input.description !== undefined)
+      updates.description = input.description;
+    if (input.status !== undefined) updates.status = input.status;
+    if (input.priority !== undefined) updates.priority = input.priority;
+
+    if (Object.keys(updates).length > 0) {
+      update(db, "tasks", existing.id, updates);
+    }
+
+    const row = findById<TaskRow>(db, "tasks", existing.id);
+    if (!row) throw new Error("Failed to update Task");
+    return toTask(row);
+  }
+
+  async getTask(ref: string): Promise<Task | null> {
+    const db = getDb();
+    const row = findByRef<TaskRow>(db, "tasks", ref);
+    return row ? toTask(row) : null;
+  }
+
+  async listTasks(
+    filters?: TaskFilters,
+    pagination?: PaginationOptions,
+  ): Promise<PaginatedResult<Task>> {
+    const db = getDb();
+    const where: Record<string, unknown> = {};
+
+    if (filters?.status) where.status = filters.status;
+    if (filters?.priority) where.priority = filters.priority;
+    if (filters?.epicRef) {
+      const epic = findByRef<EpicRow>(db, "epics", filters.epicRef);
+      if (!epic)
+        return {
+          items: [],
+          total: 0,
+          limit: pagination?.limit ?? 50,
+          offset: pagination?.offset ?? 0,
+          hasMore: false,
+        };
+      where.epic_id = epic.id;
+    }
+
+    const limit = pagination?.limit ?? 50;
+    const offset = pagination?.offset ?? 0;
+
+    const total = count(db, "tasks", where);
+    const rows = findAll<TaskRow>(db, "tasks", { where, limit, offset });
+
+    return {
+      items: rows.map(toTask),
+      total,
+      limit,
+      offset,
+      hasMore: offset + rows.length < total,
+    };
+  }
+
+  async deleteTask(
+    ref: string,
+  ): Promise<{ deleted: string; cascade: CascadeResult }> {
+    const db = getDb();
+    const task = findByRef<TaskRow>(db, "tasks", ref);
+    if (!task) throw new Error(`Task not found: ${ref}`);
+
+    const cascade: CascadeResult = {
+      criteria: 0,
+      tasks: 0,
+      epics: 0,
+      dependencies: 0,
+    };
+
+    // Delete task criteria
+    const taskCriteria = findAll<CriterionRow>(db, "acceptance_criteria", {
+      parent_type: "task",
+      parent_id: task.id,
+    });
+    for (const c of taskCriteria) {
+      remove(db, "acceptance_criteria", c.id);
+      cascade.criteria++;
+    }
+
+    // Delete task dependencies
+    db.query(
+      "DELETE FROM task_dependencies WHERE task_id = ? OR depends_on_task_id = ?",
+    ).run(task.id, task.id);
+
+    remove(db, "tasks", task.id);
+
+    return { deleted: ref, cascade };
+  }
+
+  // ---------------------------------------------------------------------------
+  // Acceptance Criteria Operations
+  // ---------------------------------------------------------------------------
+
+  async addCriterion(input: AddCriterionInput): Promise<AcceptanceCriterion> {
+    const db = getDb();
+    const entityType = getEntityType(input.parentRef);
+
+    let parentId: string;
+    let parentType: "epic" | "task";
+
+    if (entityType === "E") {
+      const epic = findByRef<EpicRow>(db, "epics", input.parentRef);
+      if (!epic) throw new Error(`Epic not found: ${input.parentRef}`);
+      parentId = epic.id;
+      parentType = "epic";
+    } else if (entityType === "T") {
+      const task = findByRef<TaskRow>(db, "tasks", input.parentRef);
+      if (!task) throw new Error(`Task not found: ${input.parentRef}`);
+      parentId = task.id;
+      parentType = "task";
+    } else {
+      throw new Error("Criteria can only be added to Epics or Tasks");
+    }
+
+    const id = generateId("ac");
+    insert(db, "acceptance_criteria", {
+      id,
+      parent_type: parentType,
+      parent_id: parentId,
+      criteria: input.criteria,
+      is_met: 0,
+    });
+
+    const row = findById<CriterionRow>(db, "acceptance_criteria", id);
+    if (!row) throw new Error("Failed to add criterion");
+    return toCriterion(row);
+  }
+
+  async markCriterionMet(criterionId: string): Promise<AcceptanceCriterion> {
+    const db = getDb();
+    const existing = findById<CriterionRow>(
+      db,
+      "acceptance_criteria",
+      criterionId,
+    );
+    if (!existing) throw new Error(`Criterion not found: ${criterionId}`);
+
+    // Use direct query since acceptance_criteria table has no updated_at column
+    db.query("UPDATE acceptance_criteria SET is_met = 1 WHERE id = ?").run(
+      criterionId,
+    );
+
+    const row = findById<CriterionRow>(db, "acceptance_criteria", criterionId);
+    if (!row) throw new Error("Failed to update criterion");
+    return toCriterion(row);
+  }
+
+  async getCriteria(parentRef: string): Promise<AcceptanceCriterion[]> {
+    const db = getDb();
+    const entityType = getEntityType(parentRef);
+
+    let parentId: string;
+    let parentType: "epic" | "task";
+
+    if (entityType === "E") {
+      const epic = findByRef<EpicRow>(db, "epics", parentRef);
+      if (!epic) return [];
+      parentId = epic.id;
+      parentType = "epic";
+    } else if (entityType === "T") {
+      const task = findByRef<TaskRow>(db, "tasks", parentRef);
+      if (!task) return [];
+      parentId = task.id;
+      parentType = "task";
+    } else {
+      return [];
+    }
+
+    const rows = findAll<CriterionRow>(db, "acceptance_criteria", {
+      parent_type: parentType,
+      parent_id: parentId,
+    });
+
+    return rows.map(toCriterion);
+  }
+
+  // ---------------------------------------------------------------------------
+  // Dependency Operations
+  // ---------------------------------------------------------------------------
+
+  async addDependency(ref: string, dependsOnRef: string): Promise<void> {
+    const db = getDb();
+
+    // Check for self-dependency
+    if (ref === dependsOnRef) {
+      throw new Error("Entity cannot depend on itself");
+    }
+
+    const entityType = getEntityType(ref);
+    const dependsOnType = getEntityType(dependsOnRef);
+
+    if (entityType !== dependsOnType) {
+      throw new Error("Dependencies must be between entities of the same type");
+    }
+
+    if (entityType === "E") {
+      const epic = findByRef<EpicRow>(db, "epics", ref);
+      const dependsOnEpic = findByRef<EpicRow>(db, "epics", dependsOnRef);
+      if (!epic || !dependsOnEpic) throw new Error("Epic not found");
+
+      db.query(
+        "INSERT OR IGNORE INTO epic_dependencies (epic_id, depends_on_epic_id) VALUES (?, ?)",
+      ).run(epic.id, dependsOnEpic.id);
+    } else if (entityType === "T") {
+      const task = findByRef<TaskRow>(db, "tasks", ref);
+      const dependsOnTask = findByRef<TaskRow>(db, "tasks", dependsOnRef);
+      if (!task || !dependsOnTask) throw new Error("Task not found");
+
+      db.query(
+        "INSERT OR IGNORE INTO task_dependencies (task_id, depends_on_task_id) VALUES (?, ?)",
+      ).run(task.id, dependsOnTask.id);
+    } else {
+      throw new Error("Dependencies can only be added to Epics or Tasks");
+    }
+  }
+
+  async removeDependency(ref: string, dependsOnRef: string): Promise<void> {
+    const db = getDb();
+    const entityType = getEntityType(ref);
+
+    if (entityType === "E") {
+      const epic = findByRef<EpicRow>(db, "epics", ref);
+      const dependsOnEpic = findByRef<EpicRow>(db, "epics", dependsOnRef);
+      if (!epic || !dependsOnEpic) throw new Error("Epic not found");
+
+      db.query(
+        "DELETE FROM epic_dependencies WHERE epic_id = ? AND depends_on_epic_id = ?",
+      ).run(epic.id, dependsOnEpic.id);
+    } else if (entityType === "T") {
+      const task = findByRef<TaskRow>(db, "tasks", ref);
+      const dependsOnTask = findByRef<TaskRow>(db, "tasks", dependsOnRef);
+      if (!task || !dependsOnTask) throw new Error("Task not found");
+
+      db.query(
+        "DELETE FROM task_dependencies WHERE task_id = ? AND depends_on_task_id = ?",
+      ).run(task.id, dependsOnTask.id);
+    }
+  }
+
+  async getDependencies(ref: string): Promise<string[]> {
+    const db = getDb();
+    const entityType = getEntityType(ref);
+
+    if (entityType === "E") {
+      const epic = findByRef<EpicRow>(db, "epics", ref);
+      if (!epic) return [];
+
+      const deps = db
+        .query(
+          `SELECT e.ref FROM epic_dependencies ed
+           JOIN epics e ON ed.depends_on_epic_id = e.id
+           WHERE ed.epic_id = ?`,
+        )
+        .all(epic.id) as { ref: string }[];
+
+      return deps.map((d) => d.ref);
+    } else if (entityType === "T") {
+      const task = findByRef<TaskRow>(db, "tasks", ref);
+      if (!task) return [];
+
+      const deps = db
+        .query(
+          `SELECT t.ref FROM task_dependencies td
+           JOIN tasks t ON td.depends_on_task_id = t.id
+           WHERE td.task_id = ?`,
+        )
+        .all(task.id) as { ref: string }[];
+
+      return deps.map((d) => d.ref);
+    }
+
+    return [];
+  }
+
+  // ---------------------------------------------------------------------------
+  // Document Operations
+  // ---------------------------------------------------------------------------
+
+  async saveDocument(doc: Document): Promise<Document> {
+    const prd = await this.getPrd(doc.prdRef);
+    if (!prd) throw new Error(`PRD not found: ${doc.prdRef}`);
+
+    // Ensure folder exists
+    const folderPath =
+      prd.folderPath || join(config.fluxPath, "prds", doc.prdRef.toLowerCase());
+    if (!existsSync(folderPath)) {
+      mkdirSync(folderPath, { recursive: true });
+    }
+
+    // Update PRD folder_path if not set
+    if (!prd.folderPath) {
+      await this.updatePrd(doc.prdRef, { folderPath });
+    }
+
+    const filePath = join(folderPath, doc.filename);
+    writeFileSync(filePath, doc.content, "utf-8");
+
+    return { ...doc, url: filePath };
+  }
+
+  async getDocuments(prdRef: string): Promise<Document[]> {
+    const prd = await this.getPrd(prdRef);
+    if (!prd || !prd.folderPath) return [];
+
+    const folderPath = prd.folderPath;
+    if (!existsSync(folderPath)) return [];
+
+    const { readdirSync } = await import("node:fs");
+    const files = readdirSync(folderPath);
+
+    return files
+      .filter((f) => f.endsWith(".md"))
+      .map((filename) => ({
+        prdRef,
+        filename,
+        content: readFileSync(join(folderPath, filename), "utf-8"),
+        url: join(folderPath, filename),
+      }));
+  }
+
+  async deleteDocument(prdRef: string, filename: string): Promise<void> {
+    const prd = await this.getPrd(prdRef);
+    if (!prd || !prd.folderPath) return;
+
+    const filePath = join(prd.folderPath, filename);
+    if (existsSync(filePath)) {
+      rmSync(filePath);
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // Query Operations
+  // ---------------------------------------------------------------------------
+
+  async getStats(): Promise<Stats> {
+    const db = getDb();
+
+    // PRD stats (exclude archived from totals)
+    const prdArchived = count(db, "prds", { status: "ARCHIVED" });
+    const prdTotal = (
+      db
+        .query("SELECT COUNT(*) as count FROM prds WHERE status != 'ARCHIVED'")
+        .get() as { count: number }
+    ).count;
+
+    // Epic stats (exclude epics belonging to archived PRDs)
+    const epicTotal = (
+      db
+        .query(`
+        SELECT COUNT(*) as count FROM epics e
+        JOIN prds p ON e.prd_id = p.id
+        WHERE p.status != 'ARCHIVED'
+      `)
+        .get() as { count: number }
+    ).count;
+    const epicPending = (
+      db
+        .query(`
+        SELECT COUNT(*) as count FROM epics e
+        JOIN prds p ON e.prd_id = p.id
+        WHERE p.status != 'ARCHIVED' AND e.status = 'PENDING'
+      `)
+        .get() as { count: number }
+    ).count;
+    const epicInProgress = (
+      db
+        .query(`
+        SELECT COUNT(*) as count FROM epics e
+        JOIN prds p ON e.prd_id = p.id
+        WHERE p.status != 'ARCHIVED' AND e.status = 'IN_PROGRESS'
+      `)
+        .get() as { count: number }
+    ).count;
+    const epicCompleted = (
+      db
+        .query(`
+        SELECT COUNT(*) as count FROM epics e
+        JOIN prds p ON e.prd_id = p.id
+        WHERE p.status != 'ARCHIVED' AND e.status = 'COMPLETED'
+      `)
+        .get() as { count: number }
+    ).count;
+
+    // Task stats (exclude tasks belonging to epics of archived PRDs)
+    const taskTotal = (
+      db
+        .query(`
+        SELECT COUNT(*) as count FROM tasks t
+        JOIN epics e ON t.epic_id = e.id
+        JOIN prds p ON e.prd_id = p.id
+        WHERE p.status != 'ARCHIVED'
+      `)
+        .get() as { count: number }
+    ).count;
+    const taskPending = (
+      db
+        .query(`
+        SELECT COUNT(*) as count FROM tasks t
+        JOIN epics e ON t.epic_id = e.id
+        JOIN prds p ON e.prd_id = p.id
+        WHERE p.status != 'ARCHIVED' AND t.status = 'PENDING'
+      `)
+        .get() as { count: number }
+    ).count;
+    const taskInProgress = (
+      db
+        .query(`
+        SELECT COUNT(*) as count FROM tasks t
+        JOIN epics e ON t.epic_id = e.id
+        JOIN prds p ON e.prd_id = p.id
+        WHERE p.status != 'ARCHIVED' AND t.status = 'IN_PROGRESS'
+      `)
+        .get() as { count: number }
+    ).count;
+    const taskCompleted = (
+      db
+        .query(`
+        SELECT COUNT(*) as count FROM tasks t
+        JOIN epics e ON t.epic_id = e.id
+        JOIN prds p ON e.prd_id = p.id
+        WHERE p.status != 'ARCHIVED' AND t.status = 'COMPLETED'
+      `)
+        .get() as { count: number }
+    ).count;
+
+    return {
+      prds: {
+        total: prdTotal,
+        draft: count(db, "prds", { status: "DRAFT" }),
+        pendingReview: count(db, "prds", { status: "PENDING_REVIEW" }),
+        reviewed: count(db, "prds", { status: "REVIEWED" }),
+        approved: count(db, "prds", { status: "APPROVED" }),
+        breakdownReady: count(db, "prds", { status: "BREAKDOWN_READY" }),
+        completed: count(db, "prds", { status: "COMPLETED" }),
+        archived: prdArchived,
+      },
+      epics: {
+        total: epicTotal,
+        pending: epicPending,
+        inProgress: epicInProgress,
+        completed: epicCompleted,
+      },
+      tasks: {
+        total: taskTotal,
+        pending: taskPending,
+        inProgress: taskInProgress,
+        completed: taskCompleted,
+      },
+    };
+  }
+}