@cliangdev/flux-plugin 0.2.0 → 0.3.0

package/src/server/adapters/linear/mappers/epic.ts

@@ -0,0 +1,81 @@
+/**
+ * Epic Mapper
+ *
+ * Transforms Linear Issues to Flux Epics.
+ * Epic issues are identified by the 'epic' label in Linear.
+ */
+
+import type { Epic, EpicStatus } from "../../types.js";
+import type { LinearIssue } from "../types.js";
+import { LINEAR_EPIC_STATUS_MAP } from "../types.js";
+
+/**
+ * Transform Linear Issue to Flux Epic.
+ * Epic issues have the 'epic' label.
+ *
+ * @param issue Linear issue with epic label
+ * @param prdId Flux PRD ID to associate epic with
+ * @returns Flux Epic
+ */
+export function toEpic(issue: LinearIssue, prdId: string): Epic {
+  return {
+    id: issue.id,
+    prdId,
+    ref: issue.identifier,
+    title: issue.title,
+    description: issue.description,
+    status: toFluxEpicStatus(issue.state.name),
+    createdAt: issue.createdAt,
+    updatedAt: issue.updatedAt,
+  };
+}
+
+/**
+ * Check if a Linear issue is an epic (has epic label).
+ *
+ * @param issue Linear issue
+ * @param epicLabelName Name of the epic label (default: "epic")
+ * @returns true if issue has epic label
+ */
+export function isEpicIssue(
+  issue: LinearIssue,
+  epicLabelName: string,
+): boolean {
+  if (!issue.labels || issue.labels.length === 0) {
+    return false;
+  }
+
+  return issue.labels.some((label) => label.name === epicLabelName);
+}
+
+/**
+ * Get Linear workflow state from Flux Epic status.
+ *
+ * @param status Flux Epic status
+ * @returns Linear workflow state name
+ */
+export function toLinearEpicState(status: EpicStatus): string {
+  return LINEAR_EPIC_STATUS_MAP[status];
+}
+
+/**
+ * Get Flux Epic status from Linear workflow state name.
+ * Case-sensitive matching - Linear uses "Backlog", "Todo", "In Progress", "Done".
+ *
+ * @param stateName Linear workflow state name
+ * @returns Flux Epic status
+ */
+export function toFluxEpicStatus(stateName: string): EpicStatus {
+  switch (stateName) {
+    case "Backlog":
+    case "Todo":
+      return "PENDING";
+    case "In Progress":
+      return "IN_PROGRESS";
+    case "Done":
+      return "COMPLETED";
+    default:
+      // Default to PENDING for unknown states
+      return "PENDING";
+  }
+}

package/src/server/adapters/linear/mappers/index.ts

@@ -0,0 +1,27 @@
+/**
+ * Linear Mappers
+ *
+ * Export all mapper functions for transforming between Linear and Flux entities.
+ */
+
+export {
+  type DescriptionInput,
+  formatDescription,
+  type ParsedDescription,
+  parseDescription,
+  updateAcCompletion,
+} from "./description.js";
+export {
+  isEpicIssue,
+  toEpic,
+  toFluxEpicStatus,
+  toLinearEpicState,
+} from "./epic.js";
+export { toFluxPrdStatus, toLinearProjectState, toPrd } from "./prd.js";
+export {
+  toFluxPriority,
+  toFluxTaskStatus,
+  toLinearPriority,
+  toLinearTaskState,
+  toTask,
+} from "./task.js";

package/src/server/adapters/linear/mappers/prd.ts

