@cliangdev/flux-plugin 0.2.0 → 0.3.0

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

@@ -0,0 +1,1141 @@
+/**
+ * Linear Adapter
+ *
+ * Implements BackendAdapter for Linear API integration.
+ *
+ * Entity Mapping:
+ * - Flux Project → Linear Project (configured during configure_linear)
+ * - PRD → Linear Issue with "prd" label in configured project
+ * - Epic → Linear Issue child of PRD with "epic" label
+ * - Task → Linear Issue child of Epic with "task" label
+ */
+
+import type {
+  AcceptanceCriterion,
+  AddCriterionInput,
+  BackendAdapter,
+  CascadeResult,
+  CreateEpicInput,
+  CreatePrdInput,
+  CreateTaskInput,
+  Document,
+  Epic,
+  EpicFilters,
+  PaginatedResult,
+  PaginationOptions,
+  Prd,
+  PrdFilters,
+  Stats,
+  Task,
+  TaskFilters,
+  UpdateEpicInput,
+  UpdatePrdInput,
+  UpdateTaskInput,
+} from "../types.js";
+import { LinearClient } from "./client.js";
+import { formatDescription } from "./mappers/description.js";
+import { toFluxEpicStatus, toLinearEpicState } from "./mappers/epic.js";
+import {
+  getAllStatusLabels,
+  getStatusLabelForPrdStatus,
+  toFluxPrdStatusFromIssue,
+  toLinearPrdIssueState,
+} from "./mappers/prd.js";
+import {
+  toFluxPriority,
+  toFluxTaskStatus,
+  toLinearPriority,
+  toLinearTaskState,
+} from "./mappers/task.js";
+import {
+  extractTagFromLabels,
+  FLUX_MILESTONE_LABEL_PREFIX,
+  getMilestoneLabel,
+  type LinearConfig,
+} from "./types.js";
+
+/**
+ * Hydrated issue with all lazy-loaded fields resolved.
+ * This eliminates repeated async calls throughout the adapter.
+ */
+export interface HydratedIssue {
+  id: string;
+  identifier: string;
+  title: string;
+  description?: string;
+  stateName: string;
+  stateType?: string;
+  labels: string[];
+  parentIdentifier?: string;
+  priority: number;
+  createdAt: Date;
+  updatedAt: Date;
+  // Raw issue for operations that need it (update, archive, etc.)
+  _raw: any;
+}
+
+export class LinearAdapter implements BackendAdapter {
+  private config: LinearConfig;
+  private client: LinearClient;
+
+  constructor(config: LinearConfig) {
+    this.config = config;
+    this.client = new LinearClient(config);
+  }
+
+  // -------------------------------------------------------------------------
+  // Helper Methods
+  // -------------------------------------------------------------------------
+
+  private extractIssueNumber(identifier: string): number {
+    const match = identifier.match(/-(\d+)$/);
+    if (!match) {
+      throw new Error(`Invalid issue identifier format: ${identifier}`);
+    }
+    return parseInt(match[1], 10);
+  }
+
+  /**
+   * Hydrate a raw Linear issue by resolving all lazy-loaded fields in parallel.
+   */
+  async hydrateIssue(issue: any): Promise<HydratedIssue> {
+    const [state, labelsResult, parent] = await Promise.all([
+      this.client.execute<any>(() => issue.state),
+      this.client.execute<any>(() => issue.labels()),
+      issue.parent
+        ? this.client.execute<any>(() => issue.parent)
+        : Promise.resolve(null),
+    ]);
+
+    return {
+      id: issue.id,
+      identifier: issue.identifier,
+      title: issue.title,
+      description: issue.description,
+      stateName: state?.name || "Backlog",
+      stateType: state?.type,
+      labels: (labelsResult?.nodes || []).map((l: any) => l.name),
+      parentIdentifier: parent?.identifier,
+      priority: issue.priority ?? 3,
+      createdAt: issue.createdAt,
+      updatedAt: issue.updatedAt,
+      _raw: issue,
+    };
+  }
+
+  /**
+   * Fetch a single issue by ref and hydrate it.
+   */
+  async fetchIssue(ref: string): Promise<HydratedIssue | null> {
+    const issueNumber = this.extractIssueNumber(ref);
+    const result = await this.client.execute(() =>
+      this.client.client.issues({
+        filter: {
+          number: { eq: issueNumber },
+          team: { id: { eq: this.config.teamId } },
+        },
+      }),
+    );
+
+    const issue = result.nodes[0];
+    if (!issue) return null;
+
+    return this.hydrateIssue(issue);
+  }
+
+  /**
+   * Fetch multiple issues with a filter and hydrate them.
+   */
+  async fetchIssues(filter: any, limit: number): Promise<HydratedIssue[]> {
+    const result = await this.client.execute(() =>
+      this.client.client.issues({ filter, first: limit }),
+    );
+
+    return Promise.all(
+      result.nodes.map((issue: any) => this.hydrateIssue(issue)),
+    );
+  }
+
+  /**
+   * Get label ID by name.
+   */
+  private async getLabelId(labelName: string): Promise<string> {
+    const labelsResult = await this.client.execute(() =>
+      this.client.client.issueLabels({
+        filter: {
+          name: { eq: labelName },
+          team: { id: { eq: this.config.teamId } },
+        },
+      }),
+    );
+
+    const label = labelsResult.nodes[0];
+    if (!label) {
+      throw new Error(`Label "${labelName}" not found in team`);
+    }
+
+    return label.id;
+  }
+
+  /**
+   * Get workflow state ID by name.
+   */
+  private async getStateId(stateName: string): Promise<string> {
+    const team = await this.client.execute(() =>
+      this.client.client.team(this.config.teamId),
+    );
+    const states = await this.client.execute(() => team.states());
+    const targetState = states.nodes.find((s: any) => s.name === stateName);
+    if (!targetState) {
+      throw new Error(`Workflow state '${stateName}' not found`);
+    }
+    return targetState.id;
+  }
+
+  // Converters from HydratedIssue to domain types
+
+  private toPrd(issue: HydratedIssue): Prd {
+    return {
+      id: issue.id,
+      projectId: this.config.projectId,
+      ref: issue.identifier,
+      title: issue.title,
+      description: issue.description,
+      status: toFluxPrdStatusFromIssue(issue.stateName, issue.labels),
+      tag: extractTagFromLabels(issue.labels),
+      createdAt: issue.createdAt.toISOString(),
+      updatedAt: issue.updatedAt.toISOString(),
+    };
+  }
+
+  private toEpic(issue: HydratedIssue): Epic {
+    return {
+      id: issue.id,
+      prdId: issue.parentIdentifier || "",
+      ref: issue.identifier,
+      title: issue.title,
+      description: issue.description,
+      status: toFluxEpicStatus(issue.stateName),
+      createdAt: issue.createdAt.toISOString(),
+      updatedAt: issue.updatedAt.toISOString(),
+    };
+  }
+
+  private toTask(issue: HydratedIssue): Task {
+    return {
+      id: issue.id,
+      epicId: issue.parentIdentifier || "",
+      ref: issue.identifier,
+      title: issue.title,
+      description: issue.description,
+      status: toFluxTaskStatus(issue.stateName),
+      priority: toFluxPriority(issue.priority),
+      createdAt: issue.createdAt.toISOString(),
+      updatedAt: issue.updatedAt.toISOString(),
+    };
+  }
+
+  // Label checkers
+
+  private isPrd(issue: HydratedIssue): boolean {
+    return issue.labels.includes(this.config.defaultLabels.prd);
+  }
+
+  private isEpic(issue: HydratedIssue): boolean {
+    return issue.labels.includes(this.config.defaultLabels.epic);
+  }
+
+  private isTask(issue: HydratedIssue): boolean {
+    return issue.labels.includes(this.config.defaultLabels.task);
+  }
+
+  // -------------------------------------------------------------------------
+  // PRD Operations
+  // -------------------------------------------------------------------------
+
+  async createPrd(input: CreatePrdInput): Promise<Prd> {
+    const labelIds = [await this.getLabelId(this.config.defaultLabels.prd)];
+
+    // Add milestone label if tag provided
+    if (input.tag) {
+      const tagLabelId = await this.getOrCreateLabel(
+        getMilestoneLabel(input.tag),
+      );
+      labelIds.push(tagLabelId);
+    }
+
+    const createResult = await this.client.execute(() =>
+      this.client.client.createIssue({
+        title: input.title,
+        description: input.description,
+        teamId: this.config.teamId,
+        projectId: this.config.projectId,
+        labelIds,
+      }),
+    );
+
+    const rawIssue = await this.client.execute<any>(
+      () => (createResult as any).issue,
+    );
+    if (!rawIssue) {
+      throw new Error("Failed to create PRD issue");
+    }
+
+    const issue = await this.hydrateIssue(rawIssue);
+    return this.toPrd(issue);
+  }
+
+  async updatePrd(ref: string, input: UpdatePrdInput): Promise<Prd> {
+    const issue = await this.fetchIssue(ref);
+    if (!issue) throw new Error(`PRD not found: ${ref}`);
+    if (!this.isPrd(issue)) throw new Error(`Issue ${ref} is not a PRD`);
+
+    const updatePayload: any = {};
+    if (input.title !== undefined) updatePayload.title = input.title;
+    if (input.description !== undefined)
+      updatePayload.description = input.description;
+
+    // Handle status change
+    if (input.status !== undefined) {
+      updatePayload.stateId = await this.getStateId(
+        toLinearPrdIssueState(input.status),
+      );
+    }
+
+    // Handle tag and/or status change - both require label updates
+    if (input.status !== undefined || input.tag !== undefined) {
+      const currentStatus = toFluxPrdStatusFromIssue(
+        issue.stateName,
+        issue.labels,
+      );
+      updatePayload.labelIds = await this.buildPrdLabelIdsWithTag(
+        issue.labels,
+        input.status ?? currentStatus,
+        input.tag !== undefined
+          ? input.tag
+          : extractTagFromLabels(issue.labels),
+      );
+    }
+
+    await this.client.execute(() => issue._raw.update(updatePayload));
+
+    const updated = await this.fetchIssue(ref);
+    if (!updated) throw new Error(`Failed to fetch updated PRD: ${ref}`);
+    return this.toPrd(updated);
+  }
+
+  /**
+   * Build label IDs for a PRD status update.
+   * Keeps existing non-status labels, adds new status label if needed.
+   * @deprecated Use buildPrdLabelIdsWithTag for updates that may include tag changes
+   */
+  private async buildPrdLabelIds(
+    currentLabels: string[],
+    newStatus: import("../types.js").PrdStatus,
+  ): Promise<string[]> {
+    const statusLabels = getAllStatusLabels();
+    const newStatusLabel = getStatusLabelForPrdStatus(newStatus);
+
+    const labelsToKeep = currentLabels.filter((l) => !statusLabels.includes(l));
+    if (newStatusLabel) {
+      labelsToKeep.push(newStatusLabel);
+    }
+
+    const labelIds: string[] = [];
+    for (const labelName of labelsToKeep) {
+      const id = await this.getOrCreateLabel(labelName);
+      labelIds.push(id);
+    }
+    return labelIds;
+  }
+
+  /**
+   * Build label IDs for a PRD update, handling both status and tag changes.
+   * Filters out status labels and milestone labels, then adds the appropriate ones back.
+   */
+  private async buildPrdLabelIdsWithTag(
+    currentLabels: string[],
+    newStatus: import("../types.js").PrdStatus,
+    newTag: string | null | undefined,
+  ): Promise<string[]> {
+    const statusLabels = getAllStatusLabels();
+    const newStatusLabel = getStatusLabelForPrdStatus(newStatus);
+
+    // Filter out status labels AND existing milestone labels
+    const labelsToKeep = currentLabels.filter(
+      (l) =>
+        !statusLabels.includes(l) && !l.startsWith(FLUX_MILESTONE_LABEL_PREFIX),
+    );
+
+    // Add status label if needed
+    if (newStatusLabel) {
+      labelsToKeep.push(newStatusLabel);
+    }
+
+    // Add new tag label if provided (not null/undefined and not empty string)
+    if (newTag) {
+      labelsToKeep.push(getMilestoneLabel(newTag));
+    }
+
+    // Convert to IDs
+    const labelIds: string[] = [];
+    for (const labelName of labelsToKeep) {
+      const id = await this.getOrCreateLabel(labelName);
+      labelIds.push(id);
+    }
+    return labelIds;
+  }
+
+  /**
+   * Get or create a label by name.
+   */
+  private async getOrCreateLabel(labelName: string): Promise<string> {
+    try {
+      return await this.getLabelId(labelName);
+    } catch {
+      const result = await this.client.execute<any>(() =>
+        (this.client.client as any).createIssueLabel({
+          name: labelName,
+          teamId: this.config.teamId,
+        }),
+      );
+      // Linear SDK returns _issueLabel (with underscore prefix)
+      const labelId = result?._issueLabel?.id ?? result?.issueLabel?.id;
+      if (!labelId || typeof labelId !== "string") {
+        throw new Error(
+          `Failed to create label: ${labelName}. Result: ${JSON.stringify(result)}`,
+        );
+      }
+      return labelId;
+    }
+  }
+
+  async getPrd(ref: string): Promise<Prd | null> {
+    const issue = await this.fetchIssue(ref);
+    if (!issue || !this.isPrd(issue)) return null;
+    return this.toPrd(issue);
+  }
+
+  async listPrds(
+    filters?: PrdFilters,
+    pagination?: PaginationOptions,
+  ): Promise<PaginatedResult<Prd>> {
+    const limit = pagination?.limit ?? 50;
+    const offset = pagination?.offset ?? 0;
+
+    const linearFilter: any = {
+      project: { id: { eq: this.config.projectId } },
+    };
+
+    // Build label filter - always include prd label, optionally include tag label
+    if (filters?.tag) {
+      linearFilter.labels = {
+        and: [
+          { name: { eq: this.config.defaultLabels.prd } },
+          { name: { eq: getMilestoneLabel(filters.tag) } },
+        ],
+      };
+    } else {
+      linearFilter.labels = { name: { eq: this.config.defaultLabels.prd } };
+    }
+
+    if (filters?.status) {
+      linearFilter.state = {
+        name: { eq: toLinearPrdIssueState(filters.status) },
+      };
+    }
+
+    const issues = await this.fetchIssues(linearFilter, limit + offset);
+    const prdIssues = issues.filter((i) => this.isPrd(i));
+    const paginated = prdIssues.slice(offset, offset + limit);
+
+    return {
+      items: paginated.map((i) => this.toPrd(i)),
+      total: prdIssues.length,
+      limit,
+      offset,
+      hasMore: offset + limit < prdIssues.length,
+    };
+  }
+
+  async deletePrd(
+    ref: string,
+  ): Promise<{ deleted: string; cascade: CascadeResult }> {
+    const issue = await this.fetchIssue(ref);
+    if (!issue) throw new Error(`PRD not found: ${ref}`);
+
+    const childrenResult = await this.client.execute<any>(() =>
+      issue._raw.children(),
+    );
+    const children = childrenResult.nodes || [];
+
+    let epicCount = 0;
+    let taskCount = 0;
+
+    for (const child of children) {
+      const hydratedChild = await this.hydrateIssue(child);
+      if (this.isEpic(hydratedChild)) {
+        const epicChildren = await this.client.execute<any>(() =>
+          child.children(),
+        );
+        for (const task of epicChildren.nodes || []) {
+          await this.client.execute<any>(() => task.archive());
+          taskCount++;
+        }
+        await this.client.execute<any>(() => child.archive());
+        epicCount++;
+      }
+    }
+
+    await this.client.execute<any>(() => issue._raw.archive());
+
+    return {
+      deleted: ref,
+      cascade: {
+        epics: epicCount,
+        tasks: taskCount,
+        criteria: 0,
+        dependencies: 0,
+      },
+    };
+  }
+
+  // -------------------------------------------------------------------------
+  // Epic Operations
+  // -------------------------------------------------------------------------
+
+  async createEpic(input: CreateEpicInput): Promise<Epic> {
+    const prdIssue = await this.fetchIssue(input.prdRef);
+    if (!prdIssue) throw new Error(`PRD not found: ${input.prdRef}`);
+    if (!this.isPrd(prdIssue))
+      throw new Error(`Issue ${input.prdRef} is not a PRD`);
+
+    const epicLabelId = await this.getLabelId(this.config.defaultLabels.epic);
+    const todoStateId = await this.getStateId("Todo");
+    const formattedDescription = formatDescription({
+      description: input.description,
+      acceptanceCriteria: input.acceptanceCriteria,
+    });
+
+    const createResult = await this.client.execute(() =>
+      this.client.client.createIssue({
+        title: input.title,
+        description: formattedDescription,
+        teamId: this.config.teamId,
+        projectId: this.config.projectId,
+        parentId: prdIssue.id,
+        labelIds: [epicLabelId],
+        stateId: todoStateId,
+      }),
+    );
+
+    const rawIssue = await this.client.execute<any>(
+      () => (createResult as any).issue,
+    );
+    if (!rawIssue) throw new Error("Failed to create Epic issue");
+
+    const issue = await this.hydrateIssue(rawIssue);
+    return this.toEpic(issue);
+  }
+
+  async updateEpic(ref: string, input: UpdateEpicInput): Promise<Epic> {
+    const issue = await this.fetchIssue(ref);
+    if (!issue) throw new Error(`Epic not found: ${ref}`);
+
+    const updatePayload: any = {};
+    if (input.title !== undefined) updatePayload.title = input.title;
+    if (input.description !== undefined)
+      updatePayload.description = input.description;
+    if (input.status !== undefined) {
+      updatePayload.stateId = await this.getStateId(
+        toLinearEpicState(input.status),
+      );
+    }
+
+    await this.client.execute(() => issue._raw.update(updatePayload));
+    // Re-fetch to get the updated issue with all fields
+    const updated = await this.fetchIssue(ref);
+    if (!updated) {
+      throw new Error(`Failed to fetch updated Epic: ${ref}`);
+    }
+    return this.toEpic(updated);
+  }
+
+  async getEpic(ref: string): Promise<Epic | null> {
+    const issue = await this.fetchIssue(ref);
+    if (!issue || !this.isEpic(issue)) return null;
+    return this.toEpic(issue);
+  }
+
+  async listEpics(
+    filters?: EpicFilters,
+    pagination?: PaginationOptions,
+  ): Promise<PaginatedResult<Epic>> {
+    const limit = pagination?.limit ?? 50;
+    const offset = pagination?.offset ?? 0;
+
+    const linearFilter: any = {
+      labels: { name: { eq: this.config.defaultLabels.epic } },
+      project: { id: { eq: this.config.projectId } },
+    };
+
+    if (filters?.prdRef) {
+      const prdIssue = await this.fetchIssue(filters.prdRef);
+      if (prdIssue) {
+        linearFilter.parent = { id: { eq: prdIssue.id } };
+      }
+    }
+
+    if (filters?.status) {
+      linearFilter.state = { name: { eq: toLinearEpicState(filters.status) } };
+    }
+
+    const issues = await this.fetchIssues(linearFilter, limit + offset);
+    const epicIssues = issues.filter((i) => this.isEpic(i));
+    const paginated = epicIssues.slice(offset, offset + limit);
+
+    return {
+      items: paginated.map((i) => this.toEpic(i)),
+      total: epicIssues.length,
+      limit,
+      offset,
+      hasMore: offset + limit < epicIssues.length,
+    };
+  }
+
+  async deleteEpic(
+    ref: string,
+  ): Promise<{ deleted: string; cascade: CascadeResult }> {
+    const issue = await this.fetchIssue(ref);
+    if (!issue) throw new Error(`Epic not found: ${ref}`);
+
+    const childrenResult = await this.client.execute<any>(() =>
+      issue._raw.children(),
+    );
+    const children = childrenResult.nodes || [];
+
+    for (const child of children) {
+      await this.client.execute<any>(() => child.archive());
+    }
+
+    await this.client.execute<any>(() => issue._raw.archive());
+
+    return {
+      deleted: ref,
+      cascade: {
+        epics: 0,
+        tasks: children.length,
+        criteria: 0,
+        dependencies: 0,
+      },
+    };
+  }
+
+  // -------------------------------------------------------------------------
+  // Task Operations
+  // -------------------------------------------------------------------------
+
+  async createTask(input: CreateTaskInput): Promise<Task> {
+    const epicIssue = await this.fetchIssue(input.epicRef);
+    if (!epicIssue) throw new Error(`Epic not found: ${input.epicRef}`);
+
+    const taskLabelId = await this.getLabelId(this.config.defaultLabels.task);
+    const todoStateId = await this.getStateId("Todo");
+    const formattedDescription = formatDescription({
+      description: input.description,
+      acceptanceCriteria: input.acceptanceCriteria,
+    });
+
+    const createResult = await this.client.execute(() =>
+      this.client.client.createIssue({
+        title: input.title,
+        description: formattedDescription,
+        teamId: this.config.teamId,
+        projectId: this.config.projectId,
+        parentId: epicIssue.id,
+        labelIds: [taskLabelId],
+        stateId: todoStateId,
+        priority: toLinearPriority(input.priority ?? "MEDIUM"),
+      }),
+    );
+
+    const rawIssue = await this.client.execute<any>(
+      () => (createResult as any).issue,
+    );
+    if (!rawIssue) throw new Error("Failed to create Task issue");
+
+    const issue = await this.hydrateIssue(rawIssue);
+    return this.toTask(issue);
+  }
+
+  async updateTask(ref: string, input: UpdateTaskInput): Promise<Task> {
+    const issue = await this.fetchIssue(ref);
+    if (!issue) throw new Error(`Task not found: ${ref}`);
+
+    const updatePayload: any = {};
+    if (input.title !== undefined) updatePayload.title = input.title;
+    if (input.description !== undefined)
+      updatePayload.description = input.description;
+    if (input.priority !== undefined)
+      updatePayload.priority = toLinearPriority(input.priority);
+    if (input.status !== undefined) {
+      const stateName = toLinearTaskState(input.status);
+      const team = await this.client.execute(() =>
+        this.client.client.team(this.config.teamId),
+      );
+      const states = await this.client.execute(() => team.states());
+      const targetState = states.nodes.find((s: any) => s.name === stateName);
+      if (targetState) updatePayload.stateId = targetState.id;
+    }
+
+    await this.client.execute(() => issue._raw.update(updatePayload));
+    // Re-fetch to get the updated issue with all fields
+    const updated = await this.fetchIssue(ref);
+    if (!updated) {
+      throw new Error(`Failed to fetch updated Task: ${ref}`);
+    }
+    return this.toTask(updated);
+  }
+
+  async getTask(ref: string): Promise<Task | null> {
+    const issue = await this.fetchIssue(ref);
+    if (!issue) return null;
+    // Task must have task label or have a parent
+    if (!this.isTask(issue) && !issue.parentIdentifier) return null;
+    return this.toTask(issue);
+  }
+
+  async listTasks(
+    filters?: TaskFilters,
+    pagination?: PaginationOptions,
+  ): Promise<PaginatedResult<Task>> {
+    const limit = pagination?.limit ?? 50;
+    const offset = pagination?.offset ?? 0;
+
+    const linearFilter: any = {
+      labels: { name: { eq: this.config.defaultLabels.task } },
+      project: { id: { eq: this.config.projectId } },
+    };
+
+    if (filters?.epicRef) {
+      const epicIssue = await this.fetchIssue(filters.epicRef);
+      if (!epicIssue) throw new Error(`Epic not found: ${filters.epicRef}`);
+      linearFilter.parent = { id: { eq: epicIssue.id } };
+    }
+
+    const result = await this.client.execute(() =>
+      this.client.client.issues({
+        filter: linearFilter,
+        first: limit + offset,
+      }),
+    );
+
+    const issues = await Promise.all(
+      result.nodes.map((i: any) => this.hydrateIssue(i)),
+    );
+    const paginated = issues.slice(offset, offset + limit);
+
+    return {
+      items: paginated.map((i) => this.toTask(i)),
+      total: issues.length,
+      limit,
+      offset,
+      hasMore: result.pageInfo?.hasNextPage ?? false,
+    };
+  }
+
+  async deleteTask(
+    ref: string,
+  ): Promise<{ deleted: string; cascade: CascadeResult }> {
+    const issue = await this.fetchIssue(ref);
+    if (!issue) throw new Error(`Task not found: ${ref}`);
+
+    await this.client.execute(() => issue._raw.archive());
+
+    return {
+      deleted: ref,
+      cascade: { epics: 0, tasks: 0, criteria: 0, dependencies: 0 },
+    };
+  }
+
+  // -------------------------------------------------------------------------
+  // Acceptance Criteria Operations
+  // -------------------------------------------------------------------------
+
+  async addCriterion(input: AddCriterionInput): Promise<AcceptanceCriterion> {
+    const issue = await this.fetchIssue(input.parentRef);
+    if (!issue) throw new Error(`Entity not found: ${input.parentRef}`);
+
+    const { addCriterionToDescription, generateCriteriaId } = await import(
+      "./helpers/index.js"
+    );
+    const newDescription = addCriterionToDescription(
+      issue.description,
+      input.criteria,
+    );
+
+    await this.client.execute<any>(() =>
+      issue._raw.update({ description: newDescription }),
+    );
+
+    return {
+      id: generateCriteriaId(input.criteria),
+      parentType: "epic" as const,
+      parentId: input.parentRef,
+      criteria: input.criteria,
+      isMet: false,
+      createdAt: new Date().toISOString(),
+    };
+  }
+
+  async markCriterionMet(criterionId: string): Promise<AcceptanceCriterion> {
+    const { parseCriteriaFromDescription, updateCriterionInDescription } =
+      await import("./helpers/index.js");
+
+    const issues = await this.fetchIssues(
+      { project: { id: { eq: this.config.projectId } } },
+      100,
+    );
+
+    for (const issue of issues) {
+      const criteria = parseCriteriaFromDescription(issue.description);
+      const criterion = criteria.find((c) => c.id === criterionId);
+
+      if (criterion) {
+        const newDescription = updateCriterionInDescription(
+          issue.description || "",
+          criterionId,
+          true,
+        );
+
+        await this.client.execute<any>(() =>
+          issue._raw.update({ description: newDescription }),
+        );
+
+        return {
+          id: criterionId,
+          parentType: "epic" as const,
+          parentId: issue.identifier,
+          criteria: criterion.text,
+          isMet: true,
+          createdAt: new Date().toISOString(),
+        };
+      }
+    }
+
+    throw new Error(`Criterion not found: ${criterionId}`);
+  }
+
+  async getCriteria(parentRef: string): Promise<AcceptanceCriterion[]> {
+    const issue = await this.fetchIssue(parentRef);
+    if (!issue) throw new Error(`Entity not found: ${parentRef}`);
+
+    const { parseCriteriaFromDescription } = await import("./helpers/index.js");
+    const parsed = parseCriteriaFromDescription(issue.description);
+
+    return parsed.map((c) => ({
+      id: c.id,
+      parentType: "epic" as const,
+      parentId: parentRef,
+      criteria: c.text,
+      isMet: c.isMet,
+      createdAt: new Date().toISOString(),
+    }));
+  }
+
+  // -------------------------------------------------------------------------
+  // Dependency Operations
+  // -------------------------------------------------------------------------
+
+  async addDependency(ref: string, dependsOnRef: string): Promise<void> {
+    if (ref === dependsOnRef) {
+      throw new Error("Entity cannot depend on itself");
+    }
+
+    const [blockedIssue, blockerIssue] = await Promise.all([
+      this.fetchIssue(ref),
+      this.fetchIssue(dependsOnRef),
+    ]);
+
+    if (!blockedIssue) throw new Error(`Issue not found: ${ref}`);
+    if (!blockerIssue) throw new Error(`Issue not found: ${dependsOnRef}`);
+
+    const blockedType = this.getEntityType(blockedIssue);
+    const blockerType = this.getEntityType(blockerIssue);
+
+    if (blockedType !== blockerType) {
+      throw new Error(
+        `Cannot create dependency between different entity types (${blockedType} and ${blockerType})`,
+      );
+    }
+
+    await this.client.execute<any>(() =>
+      this.client.client.createIssueRelation({
+        issueId: blockerIssue.id,
+        relatedIssueId: blockedIssue.id,
+        type: "blocks" as any,
+      }),
+    );
+  }
+
+  async removeDependency(ref: string, dependsOnRef: string): Promise<void> {
+    const [blockedIssue, blockerIssue] = await Promise.all([
+      this.fetchIssue(ref),
+      this.fetchIssue(dependsOnRef),
+    ]);
+
+    if (!blockedIssue) throw new Error(`Issue not found: ${ref}`);
+    if (!blockerIssue) throw new Error(`Issue not found: ${dependsOnRef}`);
+
+    // Use inverseRelations to find relations where blockedIssue is the target
+    const relations = await this.client.execute<any>(() =>
+      blockedIssue._raw.inverseRelations(),
+    );
+
+    // Find the relation to delete - need to await rel.issue since it's lazy-loaded
+    let relationToDelete: any = null;
+    for (const rel of relations.nodes) {
+      if (rel.type === "blocks") {
+        const relIssue = await rel.issue;
+        if (relIssue?.id === blockerIssue.id) {
+          relationToDelete = rel;
+          break;
+        }
+      }
+    }
+
+    if (!relationToDelete) {
+      throw new Error(
+        `Dependency not found between ${ref} and ${dependsOnRef}`,
+      );
+    }
+
+    await this.client.execute<any>(() => relationToDelete.delete());
+  }
+
+  async getDependencies(ref: string): Promise<string[]> {
+    const issue = await this.fetchIssue(ref);
+    if (!issue) throw new Error(`Issue not found: ${ref}`);
+
+    // Use inverseRelations to get relations where this issue is the target (relatedIssueId)
+    // This finds issues that block this one
+    const relations = await this.client.execute<any>(() =>
+      issue._raw.inverseRelations(),
+    );
+
+    const blockingRefs: string[] = [];
+    for (const rel of relations.nodes) {
+      if (rel.type === "blocks") {
+        // Linear SDK returns lazy-loaded promises for related objects
+        const blockerIssue = await rel.issue;
+        if (blockerIssue?.identifier) {
+          blockingRefs.push(blockerIssue.identifier);
+        }
+      }
+    }
+
+    return blockingRefs;
+  }
+
+  private getEntityType(issue: HydratedIssue): "prd" | "epic" | "task" {
+    if (this.isPrd(issue)) return "prd";
+    if (this.isEpic(issue)) return "epic";
+    if (this.isTask(issue)) return "task";
+    return issue.parentIdentifier ? "task" : "epic";
+  }
+
+  // -------------------------------------------------------------------------
+  // Document Operations
+  // -------------------------------------------------------------------------
+
+  async saveDocument(doc: Document): Promise<Document> {
+    const issue = await this.fetchIssue(doc.prdRef);
+    if (!issue) throw new Error(`PRD ${doc.prdRef} not found`);
+
+    const existingAttachments = await this.client.execute<any>(() =>
+      issue._raw.attachments(),
+    );
+    const existingAttachment = existingAttachments.nodes.find(
+      (att: any) => att.title === doc.filename,
+    );
+
+    if (existingAttachment) {
+      await this.client.execute<any>(() => existingAttachment.archive());
+    }
+
+    const contentUrl = `data:text/markdown;base64,${Buffer.from(doc.content).toString("base64")}`;
+
+    const attachResult = await this.client.execute<any>(() =>
+      (this.client.client as any).attachmentCreate({
+        title: doc.filename,
+        url: contentUrl,
+        issueId: issue.id,
+      }),
+    );
+
+    if (!attachResult.success || !attachResult.attachment) {
+      throw new Error(`Failed to create attachment for ${doc.filename}`);
+    }
+
+    return {
+      prdRef: doc.prdRef,
+      filename: doc.filename,
+      content: doc.content,
+      url: attachResult.attachment.url,
+    };
+  }
+
+  async getDocuments(prdRef: string): Promise<Document[]> {
+    const issue = await this.fetchIssue(prdRef);
+    if (!issue) throw new Error(`PRD ${prdRef} not found`);
+
+    const attachments = await this.client.execute<any>(() =>
+      issue._raw.attachments(),
+    );
+    const documents: Document[] = [];
+
+    for (const attachment of attachments.nodes) {
+      try {
+        const url = attachment.url || "";
+        if (url.startsWith("data:text/markdown;base64,")) {
+          const base64Content = url.substring(
+            "data:text/markdown;base64,".length,
+          );
+          const content = Buffer.from(base64Content, "base64").toString(
+            "utf-8",
+          );
+          documents.push({
+            prdRef,
+            filename: attachment.title,
+            content,
+            url: attachment.url,
+          });
+        }
+      } catch {}
+    }
+
+    return documents;
+  }
+
+  async deleteDocument(prdRef: string, filename: string): Promise<void> {
+    const issue = await this.fetchIssue(prdRef);
+    if (!issue) throw new Error(`PRD ${prdRef} not found`);
+
+    const attachments = await this.client.execute<any>(() =>
+      issue._raw.attachments(),
+    );
+    const attachment = attachments.nodes.find(
+      (att: any) => att.title === filename,
+    );
+
+    if (!attachment) throw new Error(`Document ${filename} not found`);
+
+    await this.client.execute<any>(() => attachment.archive());
+  }
+
+  // -------------------------------------------------------------------------
+  // Stats
+  // -------------------------------------------------------------------------
+
+  async getStats(): Promise<Stats> {
+    const issues = await this.fetchIssues(
+      { project: { id: { eq: this.config.projectId } } },
+      200,
+    );
+
+    const prdStats = {
+      total: 0,
+      draft: 0,
+      pendingReview: 0,
+      reviewed: 0,
+      approved: 0,
+      breakdownReady: 0,
+      completed: 0,
+      archived: 0,
+    };
+    const epicStats = { total: 0, pending: 0, inProgress: 0, completed: 0 };
+    const taskStats = { total: 0, pending: 0, inProgress: 0, completed: 0 };
+
+    for (const issue of issues) {
+      if (this.isPrd(issue)) {
+        prdStats.total++;
+        if (issue.stateName === "Backlog" || issue.stateType === "backlog") {
+          prdStats.draft++;
+        } else if (
+          issue.stateName === "In Progress" ||
+          issue.stateType === "started"
+        ) {
+          prdStats.approved++;
+        } else if (
+          issue.stateName === "Done" ||
+          issue.stateType === "completed"
+        ) {
+          prdStats.completed++;
+        } else if (
+          issue.stateName === "Canceled" ||
+          issue.stateType === "canceled"
+        ) {
+          prdStats.archived++;
+        } else {
+          prdStats.draft++;
+        }
+      } else if (this.isEpic(issue)) {
+        epicStats.total++;
+        if (issue.stateType === "backlog" || issue.stateType === "unstarted") {
+          epicStats.pending++;
+        } else if (issue.stateType === "started") {
+          epicStats.inProgress++;
+        } else if (issue.stateType === "completed") {
+          epicStats.completed++;
+        }
+      } else if (this.isTask(issue)) {
+        taskStats.total++;
+        if (issue.stateType === "backlog" || issue.stateType === "unstarted") {
+          taskStats.pending++;
+        } else if (issue.stateType === "started") {
+          taskStats.inProgress++;
+        } else if (issue.stateType === "completed") {
+          taskStats.completed++;
+        }
+      }
+    }
+
+    return { prds: prdStats, epics: epicStats, tasks: taskStats };
+  }
+
+  // -------------------------------------------------------------------------
+  // URL Generation
+  // -------------------------------------------------------------------------
+
+  async getLinearUrl(ref: string): Promise<{
+    url: string;
+    type: string;
+    name?: string;
+    identifier?: string;
+  }> {
+    const org = await this.client.execute(
+      () => this.client.client.organization,
+    );
+    const workspaceSlug = org.urlKey;
+
+    // Check if it's a project ref (starts with "proj_" or similar)
+    if (ref.startsWith("proj_") || ref.includes("_")) {
+      const project = await this.client.execute(() =>
+        this.client.client.project(ref),
+      );
+      const slug = project.name.toLowerCase().replace(/\s+/g, "-");
+      return {
+        url: `https://linear.app/${workspaceSlug}/project/${slug}-${project.id}`,
+        type: "project",
+        name: project.name,
+      };
+    }
+
+    // It's an issue identifier (ENG-42)
+    return {
+      url: `https://linear.app/${workspaceSlug}/issue/${ref}`,
+      type: "issue",
+      identifier: ref,
+    };
+  }
+}