@cliangdev/flux-plugin 0.2.0 → 0.3.0

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

@@ -0,0 +1,169 @@
+/**
+ * Linear SDK Client Wrapper
+ *
+ * Wraps @linear/sdk with automatic retry logic for transient errors.
+ * - Rate limit errors (429) trigger exponential backoff
+ * - Network errors are retried with backoff
+ * - Other errors fail immediately
+ */
+
+import { LinearClient as LinearSDK } from "@linear/sdk";
+import type { LinearConfig } from "./types.js";
+
+/**
+ * Custom error class for Linear API errors.
+ */
+export class LinearApiError extends Error {
+  constructor(
+    message: string,
+    public readonly code: string,
+    public readonly statusCode?: number,
+    public readonly originalError?: Error,
+  ) {
+    super(message);
+    this.name = "LinearApiError";
+  }
+}
+
+/**
+ * Options for configuring retry behavior.
+ */
+interface RetryOptions {
+  /** Maximum number of retry attempts (default: 3) */
+  maxRetries?: number;
+  /** Base delay in milliseconds for exponential backoff (default: 1000) */
+  baseDelay?: number;
+}
+
+/**
+ * LinearClient wraps the Linear SDK with automatic retry logic.
+ */
+export class LinearClient {
+  private sdk: LinearSDK;
+  private maxRetries: number;
+  private baseDelay: number;
+
+  constructor(config: LinearConfig, options?: RetryOptions) {
+    this.sdk = new LinearSDK({ apiKey: config.apiKey });
+    this.maxRetries = options?.maxRetries ?? 3;
+    this.baseDelay = options?.baseDelay ?? 1000;
+  }
+
+  /**
+   * Get the underlying SDK for direct access when needed.
+   */
+  get client(): LinearSDK {
+    return this.sdk;
+  }
+
+  /**
+   * Execute a request with automatic retry on transient errors.
+   * - 429 (rate limit) → exponential backoff with retry
+   * - Network errors → retry with backoff
+   * - 401 (unauthorized) → throw immediately with UNAUTHORIZED code
+   * - Other errors → throw immediately
+   *
+   * @param operation The async operation to execute
+   * @returns Promise resolving to the operation result
+   * @throws LinearApiError on failure
+   */
+  async execute<T>(operation: () => Promise<T>): Promise<T> {
+    let lastError: Error | undefined;
+
+    for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+      try {
+        return await operation();
+      } catch (error: any) {
+        lastError = error;
+
+        // Check if error is retryable
+        const isRateLimited = error.status === 429;
+        const isNetworkError = this.isNetworkError(error);
+        const isUnauthorized = error.status === 401;
+
+        // Throw immediately for unauthorized errors
+        if (isUnauthorized) {
+          throw new LinearApiError(
+            "Unauthorized: Invalid API key",
+            "UNAUTHORIZED",
+            401,
+            error,
+          );
+        }
+
+        // Throw immediately for non-retryable errors
+        if (!isRateLimited && !isNetworkError) {
+          throw new LinearApiError(
+            error.message || "Linear API error",
+            "API_ERROR",
+            error.status,
+            error,
+          );
+        }
+
+        // If we've exhausted retries, throw with appropriate error code
+        if (attempt === this.maxRetries) {
+          if (isRateLimited) {
+            throw new LinearApiError(
+              `Rate limited after ${this.maxRetries} retries`,
+              "RATE_LIMITED",
+              429,
+              error,
+            );
+          }
+          throw new LinearApiError(
+            `Network error after ${this.maxRetries} retries: ${error.message}`,
+            "NETWORK_ERROR",
+            undefined,
+            error,
+          );
+        }
+
+        // Calculate delay with exponential backoff and jitter
+        const delay = this.calculateDelay(attempt);
+        await this.sleep(delay);
+      }
+    }
+
+    // This should never be reached, but TypeScript needs it
+    throw new LinearApiError(
+      "Unexpected error: max retries exceeded",
+      "API_ERROR",
+      undefined,
+      lastError,
+    );
+  }
+
+  /**
+   * Check if an error is a network error.
+   */
+  private isNetworkError(error: any): boolean {
+    // Common network error codes
+    const networkErrorCodes = [
+      "ECONNRESET",
+      "ECONNREFUSED",
+      "ETIMEDOUT",
+      "ENOTFOUND",
+      "ENETUNREACH",
+    ];
+
+    return networkErrorCodes.includes(error.code);
+  }
+
+  /**
+   * Calculate delay with exponential backoff and jitter.
+   * Formula: baseDelay * 2^attempt with ±10% randomization
+   */
+  private calculateDelay(attempt: number): number {
+    const exponentialDelay = this.baseDelay * 2 ** attempt;
+    const jitter = exponentialDelay * 0.1 * (Math.random() * 2 - 1); // ±10%
+    return Math.floor(exponentialDelay + jitter);
+  }
+
+  /**
+   * Sleep for the specified duration.
+   */
+  private sleep(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+}

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

