@cliangdev/flux-plugin 0.2.0 → 0.3.0

package/src/server/tools/query-entities.ts

@@ -0,0 +1,167 @@
+import { z } from "zod";
+import { getAdapter } from "../adapters/index.js";
+import type { ToolDefinition } from "./index.js";
+
+const inputSchema = z.object({
+  type: z.enum(["prd", "epic", "task"]),
+  status: z.string().optional(),
+  tag: z.string().optional(),
+  prd_ref: z.string().optional(),
+  epic_ref: z.string().optional(),
+  include: z.array(z.string()).optional(),
+  limit: z.number().min(1).max(100).optional().default(50),
+  offset: z.number().min(0).optional().default(0),
+});
+
+async function handler(input: unknown) {
+  const parsed = inputSchema.parse(input);
+  const adapter = getAdapter();
+  const includes = parsed.include || [];
+
+  if (parsed.type === "prd") {
+    const result = await adapter.listPrds(
+      {
+        status: parsed.status as
+          | "DRAFT"
+          | "PENDING_REVIEW"
+          | "REVIEWED"
+          | "APPROVED"
+          | "BREAKDOWN_READY"
+          | "COMPLETED"
+          | "ARCHIVED"
+          | undefined,
+        tag: parsed.tag,
+      },
+      { limit: parsed.limit, offset: parsed.offset },
+    );
+
+    const items = await Promise.all(
+      result.items.map(async (prd) => {
+        const minimal: Record<string, unknown> = {
+          ref: prd.ref,
+          title: prd.title,
+          description: prd.description,
+          status: prd.status,
+          tag: prd.tag,
+          folder_path: prd.folderPath,
+        };
+
+        if (includes.includes("epics")) {
+          const epics = await adapter.listEpics(
+            { prdRef: prd.ref },
+            { limit: 100 },
+          );
+          minimal.epic_count = epics.total;
+        }
+
+        return minimal;
+      }),
+    );
+
+    return {
+      items,
+      total: result.total,
+      limit: result.limit,
+      offset: result.offset,
+      has_more: result.hasMore,
+    };
+  }
+
+  if (parsed.type === "epic") {
+    const result = await adapter.listEpics(
+      {
+        status: parsed.status as
+          | "PENDING"
+          | "IN_PROGRESS"
+          | "COMPLETED"
+          | undefined,
+        prdRef: parsed.prd_ref,
+      },
+      { limit: parsed.limit, offset: parsed.offset },
+    );
+
+    const items = await Promise.all(
+      result.items.map(async (epic) => {
+        const minimal: Record<string, unknown> = {
+          ref: epic.ref,
+          title: epic.title,
+          description: epic.description,
+          status: epic.status,
+        };
+
+        if (includes.includes("criteria")) {
+          const criteria = await adapter.getCriteria(epic.ref);
+          minimal.criteria_count = criteria.length;
+          minimal.criteria_met = criteria.filter((c) => c.isMet).length;
+        }
+
+        if (includes.includes("tasks")) {
+          const tasks = await adapter.listTasks(
+            { epicRef: epic.ref },
+            { limit: 100 },
+          );
+          minimal.task_count = tasks.total;
+        }
+
+        return minimal;
+      }),
+    );
+
+    return {
+      items,
+      total: result.total,
+      limit: result.limit,
+      offset: result.offset,
+      has_more: result.hasMore,
+    };
+  }
+
+  // task type
+  const result = await adapter.listTasks(
+    {
+      status: parsed.status as
+        | "PENDING"
+        | "IN_PROGRESS"
+        | "COMPLETED"
+        | undefined,
+      epicRef: parsed.epic_ref,
+    },
+    { limit: parsed.limit, offset: parsed.offset },
+  );
+
+  const items = await Promise.all(
+    result.items.map(async (task) => {
+      const minimal: Record<string, unknown> = {
+        ref: task.ref,
+        title: task.title,
+        description: task.description,
+        status: task.status,
+        priority: task.priority,
+      };
+
+      if (includes.includes("criteria")) {
+        const criteria = await adapter.getCriteria(task.ref);
+        minimal.criteria_count = criteria.length;
+        minimal.criteria_met = criteria.filter((c) => c.isMet).length;
+      }
+
+      return minimal;
+    }),
+  );
+
+  return {
+    items,
+    total: result.total,
+    limit: result.limit,
+    offset: result.offset,
+    has_more: result.hasMore,
+  };
+}
+
+export const queryEntitiesTool: ToolDefinition = {
+  name: "query_entities",
+  description:
+    "Query entities with filters and pagination. Required: type (prd|epic|task). Optional: status, tag (PRD only), prd_ref (Epic filter), epic_ref (Task filter), include (['epics','tasks','criteria'] for counts only), limit (1-100, default 50), offset (default 0). Returns minimal data: {items: [{ref, title, description, status, ...counts}], total, limit, offset, has_more}. Description provides context to decide if full read is needed. Use get_entity for more details, Read tool for full PRD content.",
+  inputSchema,
+  handler,
+};