@@ -0,0 +1,178 @@
+/**
+ * PRD Mapper
+ *
+ * Transforms between Linear Issues and Flux Prd entities.
+ * PRDs are represented as Linear Issues with a 'prd' label within a configured project.
+ */
+
+import type { Prd, PrdStatus } from "../../types.js";
+import type { LinearIssue, LinearProject } from "../types.js";
+import {
+  FLUX_STATUS_LABELS,
+  LINEAR_PRD_ISSUE_STATUS_MAP,
+  LINEAR_PRD_STATUS_MAP,
+  PRD_STATUSES_WITH_LABELS,
+} from "../types.js";
+
+// =============================================================================
+// Issue-based PRD mapping (new approach)
+// =============================================================================
+
+/**
+ * Transform Linear Issue to Flux Prd.
+ * PRD issues have the 'prd' label and are in the configured project.
+ *
+ * @param issue - Linear Issue with prd label
+ * @param projectId - The Linear Project ID (container for all entities)
+ * @returns Flux Prd entity
+ */
+export function toPrdFromIssue(issue: LinearIssue, projectId: string): Prd {
+  return {
+    id: issue.id,
+    projectId,
+    ref: issue.identifier,
+    title: issue.title,
+    description: issue.description,
+    status: toFluxPrdStatusFromIssue(issue.state.name),
+    createdAt: issue.createdAt,
+    updatedAt: issue.updatedAt,
+  };
+}
+
+/**
+ * Check if a Linear issue is a PRD (has prd label).
+ *
+ * @param issue - Linear issue
+ * @param prdLabelName - Name of the prd label (default: "prd")
+ * @returns true if issue has prd label
+ */
+export function isPrdIssue(issue: LinearIssue, prdLabelName: string): boolean {
+  if (!issue.labels || issue.labels.length === 0) {
+    return false;
+  }
+
+  return issue.labels.some((label) => label.name === prdLabelName);
+}
+
+/**
+ * Get Flux PRD status from Linear workflow state name and labels.
+ * Uses status labels to disambiguate states that share the same Linear workflow state.
+ *
+ * Linear "Todo" → PENDING_REVIEW or REVIEWED (check for flux:reviewed label)
+ * Linear "In Progress" → APPROVED or BREAKDOWN_READY (check for flux:breakdown-ready label)
+ *
+ * @param stateName - Linear workflow state name
+ * @param labels - Array of label names on the issue (optional)
+ * @returns Flux PRD status
+ */
+export function toFluxPrdStatusFromIssue(
+  stateName: string,
+  labels: string[] = [],
+): PrdStatus {
+  const hasReviewedLabel = labels.includes(FLUX_STATUS_LABELS.REVIEWED);
+  const hasBreakdownReadyLabel = labels.includes(
+    FLUX_STATUS_LABELS.BREAKDOWN_READY,
+  );
+
+  switch (stateName) {
+    case "Backlog":
+      return "DRAFT";
+    case "Todo":
+      return hasReviewedLabel ? "REVIEWED" : "PENDING_REVIEW";
+    case "In Progress":
+      return hasBreakdownReadyLabel ? "BREAKDOWN_READY" : "APPROVED";
+    case "Done":
+      return "COMPLETED";
+    case "Canceled":
+      return "ARCHIVED";
+    default:
+      return "DRAFT";
+  }
+}
+
+/**
+ * Get the status label that should be applied for a given Flux PRD status.
+ * Returns null if no label is needed for disambiguation.
+ *
+ * @param status - Flux PRD status
+ * @returns Label name or null
+ */
+export function getStatusLabelForPrdStatus(status: PrdStatus): string | null {
+  return PRD_STATUSES_WITH_LABELS[status];
+}
+
+/**
+ * Get all status labels that should be removed when changing status.
+ * This ensures we don't have stale status labels after a transition.
+ *
+ * @returns Array of all status label names
+ */
+export function getAllStatusLabels(): string[] {
+  return Object.values(FLUX_STATUS_LABELS);
+}
+
+/**
+ * Get Linear workflow state name from Flux PRD status.
+ * Used for issue-based PRDs.
+ *
+ * @param status - Flux PRD status
+ * @returns Linear workflow state name
+ */
+export function toLinearPrdIssueState(status: PrdStatus): string {
+  return LINEAR_PRD_ISSUE_STATUS_MAP[status];
+}
+
+// =============================================================================
+// Project-based PRD mapping (deprecated - kept for backward compatibility)
+// =============================================================================
+
+/**
+ * Transform Linear Project to Flux Prd.
+ *
+ * @deprecated Use toPrdFromIssue for new issue-based PRD mapping
+ * @param project - Linear Project object
+ * @param projectId - Project ID (used as both id and projectId in Flux)
+ * @returns Flux Prd entity
+ */
+export function toPrd(project: LinearProject, projectId: string): Prd {
+  return {
+    id: projectId,
+    projectId: projectId,
+    ref: project.id,
+    title: project.name,
+    description: project.description,
+    status: toFluxPrdStatus(project.state),
+    createdAt: project.createdAt,
+    updatedAt: project.updatedAt,
+  };
+}
+
+/**
+ * Get Linear project state from Flux PRD status.
+ *
+ * @deprecated Use toLinearPrdIssueState for new issue-based PRD mapping
+ * @param status - Flux PRD status
+ * @returns Linear project state (backlog, planned, started, completed, canceled)
+ */
+export function toLinearProjectState(status: PrdStatus): string {
+  return LINEAR_PRD_STATUS_MAP[status];
+}
+
+/**
+ * Get Flux PRD status from Linear project state.
+ *
+ * @deprecated Use toFluxPrdStatusFromIssue for new issue-based PRD mapping
+ * @param state - Linear project state
+ * @returns Flux PRD status
+ */
+export function toFluxPrdStatus(state: string): PrdStatus {
+  const stateMap: Record<string, PrdStatus> = {
+    backlog: "DRAFT",
+    planned: "PENDING_REVIEW",
+    started: "APPROVED",
+    completed: "COMPLETED",
+    canceled: "ARCHIVED",
+  };
+
+  return stateMap[state] || "DRAFT";
+}

