@cliangdev/flux-plugin 0.2.0 → 0.3.0

package/src/server/adapters/types.ts

@@ -0,0 +1,293 @@
+/**
+ * Backend Adapter Types
+ *
+ * Defines the interface for storage backends (local SQLite, SpecFlux API, Linear, Notion).
+ * All adapters must implement BackendAdapter to ensure consistent behavior.
+ */
+
+// =============================================================================
+// Entity Types
+// =============================================================================
+
+export type PrdStatus =
+  | "DRAFT"
+  | "PENDING_REVIEW"
+  | "REVIEWED"
+  | "APPROVED"
+  | "BREAKDOWN_READY"
+  | "COMPLETED"
+  | "ARCHIVED";
+
+export type EpicStatus = "PENDING" | "IN_PROGRESS" | "COMPLETED";
+export type TaskStatus = "PENDING" | "IN_PROGRESS" | "COMPLETED";
+export type Priority = "LOW" | "MEDIUM" | "HIGH";
+
+export interface Prd {
+  id: string;
+  projectId: string;
+  ref: string;
+  title: string;
+  description?: string;
+  status: PrdStatus;
+  tag?: string;
+  folderPath?: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface Epic {
+  id: string;
+  prdId: string;
+  ref: string;
+  title: string;
+  description?: string;
+  status: EpicStatus;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface Task {
+  id: string;
+  epicId: string;
+  ref: string;
+  title: string;
+  description?: string;
+  status: TaskStatus;
+  priority: Priority;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface AcceptanceCriterion {
+  id: string;
+  parentType: "epic" | "task";
+  parentId: string;
+  criteria: string;
+  isMet: boolean;
+  createdAt: string;
+}
+
+export interface Document {
+  prdRef: string;
+  filename: string;
+  content: string;
+  /** For external adapters (Linear/Notion), this is the URL */
+  url?: string;
+}
+
+// =============================================================================
+// Input Types (for create/update operations)
+// =============================================================================
+
+export interface CreatePrdInput {
+  title: string;
+  description?: string;
+  tag?: string;
+  folderPath?: string;
+}
+
+export interface UpdatePrdInput {
+  title?: string;
+  description?: string;
+  status?: PrdStatus;
+  tag?: string;
+  folderPath?: string;
+}
+
+export interface CreateEpicInput {
+  prdRef: string;
+  title: string;
+  description?: string;
+  acceptanceCriteria?: string[];
+}
+
+export interface UpdateEpicInput {
+  title?: string;
+  description?: string;
+  status?: EpicStatus;
+}
+
+export interface CreateTaskInput {
+  epicRef: string;
+  title: string;
+  description?: string;
+  priority?: Priority;
+  acceptanceCriteria?: string[];
+}
+
+export interface UpdateTaskInput {
+  title?: string;
+  description?: string;
+  status?: TaskStatus;
+  priority?: Priority;
+}
+
+export interface AddCriterionInput {
+  parentRef: string;
+  criteria: string;
+}
+
+// =============================================================================
+// Query Types
+// =============================================================================
+
+export interface PrdFilters {
+  status?: PrdStatus;
+  tag?: string;
+}
+
+export interface EpicFilters {
+  prdRef?: string;
+  status?: EpicStatus;
+}
+
+export interface TaskFilters {
+  epicRef?: string;
+  status?: TaskStatus;
+  priority?: Priority;
+}
+
+export interface PaginationOptions {
+  limit?: number;
+  offset?: number;
+}
+
+export interface PaginatedResult<T> {
+  items: T[];
+  total: number;
+  limit: number;
+  offset: number;
+  hasMore: boolean;
+}
+
+// =============================================================================
+// Stats Types
+// =============================================================================
+
+export interface Stats {
+  prds: {
+    total: number;
+    draft: number;
+    pendingReview: number;
+    reviewed: number;
+    approved: number;
+    breakdownReady: number;
+    completed: number;
+    archived: number;
+  };
+  epics: {
+    total: number;
+    pending: number;
+    inProgress: number;
+    completed: number;
+  };
+  tasks: {
+    total: number;
+    pending: number;
+    inProgress: number;
+    completed: number;
+  };
+}
+
+// =============================================================================
+// Backend Adapter Interface
+// =============================================================================
+
+/**
+ * BackendAdapter defines the contract for storage backends.
+ *
+ * Implementations:
+ * - LocalAdapter: SQLite + filesystem (default)
+ * - SpecFluxAdapter: SpecFlux REST API (future)
+ * - LinearAdapter: Linear API (future)
+ * - NotionAdapter: Notion API (future)
+ */
+export interface BackendAdapter {
+  // -------------------------------------------------------------------------
+  // PRD Operations
+  // -------------------------------------------------------------------------
+
+  createPrd(input: CreatePrdInput): Promise<Prd>;
+  updatePrd(ref: string, input: UpdatePrdInput): Promise<Prd>;
+  getPrd(ref: string): Promise<Prd | null>;
+  listPrds(
+    filters?: PrdFilters,
+    pagination?: PaginationOptions,
+  ): Promise<PaginatedResult<Prd>>;
+  deletePrd(ref: string): Promise<{ deleted: string; cascade: CascadeResult }>;
+
+  // -------------------------------------------------------------------------
+  // Epic Operations
+  // -------------------------------------------------------------------------
+
+  createEpic(input: CreateEpicInput): Promise<Epic>;
+  updateEpic(ref: string, input: UpdateEpicInput): Promise<Epic>;
+  getEpic(ref: string): Promise<Epic | null>;
+  listEpics(
+    filters?: EpicFilters,
+    pagination?: PaginationOptions,
+  ): Promise<PaginatedResult<Epic>>;
+  deleteEpic(ref: string): Promise<{ deleted: string; cascade: CascadeResult }>;
+
+  // -------------------------------------------------------------------------
+  // Task Operations
+  // -------------------------------------------------------------------------
+
+  createTask(input: CreateTaskInput): Promise<Task>;
+  updateTask(ref: string, input: UpdateTaskInput): Promise<Task>;
+  getTask(ref: string): Promise<Task | null>;
+  listTasks(
+    filters?: TaskFilters,
+    pagination?: PaginationOptions,
+  ): Promise<PaginatedResult<Task>>;
+  deleteTask(ref: string): Promise<{ deleted: string; cascade: CascadeResult }>;
+
+  // -------------------------------------------------------------------------
+  // Acceptance Criteria Operations
+  // -------------------------------------------------------------------------
+
+  addCriterion(input: AddCriterionInput): Promise<AcceptanceCriterion>;
+  markCriterionMet(criterionId: string): Promise<AcceptanceCriterion>;
+  getCriteria(parentRef: string): Promise<AcceptanceCriterion[]>;
+
+  // -------------------------------------------------------------------------
+  // Dependency Operations
+  // -------------------------------------------------------------------------
+
+  addDependency(ref: string, dependsOnRef: string): Promise<void>;
+  removeDependency(ref: string, dependsOnRef: string): Promise<void>;
+  getDependencies(ref: string): Promise<string[]>;
+
+  // -------------------------------------------------------------------------
+  // Document Operations (for PRD supporting files)
+  // -------------------------------------------------------------------------
+
+  saveDocument(doc: Document): Promise<Document>;
+  getDocuments(prdRef: string): Promise<Document[]>;
+  deleteDocument(prdRef: string, filename: string): Promise<void>;
+
+  // -------------------------------------------------------------------------
+  // Query Operations
+  // -------------------------------------------------------------------------
+
+  getStats(): Promise<Stats>;
+}
+
+// =============================================================================
+// Helper Types
+// =============================================================================
+
+export interface CascadeResult {
+  criteria: number;
+  tasks: number;
+  epics: number;
+  dependencies: number;
+}
+
+/**
+ * Adapter configuration stored in project.json
+ */
+export interface AdapterConfig {
+  type: "local" | "specflux" | "linear" | "notion";
+  config?: Record<string, unknown>;
+}

package/src/server/config.ts

@@ -0,0 +1,73 @@
+import { existsSync } from "node:fs";
+import { dirname } from "node:path";
+
+function findFluxRoot(startDir: string): string | null {
+  let dir = startDir;
+  const root = "/";
+
+  while (dir !== root) {
+    if (existsSync(`${dir}/.flux/project.json`)) {
+      return dir;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+
+  if (existsSync(`${root}.flux/project.json`)) {
+    return root;
+  }
+
+  return null;
+}
+
+let cachedProjectRoot: string | null = null;
+
+export const config = {
+  fluxDir: ".flux",
+  dbFile: "flux.db",
+  projectFile: "project.json",
+
+  /**
+   * Get the project root directory.
+   * Priority: env var > walk up to find .flux > cwd fallback
+   */
+  get projectRoot() {
+    if (cachedProjectRoot) {
+      return cachedProjectRoot;
+    }
+
+    const envVar = process.env.FLUX_PROJECT_ROOT;
+    if (envVar && !envVar.startsWith("${")) {
+      cachedProjectRoot = envVar;
+      return envVar;
+    }
+
+    const cwd = process.cwd();
+    const found = findFluxRoot(cwd);
+    if (found) {
+      cachedProjectRoot = found;
+      return found;
+    }
+
+    return cwd;
+  },
+
+  clearCache() {
+    cachedProjectRoot = null;
+  },
+
+  get fluxPath() {
+    return `${this.projectRoot}/${this.fluxDir}`;
+  },
+  get dbPath() {
+    return `${this.fluxPath}/${this.dbFile}`;
+  },
+  get projectJsonPath() {
+    return `${this.fluxPath}/${this.projectFile}`;
+  },
+
+  get projectExists() {
+    return existsSync(this.projectJsonPath);
+  },
+};