package/src/server/tools/render-status.ts

@@ -0,0 +1,219 @@
+import { existsSync, readFileSync } from "node:fs";
+import { z } from "zod";
+import {
+  renderFullTreeView,
+  renderSummaryView,
+} from "../../utils/status-renderer.js";
+import { VERSION } from "../../version.js";
+import { getAdapter } from "../adapters/index.js";
+import { config } from "../config.js";
+import { computeStats } from "./get-stats.js";
+import type { ToolDefinition } from "./index.js";
+
+const inputSchema = z.object({
+  view: z
+    .enum(["summary", "full"])
+    .default("summary")
+    .describe("View type: 'summary' (default) or 'full' tree view"),
+});
+
+interface EpicForSummary {
+  ref: string;
+  title: string;
+  status: string;
+  task_count: number;
+  tasks_completed: number;
+  dependencies: string[];
+}
+
+interface PrdForSummary {
+  ref: string;
+  title: string;
+  status: string;
+  epics: EpicForSummary[];
+  dependencies: string[];
+}
+
+interface TaskForFull {
+  ref: string;
+  title: string;
+  status: string;
+  dependencies: string[];
+}
+
+interface EpicForFull {
+  ref: string;
+  title: string;
+  status: string;
+  tasks: TaskForFull[];
+  dependencies: string[];
+}
+
+interface PrdForFull {
+  ref: string;
+  title: string;
+  status: string;
+  epics: EpicForFull[];
+  dependencies: string[];
+}
+
+function getProjectInfo(): { name: string; ref_prefix: string } | null {
+  if (!existsSync(config.projectJsonPath)) {
+    return null;
+  }
+  try {
+    const content = readFileSync(config.projectJsonPath, "utf-8");
+    const project = JSON.parse(content);
+    return {
+      name: project.name || "Unnamed Project",
+      ref_prefix: project.ref_prefix || "FLUX",
+    };
+  } catch {
+    return null;
+  }
+}
+
+async function handler(input: unknown) {
+  const parsed = inputSchema.parse(input);
+  const adapter = getAdapter();
+
+  const project = getProjectInfo();
+  if (!project) {
+    return { error: true, message: "No project found", code: "NO_PROJECT" };
+  }
+
+  const stats = await computeStats();
+
+  if (parsed.view === "full") {
+    const prds = await getFullTreeData(adapter);
+    return { output: renderFullTreeView(prds) };
+  }
+
+  const prds = await getSummaryData(adapter);
+  const output = renderSummaryView(
+    {
+      name: project.name,
+      ref_prefix: project.ref_prefix,
+    },
+    stats,
+    prds,
+    VERSION,
+  );
+
+  return { output };
+}
+
+type Adapter = ReturnType<typeof getAdapter>;
+
+async function getSummaryData(adapter: Adapter): Promise<PrdForSummary[]> {
+  // Get all PRDs except archived
+  const prdsResult = await adapter.listPrds({}, { limit: 100 });
+  const nonArchivedPrds = prdsResult.items.filter(
+    (prd) => prd.status !== "ARCHIVED",
+  );
+
+  const result: PrdForSummary[] = [];
+
+  for (const prd of nonArchivedPrds) {
+    const [prdDeps, epicsResult] = await Promise.all([
+      adapter.getDependencies(prd.ref),
+      adapter.listEpics({ prdRef: prd.ref }, { limit: 100 }),
+    ]);
+
+    const epicsWithCounts: EpicForSummary[] = await Promise.all(
+      epicsResult.items.map(async (epic) => {
+        const [epicDeps, tasksResult] = await Promise.all([
+          adapter.getDependencies(epic.ref),
+          adapter.listTasks({ epicRef: epic.ref }, { limit: 100 }),
+        ]);
+        const completedCount = tasksResult.items.filter(
+          (t) => t.status === "COMPLETED",
+        ).length;
+
+        return {
+          ref: epic.ref,
+          title: epic.title,
+          status: epic.status,
+          task_count: tasksResult.total,
+          tasks_completed: completedCount,
+          dependencies: epicDeps,
+        };
+      }),
+    );
+
+    result.push({
+      ref: prd.ref,
+      title: prd.title,
+      status: prd.status,
+      epics: epicsWithCounts,
+      dependencies: prdDeps,
+    });
+  }
+
+  return result;
+}
+
+async function getFullTreeData(adapter: Adapter): Promise<PrdForFull[]> {
+  // Get all PRDs except archived
+  const prdsResult = await adapter.listPrds({}, { limit: 100 });
+  const allPrds = prdsResult.items
+    .filter((prd) => prd.status !== "ARCHIVED")
+    .sort((a, b) => a.ref.localeCompare(b.ref));
+
+  const result: PrdForFull[] = [];
+
+  for (const prd of allPrds) {
+    const [prdDeps, epicsResult] = await Promise.all([
+      adapter.getDependencies(prd.ref),
+      adapter.listEpics({ prdRef: prd.ref }, { limit: 100 }),
+    ]);
+
+    const epicsWithTasks: EpicForFull[] = await Promise.all(
+      epicsResult.items.map(async (epic) => {
+        const [epicDeps, tasksResult] = await Promise.all([
+          adapter.getDependencies(epic.ref),
+          adapter.listTasks({ epicRef: epic.ref }, { limit: 100 }),
+        ]);
+
+        // Get dependencies for each task
+        const tasksWithDeps: TaskForFull[] = await Promise.all(
+          tasksResult.items.map(async (t) => {
+            const taskDeps = await adapter.getDependencies(t.ref);
+            return {
+              ref: t.ref,
+              title: t.title,
+              status: t.status,
+              dependencies: taskDeps,
+            };
+          }),
+        );
+
+        return {
+          ref: epic.ref,
+          title: epic.title,
+          status: epic.status,
+          tasks: tasksWithDeps,
+          dependencies: epicDeps,
+        };
+      }),
+    );
+
+    result.push({
+      ref: prd.ref,
+      title: prd.title,
+      status: prd.status,
+      epics: epicsWithTasks,
+      dependencies: prdDeps,
+    });
+  }
+
+  return result;
+}
+
+export const renderStatusTool: ToolDefinition = {
+  name: "render_status",
+  description:
+    "Render project status with ANSI colors. Optional: view ('summary' or 'full', default 'summary'). Returns {output: string} with pre-formatted terminal output including progress bars, status icons, and colors. Display the output directly to user.",
+  inputSchema,
+  handler,
+};

