@cliangdev/flux-plugin 0.2.0 → 0.3.0

package/src/server/tools/configure-linear.ts

@@ -0,0 +1,373 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { LinearClient } from "@linear/sdk";
+import { z } from "zod";
+import { clearAdapterCache } from "../adapters/index.js";
+import { saveLinearConfig } from "../adapters/linear/config.js";
+import type { LinearConfig } from "../adapters/linear/types.js";
+import { config } from "../config.js";
+import type { ToolDefinition } from "./index.js";
+
+const LINEAR_API_KEY_ENV = "LINEAR_API_KEY";
+
+const inputSchema = z
+  .object({
+    apiKey: z.string().optional(),
+    teamId: z.string().optional(),
+    projectName: z.string().optional(),
+    existingProjectId: z.string().optional(),
+    prdLabel: z.string().optional().default("prd"),
+    epicLabel: z.string().optional().default("epic"),
+    taskLabel: z.string().optional().default("task"),
+    interactive: z.boolean().optional().default(false),
+  })
+  .refine(
+    (data) => {
+      if (data.interactive) {
+        return true;
+      }
+      return (
+        data.teamId &&
+        data.teamId.length > 0 &&
+        (data.projectName || data.existingProjectId)
+      );
+    },
+    {
+      message:
+        "teamId and either projectName or existingProjectId are required (unless interactive mode)",
+    },
+  );
+
+function resolveApiKey(inputApiKey?: string): {
+  apiKey: string;
+  source: string;
+} {
+  if (inputApiKey) {
+    return { apiKey: inputApiKey, source: "input" };
+  }
+
+  const envApiKey = process.env[LINEAR_API_KEY_ENV];
+  if (envApiKey) {
+    return { apiKey: envApiKey, source: "environment" };
+  }
+
+  const configPath = `${config.fluxPath}/linear-config.json`;
+  if (existsSync(configPath)) {
+    try {
+      const configData = JSON.parse(readFileSync(configPath, "utf-8"));
+      if (configData.apiKey) {
+        return { apiKey: configData.apiKey, source: "config" };
+      }
+    } catch {
+      // Ignore parse errors, fall through to error
+    }
+  }
+
+  throw new Error(
+    `Linear API key not found. Provide it via one of:\n` +
+      `  1. Environment variable: export ${LINEAR_API_KEY_ENV}=lin_api_xxx\n` +
+      `  2. Existing config: .flux/linear-config.json with "apiKey" field\n` +
+      `  3. Tool parameter: apiKey (not recommended - visible in logs)`,
+  );
+}
+
+async function ensureLabelExists(
+  client: LinearClient,
+  teamId: string,
+  labelName: string,
+): Promise<string> {
+  const labelsResult = await client.issueLabels({
+    filter: {
+      name: { eq: labelName },
+      team: { id: { eq: teamId } },
+    },
+  });
+
+  const existingLabel = labelsResult.nodes[0];
+  if (existingLabel) {
+    return existingLabel.id;
+  }
+
+  const createResult = await client.createIssueLabel({
+    name: labelName,
+    teamId,
+  });
+
+  if (!createResult.success || !createResult.issueLabel) {
+    throw new Error(`Failed to create label '${labelName}'`);
+  }
+
+  const newLabel = await createResult.issueLabel;
+  return newLabel.id;
+}
+
+interface ViewCreationResult {
+  created: string | null;
+  error?: string;
+  skipped?: boolean;
+  setup_hint?: string;
+}
+
+async function createDefaultView(
+  client: LinearClient,
+  teamId: string,
+  projectId: string,
+  projectName: string,
+  labels: { prd: string; epic: string; task: string },
+): Promise<ViewCreationResult> {
+  try {
+    const viewName = `Flux: ${projectName}`;
+    const createResult = await client.createCustomView({
+      name: viewName,
+      description:
+        "Flux PRDs, Epics & Tasks. For hierarchy: Display → Grouping → 'Parent issue'",
+      teamId,
+      projectId,
+      color: "#5E6AD2",
+      filterData: {
+        project: { id: { eq: projectId } },
+        labels: {
+          some: {
+            name: { in: [labels.prd, labels.epic, labels.task] },
+          },
+        },
+      },
+      shared: true,
+    });
+
+    if (!createResult.success) {
+      return { created: null, error: "View creation unsuccessful" };
+    }
+
+    return {
+      created: viewName,
+      setup_hint: `For best hierarchy view: Open '${viewName}' view → Click 'Display' → Set Grouping to 'Parent issue' → Click 'Set default for everyone'`,
+    };
+  } catch (error) {
+    return {
+      created: null,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+interface TeamInfo {
+  id: string;
+  name: string;
+  key: string;
+}
+
+interface ProjectInfo {
+  id: string;
+  name: string;
+  description: string | null;
+  state: string;
+  updatedAt: string;
+}
+
+async function listTeams(client: LinearClient): Promise<TeamInfo[]> {
+  const teamsResult = await client.teams();
+  return teamsResult.nodes.map((team) => ({
+    id: team.id,
+    name: team.name,
+    key: team.key,
+  }));
+}
+
+async function listProjects(
+  client: LinearClient,
+  teamId: string,
+): Promise<ProjectInfo[]> {
+  const projectsResult = await client.projects({
+    filter: {
+      accessibleTeams: { some: { id: { eq: teamId } } },
+      state: { nin: ["canceled"] },
+    },
+  });
+
+  return projectsResult.nodes.map((project) => ({
+    id: project.id,
+    name: project.name,
+    description: project.description ?? null,
+    state: project.state,
+    updatedAt: project.updatedAt.toISOString(),
+  }));
+}
+
+async function handler(input: unknown) {
+  const parsed = inputSchema.parse(input);
+
+  const { apiKey, source: apiKeySource } = resolveApiKey(parsed.apiKey);
+
+  const client = new LinearClient({ apiKey });
+
+  let viewerName: string;
+  let viewerEmail: string | undefined;
+  try {
+    const viewer = await client.viewer;
+    if (!viewer) {
+      throw new Error("Invalid API key");
+    }
+    viewerName = viewer.name;
+    viewerEmail = viewer.email;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(
+      `Invalid Linear API key (source: ${apiKeySource}): ${message}`,
+    );
+  }
+
+  if (parsed.interactive && !parsed.teamId) {
+    const teams = await listTeams(client);
+    return {
+      step: "select_team",
+      user: { name: viewerName, email: viewerEmail },
+      api_key_source: apiKeySource,
+      teams,
+    };
+  }
+
+  if (
+    parsed.interactive &&
+    parsed.teamId &&
+    !parsed.projectName &&
+    !parsed.existingProjectId
+  ) {
+    const team = await client.team(parsed.teamId);
+    if (!team) {
+      throw new Error(`Team ${parsed.teamId} not found`);
+    }
+
+    const projects = await listProjects(client, parsed.teamId);
+    return {
+      step: "select_project",
+      user: { name: viewerName, email: viewerEmail },
+      api_key_source: apiKeySource,
+      team: { id: team.id, name: team.name, key: team.key },
+      projects,
+    };
+  }
+
+  if (!parsed.teamId) {
+    throw new Error("teamId is required");
+  }
+
+  const team = await client.team(parsed.teamId);
+  if (!team) {
+    throw new Error(`Team ${parsed.teamId} not found`);
+  }
+
+  let projectId: string;
+  let projectName: string;
+  let isNewProject = false;
+
+  if (parsed.existingProjectId) {
+    const project = await client.project(parsed.existingProjectId);
+    if (!project) {
+      throw new Error(`Project ${parsed.existingProjectId} not found`);
+    }
+    projectId = project.id;
+    projectName = project.name;
+  } else if (parsed.projectName) {
+    const createResult = await client.createProject({
+      name: parsed.projectName,
+      teamIds: [parsed.teamId],
+    });
+
+    if (!createResult.success || !createResult.project) {
+      throw new Error(`Failed to create project '${parsed.projectName}'`);
+    }
+
+    const newProject = await createResult.project;
+    projectId = newProject.id;
+    projectName = newProject.name;
+    isNewProject = true;
+  } else {
+    throw new Error("Either projectName or existingProjectId must be provided");
+  }
+
+  const prdLabelId = await ensureLabelExists(
+    client,
+    parsed.teamId,
+    parsed.prdLabel,
+  );
+  const epicLabelId = await ensureLabelExists(
+    client,
+    parsed.teamId,
+    parsed.epicLabel,
+  );
+  const taskLabelId = await ensureLabelExists(
+    client,
+    parsed.teamId,
+    parsed.taskLabel,
+  );
+
+  let viewResult: ViewCreationResult | undefined;
+  if (isNewProject) {
+    viewResult = await createDefaultView(
+      client,
+      parsed.teamId,
+      projectId,
+      projectName,
+      {
+        prd: parsed.prdLabel,
+        epic: parsed.epicLabel,
+        task: parsed.taskLabel,
+      },
+    );
+  }
+
+  const linearConfig: LinearConfig = {
+    apiKey,
+    teamId: parsed.teamId,
+    projectId,
+    defaultLabels: {
+      prd: parsed.prdLabel,
+      epic: parsed.epicLabel,
+      task: parsed.taskLabel,
+    },
+  };
+  saveLinearConfig(linearConfig);
+
+  const projectJsonPath = config.projectJsonPath;
+  const projectData = JSON.parse(readFileSync(projectJsonPath, "utf-8"));
+  projectData.adapter = { type: "linear" };
+  writeFileSync(projectJsonPath, JSON.stringify(projectData, null, 2));
+
+  clearAdapterCache();
+  config.clearCache();
+
+  return {
+    success: true,
+    message: "Linear integration configured successfully",
+    api_key_source: apiKeySource,
+    team: team.name,
+    project: {
+      id: projectId,
+      name: projectName,
+    },
+    labels: {
+      prd: { name: parsed.prdLabel, id: prdLabelId },
+      epic: { name: parsed.epicLabel, id: epicLabelId },
+      task: { name: parsed.taskLabel, id: taskLabelId },
+    },
+    view: viewResult ?? { created: null, skipped: true },
+  };
+}
+
+export const configureLinearTool: ToolDefinition = {
+  name: "configure_linear",
+  description:
+    "Configure Linear integration for the Flux project. " +
+    "Use interactive mode for guided setup: " +
+    "1) Call with {interactive: true} to get list of teams. " +
+    "2) Call with {interactive: true, teamId: '...'} to get list of projects. " +
+    "3) Call with full params to configure. " +
+    "API Key Resolution (priority order): 1) LINEAR_API_KEY environment variable (recommended), 2) Existing .flux/linear-config.json, 3) apiKey parameter (not recommended - visible in logs). " +
+    "Required (non-interactive): teamId (Linear team ID), and either projectName (to create new) or existingProjectId (to use existing). " +
+    "Optional: apiKey, prdLabel (default 'prd'), epicLabel (default 'epic'), taskLabel (default 'task'). " +
+    "Creates a Linear Project, ensures labels exist, creates 'Flux' custom view for new projects, saves config to .flux/linear-config.json. " +
+    "Returns {success, message, api_key_source, team, project, labels, view} on final configuration. " +
+    "Setup: export LINEAR_API_KEY=lin_api_xxx before running.",
+  inputSchema,
+  handler,
+};

package/src/server/tools/create-epic.ts

@@ -0,0 +1,44 @@
+import { z } from "zod";
+import { getAdapter } from "../adapters/index.js";
+import { toMcpEpic } from "../utils/mcp-response.js";
+import type { ToolDefinition } from "./index.js";
+
+const inputSchema = z.object({
+  prd_ref: z.string().min(1, "PRD reference is required"),
+  title: z.string().min(1, "Title is required"),
+  description: z.string().optional(),
+  acceptance_criteria: z.array(z.string()).optional(),
+  depends_on: z.array(z.string()).optional(),
+});
+
+async function handler(input: unknown) {
+  const parsed = inputSchema.parse(input);
+  const adapter = getAdapter();
+
+  const epic = await adapter.createEpic({
+    prdRef: parsed.prd_ref,
+    title: parsed.title,
+    description: parsed.description,
+    acceptanceCriteria: parsed.acceptance_criteria,
+  });
+
+  const criteriaCount = parsed.acceptance_criteria?.length || 0;
+
+  const dependencies: string[] = [];
+  if (parsed.depends_on && parsed.depends_on.length > 0) {
+    for (const depRef of parsed.depends_on) {
+      await adapter.addDependency(epic.ref, depRef);
+      dependencies.push(depRef);
+    }
+  }
+
+  return { ...toMcpEpic(epic), criteria_count: criteriaCount, dependencies };
+}
+
+export const createEpicTool: ToolDefinition = {
+  name: "create_epic",
+  description:
+    "Create a new Epic under a PRD. Required: prd_ref (e.g., 'FLUX-P1'), title. Optional: description, acceptance_criteria (string array), depends_on (array of Epic refs this Epic depends on, e.g., ['FLUX-E1']). Returns {id, ref, title, status, criteria_count, dependencies}. Status starts as PENDING.",
+  inputSchema,
+  handler,
+};

package/src/server/tools/create-prd.ts

@@ -0,0 +1,40 @@
+import { z } from "zod";
+import { getAdapter } from "../adapters/index.js";
+import { toMcpPrd } from "../utils/mcp-response.js";
+import type { ToolDefinition } from "./index.js";
+
+const inputSchema = z.object({
+  title: z.string().min(1, "Title is required"),
+  description: z.string().optional(),
+  tag: z.string().optional(),
+  depends_on: z.array(z.string()).optional(),
+});
+
+async function handler(input: unknown) {
+  const parsed = inputSchema.parse(input);
+  const adapter = getAdapter();
+
+  const prd = await adapter.createPrd({
+    title: parsed.title,
+    description: parsed.description,
+    tag: parsed.tag,
+  });
+
+  const dependencies: string[] = [];
+  if (parsed.depends_on && parsed.depends_on.length > 0) {
+    for (const depRef of parsed.depends_on) {
+      await adapter.addDependency(prd.ref, depRef);
+      dependencies.push(depRef);
+    }
+  }
+
+  return { ...toMcpPrd(prd), dependencies };
+}
+
+export const createPrdTool: ToolDefinition = {
+  name: "create_prd",
+  description:
+    "Create a new PRD (Product Requirements Document). Required: title. Optional: description, tag, depends_on (array of PRD refs this PRD depends on, e.g., ['FLUX-P1', 'FLUX-P2']). Returns the created PRD with {id, ref, title, description, status, tag, dependencies}. Status starts as DRAFT.",
+  inputSchema,
+  handler,
+};

package/src/server/tools/create-task.ts

@@ -0,0 +1,47 @@
+import { z } from "zod";
+import { getAdapter } from "../adapters/index.js";
+import type { Priority } from "../adapters/types.js";
+import { toMcpTask } from "../utils/mcp-response.js";
+import type { ToolDefinition } from "./index.js";
+
+const inputSchema = z.object({
+  epic_ref: z.string().min(1, "Epic reference is required"),
+  title: z.string().min(1, "Title is required"),
+  description: z.string().optional(),
+  priority: z.enum(["LOW", "MEDIUM", "HIGH"]).optional().default("MEDIUM"),
+  acceptance_criteria: z.array(z.string()).optional(),
+  depends_on: z.array(z.string()).optional(),
+});
+
+async function handler(input: unknown) {
+  const parsed = inputSchema.parse(input);
+  const adapter = getAdapter();
+
+  const task = await adapter.createTask({
+    epicRef: parsed.epic_ref,
+    title: parsed.title,
+    description: parsed.description,
+    priority: parsed.priority as Priority,
+    acceptanceCriteria: parsed.acceptance_criteria,
+  });
+
+  const criteriaCount = parsed.acceptance_criteria?.length || 0;
+
+  const dependencies: string[] = [];
+  if (parsed.depends_on && parsed.depends_on.length > 0) {
+    for (const depRef of parsed.depends_on) {
+      await adapter.addDependency(task.ref, depRef);
+      dependencies.push(depRef);
+    }
+  }
+
+  return { ...toMcpTask(task), criteria_count: criteriaCount, dependencies };
+}
+
+export const createTaskTool: ToolDefinition = {
+  name: "create_task",
+  description:
+    "Create a new Task under an Epic. Required: epic_ref (e.g., 'FLUX-E1'), title. Optional: description, priority (LOW|MEDIUM|HIGH, default MEDIUM), acceptance_criteria (string array), depends_on (array of Task refs this Task depends on, e.g., ['FLUX-T1']). Returns {id, ref, title, status, priority, criteria_count, dependencies}.",
+  inputSchema,
+  handler,
+};

package/src/server/tools/criteria.ts

@@ -0,0 +1,50 @@
+import { z } from "zod";
+import { getAdapter } from "../adapters/index.js";
+import { toMcpCriterion } from "../utils/mcp-response.js";
+import type { ToolDefinition } from "./index.js";
+
+const addCriteriaSchema = z.object({
+  parent_ref: z.string().min(1, "Parent reference is required"),
+  criteria: z.string().min(1, "Criteria text is required"),
+});
+
+const markCriteriaMetSchema = z.object({
+  criteria_id: z.string().min(1, "Criteria ID is required"),
+});
+
+async function addCriteriaHandler(input: unknown) {
+  const parsed = addCriteriaSchema.parse(input);
+  const adapter = getAdapter();
+
+  const criterion = await adapter.addCriterion({
+    parentRef: parsed.parent_ref,
+    criteria: parsed.criteria,
+  });
+
+  return toMcpCriterion(criterion);
+}
+
+async function markCriteriaMetHandler(input: unknown) {
+  const parsed = markCriteriaMetSchema.parse(input);
+  const adapter = getAdapter();
+
+  const criterion = await adapter.markCriterionMet(parsed.criteria_id);
+
+  return toMcpCriterion(criterion);
+}
+
+export const addCriteriaTool: ToolDefinition = {
+  name: "add_criteria",
+  description:
+    "Add an acceptance criterion to an Epic or Task. Required: parent_ref (e.g., 'FLUX-E1' or 'FLUX-T1'), criteria (text). Returns created criterion {id, parent_type, parent_id, criteria, is_met}. PRDs don't have direct criteria.",
+  inputSchema: addCriteriaSchema,
+  handler: addCriteriaHandler,
+};
+
+export const markCriteriaMetTool: ToolDefinition = {
+  name: "mark_criteria_met",
+  description:
+    "Mark an acceptance criterion as met/completed. Required: criteria_id (not ref, the actual id like 'ac_abc123'). Returns updated criterion with is_met=true. Use get_entity with include=['criteria'] to find criterion IDs.",
+  inputSchema: markCriteriaMetSchema,
+  handler: markCriteriaMetHandler,
+};

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

@@ -0,0 +1,76 @@
+import { z } from "zod";
+import { getAdapter } from "../adapters/index.js";
+import { toMcpCascadeResult } from "../utils/mcp-response.js";
+import type { ToolDefinition } from "./index.js";
+
+const inputSchema = z.object({
+  ref: z.string().min(1, "Entity reference is required"),
+});
+
+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}`);
+        }
+      }
+    }
+  }
+
+  let result: {
+    deleted: string;
+    cascade: {
+      criteria: number;
+      tasks: number;
+      epics: number;
+      dependencies: number;
+    };
+  };
+
+  if (entityType === "P") {
+    result = await adapter.deletePrd(parsed.ref);
+  } else if (entityType === "E") {
+    result = await adapter.deleteEpic(parsed.ref);
+  } else {
+    result = await adapter.deleteTask(parsed.ref);
+  }
+
+  return {
+    deleted: result.deleted,
+    cascade: toMcpCascadeResult(result.cascade),
+  };
+}
+
+export const deleteEntityTool: ToolDefinition = {
+  name: "delete_entity",
+  description:
+    "Delete any entity by reference with cascade deletion. Deleting a PRD removes all its Epics/Tasks/Criteria. Deleting an Epic removes its Tasks/Criteria. Returns {deleted: ref, cascade: {criteria, tasks, epics, dependencies}}.",
+  inputSchema,
+  handler,
+};

package/src/server/tools/dependencies.ts

@@ -0,0 +1,55 @@
+import { z } from "zod";
+import { getAdapter } from "../adapters/index.js";
+import type { ToolDefinition } from "./index.js";
+
+const addDependencySchema = z.object({
+  ref: z.string().min(1, "Entity reference is required"),
+  depends_on_ref: z.string().min(1, "Dependency reference is required"),
+});
+
+const removeDependencySchema = z.object({
+  ref: z.string().min(1, "Entity reference is required"),
+  depends_on_ref: z.string().min(1, "Dependency reference is required"),
+});
+
+async function addDependencyHandler(input: unknown) {
+  const parsed = addDependencySchema.parse(input);
+  const adapter = getAdapter();
+
+  await adapter.addDependency(parsed.ref, parsed.depends_on_ref);
+
+  return {
+    success: true,
+    ref: parsed.ref,
+    depends_on: parsed.depends_on_ref,
+  };
+}
+
+async function removeDependencyHandler(input: unknown) {
+  const parsed = removeDependencySchema.parse(input);
+  const adapter = getAdapter();
+
+  await adapter.removeDependency(parsed.ref, parsed.depends_on_ref);
+
+  return {
+    success: true,
+    ref: parsed.ref,
+    removed_dependency: parsed.depends_on_ref,
+  };
+}
+
+export const addDependencyTool: ToolDefinition = {
+  name: "add_dependency",
+  description:
+    "Add a dependency between two entities of the same type. Required: ref (depends on depends_on_ref), depends_on_ref. Both must be PRDs (FLUX-P*), Epics (FLUX-E*), or Tasks (FLUX-T*). Validates no circular dependencies. Returns {success, ref, depends_on}.",
+  inputSchema: addDependencySchema,
+  handler: addDependencyHandler,
+};
+
+export const removeDependencyTool: ToolDefinition = {
+  name: "remove_dependency",
+  description:
+    "Remove a dependency between two entities. Required: ref, depends_on_ref. Both must be same type (PRD, Epic, or Task). Returns {success, ref, removed_dependency}.",
+  inputSchema: removeDependencySchema,
+  handler: removeDependencyHandler,
+};