package/src/server/adapters/linear/mappers/task.ts

@@ -0,0 +1,82 @@
+/**
+ * Linear Task Mapper
+ *
+ * Transforms Linear Issues to/from Flux Tasks.
+ */
+
+import type { Priority, Task, TaskStatus } from "../../types.js";
+import type { LinearIssue } from "../types.js";
+import {
+  FLUX_PRIORITY_MAP,
+  LINEAR_PRIORITY_MAP,
+  LINEAR_TASK_STATUS_MAP,
+} from "../types.js";
+
+/**
+ * Transform Linear Issue to Flux Task.
+ *
+ * @param issue - Linear Issue object
+ * @param epicId - Parent Epic ID in Flux
+ * @returns Flux Task object
+ */
+export function toTask(issue: LinearIssue, epicId: string): Task {
+  return {
+    id: issue.id,
+    epicId,
+    ref: issue.identifier,
+    title: issue.title,
+    description: issue.description,
+    status: toFluxTaskStatus(issue.state.name),
+    priority: toFluxPriority(issue.priority),
+    createdAt: issue.createdAt,
+    updatedAt: issue.updatedAt,
+  };
+}
+
+/**
+ * Get Linear priority number from Flux priority.
+ *
+ * @param priority - Flux Priority (LOW, MEDIUM, HIGH)
+ * @returns Linear priority number (1-4)
+ */
+export function toLinearPriority(priority: Priority): number {
+  return LINEAR_PRIORITY_MAP[priority];
+}
+
+/**
+ * Get Flux priority from Linear priority number.
+ *
+ * @param linearPriority - Linear priority (1=urgent, 2=high, 3=medium, 4=low)
+ * @returns Flux Priority
+ */
+export function toFluxPriority(linearPriority: number): Priority {
+  return FLUX_PRIORITY_MAP[linearPriority] ?? "LOW";
+}
+
+/**
+ * Get Linear workflow state from Flux Task status.
+ *
+ * @param status - Flux Task status
+ * @returns Linear workflow state name
+ */
+export function toLinearTaskState(status: TaskStatus): string {
+  return LINEAR_TASK_STATUS_MAP[status];
+}
+
+/**
+ * Get Flux Task status from Linear workflow state name.
+ *
+ * @param stateName - Linear workflow state name
+ * @returns Flux Task status
+ */
+export function toFluxTaskStatus(stateName: string): TaskStatus {
+  // Map Linear states to Flux statuses
+  const stateMap: Record<string, TaskStatus> = {
+    Backlog: "PENDING",
+    Todo: "PENDING",
+    "In Progress": "IN_PROGRESS",
+    Done: "COMPLETED",
+  };
+
+  return stateMap[stateName] ?? "PENDING";
+}

package/src/server/adapters/linear/types.ts