@@ -0,0 +1,152 @@
+/**
+ * Linear Configuration Loader and Validator
+ *
+ * Manages Linear configuration stored in .flux/linear-config.json
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { config } from "../../config.js";
+import type { LinearConfig } from "./types.js";
+
+const LINEAR_CONFIG_FILE = "linear-config.json";
+
+/**
+ * Get the path to the Linear config file.
+ */
+function getLinearConfigPath(): string {
+  return `${config.fluxPath}/${LINEAR_CONFIG_FILE}`;
+}
+
+/**
+ * Check if Linear config exists.
+ */
+export function linearConfigExists(): boolean {
+  return existsSync(getLinearConfigPath());
+}
+
+/**
+ * Validate LinearConfig object.
+ * @throws Error with clear message if invalid
+ */
+export function validateLinearConfig(input: unknown): LinearConfig {
+  // Check if input is an object
+  if (typeof input !== "object" || input === null || Array.isArray(input)) {
+    throw new Error("Invalid Linear config: must be an object");
+  }
+
+  const config = input as Record<string, unknown>;
+
+  // Validate apiKey
+  if (!config.apiKey) {
+    throw new Error("Invalid Linear config: apiKey is required");
+  }
+  if (typeof config.apiKey !== "string") {
+    throw new Error("Invalid Linear config: apiKey must be a string");
+  }
+
+  // Validate teamId
+  if (!config.teamId) {
+    throw new Error("Invalid Linear config: teamId is required");
+  }
+  if (typeof config.teamId !== "string") {
+    throw new Error("Invalid Linear config: teamId must be a string");
+  }
+
+  // Validate projectId
+  if (!config.projectId) {
+    throw new Error("Invalid Linear config: projectId is required");
+  }
+  if (typeof config.projectId !== "string") {
+    throw new Error("Invalid Linear config: projectId must be a string");
+  }
+
+  // Handle defaultLabels - use defaults if not provided
+  const defaultLabels = {
+    prd: "prd",
+    epic: "epic",
+    task: "task",
+  };
+
+  if (config.defaultLabels) {
+    if (
+      typeof config.defaultLabels !== "object" ||
+      config.defaultLabels === null ||
+      Array.isArray(config.defaultLabels)
+    ) {
+      throw new Error("Invalid Linear config: defaultLabels must be an object");
+    }
+
+    const labels = config.defaultLabels as Record<string, unknown>;
+
+    // Merge with defaults
+    if (labels.prd !== undefined) {
+      if (typeof labels.prd !== "string") {
+        throw new Error(
+          "Invalid Linear config: defaultLabels.prd must be a string",
+        );
+      }
+      defaultLabels.prd = labels.prd;
+    }
+
+    if (labels.epic !== undefined) {
+      if (typeof labels.epic !== "string") {
+        throw new Error(
+          "Invalid Linear config: defaultLabels.epic must be a string",
+        );
+      }
+      defaultLabels.epic = labels.epic;
+    }
+
+    if (labels.task !== undefined) {
+      if (typeof labels.task !== "string") {
+        throw new Error(
+          "Invalid Linear config: defaultLabels.task must be a string",
+        );
+      }
+      defaultLabels.task = labels.task;
+    }
+  }
+
+  return {
+    apiKey: config.apiKey,
+    teamId: config.teamId,
+    projectId: config.projectId,
+    defaultLabels,
+  };
+}
+
+/**
+ * Load Linear config from .flux/linear-config.json.
+ * @throws Error if config file doesn't exist
+ * @throws Error if config is invalid (missing required fields)
+ */
+export function loadLinearConfig(): LinearConfig {
+  const configPath = getLinearConfigPath();
+
+  if (!existsSync(configPath)) {
+    throw new Error("Linear config not found. Run configure_linear first.");
+  }
+
+  const raw = readFileSync(configPath, "utf-8");
+  const parsed = JSON.parse(raw);
+
+  return validateLinearConfig(parsed);
+}
+
+/**
+ * Save Linear config to .flux/linear-config.json.
+ * Used by configure_linear MCP tool.
+ */
+export function saveLinearConfig(linearConfig: LinearConfig): void {
+  // Validate before saving
+  const validated = validateLinearConfig(linearConfig);
+
+  // Ensure .flux directory exists
+  const fluxPath = config.fluxPath;
+  if (!existsSync(fluxPath)) {
+    mkdirSync(fluxPath, { recursive: true });
+  }
+
+  const configPath = getLinearConfigPath();
+  writeFileSync(configPath, JSON.stringify(validated, null, 2), "utf-8");
+}