package/src/server/tools/update-entity.ts

@@ -0,0 +1,140 @@
+import { z } from "zod";
+import { getAdapter } from "../adapters/index.js";
+import type {
+  EpicStatus,
+  PrdStatus,
+  Priority,
+  TaskStatus,
+} from "../adapters/types.js";
+import { toMcpEpic, toMcpPrd, toMcpTask } from "../utils/mcp-response.js";
+import type { ToolDefinition } from "./index.js";
+
+const inputSchema = z.object({
+  ref: z.string().min(1, "Entity reference is required"),
+  fields: z.record(z.string(), z.unknown()),
+});
+
+// Allowed fields per entity type (snake_case as received from MCP)
+const ALLOWED_FIELDS: Record<string, string[]> = {
+  P: ["title", "description", "status", "tag", "folder_path"],
+  E: ["title", "description", "status"],
+  T: ["title", "description", "status", "priority"],
+};
+
+function getEntityType(ref: string): "P" | "E" | "T" | null {
+  // Try Flux-style ref format first (e.g., FLUX-P1, FLUX-E2, FLUX-T3)
+  const match = ref.match(/-([PET])\d+$/);
+  if (match) {
+    return match[1] as "P" | "E" | "T";
+  }
+  // For other ref formats (e.g., Linear: CAL-10), return null
+  return null;
+}
+
+async function handler(input: unknown) {
+  const parsed = inputSchema.parse(input);
+  const adapter = getAdapter();
+
+  let entityType = getEntityType(parsed.ref);
+
+  // If ref format is unknown (e.g., Linear refs), try each entity type
+  if (!entityType) {
+    const prd = await adapter.getPrd(parsed.ref);
+    if (prd) {
+      entityType = "P";
+    } else {
+      const epic = await adapter.getEpic(parsed.ref);
+      if (epic) {
+        entityType = "E";
+      } else {
+        const task = await adapter.getTask(parsed.ref);
+        if (task) {
+          entityType = "T";
+        } else {
+          throw new Error(`Entity not found: ${parsed.ref}`);
+        }
+      }
+    }
+  }
+
+  const allowedFields = ALLOWED_FIELDS[entityType];
+
+  // Filter to allowed fields only
+  const validFields: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(parsed.fields)) {
+    if (allowedFields.includes(key)) {
+      validFields[key] = value;
+    }
+  }
+
+  if (Object.keys(validFields).length === 0) {
+    throw new Error(
+      `No valid fields to update. Allowed: ${allowedFields.join(", ")}`,
+    );
+  }
+
+  // Convert to adapter format and call appropriate update method
+  if (entityType === "P") {
+    const updateInput: {
+      title?: string;
+      description?: string;
+      status?: PrdStatus;
+      tag?: string;
+      folderPath?: string;
+    } = {};
+    if (validFields.title !== undefined)
+      updateInput.title = validFields.title as string;
+    if (validFields.description !== undefined)
+      updateInput.description = validFields.description as string;
+    if (validFields.status !== undefined)
+      updateInput.status = validFields.status as PrdStatus;
+    if (validFields.tag !== undefined)
+      updateInput.tag = validFields.tag as string;
+    if (validFields.folder_path !== undefined)
+      updateInput.folderPath = validFields.folder_path as string;
+
+    const prd = await adapter.updatePrd(parsed.ref, updateInput);
+    return toMcpPrd(prd);
+  } else if (entityType === "E") {
+    const updateInput: {
+      title?: string;
+      description?: string;
+      status?: EpicStatus;
+    } = {};
+    if (validFields.title !== undefined)
+      updateInput.title = validFields.title as string;
+    if (validFields.description !== undefined)
+      updateInput.description = validFields.description as string;
+    if (validFields.status !== undefined)
+      updateInput.status = validFields.status as EpicStatus;
+
+    const epic = await adapter.updateEpic(parsed.ref, updateInput);
+    return toMcpEpic(epic);
+  } else {
+    const updateInput: {
+      title?: string;
+      description?: string;
+      status?: TaskStatus;
+      priority?: Priority;
+    } = {};
+    if (validFields.title !== undefined)
+      updateInput.title = validFields.title as string;
+    if (validFields.description !== undefined)
+      updateInput.description = validFields.description as string;
+    if (validFields.status !== undefined)
+      updateInput.status = validFields.status as TaskStatus;
+    if (validFields.priority !== undefined)
+      updateInput.priority = validFields.priority as Priority;
+
+    const task = await adapter.updateTask(parsed.ref, updateInput);
+    return toMcpTask(task);
+  }
+}
+
+export const updateEntityTool: ToolDefinition = {
+  name: "update_entity",
+  description:
+    "Update fields on any entity by reference. Required: ref (e.g., 'FLUX-P1'), fields object. Allowed fields - PRD: title, description, status, tag, folder_path. Epic: title, description, status. Task: title, description, status, priority. Returns updated entity.",
+  inputSchema,
+  handler,
+};