@@ -0,0 +1,264 @@
+/**
+ * Linear Adapter Types
+ *
+ * Defines Linear-specific types for API responses and configuration.
+ * These types are internal to the Linear adapter and not exposed to MCP tools.
+ */
+
+import type { EpicStatus, PrdStatus, Priority, TaskStatus } from "../types.js";
+
+// =============================================================================
+// Configuration
+// =============================================================================
+
+/**
+ * Linear adapter configuration.
+ * Stored in project.json under adapter.config.
+ */
+export interface LinearConfig {
+  /** Linear API key (lin_api_...) */
+  apiKey: string;
+  /** Linear team ID */
+  teamId: string;
+  /** Linear Project ID - container for all PRDs, Epics, and Tasks */
+  projectId: string;
+  /** Label names used to identify entity types */
+  defaultLabels: {
+    /** Label for PRD issues */
+    prd: string;
+    /** Label for epic issues */
+    epic: string;
+    /** Label for task issues */
+    task: string;
+  };
+}
+
+// =============================================================================
+// Linear API Response Types
+// =============================================================================
+
+/**
+ * Linear Project represents a PRD in Flux.
+ * ref = project.id (e.g., "proj_abc123")
+ */
+export interface LinearProject {
+  /** Project ID */
+  id: string;
+  /** Project name (maps to PRD title) */
+  name: string;
+  /** Project description (maps to PRD description) */
+  description?: string;
+  /** Project state (backlog, planned, started, completed, canceled) */
+  state: string;
+  /** Creation timestamp */
+  createdAt: string;
+  /** Last update timestamp */
+  updatedAt: string;
+}
+
+/**
+ * Linear Issue represents an Epic or Task in Flux.
+ * - Epic: Issue with "epic" label (ref = issue.identifier like "ENG-42")
+ * - Task: Issue child of epic (ref = issue.identifier like "ENG-43")
+ */
+export interface LinearIssue {
+  /** Issue ID */
+  id: string;
+  /** Issue identifier (e.g., "ENG-42") - used as ref */
+  identifier: string;
+  /** Issue title */
+  title: string;
+  /** Issue description */
+  description?: string;
+  /** Workflow state */
+  state: LinearWorkflowState;
+  /** Priority (1=urgent, 2=high, 3=medium, 4=low/none) */
+  priority: number;
+  /** Parent issue ID (for tasks) */
+  parentId?: string;
+  /** Project ID (for PRD association) */
+  projectId?: string;
+  /** Labels for categorization */
+  labels?: LinearLabel[];
+  /** Creation timestamp */
+  createdAt: string;
+  /** Last update timestamp */
+  updatedAt: string;
+}
+
+/**
+ * Linear Workflow State.
+ * Maps to Epic/Task status in Flux.
+ */
+export interface LinearWorkflowState {
+  /** State ID */
+  id: string;
+  /** State name (e.g., "Backlog", "In Progress", "Done") */
+  name: string;
+  /** State type (backlog, unstarted, started, completed, canceled) */
+  type: string;
+}
+
+/**
+ * Linear Label.
+ * Used to identify epic vs task issues.
+ */
+export interface LinearLabel {
+  /** Label ID */
+  id: string;
+  /** Label name */
+  name: string;
+}
+
+/**
+ * Linear Document (future).
+ * Represents attachments or linked documents.
+ */
+export interface LinearDocument {
+  /** Document ID */
+  id: string;
+  /** Document title */
+  title: string;
+  /** Document URL */
+  url: string;
+  /** Creation timestamp */
+  createdAt: string;
+}
+
+// =============================================================================
+// Status and Priority Mapping
+// =============================================================================
+
+/**
+ * Maps Flux PRD status to Linear project state.
+ * @deprecated Use LINEAR_PRD_ISSUE_STATUS_MAP for issue-based PRDs
+ */
+export const LINEAR_PRD_STATUS_MAP: Record<PrdStatus, string> = {
+  DRAFT: "backlog",
+  PENDING_REVIEW: "planned",
+  REVIEWED: "planned",
+  APPROVED: "started",
+  BREAKDOWN_READY: "started",
+  COMPLETED: "completed",
+  ARCHIVED: "canceled",
+};
+
+/**
+ * Maps Flux PRD status to Linear workflow state name.
+ * Used for issue-based PRDs (new mapping).
+ */
+export const LINEAR_PRD_ISSUE_STATUS_MAP: Record<PrdStatus, string> = {
+  DRAFT: "Backlog",
+  PENDING_REVIEW: "Todo",
+  REVIEWED: "Todo",
+  APPROVED: "In Progress",
+  BREAKDOWN_READY: "In Progress",
+  COMPLETED: "Done",
+  ARCHIVED: "Canceled",
+};
+
+/**
+ * Maps Flux Epic status to Linear workflow state name.
+ */
+export const LINEAR_EPIC_STATUS_MAP: Record<EpicStatus, string> = {
+  PENDING: "Todo",
+  IN_PROGRESS: "In Progress",
+  COMPLETED: "Done",
+};
+
+/**
+ * Maps Flux Task status to Linear workflow state name.
+ */
+export const LINEAR_TASK_STATUS_MAP: Record<TaskStatus, string> = {
+  PENDING: "Todo",
+  IN_PROGRESS: "In Progress",
+  COMPLETED: "Done",
+};
+
+/**
+ * Maps Flux Priority to Linear priority number.
+ * Linear: 1=urgent, 2=high, 3=medium, 4=low/none
+ */
+export const LINEAR_PRIORITY_MAP: Record<Priority, number> = {
+  LOW: 4,
+  MEDIUM: 3,
+  HIGH: 2,
+};
+
+/**
+ * Reverse map: Linear priority to Flux Priority.
+ */
+export const FLUX_PRIORITY_MAP: Record<number, Priority> = {
+  1: "HIGH", // urgent -> HIGH
+  2: "HIGH",
+  3: "MEDIUM",
+  4: "LOW",
+};
+
+// =============================================================================
+// Status Labels for Disambiguation
+// =============================================================================
+
+/**
+ * Status labels used to disambiguate Flux statuses that share the same
+ * Linear workflow state.
+ *
+ * Problem: Linear has limited workflow states, but Flux has more granular statuses.
+ * - "Todo" maps to both PENDING_REVIEW and REVIEWED
+ * - "In Progress" maps to both APPROVED and BREAKDOWN_READY
+ *
+ * Solution: Use labels to track the exact Flux status.
+ */
+export const FLUX_STATUS_LABELS = {
+  /** Applied when PRD is in REVIEWED state (disambiguates from PENDING_REVIEW) */
+  REVIEWED: "flux:reviewed",
+  /** Applied when PRD is in BREAKDOWN_READY state (disambiguates from APPROVED) */
+  BREAKDOWN_READY: "flux:breakdown-ready",
+} as const;
+
+/**
+ * PRD statuses that require a status label for disambiguation.
+ */
+export const PRD_STATUSES_WITH_LABELS: Record<PrdStatus, string | null> = {
+  DRAFT: null,
+  PENDING_REVIEW: null,
+  REVIEWED: FLUX_STATUS_LABELS.REVIEWED,
+  APPROVED: null,
+  BREAKDOWN_READY: FLUX_STATUS_LABELS.BREAKDOWN_READY,
+  COMPLETED: null,
+  ARCHIVED: null,
+};
+
+// =============================================================================
+// Milestone/Tag Labels
+// =============================================================================
+
+/**
+ * Prefix for milestone labels that map to PRD tags.
+ * Format: flux:milestone:<tag>
+ */
+export const FLUX_MILESTONE_LABEL_PREFIX = "flux:milestone:";
+
+/**
+ * Get the milestone label name for a given tag.
+ * @param tag - The tag value (e.g., "mvp-phase-1")
+ * @returns Full label name (e.g., "flux:milestone:mvp-phase-1")
+ */
+export function getMilestoneLabel(tag: string): string {
+  return `${FLUX_MILESTONE_LABEL_PREFIX}${tag}`;
+}
+
+/**
+ * Extract tag value from a list of labels.
+ * Finds the first label starting with the milestone prefix and extracts the tag.
+ * @param labels - Array of label names
+ * @returns The tag value or undefined if no milestone label found
+ */
+export function extractTagFromLabels(labels: string[]): string | undefined {
+  for (const label of labels) {
+    if (label.startsWith(FLUX_MILESTONE_LABEL_PREFIX)) {
+      return label.substring(FLUX_MILESTONE_LABEL_PREFIX.length);
+    }
+  }
+  return undefined;
+}