package/src/server/adapters/linear/helpers/criteria-parser.ts

@@ -0,0 +1,197 @@
+/**
+ * Criteria Parser for Linear Adapter
+ *
+ * Parses acceptance criteria from issue descriptions and provides
+ * efficient operations for reading and updating criteria.
+ */
+
+import { createHash } from "node:crypto";
+
+export interface ParsedCriterion {
+  id: string; // Hash-based stable ID
+  text: string; // Criterion text
+  isMet: boolean; // Whether checkbox is checked
+  lineIndex: number; // Line number in description (for updates)
+}
+
+/**
+ * Generate a stable ID for a criterion based on its text content.
+ * Uses first 8 chars of SHA-256 hash for brevity while maintaining uniqueness.
+ */
+export function generateCriteriaId(text: string): string {
+  const hash = createHash("sha256").update(text.trim()).digest("hex");
+  return `ac_${hash.substring(0, 8)}`;
+}
+
+/**
+ * Parse acceptance criteria from a markdown description.
+ * Looks for checkbox items: `- [ ] text` or `- [x] text`
+ *
+ * Only parses items under "Acceptance Criteria" heading if present,
+ * otherwise parses all checkbox items in the document.
+ */
+export function parseCriteriaFromDescription(
+  description: string | undefined,
+): ParsedCriterion[] {
+  if (!description) {
+    return [];
+  }
+
+  const lines = description.split("\n");
+
+  // First pass: check if AC section exists
+  let acSectionStart = -1;
+  for (let i = 0; i < lines.length; i++) {
+    const trimmedLine = lines[i].trim().toLowerCase();
+    if (
+      trimmedLine.includes("acceptance criteria") &&
+      (trimmedLine.startsWith("#") || trimmedLine.startsWith("**"))
+    ) {
+      acSectionStart = i;
+      break;
+    }
+  }
+
+  // Second pass: parse checkboxes
+  const criteria: ParsedCriterion[] = [];
+  let inACSection = acSectionStart === -1; // If no AC section, parse all
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const trimmedLine = line.trim().toLowerCase();
+
+    // Check for AC section header
+    if (i === acSectionStart) {
+      inACSection = true;
+      continue;
+    }
+
+    // If we're in AC section, check for next section header
+    if (acSectionStart !== -1 && i > acSectionStart && inACSection) {
+      if (
+        trimmedLine.startsWith("#") ||
+        (trimmedLine.startsWith("**") && trimmedLine.endsWith("**"))
+      ) {
+        break;
+      }
+    }
+
+    // Parse checkbox items only when in correct section
+    if (inACSection) {
+      const checkboxMatch = line.match(/^[\s]*[-*]\s*\[([ xX])\]\s*(.+)$/);
+      if (checkboxMatch) {
+        const isChecked = checkboxMatch[1].toLowerCase() === "x";
+        const text = checkboxMatch[2].trim();
+
+        criteria.push({
+          id: generateCriteriaId(text),
+          text,
+          isMet: isChecked,
+          lineIndex: i,
+        });
+      }
+    }
+  }
+
+  return criteria;
+}
+
+/**
+ * Update a specific criterion's checked state in the description.
+ * Returns the updated description string.
+ */
+export function updateCriterionInDescription(
+  description: string,
+  criteriaId: string,
+  isMet: boolean,
+): string {
+  const lines = description.split("\n");
+  const criteria = parseCriteriaFromDescription(description);
+
+  const criterion = criteria.find((c) => c.id === criteriaId);
+  if (!criterion) {
+    throw new Error(`Criterion not found: ${criteriaId}`);
+  }
+
+  // Update the specific line
+  const line = lines[criterion.lineIndex];
+  const newCheckbox = isMet ? "[x]" : "[ ]";
+  const updatedLine = line.replace(/\[([ xX])\]/, newCheckbox);
+  lines[criterion.lineIndex] = updatedLine;
+
+  return lines.join("\n");
+}
+
+/**
+ * Add a new criterion to the description.
+ * Appends to the Acceptance Criteria section if it exists,
+ * otherwise creates a new section at the end.
+ */
+export function addCriterionToDescription(
+  description: string | undefined,
+  criterionText: string,
+): string {
+  if (!description) {
+    return `## Acceptance Criteria\n\n- [ ] ${criterionText}`;
+  }
+
+  const lines = description.split("\n");
+
+  // Find the AC section
+  let acSectionStart = -1;
+  let acSectionEnd = lines.length;
+
+  for (let i = 0; i < lines.length; i++) {
+    const trimmedLine = lines[i].trim().toLowerCase();
+
+    if (
+      trimmedLine.includes("acceptance criteria") &&
+      (trimmedLine.startsWith("#") || trimmedLine.startsWith("**"))
+    ) {
+      acSectionStart = i;
+      continue;
+    }
+
+    // If we're past the AC header, look for next section
+    if (acSectionStart !== -1 && i > acSectionStart) {
+      const line = lines[i].trim();
+      if (
+        line.startsWith("#") ||
+        (line.startsWith("**") && line.endsWith("**"))
+      ) {
+        acSectionEnd = i;
+        break;
+      }
+    }
+  }
+
+  // Find the last checkbox in the AC section to insert after
+  let insertIndex = acSectionEnd;
+  if (acSectionStart !== -1) {
+    for (let i = acSectionEnd - 1; i > acSectionStart; i--) {
+      if (lines[i].match(/^[\s]*[-*]\s*\[([ xX])\]/)) {
+        insertIndex = i + 1;
+        break;
+      }
+    }
+    // If no checkboxes found, insert after the header
+    if (insertIndex === acSectionEnd) {
+      insertIndex = acSectionStart + 1;
+      // Skip empty lines after header
+      while (insertIndex < lines.length && lines[insertIndex].trim() === "") {
+        insertIndex++;
+      }
+    }
+  } else {
+    // No AC section exists, add one at the end
+    lines.push("");
+    lines.push("## Acceptance Criteria");
+    lines.push("");
+    insertIndex = lines.length;
+  }
+
+  // Insert the new criterion
+  lines.splice(insertIndex, 0, `- [ ] ${criterionText}`);
+
+  return lines.join("\n");
+}

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