package/src/server/tools/update-status.ts

@@ -0,0 +1,166 @@
+import { z } from "zod";
+import { getAdapter } from "../adapters/index.js";
+import type { EpicStatus, PrdStatus, TaskStatus } from "../adapters/types.js";
+import { toMcpEpic, toMcpPrd, toMcpTask } from "../utils/mcp-response.js";
+import {
+  type EntityType,
+  getTransitionErrorMessage,
+  getValidTransitions,
+  isValidTransition,
+} from "../utils/status-transitions.js";
+import type { ToolDefinition } from "./index.js";
+
+const PRD_STATUSES = [
+  "DRAFT",
+  "PENDING_REVIEW",
+  "REVIEWED",
+  "APPROVED",
+  "BREAKDOWN_READY",
+  "COMPLETED",
+  "ARCHIVED",
+] as const;
+const EPIC_STATUSES = ["PENDING", "IN_PROGRESS", "COMPLETED"] as const;
+const TASK_STATUSES = ["PENDING", "IN_PROGRESS", "COMPLETED"] as const;
+
+const inputSchema = z.object({
+  ref: z.string().min(1, "Entity reference is required"),
+  status: z.string().min(1, "Status is required"),
+});
+
+function getEntityTypeFromRef(
+  ref: string,
+): { type: EntityType; code: string } | null {
+  // Try Flux-style ref format first (e.g., FLUX-P1, FLUX-E2, FLUX-T3)
+  const match = ref.match(/-([PET])\d+$/);
+  if (match) {
+    const code = match[1];
+    const type: EntityType =
+      code === "P" ? "prd" : code === "E" ? "epic" : "task";
+    return { type, code };
+  }
+  // For other ref formats (e.g., Linear: CAL-10), return null
+  return null;
+}
+
+function getValidStatuses(code: string): readonly string[] {
+  switch (code) {
+    case "P":
+      return PRD_STATUSES;
+    case "E":
+      return EPIC_STATUSES;
+    case "T":
+      return TASK_STATUSES;
+    default:
+      throw new Error(`Unknown entity type: ${code}`);
+  }
+}
+
+async function handler(input: unknown) {
+  const parsed = inputSchema.parse(input);
+  const adapter = getAdapter();
+
+  const typeInfo = getEntityTypeFromRef(parsed.ref);
+  let entityType: EntityType;
+  let code: string;
+  let currentStatus = "";
+
+  // If ref format is unknown (e.g., Linear refs), try each entity type
+  if (typeInfo) {
+    entityType = typeInfo.type;
+    code = typeInfo.code;
+  } else {
+    // Try PRD first, then Epic, then Task
+    const prd = await adapter.getPrd(parsed.ref);
+    if (prd) {
+      entityType = "prd";
+      code = "P";
+      currentStatus = prd.status;
+    } else {
+      const epic = await adapter.getEpic(parsed.ref);
+      if (epic) {
+        entityType = "epic";
+        code = "E";
+        currentStatus = epic.status;
+      } else {
+        const task = await adapter.getTask(parsed.ref);
+        if (task) {
+          entityType = "task";
+          code = "T";
+          currentStatus = task.status;
+        } else {
+          throw new Error(`Entity not found: ${parsed.ref}`);
+        }
+      }
+    }
+  }
+
+  const validStatuses = getValidStatuses(code);
+
+  // Validate status value
+  if (!validStatuses.includes(parsed.status)) {
+    throw new Error(
+      `Invalid status '${parsed.status}' for ${entityType}. Valid: ${validStatuses.join(", ")}`,
+    );
+  }
+
+  // Get current entity status if not already set (for Flux-style refs)
+  if (typeInfo) {
+    if (code === "P") {
+      const prd = await adapter.getPrd(parsed.ref);
+      if (!prd) throw new Error(`Entity not found: ${parsed.ref}`);
+      currentStatus = prd.status;
+    } else if (code === "E") {
+      const epic = await adapter.getEpic(parsed.ref);
+      if (!epic) throw new Error(`Entity not found: ${parsed.ref}`);
+      currentStatus = epic.status;
+    } else {
+      const task = await adapter.getTask(parsed.ref);
+      if (!task) throw new Error(`Entity not found: ${parsed.ref}`);
+      currentStatus = task.status;
+    }
+  }
+
+  // Validate status transition
+  if (!isValidTransition(entityType, currentStatus, parsed.status)) {
+    throw new Error(
+      getTransitionErrorMessage(entityType, currentStatus, parsed.status),
+    );
+  }
+
+  // Update status using the appropriate adapter method
+  const availableTransitions = getValidTransitions(entityType, parsed.status);
+
+  if (code === "P") {
+    const prd = await adapter.updatePrd(parsed.ref, {
+      status: parsed.status as PrdStatus,
+    });
+    return {
+      ...toMcpPrd(prd),
+      available_transitions: availableTransitions,
+    };
+  } else if (code === "E") {
+    const epic = await adapter.updateEpic(parsed.ref, {
+      status: parsed.status as EpicStatus,
+    });
+    return {
+      ...toMcpEpic(epic),
+      available_transitions: availableTransitions,
+    };
+  } else {
+    const task = await adapter.updateTask(parsed.ref, {
+      status: parsed.status as TaskStatus,
+    });
+    return {
+      ...toMcpTask(task),
+      available_transitions: availableTransitions,
+    };
+  }
+}
+
+export const updateStatusTool: ToolDefinition = {
+  name: "update_status",
+  description:
+    "Update status of any entity with transition validation. Required: ref, status. Valid statuses - PRD: DRAFT|PENDING_REVIEW|REVIEWED|APPROVED|BREAKDOWN_READY|COMPLETED|ARCHIVED. Epic/Task: PENDING|IN_PROGRESS|COMPLETED. Returns updated entity with available_transitions. Validates transitions (e.g., PRD cannot skip from DRAFT to APPROVED).",
+  inputSchema,
+  handler,
+};