@@ -0,0 +1,7 @@
+export {
+  addCriterionToDescription,
+  generateCriteriaId,
+  type ParsedCriterion,
+  parseCriteriaFromDescription,
+  updateCriterionInDescription,
+} from "./criteria-parser.js";

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

@@ -0,0 +1,16 @@
+/**
+ * Linear Adapter Module
+ *
+ * Public exports for the Linear adapter.
+ * Only LinearAdapter is exposed; internal types remain private.
+ */
+
+export { LinearAdapter } from "./adapter.js";
+export { LinearApiError, LinearClient } from "./client.js";
+export {
+  linearConfigExists,
+  loadLinearConfig,
+  saveLinearConfig,
+  validateLinearConfig,
+} from "./config.js";
+export type { LinearConfig } from "./types.js";

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

@@ -0,0 +1,136 @@
+/**
+ * Description formatters for embedding acceptance criteria in Linear issue descriptions.
+ *
+ * Linear doesn't have native acceptance criteria fields, so we embed them
+ * as markdown checklists in the issue description.
+ */
+
+export interface DescriptionInput {
+  description?: string;
+  acceptanceCriteria?: string[];
+}
+
+export interface ParsedDescription {
+  description: string;
+  acceptanceCriteria: Array<{
+    text: string;
+    isCompleted: boolean;
+  }>;
+}
+
+const AC_SECTION_HEADER = "## Acceptance Criteria";
+const AC_SECTION_REGEX = /^## Acceptance Criteria\s*$/m;
+const AC_ITEM_REGEX = /^-\s*\[([^\]]*)\]\s*(.+)$/;
+
+/**
+ * Format description with embedded acceptance criteria checklist.
+ *
+ * @param input - Description and acceptance criteria to format
+ * @returns Formatted description with AC checklist
+ */
+export function formatDescription(input: DescriptionInput): string {
+  const { description = "", acceptanceCriteria = [] } = input;
+
+  // If no AC, return description as-is
+  if (!acceptanceCriteria || acceptanceCriteria.length === 0) {
+    return description;
+  }
+
+  // Remove existing AC section if present
+  let baseDescription = description;
+  const acSectionMatch = baseDescription.match(AC_SECTION_REGEX);
+  if (acSectionMatch && acSectionMatch.index !== undefined) {
+    const acSectionIndex = acSectionMatch.index;
+    baseDescription = baseDescription.substring(0, acSectionIndex).trim();
+  }
+
+  // Build AC checklist
+  const acLines = acceptanceCriteria.map((criterion) => `- [ ] ${criterion}`);
+  const acSection = `${AC_SECTION_HEADER}\n${acLines.join("\n")}`;
+
+  // Combine description and AC section
+  if (baseDescription) {
+    return `${baseDescription}\n\n${acSection}`;
+  }
+  return acSection;
+}
+
+/**
+ * Parse description to extract acceptance criteria.
+ *
+ * @param content - Description content with embedded AC
+ * @returns Parsed description and AC list
+ */
+export function parseDescription(content: string): ParsedDescription {
+  if (!content) {
+    return { description: "", acceptanceCriteria: [] };
+  }
+
+  // Find AC section
+  const acSectionMatch = content.match(AC_SECTION_REGEX);
+  if (!acSectionMatch || acSectionMatch.index === undefined) {
+    return { description: content.trim(), acceptanceCriteria: [] };
+  }
+
+  const acSectionIndex = acSectionMatch.index;
+  const description = content.substring(0, acSectionIndex).trim();
+
+  // Extract AC items from section
+  const acSectionContent = content.substring(acSectionIndex);
+  const lines = acSectionContent.split("\n");
+  const acceptanceCriteria: Array<{ text: string; isCompleted: boolean }> = [];
+
+  for (const line of lines) {
+    const match = line.match(AC_ITEM_REGEX);
+    if (match) {
+      const [, checkbox, text] = match;
+      const checkboxTrimmed = checkbox.trim().toLowerCase();
+      acceptanceCriteria.push({
+        text: text.trim(),
+        isCompleted: checkboxTrimmed === "x",
+      });
+    }
+  }
+
+  return { description, acceptanceCriteria };
+}
+
+/**
+ * Update completion status of AC in description.
+ *
+ * @param content - Description content with embedded AC
+ * @param acText - Text of the AC item to update
+ * @param isCompleted - New completion status
+ * @returns Updated description content
+ */
+export function updateAcCompletion(
+  content: string,
+  acText: string,
+  isCompleted: boolean,
+): string {
+  // Find AC section
+  const acSectionMatch = content.match(AC_SECTION_REGEX);
+  if (!acSectionMatch) {
+    return content;
+  }
+
+  const checkbox = isCompleted ? "[x]" : "[ ]";
+  const lines = content.split("\n");
+  let updated = false;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const match = line.match(AC_ITEM_REGEX);
+    if (match) {
+      const [, , text] = match;
+      // Exact match only to avoid partial matches
+      if (text.trim() === acText) {
+        lines[i] = `- ${checkbox} ${text.trim()}`;
+        updated = true;
+        break;
+      }
+    }
+  }
+
+  return updated ? lines.join("\n") : content;
+}